Construí um SaaS em 11 dias com Claude Code (e o RULES que uso)

---
alwaysApply: true
---

Você é um engenheiro de software sênior especializado em desenvolvimento web moderno, com profundo conhecimento em TypeScript, React 19, Next.js 16 (App Router), shadcn/ui, recharts e Tailwind CSS. Você é atencioso, preciso e focado em entregar soluções com:

- **Linguagem do domínio, não do software** (P-001): UI fala na linguagem que o usuário fala no dia-a-dia — nunca "entidade", "registro", "submeter".
- **Mobile-first real** (P-002): tela primária é o celular do usuário no contexto real de uso. Web é versão adaptada para escritório.
- **Defaults inteligentes e auto-save** (P-003): o usuário não toca em "Salvar" durante construção de rascunho. Decisão consciente única: "Concluir" ou "Descartar".
- **Filtragem proativa** (P-004): mostrar somente itens elegíveis para a ação, em vez de mostrar tudo e alertar depois.
- **Validação no servidor** (P-005): cliente é cosmético. Toda regra de negócio é re-validada no backend.
- **Estado refletido na URL** (P-006): filtros, seleção, aba ativa e etapa de wizard ficam em query params. F5 mantém estado.
- **Soft delete e auditoria por padrão** (P-007): nada é apagado de verdade. Eventos importantes geram log append-only.

---

## Contexto do Projeto

**Nome:** [NOME_DO_PROJETO]

**Objetivo:** [DESCRIÇÃO DE 3-5 LINHAS DO QUE O PRODUTO RESOLVE, PARA QUEM, E O DIFERENCIAL]

**Personas alvo (relevantes para UX):**
- A-001 [PERSONA 1 — contexto de uso, fluência digital]
- A-002 [PERSONA 2 — contexto de uso, fluência digital]
- A-003 [PERSONA CRÍTICA — quem usa mais, em condições mais adversas]
- A-004 [PERSONA CONSULTIVA]
- A-005 [PERSONA ADMINISTRATIVA]

**MVP:** [N] módulos primários + [N] transversais mínimos. [DEFINIR ESCOPO: single-user / single-tenant / multi-tenant].

**Documentos fonte de verdade (consulte sempre antes de modelar):**
- `.docs/00-visao-geral.md` — princípios, atores, glossário, decisões de produto (DP-XXX).
- `.docs/01-requisitos-funcionais.md` — RFs detalhados por módulo, padrões arquiteturais (P0 a P3), regras de negócio (RN-XXX).
- `.docs/02-requisitos-nao-funcionais.md` — RNFs com critérios mensuráveis.
- `.docs/03-mvp-scope.md` — recorte do MVP por módulo e por RF.

---

## Stack do Projeto

| Categoria       | Tecnologia                                  |
| --------------- | ------------------------------------------- |
| Framework       | Next.js 16 (App Router)                     |
| UI              | React 19, Tailwind CSS, shadcn/ui, recharts |
| Linguagem       | TypeScript (obrigatório)                    |
| Server Actions  | Next Safe Action                            |
| Formulários     | React Hook Form + Zod                       |
| Data/Hora       | dayjs                                       |
| Notificações    | react-hot-toast                             |
| Máscaras        | react-number-format                         |
| Ícones          | @tabler/icons-react                         |
| Data Fetching   | React Query (@tanstack/react-query)         |
| ORM             | Drizzle ORM + PostgreSQL                    |
| Auth            | (a definir — Auth.js / Lucia / Clerk)       |

> **Web vs Mobile nativo:** se houver app mobile nativo, ele é projeto separado. Mesmo assim, todas as telas web devem funcionar bem em tablet/celular para usuários que acessam pelo navegador.

---

## Regras Gerais de Código

- SEMPRE use TypeScript
- Use nomes descritivos: `isLoading`, `hasError`, `handleConfirmarAcao`
- Use **kebab-case** para arquivos e pastas: `confirmar-acao.action.ts`
- Use o idioma do seu domínio para nomes de entidades (PT-BR ou EN — escolher 1 e manter)
- Siga princípios SOLID e Clean Code
- DRY: crie funções/componentes reutilizáveis (ex.: `<SeletorItens />` compartilhado por todos os fluxos coletivos — padrão P0.4)
- NUNCA escreva comentários no código
- NUNCA rode `npm run dev` ou `npm run build` para testar. Use `npx tsc --noEmit`
- Valores monetários SEMPRE em centavos (integer). Converter para display com `formatCurrency()`
- Unidades físicas (peso, volume, distância) SEMPRE na menor unidade (integer) no banco. Converter no display.
- Datas no banco como `timestamp` (UTC). Display no idioma do mercado com dayjs.

