# Metodologia — Blueprint de ERP por Nicho

Índice:
- [Fase 0 — Captura do Nicho](#fase-0--captura-do-nicho)
- [Fase 1 — Mapa de Setores e Processos](#fase-1--mapa-de-setores-e-processos)
- [Fase 1.5 — Macroprocessos Transversais](#fase-15--macroprocessos-transversais)
- [Fase 2 — Organograma](#fase-2--organograma)
- [Fase 3 — Apps por Setor (mini-spec)](#fase-3--apps-por-setor-mini-spec)
- [Fase 4 — Visão ERP + Roadmap de Build](#fase-4--visão-erp--roadmap-de-build)
- [Backbone universal de setores](#backbone-universal-de-setores)
- [Template de mini-spec de app](#template-de-mini-spec-de-app)
- [Anti-patterns](#anti-patterns)

Cada fase tem um **checkpoint**: mostrar o resultado e confirmar antes de avançar. Não despejar as 4 fases de uma vez.

---

## Fase 0 — Captura do Nicho

Perguntar o nicho. Se vier vago ("loja"), pedir especificidade ("loja de quê? roupa, autopeças, materiais de construção?"). O nicho específico muda o setor operacional central.

Depois do nicho, fazer **no máximo 4 perguntas calibradoras** (de uma vez, não uma por uma):

1. **Porte** — solo / pequeno (até ~10 pessoas) / médio / rede-franquia. Calibra quantos setores fazem sentido (negócio solo não tem RH formal).
2. **Modelo de receita** — venda de produto, serviço recorrente, projeto/sob-demanda, infoproduto, marketplace. Define o setor operacional central.
3. **B2B, B2C ou ambos** — muda comercial, pós-venda e financeiro.
4. **O que já existe** — já usa planilha/sistema/ERP em algum setor? Evita reinventar e indica por onde começar a substituir.

Se a pessoa não souber responder, assumir o cenário mais comum do nicho (a biblioteca de nichos traz o default) e seguir, deixando registrado o pressuposto.

**Checkpoint 0:** confirmar nicho + porte antes de mapear setores.

---

## Fase 1 — Mapa de Setores e Processos

Para o nicho, listar **todos os setores que devem existir** e, dentro de cada um, os **processos-chave** (o que de fato acontece ali, em verbo: "emitir nota", "agendar visita", "calibrar máquina").

Método:
1. Partir do [backbone universal](#backbone-universal-de-setores) — toda empresa tem essas macro-áreas.
2. **Adaptar o setor operacional central** ao nicho (é o que mais varia: numa clínica é "Atendimento Clínico", numa marmoraria é "Produção/Marmoraria", numa agência é "Operação/Delivery de Campanhas").
3. **Podar pelo porte** — negócio solo funde setores (Financeiro+Administrativo viram um só); rede expande (Expansão/Franquias vira setor).
4. Para cada setor: nome, missão em 1 linha, 3–8 processos-chave, e a **dor atual típica** (onde costuma usar planilha/papel/WhatsApp solto — é ali que o app entra).

Consultar `references/biblioteca-nichos.md` primeiro: se o nicho (ou um análogo) já estiver mapeado, usar como base e ajustar, não recomeçar do zero.

Saída desta fase vai pro arquivo `02-Setores-e-Apps.md` (parte 1).

**Checkpoint 1:** revisar a lista de setores antes de desenhar o organograma — é mais barato adicionar/remover setor agora.

---

## Fase 1.5 — Macroprocessos Transversais

**Esta é a fase que transforma "lista de apps" em "ERP".** A Fase 1 mapeia o que acontece *dentro* de cada setor. Aqui mapeamos os processos que **atravessam vários setores** — é por eles que o dado flui e é o que um ERP de verdade orquestra.

Identificar quais dos macroprocessos clássicos existem no nicho (nem todos existem em todo negócio):

| Macroprocesso | Atravessa | Existe quando o negócio… |
|---|---|---|
| **Lead-to-Cash** (lead → fechamento → entrega → recebimento) | Marketing → Vendas → Operação → Financeiro | …capta lead e vende (quase todo negócio) |
| **Order-to-Cash** (pedido → produção/entrega → faturamento → recebimento) | Vendas → Estoque/Produção → Fiscal → Financeiro | …vende produto/serviço com pedido formal |
| **Procure-to-Pay** (necessidade → compra → recebimento → pagamento) | Suprimentos → Estoque → Financeiro | …compra de fornecedor pra operar |
| **Hire-to-Retire** (recrutar → admitir → gerir → desligar) | RH → Financeiro | …tem equipe formal (porte médio+) |
| **Atendimento-to-Resolução** (chamado → triagem → resolução → CSAT) | Pós-venda → Operação | …tem suporte/pós-venda estruturado |

Para **cada macroprocesso que existe**, desenhar a cadeia em uma linha mostrando o **dado que passa de mão em mão** e o **status que muda**:

> Ex. Order-to-Cash numa marmoraria: `Orçamento (rascunho)` → cliente aprova → `Pedido (aprovado)` → produção gera `OS (em produção → pronta)` → entrega muda pra `Entregue` → Fiscal emite `NF-e` → Financeiro abre `Conta a receber` → pagamento → `Quitado`.

**Ciclo de vida do documento:** todo documento de negócio (orçamento, pedido, OS, fatura) tem **estados** que mudam conforme atravessa os setores. Listar os estados de cada documento-chave — é isso que os apps vão precisar respeitar pra conversar. Sem estados compartilhados, os apps viram CRUD solto.

**Saída:** um bloco "Macroprocessos" no `00-Blueprint.md`, com 1 diagrama Mermaid (`flowchart LR`) por macroprocesso existente, anotando o documento + status em cada seta. Esses diagramas são a **planta da integração da Fase 4** — a Fase 4 só conecta os apps que servem esses fluxos.

**Checkpoint 1.5:** confirmar os macroprocessos antes do organograma. Se um setor da Fase 1 não aparece em nenhum macroprocesso, questionar se ele realmente vira app agora.

---

## Fase 2 — Organograma

Desenhar o organograma dos setores em **Mermaid** (`flowchart TD`), do topo (Direção/Dono) para baixo, agrupando setores por bloco (Comercial, Operacional, Suporte/Back-office).

Convenções:
- Topo: `Direção / Dono`.
- Nível 2: blocos macro (ex: Comercial, Operação, Back-office) quando há muitos setores; senão, setores direto.
- Nível 3: setores; opcionalmente sub-áreas relevantes.
- Manter rótulos curtos. Não colocar nomes de pessoas — é organograma de **função**, não de gente.
- Salvar em `01-Organograma.mmd` e também embutir o mesmo bloco ```mermaid``` dentro do `00-Blueprint.md` (Obsidian renderiza).

Exemplo de esqueleto:

```mermaid
flowchart TD
    D[Direção / Dono]
    D --> C[Comercial & Marketing]
    D --> O[Operação / Núcleo do Nicho]
    D --> B[Back-office]
    C --> C1[Marketing]
    C --> C2[Vendas]
    C --> C3[Pós-venda / CS]
    O --> O1[Setor Operacional Central]
    O --> O2[Suprimentos / Estoque]
    B --> B1[Financeiro]
    B --> B2[Administrativo / RH]
    B --> B3[Gestão / BI]
```

**Checkpoint 2:** confirmar o organograma.

---

## Fase 3 — Apps por Setor (mini-spec)

Para **cada setor**, especificar o(s) app(s) que dá pra construir no Claude Code, usando o [template de mini-spec](#template-de-mini-spec-de-app). Regras:

- Começar com **1 app por setor** (o que resolve a maior dor). Só sugerir 2º app no setor se a dor for claramente partida (ex: Financeiro → "Contas a Pagar/Receber" + "Fluxo de Caixa/DRE" pode ser um app só no começo).
- Cada app recebe **prioridade P1/P2/P3** olhando o negócio inteiro (não dentro do setor): P1 = dói agora e destrava caixa/tempo; P2 = importante, depende de P1; P3 = otimização.
- Indicar a **skill do ecossistema** que constrói aquele app (consultar `references/catalogo-skills-build.md`).
- Marcar quais dados o app **produz** e **consome** de outros apps — é isso que costura o ERP depois.

Saída vai pro `02-Setores-e-Apps.md` (parte 2).

**Checkpoint 3:** revisar a fila de apps + prioridades.

---

## Fase 4 — Visão ERP + Roadmap de Build

Fechar mostrando como os apps deixam de ser ilhas e viram **um ERP**:

1. **Mapa de integração** — diagrama Mermaid (`flowchart LR`) com os apps como nós e setas = dado que flui entre eles (ex: Vendas → gera pedido → Estoque baixa → Financeiro fatura). Revela a espinha de dados compartilhada.
2. **Núcleo compartilhado do ERP** — o que todos os apps dividem desde o dia 1 pra não virar retrabalho. Recomendar decidir isso ANTES de construir o 1º app:
   - **Login único** (auth central) — uma identidade pra todos os apps.
   - **Cadastro mestre** (clientes, produtos/serviços, fornecedores) — fonte única de verdade; os apps leem daqui, não duplicam.
   - **Banco único** multi-schema ou um schema por app no mesmo Postgres.
   - **Papéis e permissões (RBAC)** — quem vê/edita o quê, por perfil (dono, vendedor, financeiro, operação). Definir os perfis no núcleo e cada app respeita; sem isso não é ERP, é CRUD aberto. Os perfis saem direto do organograma da Fase 2.
   - **Trilha de auditoria (audit log)** — registrar quem fez o quê e quando nos eventos sensíveis (mudança de status, valores, exclusões). Requisito básico de ERP e barato se decidido cedo.
   - **Propagação entre apps** — COMO o dado de um app atualiza o outro em tempo (evento/webhook/fila). No porte pequeno pode ser leitura direta do banco compartilhado; em porte maior, fila (ex: BullMQ). Apontar a decisão e, se a pessoa quiser aprofundar, mandar pra `/arquitetura-imperatriz`.
   - **Camada fiscal/contábil** (quando o nicho vende com nota) — emissão de NF-e/NFS-e, impostos e DRE. Pode ser integração com emissor externo (ex: Focus NFe, eNotas) em vez de construir do zero; registrar como decisão, não ignorar — pra PME brasileira isso costuma ser obrigatório.
   - **Padrão visual** (Painel da Tata) — paleta creme+navy+púrpura, Montserrat+Cormorant.
3. **Roadmap por fases** — ordenar a construção por prioridade + dependência:
   - Fase 1: núcleo compartilhado + 1–2 apps P1 que sozinhos já dão ROI.
   - Fase 2: apps P1/P2 que dependem dos dados da Fase 1.
   - Fase 3: apps P3 + camada de BI/dashboard que lê todos.
   - Marcar em cada fase qual skill de build usar e estimativa grosseira de esforço (P/M/G).
   - **Migração dos dados que já existem** — pra cada app que substitui uma planilha/sistema (mapeado na Fase 0), prever a importação inicial dos dados (clientes, produtos, saldos) pro cadastro mestre. Sem plano de migração a pessoa fica com o app vazio e volta pra planilha. Marcar em qual fase cada migração acontece.
4. **Apontar a virada pra ERP de verdade** — quando os apps já compartilham auth+cadastro+banco e têm um dashboard que lê todos, o "ERP" já existe de fato. Deixar claro esse marco.

Saída vai pro fim do `00-Blueprint.md`.

**Checkpoint 4 (final):** entregar tudo + gerar o `dashboard.html` a partir de `assets/dashboard-template.html`.

---

## Backbone universal de setores

Toda empresa tem alguma versão destes. Usar como checklist e podar/expandir pelo porte e nicho:

| Bloco | Setor | Existe sempre? | Vira app? |
|---|---|---|---|
| Comercial | Marketing / Aquisição | Sim | Captação de leads, gestão de campanhas |
| Comercial | Vendas / Comercial | Sim | CRM / funil / orçamentos |
| Comercial | Pós-venda / CS / Atendimento | Sim | Tickets, NPS, retenção |
| Operação | **Setor operacional central (muda por nicho)** | Sim | **O app mais importante** |
| Operação | Suprimentos / Compras / Estoque | Quase sempre | Controle de estoque, pedidos a fornecedor |
| Operação | Logística / Entrega | Depende | Rastreio, rotas, agendamento |
| Back-office | Financeiro | Sim | Contas a pagar/receber, fluxo de caixa, DRE |
| Back-office | Administrativo / Jurídico / Compliance | Médio+ | Contratos, documentos, prazos |
| Back-office | RH / Pessoas / DP | Médio+ | Ponto, recrutamento, escala |
| Gestão | Estratégia / Gestão / BI | Sim (mesmo que informal) | Dashboard de indicadores (lê todos) |
| Gestão | Expansão / Franquias | Só rede | Padronização, onboarding de unidades |

Regra de porte:
- **Solo / pequeno:** fundir Financeiro+Administrativo; RH pode não virar app; foco em 3–4 apps.
- **Médio:** todos os setores do backbone, ~6–8 apps.
- **Rede / franquia:** + Expansão; apps multi-tenant/multi-unidade.

---

## Template de mini-spec de app

Usar este formato exato para cada app na Fase 3:

```markdown
### 🟦 [Nome do App]  ·  Setor: {setor}  ·  Prioridade: P{1-3}

- **Dor que resolve:** {a planilha/WhatsApp/papel que ele substitui}
- **Funcionalidades core:** {3–6 bullets do MVP — só o essencial}
- **Usuários & permissões:** {quem usa e o que cada perfil pode fazer — ex: vendedor cria pedido, só financeiro fatura, dono vê tudo}
- **Documento + status:** {o documento que o app movimenta e seus estados — ex: Pedido (rascunho → aprovado → faturado → entregue); "n/a" se for só cadastro/consulta}
- **Stack sugerida:** {ex: Node + Express + Postgres + Next; ou HTML único; calibrar pelo porte}
- **Dados que produz:** {ex: pedidos, clientes}
- **Dados que consome:** {de qual app vem; "nenhum / cadastro mestre" se for fundação}
- **Macroprocesso que serve:** {qual fluxo da Fase 1.5 ele faz andar — ex: Order-to-Cash; "interno" se não cruza setores}
- **Build via:** {skill do ecossistema — ver catalogo-skills-build.md}
- **Esforço:** P / M / G
```

---

## Anti-patterns

- **Não** entregar as 4 fases num bloco só — respeitar os checkpoints.
- **Não** listar setor que o porte não comporta (RH formal pra negócio solo). Calibrar.
- **Não** especificar 5 apps por setor — começa com 1, o que mais dói.
- **Não** tratar os apps como ilhas: a Fase 4 (integração + núcleo compartilhado) é o que justifica chamar de "ERP". Sem ela, é só uma lista de appzinhos.
- **Não** colocar nomes de pessoas no organograma — é mapa de função.
- **Não** recomendar stack pesada (Kubernetes, microserviços) pra negócio pequeno. Calibrar pelo porte — ver `/arquitetura-imperatriz` se a pessoa quiser aprofundar arquitetura.
- **Não** reinventar nichos já mapeados — checar `biblioteca-nichos.md` antes.
- **Não** pular a Fase 1.5: sem macroprocessos transversais + ciclo de vida de documento, os apps viram CRUD solto e a "integração" da Fase 4 fica sem planta. É o que separa ERP de lista de appzinhos.
- **Não** deixar permissões, audit log e fiscal pro "depois" — são decisões do núcleo (Fase 4). Adicionar RBAC e nota fiscal num app já construído custa 10x. Decidir cedo, mesmo que a implementação seja simples no começo.
- **Não** entregar app que substitui planilha sem plano de migração dos dados existentes — a pessoa volta pra planilha.
