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.
- package/bin/cli.js +52 -0
- package/package.json +25 -0
- package/templates/.ai/memory/napkin.md +68 -0
- package/templates/.claude/agents/backend-coder.md +215 -0
- package/templates/.claude/agents/db-coder.md +165 -0
- package/templates/.claude/agents/doc-writer.md +51 -0
- package/templates/.claude/agents/frontend-coder.md +222 -0
- package/templates/.claude/agents/infra-coder.md +341 -0
- package/templates/.claude/agents/reviewer.md +99 -0
- package/templates/.claude/agents/security-reviewer.md +153 -0
- package/templates/.claude/commands/design.md +107 -0
- package/templates/.claude/commands/dev.md +167 -0
- package/templates/.claude/commands/discovery.md +405 -0
- package/templates/.claude/commands/extract.md +137 -0
- package/templates/.claude/commands/feature.md +60 -0
- package/templates/.claude/commands/merge-delta.md +70 -0
- package/templates/.claude/commands/pausar.md +83 -0
- package/templates/.claude/commands/plan.md +86 -0
- package/templates/.claude/commands/setup-projeto.md +68 -0
- package/templates/.claude/settings.local.json +6 -0
- package/templates/CLAUDE.md +199 -0
- package/templates/docs/Desenvolvimento/.gitkeep +0 -0
- package/templates/docs/Desenvolvimento/rules.md +229 -0
- package/templates/docs/Estrutura/.gitkeep +0 -0
- package/templates/docs/PM/.gitkeep +0 -0
- package/templates/docs/PM/setup_projeto/.gitkeep +0 -0
- package/templates/docs/_templates/estrutura/ADRs.template.md +91 -0
- package/templates/docs/_templates/estrutura/API.template.md +144 -0
- package/templates/docs/_templates/estrutura/Arquitetura.template.md +82 -0
- package/templates/docs/_templates/estrutura/Infraestrutura.template.md +104 -0
- package/templates/docs/_templates/estrutura/Modelo_Dados.template.md +99 -0
- package/templates/docs/_templates/estrutura/Seguranca.template.md +138 -0
- package/templates/docs/_templates/estrutura/Stack.template.md +78 -0
- package/templates/docs/_templates/estrutura/Visao.template.md +82 -0
- package/templates/docs/_templates/feature/PRD.template.md +256 -0
- package/templates/docs/_templates/feature/Progresso.template.md +136 -0
- package/templates/docs/_templates/feature/TRD.template.md +200 -0
- package/templates/docs/_templates/feature/backlog-extraido.template.md +154 -0
- package/templates/docs/_templates/feature/context.template.md +42 -0
- package/templates/docs/_templates/feature/extract-log.template.md +38 -0
- package/templates/docs/_templates/feature/projetos.template.yaml +73 -0
- package/templates/docs/_templates/feature/sdd.template.md +372 -0
- package/templates/docs/_templates/feature/tasks.template.md +115 -0
- 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
|
+
| | | | |
|