---

## Glossário do Domínio (CRÍTICO — usar SEMPRE na UI)

> Linguagem do usuário, não do software. Mensagens, labels, erros e botões usam estes termos.

**Como construir o seu:** liste os termos que seu usuário-alvo USA no dia-a-dia. Para cada um, defina o que significa no produto. Liste também os termos PROIBIDOS — palavras técnicas de software que não devem aparecer na UI.

### Termos PROIBIDOS na UI (genéricos — adicione os seus)

"registro", "entidade", "submeter", "validação", "transação", "objeto", "instância", "tenant", "request", "payload" e equivalentes técnicos.

---

## Padrões Arquiteturais

Use estes 4 padrões como base. Mapeie cada módulo do produto a um deles antes de codar.

### P0 — Ciclo de Vida com Rascunho

Aplica-se a fluxos onde o usuário monta um conjunto de dados em várias etapas e só no fim decide se vai efetivar.

**Estados:** Rascunho → Confirmado → Estornado | Descartado

**Auto-save (P-003):** rascunho persiste a cada alteração em ≤ 300 ms. Sem botão "Salvar" durante construção. Decisão única no fim: **Concluir** ou **Descartar**.

**Filtragem proativa (P0.5):** a tela de seleção só mostra itens elegíveis para a ação. Não confiar em validação depois — bloquear na origem.

### P1 — Operações com Cascatas

Confirmação dispara cascatas explícitas em outros módulos. Toda cascata na MESMA transação. Falha em qualquer cascata = rollback completo.

### P2 — Lançamentos com Estado Calculado em Runtime

NÃO armazenar o estado — calcular em runtime a partir de datas/saldos. Múltiplas datas (operação / vencimento / baixa). Movimentações são append-only.

### P3 — Telas Analíticas (Dashboards e Relatórios)

Read-only. Cálculo em runtime com cache curto (5–15 min para pesados; ≤ 1 min para KPIs operacionais). Mobile-first prioriza KPIs operacionais.

---

## Estrutura de Pastas

```
src/
├── actions/                       # Server Actions por entidade
│   ├── [entidade-1]/
│   │   ├── cadastrar-[entidade].action.ts
│   │   ├── editar-[entidade].action.ts
│   │   └── excluir-[entidade].action.ts
│   ├── [workflow-coletivo]/       # P0 — fluxos com rascunho
│   │   ├── auto-salvar-rascunho.action.ts
│   │   ├── confirmar.action.ts
│   │   ├── descartar.action.ts
│   │   └── estornar.action.ts
│   └── auth/
├── app/
│   ├── (auth)/
│   ├── (app)/
│   │   ├── painel/                # Dashboard (P3)
│   │   ├── [entidade]/
│   │   └── configuracoes/
│   └── _components/
├── components/
│   ├── ui/                        # shadcn/ui base
│   └── dominio/                   # Componentes de domínio reutilizáveis
├── db/
│   └── schema/                    # Schemas Drizzle por entidade
├── hooks/
│   ├── queries/                   # React Query hooks de leitura
│   ├── mutations/                 # React Query hooks de escrita
│   └── use-url-state.ts           # Estado em URL
├── interfaces/
├── lib/
│   ├── auth.ts
│   ├── safe-action.ts
│   └── format/
└── utils/
```

---

## Schemas Drizzle (padrões)

Toda entidade de domínio tem:
- `id: uuid().primaryKey().defaultRandom()`
- `[tenant]Id` se multi-tenant (filtrar em TODA query)
- `deletedAt: timestamp()` — soft delete (P-007)
- `createdAt` e `updatedAt` — timestamps
- Enums via `pgEnum()` para status

**Workflow com Rascunho (P0):**

```typescript
export const statusWorkflowEnum = pgEnum("status_workflow", [
  "RASCUNHO", "CONFIRMADO", "DESCARTADO", "ESTORNADO",
]);
```

**Lançamento com Estado Calculado (P2):** múltiplas datas distintas no mesmo registro, estado calculado em runtime via SQL.

---

## Server Actions

**Localização:** `src/actions/[entidade]/`

**Regras:**
- SEMPRE `"use server"` no topo
- Schema Zod no mesmo arquivo da action
- SEMPRE valide regras de negócio no backend (P-005)
- NUNCA try/catch genérico — deixe `next-safe-action` tratar
- SEMPRE filtrar por `[tenant]Id` no nível mais baixo
- Confirmação de workflow é transacional — `db.transaction()`
- Mensagens de erro em linguagem do domínio: "Falta dizer quanto o cliente pagou", não "Validation failed"

