spec-first-claude 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/bin/cli.js +52 -0
  2. package/package.json +25 -0
  3. package/templates/.ai/memory/napkin.md +68 -0
  4. package/templates/.claude/agents/backend-coder.md +215 -0
  5. package/templates/.claude/agents/db-coder.md +165 -0
  6. package/templates/.claude/agents/doc-writer.md +51 -0
  7. package/templates/.claude/agents/frontend-coder.md +222 -0
  8. package/templates/.claude/agents/infra-coder.md +341 -0
  9. package/templates/.claude/agents/reviewer.md +99 -0
  10. package/templates/.claude/agents/security-reviewer.md +153 -0
  11. package/templates/.claude/commands/design.md +107 -0
  12. package/templates/.claude/commands/dev.md +167 -0
  13. package/templates/.claude/commands/discovery.md +405 -0
  14. package/templates/.claude/commands/extract.md +137 -0
  15. package/templates/.claude/commands/feature.md +60 -0
  16. package/templates/.claude/commands/merge-delta.md +70 -0
  17. package/templates/.claude/commands/pausar.md +83 -0
  18. package/templates/.claude/commands/plan.md +86 -0
  19. package/templates/.claude/commands/setup-projeto.md +68 -0
  20. package/templates/.claude/settings.local.json +6 -0
  21. package/templates/CLAUDE.md +199 -0
  22. package/templates/docs/Desenvolvimento/.gitkeep +0 -0
  23. package/templates/docs/Desenvolvimento/rules.md +229 -0
  24. package/templates/docs/Estrutura/.gitkeep +0 -0
  25. package/templates/docs/PM/.gitkeep +0 -0
  26. package/templates/docs/PM/setup_projeto/.gitkeep +0 -0
  27. package/templates/docs/_templates/estrutura/ADRs.template.md +91 -0
  28. package/templates/docs/_templates/estrutura/API.template.md +144 -0
  29. package/templates/docs/_templates/estrutura/Arquitetura.template.md +82 -0
  30. package/templates/docs/_templates/estrutura/Infraestrutura.template.md +104 -0
  31. package/templates/docs/_templates/estrutura/Modelo_Dados.template.md +99 -0
  32. package/templates/docs/_templates/estrutura/Seguranca.template.md +138 -0
  33. package/templates/docs/_templates/estrutura/Stack.template.md +78 -0
  34. package/templates/docs/_templates/estrutura/Visao.template.md +82 -0
  35. package/templates/docs/_templates/feature/PRD.template.md +256 -0
  36. package/templates/docs/_templates/feature/Progresso.template.md +136 -0
  37. package/templates/docs/_templates/feature/TRD.template.md +200 -0
  38. package/templates/docs/_templates/feature/backlog-extraido.template.md +154 -0
  39. package/templates/docs/_templates/feature/context.template.md +42 -0
  40. package/templates/docs/_templates/feature/extract-log.template.md +38 -0
  41. package/templates/docs/_templates/feature/projetos.template.yaml +73 -0
  42. package/templates/docs/_templates/feature/sdd.template.md +372 -0
  43. package/templates/docs/_templates/feature/tasks.template.md +115 -0
  44. package/templates/docs/_templates/global/progresso_global.template.md +57 -0
