spec-first-claude 0.2.0 → 0.4.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/README.md +144 -147
- package/bin/cli.js +52 -52
- package/lib/init.js +89 -93
- package/package.json +24 -23
- package/templates/.ai/memory/napkin.md +68 -68
- package/templates/.claude/agents/backend-coder.md +215 -215
- package/templates/.claude/agents/db-coder.md +165 -165
- package/templates/.claude/agents/doc-writer.md +51 -51
- package/templates/.claude/agents/frontend-coder.md +222 -222
- package/templates/.claude/agents/infra-coder.md +341 -341
- package/templates/.claude/agents/reviewer.md +99 -99
- package/templates/.claude/agents/security-reviewer.md +153 -153
- package/templates/.claude/commands/design.md +107 -107
- package/templates/.claude/commands/dev.md +189 -167
- package/templates/.claude/commands/extract.md +137 -137
- package/templates/.claude/commands/feature.md +60 -60
- package/templates/.claude/commands/merge-delta.md +70 -70
- package/templates/.claude/commands/plan.md +86 -86
- package/templates/.claude/commands/{pausar.md → session-finish.md} +83 -83
- package/templates/.claude/commands/setup-projeto.md +68 -68
- package/templates/.claude/settings.local.json +6 -6
- package/templates/CLAUDE.md +198 -199
- package/templates/docs/Desenvolvimento/rules.md +229 -229
- package/templates/docs/_templates/estrutura/ADRs.template.md +91 -91
- package/templates/docs/_templates/estrutura/API.template.md +144 -144
- package/templates/docs/_templates/estrutura/Arquitetura.template.md +82 -82
- package/templates/docs/_templates/estrutura/Infraestrutura.template.md +104 -104
- package/templates/docs/_templates/estrutura/Modelo_Dados.template.md +99 -99
- package/templates/docs/_templates/estrutura/Seguranca.template.md +138 -138
- package/templates/docs/_templates/estrutura/Stack.template.md +78 -78
- package/templates/docs/_templates/estrutura/Visao.template.md +82 -82
- package/templates/docs/_templates/feature/Progresso.template.md +136 -136
- package/templates/docs/_templates/feature/backlog-extraido.template.md +154 -154
- package/templates/docs/_templates/feature/context.template.md +42 -42
- package/templates/docs/_templates/feature/extract-log.template.md +38 -38
- package/templates/docs/_templates/feature/projetos.template.yaml +73 -73
- package/templates/docs/_templates/global/progresso_global.template.md +57 -57
|
@@ -1,144 +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
|
-
| | | | |
|
|
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
|
+
| | | | |
|
|
@@ -1,82 +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
|
-
| | | | |
|
|
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
|
+
| | | | |
|
|
@@ -1,104 +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
|
-
| | | | |
|
|
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
|
+
| | | | |
|