tema-bitola — Astro 电商模板

SHA-256: 8939ce132a7dea897d2c56b12f1ccbee7dc339cd9b3d507ba76a8ab216636dac

2026-10-13T01:28:56.624Z

# Bitola — loja demo do nicho de construção, ferramentas e industrial

Cópia do starter [`ecomplus/store`](https://github.com/ecomplus/store)
tematizada para **fixação, ferramenta e EPI**, atendendo profissional e
indústria além do consumidor final.

> **Este nicho ainda não existe no site institucional.** Não há marca em
> `src/config/brands.ts` nem página em `/segmentos/`. O posicionamento foi
> **proposto**, não portado. Nome, logo e domínio são placeholders.

## Por que este nicho, se não está no topo do varejo online

Porque é onde a plataforma **ganha por diferença, não por preço**. Catálogo
técnico enorme, comprador que sabe exatamente o que quer, recompra
profissional previsível e preço por grupo de cliente — o oposto da disputa de
marketplace.

Lojas do setor já na base: **Atlas Parafusos** (parafusos e ferramentas
especiais para indústria e construção civil, loja física desde 1999),
**Desicon** ("a loja do profissional", 10+ anos), **Disfoil** (telas e
importação), **Líder Ferrer**, **Comercial Luizinho**.

E há um acesso raro: **Rodrigo e Rocha**, a loja física de material de
construção da qual o Vitor é sócio, é exatamente este perfil de operador — dá
para validar a hipótese sem depender de call de venda.

## O elo com a auditoria de recursos

A [auditoria de recursos do storefront](../planning/produto/planejamento/auditoria-recursos-storefront.md)
lista como **prioridade alta** produtizar o *smart shelves* da Atlas Parafusos
(visto recentemente, retomar busca, retomar carrinho, **repetir último
pedido**) para o `storefront-template`. Hoje está marcado como **PARCIAL**:
roda sob medida em uma loja só.

Esta demo é o argumento comercial desse item — e por isso a seção de nicho
**avisa em tela** que a recompra em um clique é recurso em produtização, não
recurso disponível. Um lojista que veja a demo não pode sair achando que já
está pronto.

## O que foi customizado em relação ao starter

| Arquivo | O que mudou |
|---|---|
| `functions/ssr/content/settings.json` | Nome, descrição, domínio, logo/ícone, `primaryColor` grafite + `secondaryColor` amarelo de segurança, 5% no Pix, 6x sem juros, frete grátis a partir de R$ 249 |
| `functions/ssr/tailwind.config.js` | Escala neutra grafite frio, canto quase reto |
| `functions/ssr/content/layout.json` | Pitch bar (repetir pedido, preço profissional, frete), submenu em ordem alfabética (catálogo grande), rodapé com lista de "Linhas", `ogImage` |
| `functions/ssr/content/pages/home.json` | Hero de 2 slides, 3 vitrines, grade de 3 banners e a seção de nicho |
| `functions/ssr/src/sections/NichoConstrucaoSection.astro` | **Novo.** Facetas técnicas (bitola, rosca, material, acabamento), consumidor × profissional e chamada de recompra com aviso de produtização |
| `functions/ssr/src/sections/_Sections.astro` | Registro da seção `c:nicho-construcao` |
| `functions/ssr/content/extra-pages/` | Contato, trocas (especificação errada, defeito em EPI, item sob medida) e termos em PT-BR |
| `functions/ssr/public/img/uploads/` | Banners do Unsplash; imagens do starter removidas. Créditos em `CREDITOS.md` |

## Por que grafite e amarelo

É o par que o nicho lê sem explicação — sinalização, EPI, ferramenta elétrica.
O amarelo fica restrito a destaque e preço: como cor de ação principal ele não
tem contraste suficiente com texto branco. A escala neutra é grafite frio de
propósito: aqui o catálogo é enorme e a interface precisa sumir para a
informação aparecer.

## Por que a seção de nicho é um componente, e não HTML no CMS

O UnoCSS/Tailwind desta stack varre apenas `./src/**` — classe utilitária
escrita dentro de `content/pages/*.json` (seção `custom-html`) não gera CSS. Por
isso a vitrine do nicho é um `.astro` em `src/sections/`, registrado pela
convenção `c:` que o `_Sections.astro` já previa.

## Rodando

```bash
npm i
npm run dev     # http://localhost:3000
npm run build
```

O catálogo é remoto: sem uma loja E-Com Plus configurada (`npm run setup`), as
vitrines de produto vêm vazias — o hero, os banners e a seção de nicho
renderizam normalmente.

## Pendências conhecidas

- **Recompra em um clique não existe no template.** Está sinalizado em tela e
  no componente. É o item de prioridade alta da auditoria.
- **Preço por grupo de cliente não é chave que se liga.** A plataforma tem
  regras de desconto complexas, mas "profissional vê um preço, consumidor vê
  outro" precisa ser desenhado caso a caso. Também sinalizado em tela.
- As facetas técnicas são estáticas e todas apontam para `/s/catalogo` — viram
  filtro real só depois de bitola, rosca, material e acabamento estarem
  cadastrados como especificação de produto.
- A foto do hero 2 é de **ferramentaria manual de marcenaria**, não de fixação
  industrial. Funciona como imagem de oficina, mas se a hipótese avançar vale
  trocar por foto do próprio catálogo.
- Logo e ícone são wordmarks placeholder rasterizados. Ao fechar a identidade,
  vetorizar o texto.

## Como atualizar a base da plataforma

Este repositório é uma **casca fina**. O storefront, os componentes e a lógica
de loja moram nos pacotes `@cloudcommerce/*`, não aqui. Atualizar o tema para
uma versão nova da plataforma **não** é fazer merge com o starter
[`ecomplus/store`](https://github.com/ecomplus/store) — é subir a versão das
dependências, exatamente como as lojas em produção fazem: a
[tiasonia](https://www.tiasonia.com.br) tem mais de 260 commits `Update to v`
no próprio repositório e nenhum merge com o starter.

Todos os pacotes `@cloudcommerce/*` andam na mesma versão, na raiz e em cada
grupo de functions (`ssr`, `many`, `with-apps`):

```bash
# 1. ver a versão mais recente e o changelog
npm view @cloudcommerce/cli version
# https://github.com/ecomplus/cloud-commerce/releases

V=2.61.4   # troque pela versão alvo

# 2. raiz
npm i -D @cloudcommerce/cli@$V @cloudcommerce/eslint@$V

# 3. cada grupo de functions
(cd functions/ssr && npm i \
  @cloudcommerce/api@$V @cloudcommerce/firebase@$V @cloudcommerce/ssr@$V \
  @cloudcommerce/i18n@$V @cloudcommerce/storefront@$V @cloudcommerce/types@$V)
(cd functions/many && npm i \
  @cloudcommerce/feeds@$V @cloudcommerce/firebase@$V @cloudcommerce/passport@$V)
(cd functions/with-apps && npm i \
  @cloudcommerce/events@$V @cloudcommerce/firebase@$V @cloudcommerce/modules@$V)

# 4. validar antes de commitar
npm run build

# 5. commitar no padrão das lojas em produção
git commit -am "Update to v$V"
```

Se o build quebrar depois de atualizar, a correção pertence ao
[`cloud-commerce`](https://github.com/ecomplus/cloud-commerce), não a este
repositório. Aqui só entra o que é **do tema**: `functions/ssr/src/`,
`functions/ssr/content/` e `functions/ssr/public/`.

## Este repositório é um template

Use **"Use this template"** no GitHub para começar uma loja a partir deste tema.
O repositório gerado é independente: não existe upstream para puxar, e a
manutenção segue o fluxo de versão acima.

Antes de ir ao ar, troque o que é placeholder:

- `functions/ssr/content/settings.json` — nome, domínio, logo, cores, contato
- `functions/ssr/public/img/uploads/` — logo, ícone e banners (as fotos atuais
  vêm do Unsplash; créditos em `CREDITOS.md`)
- `functions/ssr/content/extra-pages/` — contato, trocas e termos
- `functions/ssr/public/robots.txt` — hoje bloqueia tudo, porque a demo é
  `noindex`
- `functions/*/config.json` — `storeId` e projeto Firebase (`npm run setup`)

> **Demo publicada:** [tema-bitola.web.app](https://tema-bitola.web.app) — `noindex`, com
> catálogo compartilhado de demonstração.

---

Documentação do starter: [SETUP.pt-BR.md](./SETUP.pt-BR.md) ·
[Cloud Commerce](https://github.com/ecomplus/cloud-commerce)