003 — Plan · Stack da Aplicação: OpenAPI, Estado, UI e Testes

003 — Plan · Stack da Aplicação: OpenAPI, Estado, UI e Testes

Data: 2026-06-29

Contexto

Sobre a fundação (ADR 001), falta a stack que o app de fato usa: contrato de API, estado, componentes, testes e banco. Tudo já é regra no Manifesto — aqui ela é instalada e exercitada por um fluxo ponta a ponta.

Decisão

• OpenAPI derivado de Zod 4 nativo (z.toJSONSchema), com paths por domínio, servido em /openapi.json e testável em /reference (Scalar). Tipos gerados do spec.
• Zustand no padrão store + sync; shadcn/ui completo; Sonner para toasts.
• Vitest com teste de contrato (TDD); Prisma + Postgres em Docker.

Consequências

• Positivas: documentação, validação e tipos a partir de uma única fonte (Zod); base testável.
• Custos: manter o spec/paths à mão (corpos vêm do Zod; rotas/summaries são escritas).

Tarefas e subtarefas

1. OpenAPI: document.ts, domains/*, schemas Zod, rotas /openapi.json e /reference.
2. Tipos: gen-openapi-types.ts (pnpm openapi) + cliente openapi-fetch.
3. Zustand: store tasks + sync + página demo.
4. shadcn/ui completo em packages/ui; Sonner no layout.
5. Vitest + teste de contrato.
6. Prisma + docker-compose + seed + scripts db:*.

Quiz de decisões

Tema: Contrato de API (OpenAPI)

P1. Como gerar o spec OpenAPI?

• ( ) A) Biblioteca zod-to-openapi (@asteasolutions/...).
• (X) B) z.toJSONSchema() NATIVO do Zod 4 + paths escritos à mão por domínio.
• ( ) C) YAML/JSON mantido à mão.

Justificativa: padrão dos projetos de referência — zero biblioteca intermediária, Zod como fonte única, infra enxuta. Cada domínio exporta { tag, schemas, paths }.

P2. Como o front consome a API?

• ( ) A) fetch cru com tipos escritos à mão.
• (X) B) Tipos gerados do spec (openapi-typescript) + cliente openapi-fetch.
• ( ) C) tRPC.

Justificativa: o manifesto exige tipos gerados — o front nunca escreve tipos da API à mão. pnpm openapi materializa o spec e regenera lib/shared/api-types.ts.

Tema: Estado

P3. Padrão de store?

• (X) A) stores/[nome]/{store.ts, sync.tsx} (manifesto, inegociável).
• ( ) B) Hooks soltos / Context.

Justificativa: regra do manifesto. A store tasks consome a API tipada; o sync.tsx carrega os dados ao montar.

Tema: Testes

P4. Estratégia de testes?

• (X) A) Desenvolvimento orientado a testes: schema Zod → teste de contrato → implementação.
• ( ) B) Testes só no fim, manuais.

Justificativa: manifesto/architecture/08. O teste de contrato (schemas.test.ts) é o ponto de partida — valida o contrato antes da rota.

Tema: Banco

P5. Qual versão do Prisma?

• ( ) A) Prisma 6 (url no schema, fluxo clássico).
• (X) B) Prisma 7 (última versão): prisma.config.ts + driver adapter @prisma/adapter-pg
  • o novo generator prisma-client.

Justificativa: pedido explícito de usar a última versão. A v7 tira a url do schema (vai para prisma.config.ts), usa driver adapter (pg) e gera o client em pasta própria (generated/).

P6. Como organizar o schema?

• ( ) A) Um único schema.prisma.
• (X) B) Schema multi-arquivo por domínio (prismaSchemaFolder): prisma/schema.prisma carrega generator + datasource; cada domínio vive em prisma/models/<dominio>.prisma.

Justificativa: pedido de “controle de domínios”. Cada domínio cresce no seu arquivo (ex.: models/tasks.prisma, models/users.prisma), com relações entre eles. Espelha a separação de domínios da API/OpenAPI.

Pós-plan

• Riscos: paths do OpenAPI mantidos à mão podem divergir de summaries; os corpos não divergem (vêm do Zod).
• Dependências: Docker para o banco.
• Fora de escopo: dados reais, auth (ADRs futuras).