@@ -0,0 +1,91 @@
1
+ # ADRs — Architecture Decision Records
2
+
3
+ > Registro de decisões arquiteturais com contexto, alternativas e consequências.
4
+ > Cada decisão é imutável após aceita. Novas decisões podem substituir anteriores.
5
+
6
+ ---
7
+
8
+ <!--
9
+ =============================================================================
10
+ INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
11
+ =============================================================================
12
+
13
+ ORIGEM: Criado pelo /setup-projeto com ADRs iniciais (stack, arquitetura base).
14
+ ATUALIZAÇÃO: Novas ADRs adicionadas quando:
15
+ - /setup-projeto define stack e arquitetura (ADRs iniciais)
16
+ - /design gera SDD §2 com decisões de design significativas
17
+ - /merge-delta detecta mudança de stack ou padrão
18
+ - Usuário toma decisão que impacta arquitetura
19
+
20
+ COMO GERAR:
21
+ 1. Para cada decisão significativa, criar ADR com TODOS os campos
22
+ 2. Contexto: POR QUE essa decisão foi necessária (não apenas "precisávamos")
23
+ 3. Alternativas: OBRIGATÓRIO listar ao menos 1 alternativa (com motivo da rejeição)
24
+ 4. Consequências: o que MUDA por causa da decisão (positivo E negativo)
25
+
26
+ REGRAS:
27
+ - IDs sequenciais: ADR-001, ADR-002... nunca reutilizar
28
+ - NUNCA editar ADR com status "aceita" — criar nova com "substituída por ADR-XXX"
29
+ - Status "proposta" = ainda em discussão, não implementar até aceitar
30
+ - Toda mudança de stack, banco, framework DEVE ter ADR
31
+ - ADRs são APPEND-ONLY — histórico importa
32
+
33
+ QUANDO CRIAR ADR:
34
+ - Escolha de tecnologia/framework
35
+ - Mudança de padrão de design
36
+ - Decisão de infra (cloud provider, DB engine)
37
+ - Trade-off significativo (performance vs simplicidade, etc.)
38
+
39
+ QUANDO NÃO CRIAR ADR:
40
+ - Escolha de nome de variável
41
+ - Implementação seguindo padrão já definido
42
+ - Bug fix
43
+ - Refactor sem mudança de interface
44
+
45
+ =============================================================================
46
+ -->
47
+
48
+ ## Índice
49
+
50
+ | ADR | Título | Status | Data |
51
+ |-----|--------|--------|------|
52
+ | ADR-001 | {{Título}} | proposta / aceita / substituída / descartada | |
53
+
54
+ ## Formato
55
+
56
+ Cada ADR segue este modelo:
57
+
58
+ ```markdown
59
+ ### ADR-NNN: Título da Decisão
60
+ - **Status**: proposta | aceita | substituída por ADR-XXX | descartada
61
+ - **Data**: YYYY-MM-DD
62
+ - **Contexto**: Por que essa decisão foi necessária?
63
+ - **Decisão**: O que decidimos?
64
+ - **Alternativas consideradas**:
65
+ 1. Alternativa A — rejeitada porque...
66
+ 2. Alternativa B — rejeitada porque...
67
+ - **Consequências**:
68
+ - Positivas: ...
69
+ - Negativas: ...
70
+ - Riscos: ...
71
+ ```
72
+
73
+ ---
74
+
75
+ ## Decisões
76
+
77
+ ### ADR-001: {{Título}}
78
+ - **Status**: aceita
79
+ - **Data**:
80
+ - **Contexto**:
81
+ - **Decisão**:
82
+ - **Alternativas consideradas**:
83
+ 1. —
84
+ - **Consequências**:
85
+ - Positivas:
86
+ - Negativas:
87
+ - Riscos:
88
+
89
+ ---
90
+
91
+ > **Regra**: ADRs aceitas são imutáveis. Para reverter uma decisão, crie nova ADR com status "substituída por ADR-XXX" na ADR original.
@@ -0,0 +1,144 @@
1
+ # Convenções de API
2
+
3
+ > Padrões globais para todas as APIs do sistema: versionamento, autenticação, paginação, erros.
4
+
5
+ ---
6
+
7
+ <!--
8
+ =============================================================================
9
+ INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
+ =============================================================================
11
+
12
+ ORIGEM: Gerado pelo /setup-projeto a partir do TRD §5.
13
+ ATUALIZAÇÃO: /merge-delta quando features adicionam endpoints (Delta Specs do SDD §5 e §11).
14
+
15
+ COMO GERAR:
16
+ 1. Ler TRD §5 (Convenções de API) — padrão geral, versionamento, autenticação
17
+ 2. Padrão geral e convenções são FIXOS após setup — definidos uma vez
18
+ 3. Catálogo de endpoints é DINÂMICO — cresce a cada feature
19
+ 4. Formatos de paginação, filtro e erro são FIXOS — toda API segue
20
+
21
+ REGRAS:
22
+ - Convenções são LEI — todo SDD §5 (endpoints) deve seguir estes padrões
23
+ - Catálogo de endpoints atualizado a cada merge-delta
24
+ - Mudanças em convenções (raro) devem gerar ADR
25
+ - Rate limiting definido por categoria de endpoint, não individual
26
+
27
+ =============================================================================
28
+ -->
29
+
30
+ ## Padrão Geral
31
+
32
+ | Aspecto | Padrão |
33
+ |---------|--------|
34
+ | Estilo | <!-- REST / GraphQL / gRPC --> |
35
+ | Formato | <!-- JSON / Protobuf --> |
36
+ | Versionamento | <!-- /api/v1/ no path? Header? --> |
37
+ | Autenticação | <!-- Bearer JWT? API Key? --> |
38
+ | Content-Type | <!-- application/json --> |
39
+ | Encoding | <!-- UTF-8 --> |
40
+
41
+ ## Convenções de Rotas
42
+
43
+ | Operação | Método | Rota | Exemplo |
44
+ |----------|--------|------|---------|
45
+ | Listar | GET | `/api/v1/{recurso}` | |
46
+ | Detalhar | GET | `/api/v1/{recurso}/:id` | |
47
+ | Criar | POST | `/api/v1/{recurso}` | |
48
+ | Atualizar completo | PUT | `/api/v1/{recurso}/:id` | |
49
+ | Atualizar parcial | PATCH | `/api/v1/{recurso}/:id` | |
50
+ | Remover/Inativar | DELETE | `/api/v1/{recurso}/:id` | |
51
+
52
+ ### Convenções de nomenclatura
53
+ | Regra | Exemplo |
54
+ |-------|---------|
55
+ | Recursos no plural, kebab-case | `/api/v1/order-items` |
56
+ | Ações não-CRUD como sub-recurso | `/api/v1/users/:id/activate` |
57
+ | Filtros via query params | `/api/v1/users?status=active` |
58
+ | Relações aninhadas (max 2 níveis) | `/api/v1/users/:id/orders` |
59
+
60
+ ## Paginação
61
+
62
+ ```json
63
+ {
64
+ "data": [],
65
+ "meta": {
66
+ "page": 1,
67
+ "per_page": 20,
68
+ "total": 0,
69
+ "total_pages": 0
70
+ }
71
+ }
72
+ ```
73
+
74
+ Query params: `?page=1&per_page=20&sort=campo&order=asc`
75
+
76
+ | Parâmetro | Default | Máximo | Descrição |
77
+ |-----------|---------|--------|-----------|
78
+ | `page` | 1 | — | Página atual |
79
+ | `per_page` | 20 | <!-- Ex: 100 --> | Itens por página |
80
+ | `sort` | — | — | Campo para ordenação |
81
+ | `order` | `asc` | — | `asc` ou `desc` |
82
+
83
+ ## Filtros
84
+
85
+ Query params: `?busca=termo&campo=valor`
86
+
87
+ | Tipo de filtro | Formato | Exemplo |
88
+ |----------------|---------|---------|
89
+ | Igualdade | `?campo=valor` | `?status=ativo` |
90
+ | Busca textual | `?busca=termo` | `?busca=joao` |
91
+ | Range de data | `?de=YYYY-MM-DD&ate=YYYY-MM-DD` | `?de=2026-01-01&ate=2026-12-31` |
92
+ | Múltiplos valores | `?campo=a,b,c` | `?status=ativo,pendente` |
93
+
94
+ ## Respostas de Erro
95
+
96
+ ```json
97
+ {
98
+ "error": {
99
+ "code": "ERROR_CODE",
100
+ "message": "Mensagem legível para o usuário",
101
+ "details": [
102
+ { "field": "campo", "message": "Detalhe do erro" }
103
+ ]
104
+ }
105
+ }
106
+ ```
107
+
108
+ ### Códigos HTTP
109
+
110
+ | Código | Quando usar | Exemplo |
111
+ |--------|-------------|---------|
112
+ | 200 | Sucesso (GET, PUT, PATCH) | Recurso retornado/atualizado |
113
+ | 201 | Criado com sucesso (POST) | Recurso criado, retorna o objeto |
114
+ | 204 | Sucesso sem conteúdo (DELETE) | Recurso removido |
115
+ | 400 | Dados inválidos (formato) | JSON malformado |
116
+ | 401 | Não autenticado | Token ausente ou expirado |
117
+ | 403 | Sem permissão | Papel sem acesso ao recurso |
118
+ | 404 | Recurso não encontrado | ID inexistente |
119
+ | 409 | Conflito (duplicidade) | Email já cadastrado |
120
+ | 422 | Validação de negócio falhou | CPF inválido, regra RN-XXX violada |
121
+ | 429 | Rate limit excedido | Muitas requisições |
122
+ | 500 | Erro interno | Bug não tratado |
123
+
124
+ ### Códigos de erro do domínio
125
+
126
+ | Código | Descrição | HTTP |
127
+ |--------|-----------|------|
128
+ | <!-- Ex: DUPLICATE_EMAIL --> | <!-- Email já cadastrado --> | <!-- 409 --> |
129
+
130
+ ## Catálogo de Endpoints
131
+
132
+ > Atualizado a cada feature via /merge-delta. Visão consolidada de todas as APIs.
133
+
134
+ | Método | Rota | Feature | Descrição |
135
+ |--------|------|---------|-----------|
136
+ | | | | |
137
+
138
+ ---
139
+
140
+ ## Changelog
141
+
142
+ | Data | Feature | Tipo | Descrição |
143
+ |------|---------|------|-----------|
144
+ | | | | |
@@ -0,0 +1,82 @@
1
+ # Arquitetura
2
+
3
+ > C4 Níveis 2-3 — Containers, componentes, comunicação e padrões adotados.
4
+
5
+ ---
6
+
7
+ <!--
8
+ =============================================================================
9
+ INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
+ =============================================================================
11
+
12
+ ORIGEM: Gerado pelo /setup-projeto a partir do TRD §3.
13
+ ATUALIZAÇÃO: /merge-delta quando features adicionam containers, componentes significativos ou novos padrões.
14
+
15
+ COMO GERAR:
16
+ 1. Ler TRD §3 (Arquitetura) — containers, padrões de comunicação, padrões de design
17
+ 2. Ler Stack.md — tecnologias já definidas para cada container
18
+ 3. Criar diagrama textual C4 Nível 2 (containers e suas conexões)
19
+ 4. Para cada container: listar componentes internos (C4 Nível 3)
20
+ 5. Documentar padrões de comunicação (sync/async, protocolos)
21
+ 6. Documentar padrões de design com justificativa
22
+
23
+ REGRAS:
24
+ - Diagrama deve mostrar TODOS os containers e suas conexões
25
+ - Cada container deve ter: tecnologia, responsabilidade, porta
26
+ - Padrões de design precisam de justificativa (não apenas nome)
27
+ - Se o sistema usa filas/eventos: documentar tópicos e consumers
28
+ - Componentes são internos ao container — não confundir com containers
29
+
30
+ =============================================================================
31
+ -->
32
+
33
+ ## Diagrama de Containers (C4 Nível 2)
34
+
35
+ ```
36
+ <!-- Representação textual dos containers e suas conexões -->
37
+ <!-- Usar formato: [Container] --protocolo--> [Container] -->
38
+ ```
39
+
40
+ ## Containers
41
+
42
+ | Container | Tecnologia | Responsabilidade | Porta | Comunicação |
43
+ |-----------|-----------|-----------------|-------|-------------|
44
+ | | | | | |
45
+
46
+ ## Componentes Principais (C4 Nível 3)
47
+
48
+ <!-- Repetir esta seção para cada container que tenha componentes internos relevantes -->
49
+
50
+ ### {{Container}}
51
+
52
+ | Componente | Responsabilidade | Dependências internas | Dependências externas |
53
+ |------------|-----------------|----------------------|----------------------|
54
+ | | | | |
55
+
56
+ ## Padrões de Comunicação
57
+
58
+ ### Síncrona (request/response)
59
+
60
+ | De | Para | Protocolo | Formato | Observações |
61
+ |----|------|-----------|---------|-------------|
62
+ | | | | | |
63
+
64
+ ### Assíncrona (eventos/filas)
65
+
66
+ | Produtor | Tópico/Fila | Consumer | Formato | Garantia |
67
+ |----------|-------------|----------|---------|----------|
68
+ | | | | | at-least-once / exactly-once |
69
+
70
+ ## Padrões de Design Adotados
71
+
72
+ | Padrão | Onde é usado | Justificativa | Ref ADR |
73
+ |--------|-------------|---------------|---------|
74
+ | | | | |
75
+
76
+ ---
77
+
78
+ ## Changelog
79
+
80
+ | Data | Feature | Tipo | Descrição |
81
+ |------|---------|------|-----------|
82
+ | | | | |
@@ -0,0 +1,104 @@
1
+ # Infraestrutura
2
+
3
+ > Ambientes, deploy, CI/CD, variáveis de ambiente, domínios e estratégia de rollback.
4
+
5
+ ---
6
+
7
+ <!--
8
+ =============================================================================
9
+ INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
+ =============================================================================
11
+
12
+ ORIGEM: Gerado pelo /setup-projeto a partir do TRD §6.
13
+ ATUALIZAÇÃO: /merge-delta quando features adicionam variáveis de ambiente, serviços ou mudam infra.
14
+
15
+ COMO GERAR:
16
+ 1. Ler TRD §6 (Infraestrutura) — ambientes, deploy, CI/CD
17
+ 2. Listar TODOS os ambientes com URLs e propósitos
18
+ 3. Pipeline CI/CD deve ser concreto (passos reais, não genéricos)
19
+ 4. Variáveis de ambiente: NUNCA colocar valores reais (só exemplos)
20
+ 5. Estratégia de rollback é OBRIGATÓRIA
21
+
22
+ REGRAS:
23
+ - Variáveis de ambiente com valores reais NÃO vão pro repositório
24
+ - Cada variável precisa de descrição (não só o nome)
25
+ - Pipeline CI/CD deve ter passos claros e ferramentas definidas
26
+ - Rollback strategy obrigatória — "como voltar se der errado?"
27
+ - Novas variáveis adicionadas via merge-delta devem entrar na tabela
28
+
29
+ =============================================================================
30
+ -->
31
+
32
+ ## Ambientes
33
+
34
+ | Ambiente | URL | Banco | Propósito | Branch |
35
+ |----------|-----|-------|-----------|--------|
36
+ | Local | `localhost:{{PORT}}` | local | Desenvolvimento | qualquer |
37
+ | Staging | | | Testes e homologação | develop |
38
+ | Produção | | | Usuários finais | main |
39
+
40
+ ## Deploy
41
+
42
+ ### Estratégia
43
+
44
+ | Aspecto | Decisão |
45
+ |---------|---------|
46
+ | Plataforma | <!-- Docker? Serverless? VPS? Cloud provider? --> |
47
+ | Orquestração | <!-- Kubernetes? ECS? PM2? --> |
48
+ | Build | <!-- Docker multi-stage? Build nativo? --> |
49
+ | Estratégia de deploy | <!-- Rolling? Blue-green? Canary? --> |
50
+
51
+ ### Pipeline CI/CD
52
+
53
+ ```
54
+ push → lint → test → build → deploy(staging) → aprovação → deploy(prod)
55
+ ```
56
+
57
+ | Etapa | Ferramenta | Trigger | Timeout |
58
+ |-------|-----------|---------|---------|
59
+ | Lint | <!-- eslint, ruff --> | push | |
60
+ | Testes | <!-- jest, pytest --> | push | |
61
+ | Build | <!-- docker build --> | push em main/develop | |
62
+ | Deploy staging | <!-- CD tool --> | push em develop | |
63
+ | Deploy produção | <!-- CD tool --> | aprovação manual | |
64
+
65
+ ### Rollback
66
+
67
+ | Cenário | Procedimento | Responsável |
68
+ |---------|-------------|-------------|
69
+ | Bug em produção | <!-- Reverter deploy? Hotfix? --> | |
70
+ | Migration com erro | <!-- Rollback da migration? --> | |
71
+ | Serviço externo fora | <!-- Fallback? Circuit breaker? --> | |
72
+
73
+ ## Variáveis de Ambiente
74
+
75
+ > NUNCA colocar valores reais aqui. Apenas nomes, descrição e exemplos.
76
+
77
+ | Variável | Ambientes | Obrigatória | Descrição | Exemplo |
78
+ |----------|-----------|-------------|-----------|---------|
79
+ | `DATABASE_URL` | todos | sim | Conexão com banco | `postgres://user:pass@host:5432/db` |
80
+ | `JWT_SECRET` | todos | sim | Chave de assinatura JWT | `sua-chave-secreta-aqui` |
81
+ | `NODE_ENV` | todos | sim | Ambiente atual | `development` / `production` |
82
+
83
+ ## Domínios e DNS
84
+
85
+ | Domínio | Aponta para | Certificado | Gerenciado por |
86
+ |---------|-------------|-------------|----------------|
87
+ | | | <!-- Let's Encrypt? AWS ACM? --> | |
88
+
89
+ ## Monitoramento e Observabilidade
90
+
91
+ | Aspecto | Ferramenta | O que monitora |
92
+ |---------|-----------|----------------|
93
+ | Logs | <!-- Ex: CloudWatch, Datadog --> | |
94
+ | APM | <!-- Ex: New Relic, Sentry --> | |
95
+ | Uptime | <!-- Ex: Pingdom, UptimeRobot --> | |
96
+ | Alertas | <!-- Ex: PagerDuty, Slack --> | |
97
+
98
+ ---
99
+
100
+ ## Changelog
101
+
102
+ | Data | Feature | Tipo | Descrição |
103
+ |------|---------|------|-----------|
104
+ | | | | |
@@ -0,0 +1,99 @@
1
+ # Modelo de Dados
2
+
3
+ > Schema completo, relações, índices, convenções de nomenclatura e estratégia de migrations.
4
+
5
+ ---
6
+
7
+ <!--
8
+ =============================================================================
9
+ INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
+ =============================================================================
11
+
12
+ ORIGEM: Gerado pelo /setup-projeto a partir do TRD §4.
13
+ ATUALIZAÇÃO: /merge-delta a cada feature que adiciona/altera tabelas (Delta Specs do SDD §3 e §11).
14
+
15
+ COMO GERAR:
16
+ 1. Ler TRD §4 (Modelo de Dados Base) — tabelas iniciais, convenções
17
+ 2. Gerar diagrama ER textual com TODAS as relações
18
+ 3. Para cada tabela: campos com tipos EXATOS (varchar(255), não "string")
19
+ 4. Convenções de nomenclatura são FIXAS após setup — não mudam por feature
20
+ 5. Estratégia de migrations deve ser concreta (ferramenta, naming, rollback)
21
+
22
+ REGRAS:
23
+ - Tipos devem ser do banco escolhido (PostgreSQL, MySQL, etc.), não genéricos
24
+ - Toda FK deve ter ON DELETE/ON UPDATE definido
25
+ - Índices precisam de justificativa (query que justifica)
26
+ - Convenções definidas aqui são LEI — SDDs e tasks seguem à risca
27
+ - Diagrama ER deve ser atualizado a cada merge-delta
28
+
29
+ =============================================================================
30
+ -->
31
+
32
+ ## Diagrama ER
33
+
34
+ ```
35
+ <!-- Representação textual do ER -->
36
+ <!-- Formato: [tabela_a] 1---N [tabela_b] (campo_fk) -->
37
+ ```
38
+
39
+ ## Convenções de Nomenclatura
40
+
41
+ | Elemento | Convenção | Exemplo |
42
+ |----------|-----------|---------|
43
+ | Tabelas | snake_case, plural | `clientes`, `pedidos` |
44
+ | Colunas | snake_case | `nome_completo`, `criado_em` |
45
+ | PKs | `id` (UUID ou SERIAL) | `id UUID PRIMARY KEY DEFAULT gen_random_uuid()` |
46
+ | FKs | `{tabela_singular}_id` | `cliente_id`, `cidade_id` |
47
+ | Índices | `idx_{tabela}_{colunas}` | `idx_clientes_cpf` |
48
+ | Unique | `uq_{tabela}_{colunas}` | `uq_clientes_email` |
49
+ | Timestamps | `criado_em`, `atualizado_em` | `TIMESTAMPTZ NOT NULL DEFAULT now()` |
50
+ | Soft delete | `ativo` (boolean) | `ativo BOOLEAN DEFAULT true` |
51
+ | Auditoria | `criado_por`, `atualizado_por` | `UUID REFERENCES usuarios(id)` |
52
+
53
+ ## Catálogo de Tabelas
54
+
55
+ <!-- Repetir bloco para cada tabela -->
56
+
57
+ ### {{tabela}}
58
+
59
+ > Descrição breve da tabela.
60
+
61
+ | Coluna | Tipo | Nullable | Default | Constraint | Descrição |
62
+ |--------|------|----------|---------|------------|-----------|
63
+ | | | | | | |
64
+
65
+ **Relações:**
66
+ - `campo_id` → `tabela_ref(id)` — ON DELETE CASCADE / SET NULL / RESTRICT
67
+
68
+ **Índices:**
69
+
70
+ | Nome | Colunas | Tipo | Justificativa |
71
+ |------|---------|------|---------------|
72
+ | | | btree / unique / gin | <!-- Qual query justifica este índice? --> |
73
+
74
+ ## Estratégia de Migrations
75
+
76
+ | Aspecto | Convenção |
77
+ |---------|-----------|
78
+ | Ferramenta | <!-- Ex: knex, prisma, flyway, alembic --> |
79
+ | Nomenclatura | <!-- Ex: 001_create_tabela.sql, YYYYMMDD_descricao --> |
80
+ | Rollback | <!-- Toda migration TEM rollback? Testado como? --> |
81
+ | Execução | <!-- Sequencial? Transacional? --> |
82
+ | Dados existentes | <!-- Como lidar com migrations em tabelas com dados? --> |
83
+
84
+ ## Regras Globais de Dados
85
+
86
+ | Regra | Descrição |
87
+ |-------|-----------|
88
+ | Soft delete | <!-- Todas as tabelas usam? Quais exceções? --> |
89
+ | Auditoria | <!-- criado_por/atualizado_por em todas? --> |
90
+ | Timestamps | <!-- criado_em/atualizado_em obrigatórios? --> |
91
+ | Encoding | <!-- UTF-8? Collation? --> |
92
+
93
+ ---
94
+
95
+ ## Changelog
96
+
97
+ | Data | Feature | Tipo | Descrição |
98
+ |------|---------|------|-----------|
99
+ | | | | |
@@ -0,0 +1,138 @@
1
+ # Segurança
2
+
3
+ > Autenticação, autorização, CORS, rate limiting, LGPD, auditoria e proteção de dados.
4
+
5
+ ---
6
+
7
+ <!--
8
+ =============================================================================
9
+ INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
+ =============================================================================
11
+
12
+ ORIGEM: Gerado pelo /setup-projeto a partir do TRD §7.
13
+ ATUALIZAÇÃO: /merge-delta quando features adicionam permissões, dados pessoais ou políticas.
14
+
15
+ COMO GERAR:
16
+ 1. Ler TRD §7 (Segurança) — autenticação, autorização, CORS, LGPD
17
+ 2. Autenticação: método, expiração, hash, refresh strategy
18
+ 3. Autorização: papéis e matriz de permissões (RBAC/ABAC)
19
+ 4. LGPD: mapear TODOS dados pessoais com base legal
20
+ 5. Auditoria: definir O QUE é logado, ONDE e POR QUANTO TEMPO
21
+
22
+ REGRAS:
23
+ - Matriz de permissões é DINÂMICA — cresce a cada feature (via merge-delta)
24
+ - Dados pessoais da LGPD precisam de base legal ESPECÍFICA
25
+ - Nunca armazenar senhas em texto plano (hash obrigatório)
26
+ - Secrets nunca no código — sempre variáveis de ambiente
27
+ - Rate limiting obrigatório em endpoints públicos (login, registro)
28
+ - Auditoria obrigatória para operações destrutivas (delete, update de dados sensíveis)
29
+
30
+ =============================================================================
31
+ -->
32
+
33
+ ## Autenticação
34
+
35
+ | Aspecto | Implementação |
36
+ |---------|--------------|
37
+ | Método | <!-- JWT? Session? OAuth2? --> |
38
+ | Expiração access token | <!-- Ex: 15min --> |
39
+ | Refresh token | <!-- Existe? Expiração? Rotação? --> |
40
+ | Hash de senha | <!-- bcrypt rounds? argon2? --> |
41
+ | Header | <!-- Authorization: Bearer {token} --> |
42
+ | Armazenamento (client) | <!-- httpOnly cookie? localStorage? --> |
43
+
44
+ ### Fluxo de autenticação
45
+
46
+ ```
47
+ <!-- Descrever o fluxo: login → token → refresh → logout -->
48
+ ```
49
+
50
+ ## Autorização
51
+
52
+ ### Modelo
53
+
54
+ | Aspecto | Decisão |
55
+ |---------|---------|
56
+ | Tipo | <!-- RBAC / ABAC / RBAC + ABAC --> |
57
+ | Onde é verificado | <!-- Middleware? Decorator? Service? --> |
58
+ | Granularidade | <!-- Por rota? Por recurso? Por campo? --> |
59
+
60
+ ### Papéis
61
+
62
+ | Papel | Descrição | Herda de |
63
+ |-------|-----------|----------|
64
+ | | | <!-- Hierarquia: admin herda de user? --> |
65
+
66
+ ### Matriz de Permissões
67
+
68
+ > Atualizada a cada feature via /merge-delta.
69
+
70
+ | Recurso | Ação | {{role_1}} | {{role_2}} | {{role_N}} |
71
+ |---------|------|------------|------------|------------|
72
+ | | criar | | | |
73
+ | | ler | | | |
74
+ | | editar | | | |
75
+ | | deletar | | | |
76
+
77
+ ## CORS
78
+
79
+ | Aspecto | Configuração |
80
+ |---------|-------------|
81
+ | Allowed Origins | <!-- Configurável por ambiente --> |
82
+ | Allowed Methods | `GET, POST, PUT, PATCH, DELETE` |
83
+ | Allowed Headers | `Authorization, Content-Type` |
84
+ | Credentials | <!-- true/false --> |
85
+ | Max Age | <!-- Preflight cache em segundos --> |
86
+
87
+ ## Rate Limiting
88
+
89
+ | Categoria | Limite | Janela | Resposta |
90
+ |-----------|--------|--------|----------|
91
+ | Login/Registro | <!-- Ex: 5 req --> | <!-- Ex: 15min --> | 429 + Retry-After |
92
+ | API autenticada | <!-- Ex: 100 req --> | <!-- Ex: 1min --> | 429 + Retry-After |
93
+ | API pública | <!-- Ex: 30 req --> | <!-- Ex: 1min --> | 429 + Retry-After |
94
+ | Upload | <!-- Ex: 10 req --> | <!-- Ex: 1h --> | 429 + Retry-After |
95
+
96
+ ## LGPD / Privacidade
97
+
98
+ ### Dados pessoais coletados
99
+
100
+ | Dado | Base legal | Finalidade | Retenção | Criptografado? |
101
+ |------|-----------|------------|----------|----------------|
102
+ | | <!-- Consentimento / Contrato / Legítimo interesse / Obrigação legal --> | | | |
103
+
104
+ ### Direitos do titular
105
+
106
+ | Direito | Implementação | Endpoint/Fluxo |
107
+ |---------|--------------|----------------|
108
+ | Acesso aos dados | | <!-- Como o usuário acessa? --> |
109
+ | Correção | | |
110
+ | Exclusão (right to be forgotten) | | <!-- Soft delete? Hard delete? Anonimização? --> |
111
+ | Portabilidade | | <!-- Formato de exportação? --> |
112
+ | Revogação de consentimento | | |
113
+
114
+ ## Auditoria
115
+
116
+ | O que é logado | Quando | Onde armazena | Retenção |
117
+ |----------------|--------|---------------|----------|
118
+ | Login/Logout | sempre | | |
119
+ | Alteração de dados sensíveis | sempre | | |
120
+ | Operações destrutivas (DELETE) | sempre | | |
121
+ | Falhas de autenticação | sempre | | |
122
+ | Mudanças de permissão | sempre | | |
123
+
124
+ ## Proteção de Dados em Trânsito e Repouso
125
+
126
+ | Aspecto | Implementação |
127
+ |---------|--------------|
128
+ | TLS | <!-- Versão mínima? --> |
129
+ | Dados sensíveis em repouso | <!-- Criptografia? Quais campos? --> |
130
+ | Backup | <!-- Criptografado? Frequência? --> |
131
+
132
+ ---
133
+
134
+ ## Changelog
135
+
136
+ | Data | Feature | Tipo | Descrição |
137
+ |------|---------|------|-----------|
138
+ | | | | |