spec-first-copilot 0.6.0-beta.9 → 0.7.0

package/templates/.github/templates/feature/sdd.template.md

@@ -1,559 +0,0 @@
-# SDD — {{NOME}}
-
-> **Software Design Document** — fonte de verdade técnica pro escopo `{{NOME}}`.
-> Gerado pelo `/sf-design` a partir do PRD (se existir) + chunks tech do `/sf-extract`.
-> O Coder lê APENAS este documento + `specs/{{NOME}}/` e seu task específica.
-> Se não está aqui, não será implementado.
->
-> **Sobre o tamanho do template**: o SDD tem 12 seções para cobrir o range completo
-> (app simples → sistema distribuído com 5 serviços). Escopo pequeno preenche 3-4
-> seções e marca as outras como "N/A" ou "não se aplica" — isso é **esperado**.
-> Áreas não tocadas (§4-§7) usam `GATE: NÃO` e ficam vazias. Não inflar conteúdo
-> pra preencher seção vazia — "N/A" é resposta válida.
-
----
-
-## Meta
-
-| Campo | Valor |
-|-------|-------|
-| Scope | `{{NOME}}` |
-| PRD | `workspace/Output/{{NOME}}/PRD.md` — `empty: {{true\|false}}` (sem aspas, bool) |
-| First-run | `{{true\|false}}` — true quando `docs/` não existia antes desta execução |
-| Áreas tocadas | `[BACK?, FRONT?, DB?, INFRA?]` |
-| Status | `rascunho` → `em revisão` → `aprovado` → `em dev` → `concluído` |
-| Autor | `/sf-design` |
-| Criado em | |
-| Ambiguidades pendentes | `{{N}}` — ver §12 |
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-QUANDO USAR: Gerado pelo /sf-design após checkpoint de aprovação do PRD.
-QUEM GERA: Agent Architect (Opus).
-
-ENTRADAS:
-1. `workspace/Output/{{NOME}}/PRD.md` — pode ter `empty: true` em first-run puro-técnico
-2. `workspace/Output/{{NOME}}/.extract-log.md` — chunks tech categorizados pelo /sf-extract
-3. `docs/` — se existir (não é first-run), usar como baseline; referenciar em vez de duplicar
-4. `workspace/Input/{{NOME}}/` — consulta adicional apenas pra desambiguação
-
-BRANCH FIRST-RUN vs FEATURE:
-- `docs/` AUSENTE → first-run:
-  - Preencher §3 §Sistema COMPLETO (todas subseções)
-  - Preencher §Área-X de todas as áreas aplicáveis (scaffolding inicial)
-  - §11 Delta Specs: TUDO em ADDED (docs/ nasce a partir daqui via /sf-merge-docs)
-- `docs/` EXISTE → feature:
-  - §3 §Sistema: só subseções que a feature MUDA (ex: nova env var → só §3.3)
-  - §Área-X: só áreas tocadas (outras ficam N/A — não remover, deixar vazia com "N/A: feature não toca esta área")
-  - §11 Delta Specs: ADDED/MODIFIED/REMOVED refletindo impacto cross-feature
-
-GATE DE SEÇÃO (obrigatório):
-Cada §Área-X começa com um bloco GATE:
-  > **GATE**: BACK tocada? [SIM|NÃO]
-  > Se NÃO, toda a seção vira "N/A — feature não toca backend" e passar.
-Coder SÓ lê §Área-X quando GATE = SIM.
-
-RASTREABILIDADE:
-- Cada §Área-X referencia PRD §X ou "no-PRD" (origem: extract tech chunks)
-- Cada decisão em §2 referencia item do PRD ou chunk do extract-log
-- Se §Sistema é preenchida em feature, cada subseção diz "mudança em docs/X §Y"
-
-AMBIGUIDADES:
-- §12 lista ambiguidades não resolvidas — BLOQUEANTE pro /sf-design concluir
-- Analyzer consulta `docs/` ANTES de marcar ambiguidade: se a resposta existe
-  (ex: auth já documentada em `docs/conventions.md`), marcar como "resolvido em
-  docs/conventions.md §Autenticação" e NÃO perguntar
-- Ambiguidades reais só surgem se (a) docs/ ausente, (b) assunto novo,
-  (c) insumo contradiz docs/
-
-DELTA SPECS:
-- §11 é a ÚNICA seção lida pelo /sf-merge-docs
-- Formato ADDED/MODIFIED/REMOVED (inspirado OpenSpec)
-- Cada entry referencia arquivo-alvo: `docs/conventions.md §Monitoramento`
-- Sem §11, docs/ não atualiza — é obrigatório (mesmo vazio com "nenhuma mudança")
-
-=============================================================================
--->
-
-## 1. Visão Geral
-
-### O que é
-<!-- 2-3 frases: o que este scope entrega, ligação com produto -->
-
-### Escopo técnico
-<!-- Limites: o que ENTRA (áreas tocadas, integrações) e o que FICA DE FORA -->
-
-### Premissas
-- [ ] <!-- Ex: Usuário já está autenticado (contexto global) -->
-
-### Referência PRD
-<!-- Se PRD existe: "Ver PRD.md §2 Jornadas, §5 Regras" -->
-<!-- Se PRD empty: "PRD empty — scope puro-técnico (first-run de infra)" -->
-
----
-
-## 2. Decisões de Design
-
-> Mini-ADRs inline — decisões técnicas deste scope com justificativa.
-> Decisões globais persistentes vão em `docs/decisions.md` via §11 Delta Specs.
-
-| # | Decisão | Justificativa | Alternativa descartada | Origem |
-|---|---------|---------------|------------------------|--------|
-| 1 | | | | PRD §X / extract-log §Y |
-
----
-
-## 3. §Sistema
-
-> **GATE**: Preencher completo em first-run. Em feature, preencher APENAS
-> subseções que a feature MODIFICA (mudanças propagam pra `docs/` via §11).
-> Se nada muda no sistema, marcar: "N/A — feature não altera baseline".
-
-### 3.1 Stack
-
-| Camada | Tecnologia | Versão | Justificativa |
-|--------|-----------|--------|---------------|
-| Backend | | | |
-| Frontend | | | |
-| Banco | | | |
-| Infra | | | |
-
-**Ferramentas auxiliares**:
-- <!-- build, lint, formatter, CI runner -->
-
-### 3.2 Arquitetura
-
-**Containers lógicos**:
-
-| Container | Tecnologia | Responsabilidade | Porta |
-|-----------|-----------|------------------|-------|
-| | | | |
-
-**Padrões de comunicação**:
-- <!-- REST síncrono, event-driven, gRPC, etc. -->
-
-**Padrões de design adotados**:
-- <!-- Clean Arch, Hexagonal, CQRS, etc. -->
-
-### 3.3 Ambientes
-
-| Ambiente | Propósito | URL pattern | Deploy trigger |
-|----------|-----------|-------------|----------------|
-| dev | | `*.dev.internal` | push em feature |
-| staging | | `staging.*` | merge em main |
-| prod | | `www.*` | tag release |
-
-**Variáveis de ambiente baseline**:
-
-| Var | Dev | Staging | Prod | Descrição |
-|-----|-----|---------|------|-----------|
-| | | | | |
-
-### 3.4 Infraestrutura
-
-| Aspecto | Decisão |
-|---------|---------|
-| Hospedagem | |
-| Orquestração | <!-- Docker Compose / K8s / ECS / etc. --> |
-| CI/CD | <!-- GitHub Actions / GitLab CI / Jenkins --> |
-| Containerização | |
-| Registry | |
-
-**Dev local** (convenção SFW: docker-compose = só dependências; apps rodam direto):
-- Serviços no docker-compose: <!-- PostgreSQL, Redis, RabbitMQ --> (apenas infra)
-- Apps (API, Worker, Web): rodam com `dotnet run`, `npm run dev`, etc.
-- Motivo: hot reload, debug breakpoints, performance I/O
-
-### 3.5 Segurança
-
-| Aspecto | Decisão | Referência |
-|---------|---------|-----------|
-| Autenticação | <!-- JWT/OAuth2/session --> | |
-| Autorização | <!-- RBAC/ABAC + fluxo --> | |
-| Secrets | <!-- Vault/AWS SSM/.env gitignored --> | |
-| CORS | | |
-| Rate limiting | | |
-| LGPD | | |
-| Auditoria | | |
-
-### 3.6 Convenções de API
-
-| Aspecto | Convenção |
-|---------|-----------|
-| Estilo | <!-- REST / GraphQL / RPC --> |
-| Formato | <!-- JSON / JSON:API --> |
-| Versionamento | <!-- /v1/, header, none --> |
-| Paginação | <!-- cursor / offset --> |
-| Erros | <!-- RFC 7807 / custom envelope --> |
-| Documentação | <!-- OpenAPI 3.1 / GraphQL Schema --> |
-
-### 3.7 Monitoramento
-
-| Aspecto | Ferramenta | Alvo |
-|---------|-----------|------|
-| Logs | <!-- Serilog/Pino + Datadog/ELK --> | |
-| Métricas | <!-- Prometheus/Datadog --> | |
-| Tracing | <!-- OpenTelemetry --> | |
-| Alertas | | |
-
----
-
-## 4. §Área-Backend
-
-> **GATE**: Feature toca backend? `[SIM|NÃO]`
-> Se NÃO → marcar toda a seção "N/A — feature não toca backend" e pular.
-
-### 4.1 Endpoints
-
-> Contratos completos. O Coder implementa exatamente estes schemas.
-
-### `{{METHOD}} {{/api/v1/recurso}}` — {{Descrição}}
-
-**Descrição**: <!-- o que faz -->
-**Regras**: <!-- RN-001, RN-002 (do PRD §5) -->
-**Autenticação**: <!-- público | Bearer token | API Key --> — se não público, justificar
-**Autorização**: <!-- roles permitidos: admin, user, owner --> — OBRIGATÓRIO se autenticado
-**Rate Limit**: <!-- N req/min ou N/A -->
-
-**Request Body**:
-```json
-{
-  "campo": "tipo (required|optional, validações)"
-}
-```
-
-**Response {{STATUS}}**:
-```json
-{
-  "campo": "tipo"
-}
-```
-
-**Erros**:
-
-| Status | Código | Quando |
-|--------|--------|--------|
-| 401 | `UNAUTHORIZED` | Token ausente ou inválido |
-| 403 | `FORBIDDEN` | Sem permissão para este recurso |
-| 400 | `VALIDATION_ERROR` | Campos inválidos |
-
-<!-- Repetir bloco para cada endpoint -->
-
-> **Regra**: todo endpoint DEVE ter Autenticação e Autorização explícitas.
-> Se público, escrever "público" — nunca omitir.
-
-### 4.2 Regras de Negócio e Validações
-
-| ID | Regra | Onde aplica | Ref PRD |
-|----|-------|-------------|---------|
-| RN-001 | | back / front / banco | PRD §5 RN-001 |
-
-**Validações de campo** (mensagens de erro obrigatórias):
-
-| Campo | Validação | Obrigatório | Mensagem de erro |
-|-------|-----------|-------------|------------------|
-| | | | |
-
-### 4.3 Integrações Externas
-
-| Serviço | Protocolo | Quando | Timeout | Retry | Fallback |
-|---------|-----------|--------|---------|-------|----------|
-| | | | | | |
-
-**Contrato por integração**:
-
-#### `{{Nome do Serviço}}`
-
-**Request**: `{{METHOD}} {{URL}}`
-```json
-{ }
-```
-
-**Response esperada**:
-```json
-{ }
-```
-
-**Tratamento de falha**: <!-- circuit breaker / retry exponencial / fallback -->
-
----
-
-## 5. §Área-Frontend
-
-> **GATE**: Feature toca frontend? `[SIM|NÃO]`
-> Se NÃO → marcar "N/A — feature não toca frontend" e pular.
-
-### 5.1 Telas e Componentes
-
-#### Tela: {{Nome}}
-
-| Propriedade | Valor |
-|-------------|-------|
-| Rota | `{{/rota}}` |
-| Permissão | {{roles}} |
-| Estado inicial | |
-
-**Componentes**:
-
-| Componente | Tipo | Comportamento |
-|------------|------|---------------|
-| | | |
-
-**Estados**:
-
-| Estado | Gatilho | Efeito visual |
-|--------|---------|---------------|
-| loading | requisição em andamento | skeleton/spinner |
-| empty | lista vazia | mensagem |
-| error | falha na API | toast + retry |
-
-<!-- Repetir bloco para cada tela -->
-
-### 5.2 Fluxos de Usuário
-
-> Referência às jornadas do PRD — aqui traduzidas em passos técnicos front-back.
-
-#### Fluxo: {{Nome}} (ref PRD §4 Jornada X)
-
-```
-Usuário {{ação}} → [front] {{passo}} → [back] {{passo}}
-  → [back] retorna {{response}}
-→ [front] {{feedback}}
-```
-
-### 5.3 Estados globais
-
-<!-- Context/Store/Redux — o que vive fora do componente -->
-
----
-
-## 6. §Área-DB
-
-> **GATE**: Feature toca banco? `[SIM|NÃO]`
-> Se NÃO → marcar "N/A — feature não toca banco" e pular.
-
-### 6.1 Entidades
-
-#### `{{nome_tabela}}`
-
-| Campo | Tipo | Null? | Default | Constraint | Descrição |
-|-------|------|-------|---------|------------|-----------|
-| `id` | `UUID` | NOT NULL | `gen_random_uuid()` | PK | |
-| `created_at` | `TIMESTAMPTZ` | NOT NULL | `NOW()` | | |
-
-**Relações**:
-- `tabela.campo` → `outra_tabela.campo` (FK, ON DELETE CASCADE)
-
-**Índices**:
-- `idx_tabela_campo` — tipo (btree/gin/gist) — justificativa
-
-### 6.2 Migrations
-
-| Ordem | Descrição | Dependência | Reversível? |
-|-------|-----------|-------------|-------------|
-| 1 | | nenhuma | sim |
-
-### 6.3 Políticas de Dados
-
-| Aspecto | Decisão |
-|---------|---------|
-| Retenção | <!-- dados ficam indefinidamente / TTL N dias --> |
-| Backup | |
-| Seed inicial | |
-
----
-
-## 7. §Área-Infra
-
-> **GATE**: Feature toca infra (docker, CI, deploy, env)? `[SIM|NÃO]`
-> Se NÃO → marcar "N/A — feature não toca infra" e pular.
-
-### 7.1 Mudanças em orquestração
-
-**docker-compose.yml** (dev):
-<!-- Novos serviços de infra apenas (apps rodam direto, ver §3.4) -->
-
-**CI/CD**:
-<!-- Novos steps, jobs, ou workflows -->
-
-**Deploy**:
-<!-- Mudanças no processo de deploy -->
-
-### 7.2 Novas dependências
-
-| Tipo | Nome | Versão | Justificativa |
-|------|------|--------|---------------|
-| pacote npm | | | |
-| pacote NuGet | | | |
-
-### 7.3 Novas variáveis de ambiente
-
-| Var | Dev | Staging | Prod | Descrição | Sensível? |
-|-----|-----|---------|------|-----------|-----------|
-| | | | | | |
-
----
-
-## 8. Fluxos de Dados (cross-area)
-
-> Sequências que atravessam múltiplas áreas. O Coder segue como guia integrativo.
-
-### Fluxo: {{Nome}} (principal)
-
-```
-Usuário {{ação}}
-  → [front] {{componente}} dispara {{chamada}}
-  → [back] {{endpoint}} valida + executa {{regra}}
-  → [db] {{query/insert}}
-  → [back] retorna {{response}}
-  → [front] atualiza {{estado}}
-```
-
-### Fluxo: {{Nome}} (erro)
-
-```
-{{sequência do fallback}}
-```
-
----
-
-## 9. Estratégia de Testes
-
-> O Coder implementa testes junto com o código — não é etapa separada.
-
-### 9.1 Testes por área (apenas áreas tocadas)
-
-| Área | Tipo | Framework | Comando | O que cobre |
-|------|------|-----------|---------|-------------|
-| BACK | Unit | | | Services, validações RN-*, regras de negócio |
-| BACK | Integration | | | Endpoints completos (request → response) |
-| FRONT | Unit | | | Componentes com lógica, hooks customizados |
-| FRONT | E2E | | | Jornadas do §5.2 / fluxos do §8 |
-| DB | Migration | | | Migration roda + rollback sem erro |
-
-### 9.2 Estrutura de testes
-
-```
-<!-- Adaptar à stack. Exemplo: -->
-backend/
-├── tests/
-│   ├── Unit/              ← services, validações
-│   ├── Integration/       ← endpoints (in-memory ou testcontainers)
-│   └── Fixtures/          ← dados de teste
-frontend/
-└── tests/
-    ├── components/        ← unit (testing library)
-    └── e2e/               ← playwright (jornadas completas)
-```
-
-### 9.3 Critérios de Aceite
-
-> Given/When/Then testável. Cada CA mapeia pelo menos 1 teste automatizado.
-
-#### CA-001: {{Título}}
-
-```gherkin
-Given {{pré-condição}}
-When {{ação do usuário}}
-Then {{resultado esperado}}
-```
-
-| CA | Tipo de teste | Arquivo |
-|----|---------------|---------|
-| CA-001 | integration | `tests/Integration/{{Teste}}.cs` |
-| CA-002 | e2e | `tests/e2e/{{teste}}.spec.ts` |
-
-### 9.4 Métricas
-
-| Métrica | Threshold | Como medir |
-|---------|-----------|------------|
-| Cobertura (linhas) | >= 70% | coverlet / vitest |
-| Cobertura (branches) | >= 60% | |
-| Tempo suite unit | < 30s | |
-
----
-
-## 10. Fora de Escopo
-
-> Lista explícita — evita scope creep durante implementação.
-
-| # | Item | Motivo | Quando entra |
-|---|------|--------|--------------|
-| 1 | | | |
-
----
-
-## 11. Delta Specs
-
-> **ÚNICA seção lida pelo `/sf-merge-docs`.** Mantém `docs/` sincronizado com estado do sistema.
-> Formato inspirado no OpenSpec: ADDED/MODIFIED/REMOVED.
-> Sempre referenciar arquivo-alvo em `docs/`.
-> Obrigatório mesmo vazio (marcar "nenhuma mudança").
-
-### ADDED
-<!-- Novos: endpoints, tabelas, componentes, regras, permissões, env vars, ADRs -->
-- `docs/apiContracts.md §Catálogo` — novo endpoint `POST /api/v1/users`
-- `docs/domain.md §Entidades` — nova tabela `users`
-- `docs/decisions.md` — ADR-NNN: escolha de JWT vs session
-
-### MODIFIED
-<!-- Alterações em funcionalidades/docs existentes -->
-- `docs/conventions.md §Autenticação` — expansão do fluxo JWT com refresh token
-
-### REMOVED
-<!-- Funcionalidades ou comportamentos que deixam de existir -->
--
-
----
-
-## 12. Ambiguidades Pendentes
-
-> ⚠️ **BLOQUEANTE** — `/sf-plan` não conclui com ambiguidades abertas.
-> Architect consultou `docs/` antes de listar — itens aqui são genuínos.
-> IDs começam em `AMB-NNN`, continuando a sequência iniciada no PRD §14 (se houver).
-
-| ID | Pergunta | Contexto | Consultei `docs/`? | Resposta |
-|----|----------|----------|--------------------|-----------|
-| AMB-001 | | | sim / não / docs ausente | (aguardando) |
-
----
-
-## Rastreabilidade
-
-> Mapa cruzado PRD/sf-extract → SDD. Garante que nenhum requisito foi perdido.
-
-### PRD → SDD
-
-| PRD Seção | SDD Seção |
-|-----------|-----------|
-| §1 Visão | §1 Visão Geral |
-| §2 Jornadas | §5.2 Fluxos de Usuário |
-| §3 Entidades | §6.1 Entidades |
-| §4 Regras (RN-*) | §4.2 Regras + §5.1 (validação UI) |
-| §5 Validações | §4.2 Validações |
-| §6 Telas | §5.1 Telas e Componentes |
-| §7 Integrações | §4.3 Integrações Externas |
-| §8 Erros | §4.1 Endpoints (Erros) |
-| §9 Não-Funcionais | §9.4 Métricas |
-| §10 Fora de Escopo | §10 Fora de Escopo |
-
-### Chunks tech → SDD (PRD empty ou complementar)
-
-| Chunk em `.extract-log.md` | SDD Seção |
-|----------------------------|-----------|
-| tech: stack | §3.1 Stack |
-| tech: arquitetura | §3.2 Arquitetura |
-| tech: schema SQL | §6.1 Entidades |
-| tech: segurança | §3.5 Segurança |
-| tech: infra | §3.4 Infra |
-
----
-
-> **Regra**: este SDD é a fonte de verdade do scope `{{NOME}}`.
-> Coder não consulta PRD, extract-log, PM, ou outro doc — lê SDD + `specs/{{NOME}}/` + task.
-> Alterações pós-aprovação: editar SDD, re-rodar `/sf-design` se grande, ou atualizar §11 delta + `/sf-merge-docs` se cross-feature.