spec-first-copilot 0.7.0-beta.1 → 0.7.0

package/templates/.github/templates/estrutura/conventions.template.md

@@ -1,212 +1,214 @@
-# Convenções
-
-> Regras transversais do sistema: autenticação, autorização, CORS, rate limiting,
-> LGPD, auditoria, variáveis de ambiente, monitoramento, códigos de erro de domínio
-> e versionamento de dependências. Padrões que todo código segue.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-PAPEL: Síntese cross-feature de regras transversais do sistema.
-Fonte única pra "qual é o padrão de auth/authz/LGPD/logs/env vars neste projeto?".
-Features consultam este doc pra seguir padrão; quando precisam mudar, fazem via SDD §11.
-
-ORIGEM (first-run, via /sf-design):
-- SDD §3.5 Segurança → Autenticação, Autorização, CORS, LGPD, Rate Limiting, Auditoria
-- SDD §3.4 Infra → Variáveis de Ambiente, Domínios
-- SDD §3.6 Convenções de API → Códigos de Erro do Domínio (reutilizáveis)
-- SDD §3.7 Monitoramento → Monitoramento e Observabilidade
-- SDD §2 Decisões de Design → Alternativas Tecnológicas Descartadas, Versionamento
-
-ATUALIZAÇÃO (feature): /sf-merge-docs aplica SDD §11 quando feature adiciona
-permissões, papéis, dados pessoais LGPD, variáveis de ambiente, códigos de erro,
-ou altera políticas de retenção/auditoria.
-
-COMO GERAR (first-run):
-1. Ler SDD §3.5 Segurança — autenticação, autorização, CORS, LGPD, rate limiting
-2. Ler SDD §3.4 Infra — variáveis de ambiente, domínios
-3. Ler SDD §3.7 Monitoramento — logs, métricas, tracing, alertas
-4. Ler SDD §3.6 Convenções de API — códigos de erro globais
-5. Ler SDD §2 Decisões — alternativas descartadas e versionamento
-6. Autenticação: método, expiração, hash, refresh strategy
-7. Autorização: papéis e matriz de permissões (RBAC/ABAC)
-8. LGPD: mapear TODOS dados pessoais com base legal específica
-9. Auditoria: O QUE é logado, ONDE, POR QUANTO TEMPO
-10. Variáveis de ambiente: NUNCA valores reais, só exemplos
-
-O QUE NÃO VAI AQUI:
-- Rotas, paginação, filtros, catálogo de endpoints → apiContracts.md
-- Containers, ambientes, deploy → architecture.md
-- Entidades, tabelas → domain.md
-
-REGRAS:
-- Matriz de permissões é DINÂMICA — cresce a cada feature (via /sf-merge-docs)
-- Dados pessoais da LGPD precisam de base legal ESPECÍFICA
-- Nunca armazenar senhas em texto plano (hash obrigatório)
-- Secrets nunca no código — sempre variáveis de ambiente
-- Rate limiting obrigatório em endpoints públicos (login, registro)
-- Auditoria obrigatória para operações destrutivas
-- Códigos de erro do domínio são globais — reutilizáveis por múltiplos endpoints
-
-=============================================================================
--->
-
-## Autenticação
-
-| Aspecto | Implementação |
-|---------|--------------|
-| Método | <!-- JWT? Session? OAuth2? --> |
-| Expiração access token | <!-- Ex: 15min --> |
-| Refresh token | <!-- Existe? Expiração? Rotação? --> |
-| Hash de senha | <!-- bcrypt rounds? argon2? --> |
-| Header | <!-- Authorization: Bearer {token} --> |
-| Armazenamento (client) | <!-- httpOnly cookie? localStorage? --> |
-
-### Fluxo de autenticação
-
-```
-<!-- Descrever o fluxo: login → token → refresh → logout -->
-```
-
-## Autorização
-
-### Modelo
-
-| Aspecto | Decisão |
-|---------|---------|
-| Tipo | <!-- RBAC / ABAC / RBAC + ABAC --> |
-| Onde é verificado | <!-- Middleware? Decorator? Service? --> |
-| Granularidade | <!-- Por rota? Por recurso? Por campo? --> |
-
-### Papéis
-
-| Papel | Descrição | Herda de |
-|-------|-----------|----------|
-|       |           | <!-- Hierarquia: admin herda de user? --> |
-
-### Matriz de Permissões
-
-> Atualizada a cada feature via /sf-merge-docs.
-
-| Recurso | Ação | {{role_1}} | {{role_2}} | {{role_N}} |
-|---------|------|------------|------------|------------|
-|         | criar | | | |
-|         | ler | | | |
-|         | editar | | | |
-|         | deletar | | | |
-
-## CORS
-
-| Aspecto | Configuração |
-|---------|-------------|
-| Allowed Origins | <!-- Configurável por ambiente --> |
-| Allowed Methods | `GET, POST, PUT, PATCH, DELETE` |
-| Allowed Headers | `Authorization, Content-Type` |
-| Credentials | <!-- true/false --> |
-| Max Age | <!-- Preflight cache em segundos --> |
-
-## Rate Limiting
-
-| Categoria | Limite | Janela | Resposta |
-|-----------|--------|--------|----------|
-| Login/Registro | <!-- Ex: 5 req --> | <!-- Ex: 15min --> | 429 + Retry-After |
-| API autenticada | <!-- Ex: 100 req --> | <!-- Ex: 1min --> | 429 + Retry-After |
-| API pública | <!-- Ex: 30 req --> | <!-- Ex: 1min --> | 429 + Retry-After |
-| Upload | <!-- Ex: 10 req --> | <!-- Ex: 1h --> | 429 + Retry-After |
-
-## LGPD / Privacidade
-
-### Dados pessoais coletados
-
-| Dado | Base legal | Finalidade | Retenção | Criptografado? |
-|------|-----------|------------|----------|----------------|
-|      | <!-- Consentimento / Contrato / Legítimo interesse / Obrigação legal --> | | | |
-
-### Direitos do titular
-
-| Direito | Implementação | Endpoint/Fluxo |
-|---------|--------------|----------------|
-| Acesso aos dados | | |
-| Correção | | |
-| Exclusão (right to be forgotten) | | <!-- Soft delete? Hard delete? Anonimização? --> |
-| Portabilidade | | <!-- Formato de exportação? --> |
-| Revogação de consentimento | | |
-
-## Auditoria
-
-| O que é logado | Quando | Onde armazena | Retenção |
-|----------------|--------|---------------|----------|
-| Login/Logout | sempre | | |
-| Alteração de dados sensíveis | sempre | | |
-| Operações destrutivas (DELETE) | sempre | | |
-| Falhas de autenticação | sempre | | |
-| Mudanças de permissão | sempre | | |
-
-## Proteção de Dados em Trânsito e Repouso
-
-| Aspecto | Implementação |
-|---------|--------------|
-| TLS | <!-- Versão mínima? --> |
-| Dados sensíveis em repouso | <!-- Criptografia? Quais campos? --> |
-| Backup | <!-- Criptografado? Frequência? --> |
-
-## Variáveis de Ambiente
-
-> NUNCA colocar valores reais aqui. Apenas nomes, descrição e exemplos.
-
-| Variável | Ambientes | Obrigatória | Descrição | Exemplo |
-|----------|-----------|-------------|-----------|---------|
-| `DATABASE_URL` | todos | sim | Conexão com banco | `postgres://user:pass@host:5432/db` |
-| `JWT_SECRET` | todos | sim | Chave de assinatura JWT | `sua-chave-secreta-aqui` |
-| `NODE_ENV` | todos | sim | Ambiente atual | `development` / `production` |
-
-## Domínios e DNS
-
-| Domínio | Aponta para | Certificado | Gerenciado por |
-|---------|-------------|-------------|----------------|
-|         |             | <!-- Let's Encrypt? AWS ACM? --> | |
-
-## Monitoramento e Observabilidade
-
-| Aspecto | Ferramenta | O que monitora |
-|---------|-----------|----------------|
-| Logs | <!-- Ex: CloudWatch, Datadog --> | |
-| APM | <!-- Ex: New Relic, Sentry --> | |
-| Uptime | <!-- Ex: Pingdom, UptimeRobot --> | |
-| Alertas | <!-- Ex: PagerDuty, Slack --> | |
-
-## Códigos de Erro do Domínio
-
-> Códigos reutilizáveis por múltiplos endpoints. Novos códigos são adicionados via /sf-merge-docs.
-
-| Código | Descrição | HTTP padrão |
-|--------|-----------|-------------|
-| <!-- Ex: DUPLICATE_EMAIL --> | <!-- Email já cadastrado --> | <!-- 409 --> |
-
-## Alternativas Tecnológicas Descartadas
-
-> Decisões já tomadas. Se alguém perguntar "por que não usamos X?", a resposta está aqui.
-
-| Tecnologia escolhida | Alternativa considerada | Por que descartamos | Ref decisão |
-|----------------------|------------------------|---------------------|-------------|
-|                      |                        |                     |             |
-
-## Convenções de Versionamento de Dependências
-
-| Aspecto | Convenção |
-|---------|-----------|
-| Versionamento | <!-- Semver? Pinned? --> |
-| Lock files | <!-- package-lock.json? yarn.lock? --> |
-| Atualização | <!-- Dependabot? Manual? Periodicidade? --> |
-
----
-
-## Changelog
-
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-|      |         |      |           |
+# Convenções
+
+> Regras transversais do sistema: autenticação, autorização, CORS, rate limiting,
+> LGPD, auditoria, variáveis de ambiente, monitoramento, códigos de erro de domínio
+> e versionamento de dependências. Padrões que todo código segue.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+PAPEL: Síntese cross-feature de regras transversais do sistema.
+Fonte única pra "qual é o padrão de auth/authz/LGPD/logs/env vars neste projeto?".
+Features consultam este doc pra seguir padrão; quando precisam mudar, o TRD
+da feature traz o novo padrão e /sf-merge-docs aplica via diff semântico.
+
+ORIGEM (first-run, via /sf-design):
+- TRD §7 Segurança Detalhada → Autenticação, Autorização, CORS, LGPD, Rate Limiting, Auditoria
+- TRD §5.3 Variáveis de ambiente + §1.3 Ambientes → Variáveis de Ambiente, Domínios
+- TRD §2 §Área-Backend (convenções de rota/erro) → Códigos de Erro do Domínio (reutilizáveis)
+- TRD §5.4 Monitoramento → Monitoramento e Observabilidade
+- TRD §9 Decisões Técnicas (ADRs) → Alternativas Tecnológicas Descartadas, Versionamento
+
+ATUALIZAÇÃO (feature): /sf-merge-docs faz diff semântico PRD+TRD ↔ docs/
+e aplica ADDED/MODIFIED/REMOVED quando feature adiciona permissões,
+papéis, dados pessoais LGPD, variáveis de ambiente, códigos de erro,
+ou altera políticas de retenção/auditoria.
+
+COMO GERAR (first-run):
+1. Ler TRD §7 Segurança Detalhada — autenticação, autorização, CORS, LGPD, rate limiting
+2. Ler TRD §5.3 Variáveis de ambiente + §1.3 Ambientes — env vars e domínios
+3. Ler TRD §5.4 Monitoramento — logs, métricas, tracing, alertas
+4. Ler TRD §2 §Área-Backend — convenções de rota e códigos de erro globais
+5. Ler TRD §9 Decisões (ADRs) — alternativas descartadas e versionamento
+6. Autenticação: método, expiração, hash, refresh strategy
+7. Autorização: papéis e matriz de permissões (RBAC/ABAC)
+8. LGPD: mapear TODOS dados pessoais com base legal específica
+9. Auditoria: O QUE é logado, ONDE, POR QUANTO TEMPO
+10. Variáveis de ambiente: NUNCA valores reais, só exemplos
+
+O QUE NÃO VAI AQUI:
+- Rotas, paginação, filtros, catálogo de endpoints → apiContracts.md
+- Containers, ambientes, deploy → architecture.md
+- Entidades, tabelas → domain.md
+
+REGRAS:
+- Matriz de permissões é DINÂMICA — cresce a cada feature (via /sf-merge-docs)
+- Dados pessoais da LGPD precisam de base legal ESPECÍFICA
+- Nunca armazenar senhas em texto plano (hash obrigatório)
+- Secrets nunca no código — sempre variáveis de ambiente
+- Rate limiting obrigatório em endpoints públicos (login, registro)
+- Auditoria obrigatória para operações destrutivas
+- Códigos de erro do domínio são globais — reutilizáveis por múltiplos endpoints
+
+=============================================================================
+-->
+
+## Autenticação
+
+| Aspecto | Implementação |
+|---------|--------------|
+| Método | <!-- JWT? Session? OAuth2? --> |
+| Expiração access token | <!-- Ex: 15min --> |
+| Refresh token | <!-- Existe? Expiração? Rotação? --> |
+| Hash de senha | <!-- bcrypt rounds? argon2? --> |
+| Header | <!-- Authorization: Bearer {token} --> |
+| Armazenamento (client) | <!-- httpOnly cookie? localStorage? --> |
+
+### Fluxo de autenticação
+
+```
+<!-- Descrever o fluxo: login → token → refresh → logout -->
+```
+
+## Autorização
+
+### Modelo
+
+| Aspecto | Decisão |
+|---------|---------|
+| Tipo | <!-- RBAC / ABAC / RBAC + ABAC --> |
+| Onde é verificado | <!-- Middleware? Decorator? Service? --> |
+| Granularidade | <!-- Por rota? Por recurso? Por campo? --> |
+
+### Papéis
+
+| Papel | Descrição | Herda de |
+|-------|-----------|----------|
+|       |           | <!-- Hierarquia: admin herda de user? --> |
+
+### Matriz de Permissões
+
+> Atualizada a cada feature via /sf-merge-docs.
+
+| Recurso | Ação | {{role_1}} | {{role_2}} | {{role_N}} |
+|---------|------|------------|------------|------------|
+|         | criar | | | |
+|         | ler | | | |
+|         | editar | | | |
+|         | deletar | | | |
+
+## CORS
+
+| Aspecto | Configuração |
+|---------|-------------|
+| Allowed Origins | <!-- Configurável por ambiente --> |
+| Allowed Methods | `GET, POST, PUT, PATCH, DELETE` |
+| Allowed Headers | `Authorization, Content-Type` |
+| Credentials | <!-- true/false --> |
+| Max Age | <!-- Preflight cache em segundos --> |
+
+## Rate Limiting
+
+| Categoria | Limite | Janela | Resposta |
+|-----------|--------|--------|----------|
+| Login/Registro | <!-- Ex: 5 req --> | <!-- Ex: 15min --> | 429 + Retry-After |
+| API autenticada | <!-- Ex: 100 req --> | <!-- Ex: 1min --> | 429 + Retry-After |
+| API pública | <!-- Ex: 30 req --> | <!-- Ex: 1min --> | 429 + Retry-After |
+| Upload | <!-- Ex: 10 req --> | <!-- Ex: 1h --> | 429 + Retry-After |
+
+## LGPD / Privacidade
+
+### Dados pessoais coletados
+
+| Dado | Base legal | Finalidade | Retenção | Criptografado? |
+|------|-----------|------------|----------|----------------|
+|      | <!-- Consentimento / Contrato / Legítimo interesse / Obrigação legal --> | | | |
+
+### Direitos do titular
+
+| Direito | Implementação | Endpoint/Fluxo |
+|---------|--------------|----------------|
+| Acesso aos dados | | |
+| Correção | | |
+| Exclusão (right to be forgotten) | | <!-- Soft delete? Hard delete? Anonimização? --> |
+| Portabilidade | | <!-- Formato de exportação? --> |
+| Revogação de consentimento | | |
+
+## Auditoria
+
+| O que é logado | Quando | Onde armazena | Retenção |
+|----------------|--------|---------------|----------|
+| Login/Logout | sempre | | |
+| Alteração de dados sensíveis | sempre | | |
+| Operações destrutivas (DELETE) | sempre | | |
+| Falhas de autenticação | sempre | | |
+| Mudanças de permissão | sempre | | |
+
+## Proteção de Dados em Trânsito e Repouso
+
+| Aspecto | Implementação |
+|---------|--------------|
+| TLS | <!-- Versão mínima? --> |
+| Dados sensíveis em repouso | <!-- Criptografia? Quais campos? --> |
+| Backup | <!-- Criptografado? Frequência? --> |
+
+## Variáveis de Ambiente
+
+> NUNCA colocar valores reais aqui. Apenas nomes, descrição e exemplos.
+
+| Variável | Ambientes | Obrigatória | Descrição | Exemplo |
+|----------|-----------|-------------|-----------|---------|
+| `DATABASE_URL` | todos | sim | Conexão com banco | `postgres://user:pass@host:5432/db` |
+| `JWT_SECRET` | todos | sim | Chave de assinatura JWT | `sua-chave-secreta-aqui` |
+| `NODE_ENV` | todos | sim | Ambiente atual | `development` / `production` |
+
+## Domínios e DNS
+
+| Domínio | Aponta para | Certificado | Gerenciado por |
+|---------|-------------|-------------|----------------|
+|         |             | <!-- Let's Encrypt? AWS ACM? --> | |
+
+## Monitoramento e Observabilidade
+
+| Aspecto | Ferramenta | O que monitora |
+|---------|-----------|----------------|
+| Logs | <!-- Ex: CloudWatch, Datadog --> | |
+| APM | <!-- Ex: New Relic, Sentry --> | |
+| Uptime | <!-- Ex: Pingdom, UptimeRobot --> | |
+| Alertas | <!-- Ex: PagerDuty, Slack --> | |
+
+## Códigos de Erro do Domínio
+
+> Códigos reutilizáveis por múltiplos endpoints. Novos códigos são adicionados via /sf-merge-docs.
+
+| Código | Descrição | HTTP padrão |
+|--------|-----------|-------------|
+| <!-- Ex: DUPLICATE_EMAIL --> | <!-- Email já cadastrado --> | <!-- 409 --> |
+
+## Alternativas Tecnológicas Descartadas
+
+> Decisões já tomadas. Se alguém perguntar "por que não usamos X?", a resposta está aqui.
+
+| Tecnologia escolhida | Alternativa considerada | Por que descartamos | Ref decisão |
+|----------------------|------------------------|---------------------|-------------|
+|                      |                        |                     |             |
+
+## Convenções de Versionamento de Dependências
+
+| Aspecto | Convenção |
+|---------|-----------|
+| Versionamento | <!-- Semver? Pinned? --> |
+| Lock files | <!-- package-lock.json? yarn.lock? --> |
+| Atualização | <!-- Dependabot? Manual? Periodicidade? --> |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |