tema-focinho — Astro 电商模板

SHA-256: 89d197a495138f0ca013c7bb8c7fcfee59bc71f58afce082f791541db7746daf

2026-10-13T01:27:22.415Z

# Focinho — loja demo do nicho pet

Cópia do starter [`ecomplus/store`](https://github.com/ecomplus/store)
tematizada para **cães e gatos**. Pet é a categoria de maior crescimento do
e-commerce brasileiro (~38%) e casa quase perfeitamente com recursos que a
plataforma já tem: assinatura, multi CD e fidelidade.

## ⚠️ Esta é a única das nove sem prova interna

Todas as outras variantes ancoram em cliente real da base:

| Nicho | Prova na base |
|---|---|
| Alimentício | Tia Sônia, BarraDoce, Festpan |
| Beleza | Help Perfumaria, Vênus Nails |
| Moda | Don't Quest, Lado Fit, Lua Cheia |
| Casa | Conexão Home, Conexão Office, Para la Casa |
| Construção | Atlas Parafusos, Desicon, Disfoil |
| Eletrônicos | Aolar, Eletrogel, Quality Áudio |
| Suplementos | Suplementos RP, Grãos da Vida |
| **Pet** | **nenhuma** |

**Isso é aposta de mercado, não de prova.** Em call de venda não há case do
nicho para mostrar — o argumento tem que se apoiar em recurso (assinatura,
multi CD) e em cases de outros nichos com dor parecida. Vale saber disso antes
de levar a demo para um prospect.

> Este nicho também não existe no site institucional: não há marca em
> `src/config/brands.ts` nem página em `/segmentos/`. Nome, logo e domínio são
> placeholders.

## O eixo: assinatura de ração

Ração é o **caso canônico de reposição programada** — consumo previsível (peso
do animal × gramas/dia), embalagem grande, recompra mensal. O bloco de "quanto
tempo dura o saco" é o que transforma assinatura de desconto em utilidade: a
pergunta do tutor não é quanto custa, é quando acaba.

Em volta disso, três dores que só existem aqui:

1. **Item pesado** — saco de 15 kg não é frete comum; é caso de multi CD.
2. **Prescrição veterinária** — dieta terapêutica e medicamento exigem receita,
   e a loja não pode fingir que não. Mesmo tratamento dado ao produto
   controlado na variante de clubes de tiro.
3. **Transição de ração** — mudança brusca faz mal ao animal, então o pedido
   sugere proporção de mistura em vez de só entregar o saco novo.

## 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` azul + `secondaryColor` laranja, 5% no Pix, 3x sem juros, frete grátis a partir de R$ 149 |
| `functions/ssr/tailwind.config.js` | Escala neutra azul-acinzentada, canto bem arredondado |
| `functions/ssr/content/layout.json` | Pitch bar (assinatura, frete, Pix), listas do rodapé, `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/NichoPetSection.astro` | **Novo.** Filtro por perfil do animal, tabela de duração da embalagem, cuidados (frete pesado, receita, transição) e chamada de assinatura |
| `functions/ssr/src/sections/_Sections.astro` | Registro da seção `c:nicho-pet` |
| `functions/ssr/content/extra-pages/` | Contato, trocas (saco violado, pet não aceitou, medicamento) e termos em PT-BR |
| `functions/ssr/public/img/uploads/` | Banners do Unsplash; imagens do starter removidas. Créditos em `CREDITOS.md` |

## Por que azul e laranja

É o par que o varejo pet brasileiro já usa — reconhecível de longe, não exige
explicação. É deliberadamente a variante mais alegre das nove: aqui a compra é
afetiva, não técnica.

## 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

- **A tabela de duração é maquete estática.** Não calcula nada e não vem do
  rótulo do produto. A conta real varia por marca, fórmula e animal.
- **O fluxo de receita veterinária é copy.** Não há upload nem validação de
  documento. Se a hipótese avançar, é o primeiro item a especificar.
- Logo e ícone são wordmarks placeholder rasterizados.
- As rotas (`/s/cao-filhote`, `/assine`…) só respondem depois que o catálogo
  tiver as categorias correspondentes.

## 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-focinho.web.app](https://tema-focinho.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)