003 — Plan · Módulo de Tarefas (EXEMPLO)

003 — Plan · Módulo de Tarefas (EXEMPLO)

Data: 2026-05-20

Contexto

Precisamos de um módulo simples de tarefas internas. O foco é validar o fluxo da ADR com um escopo enxuto, usando a stack universal (Next.js App Router, Prisma, Zustand, Zod, Vitest).

Decisão

Construir um módulo tarefas com CRUD, arquivamento lógico e filtro por status. Estado no frontend via Zustand (stores/tarefas/), validação Zod na API, Prisma direto nos services.

Consequências

• Surge a tabela tasks no schema Prisma (primeira migration do projeto).
• Estabelece o padrão de store que os próximos módulos seguirão.

---

Tarefas

• T1 — Modelar Task no Prisma + migration
• T2 — Service + rotas de API (criar/listar/concluir/arquivar) com Zod
• T3 — Store Zustand (stores/tarefas/store.ts + sync.tsx)
• T4 — Tela de lista com filtro (shadcn/ui + Tailwind)
• T5 — Smoke tests da API + testes de service (Vitest)

---

Quiz de decisões

Formato: ( ) alternativa avaliada · (X) escolhida. Alternativas descartadas permanecem como memória técnica — o que é certo está marcado; o resto é contexto do que foi rejeitado e por quê.

Tema: Dados

P1. Como tratar a exclusão de tarefas?

• ( ) A) Exclusão física (DELETE) — simples, mas perde histórico ❌ rejeitada: perde rastreabilidade
• (X) B) Arquivamento lógico (campo archivedAt) — preserva histórico ✅
• ( ) C) Tabela de lixeira separada — overkill para o escopo ❌ rejeitada: over-engineering

Justificativa: arquivamento lógico atende o requisito sem complexidade extra.

P2. Status da tarefa: enum no banco ou string livre?

• (X) A) Enum (OPEN / DONE / ARCHIVED) — integridade e tipagem ✅
• ( ) B) String livre — flexível, mas sujeito a erro ❌ rejeitada: quebra tipagem total

Tema: API

P3. Validação de entrada?

• (X) A) Zod em todo input (princípio 7) ✅
• ( ) B) Validar só no frontend ❌ rejeitada: nunca confiar no cliente

Tema: Frontend

P4. Onde mora a lógica de estado da lista?

• (X) A) Store Zustand stores/tarefas/ (store.ts + sync.tsx) ✅ — padrão obrigatório
• ( ) B) useState no componente ❌ rejeitada: lógica de negócio não vive em componente

Tema: Testes

P5. Estratégia de teste mínima?

• (X) A) Smoke da API + testes de service no Vitest ✅
• ( ) B) Só teste manual ❌ rejeitada: desenvolvimento é guiado a testes (princípio 8)

---

Pós-plan

Riscos: baixo — escopo pequeno, sem integrações. Dependências: primeira migration do projeto (define o setup do Prisma). Fora de escopo: etiquetas, prioridade, notificações, permissões. Critério de aceite: criar/listar/concluir/arquivar funcionando, filtro por status, smoke da API verde, validações lint/typecheck/build passando.