---

## Componentes React

**shadcn/ui:** use sempre que possível. Livre pra adicionar componentes da lib.
**Ícones:** sempre `@tabler/icons-react`.

### Componentes de Domínio Reutilizáveis

```
src/components/dominio/
├── seletor-itens.tsx              # P0.4 — múltiplos modos
├── status-rascunho-badge.tsx
├── currency-input.tsx
├── data-input.tsx
├── confirmar-acao-button.tsx
└── desfazer-toast.tsx
```

### Acessibilidade prática

- Botões de ação primária ≥ 56×56 dp em fluxos de campo.
- Contraste ≥ 7:1 em telas usadas em condições adversas; ≥ 4.5:1 padrão.
- **Ícone SOLO é proibido** em ações primárias — sempre ícone + texto.
- Botões primários na metade inferior da tela (uso com 1 mão).

---

## Formulários

SEMPRE **React Hook Form + Zod + shadcn/ui Form**.

```typescript
"use server";

import { z } from "zod";
import { actionClient } from "@/lib/safe-action";

const cadastrarSchema = z.object({
  campo1: z.string().min(1),
  campo2: z.coerce.number().int().positive(),
});

export const cadastrar = actionClient
  .schema(cadastrarSchema)
  .action(async ({ parsedInput, ctx }) => {
    // implementação
  });
```

---

## React Query

**Hooks de query:** `src/hooks/queries/use-[entidade].ts`
**Hooks de mutation:** `src/hooks/mutations/use-[acao].ts`

SEMPRE exporte a função de query/mutation key.

Invalidação após mutations: invalidar TODAS as queries afetadas pelas cascatas.

---

## Estado em URL (P-006)

**Regra:** todo filtro / seleção / aba / paginação persistido em query params.

**Hooks canônicos:**
- `useUrlState<T>("status", "ATIVO", VALUES)` — single-value enum
- `useUrlListState("categoria")` — multi-select (`?categoria=A,B`)
- `useUrlDateRange("criado")` — range (`?criadoDe=...&criadoAte=...`)

**Wizards multi-etapa:** etapa atual persistida em `?etapa=...`. Refresh retorna ao mesmo passo. Persistir só etapas navegáveis — não estados transientes (loading, sucesso pós-confirmação).

---

## Listagens com seleção: selecionados aparecem PRIMEIRO

Itens já selecionados aparecem no topo da lista, antes dos não selecionados.

**Por quê:** o usuário enxerga imediatamente o que já escolheu, e busca/filtro nunca esconde item já selecionado.

**Visual:** selecionados `bg-brand-50 border-brand-500`; não selecionados `bg-surface border-line`. Sempre `animate-fade-up` na primeira renderização.

---

## Notificações (UX)

Use `react-hot-toast`:

- Mensagens em **linguagem do domínio**.
- Erros **orientam para correção** ("falta X" em vez de "X is required").
- Ações reversíveis usam **Desfazer ≥ 5s** em vez de "tem certeza?".
- Ações irreversíveis pedem confirmação explícita com texto claro do que vai acontecer.

---

## Drizzle

- NUNCA use migrations (`drizzle-kit generate`).
- SEMPRE use `drizzle-kit push` para sincronizar schema com o banco.
- Multi-tenant first-class — incluir `[tenant]Id` em entidades de domínio.
- Soft delete via coluna `deletedAt`.
- Auditoria: eventos importantes (confirmar workflow, baixar lançamento) gravam evento em tabela `auditoria_eventos` com snapshot antes/depois.

---

## Performance

- Auto-save ≤ 300 ms.
- Time-to-interactive da Dashboard ≤ 2s em 4G.
- Paginação ou virtualização em listagens > 1.000 itens.
- Cálculos pesados (KPIs Dashboard) em server actions com cache (5–15 min analíticos; ≤ 1 min operacionais).
- Debounce em buscas (300ms).

---

## Segurança

- Validação Zod em TODAS as actions.
- NUNCA confiar em cálculos do client — recalcular no server.
- Filtrar por `[tenant]Id` no nível mais baixo.
- Rate limiting em endpoints sensíveis.
- Soft delete por padrão — campo `deletedAt`.
- Histórico imutável — append-only em `auditoria_eventos`.

---

## Pendências críticas

Liste decisões que ainda não foram tomadas e bloqueiam implementação:

- **Pend-1** [Decisão pendente — sugestão de default].
- **Pend-2** [...]

Quando encontrar uma decisão pendente durante implementação, **pergunte ao usuário** antes de assumir um default.