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

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

@@ -1,159 +1,160 @@
-# Contratos de API
-
-> Padrões de endpoint, convenções de rotas, paginação, filtros, respostas de erro
-> e catálogo global. Contratos HTTP do sistema.
-> Autenticação detalhada e códigos de erro do domínio vivem em conventions.md.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-PAPEL: Síntese das convenções globais de API + catálogo de endpoints cross-feature.
-Fonte única pra "como são as rotas, paginação, erros neste projeto?".
-Features novas consultam este doc; novos endpoints entram no catálogo via /sf-merge-docs.
-
-ORIGEM (first-run, via /sf-design):
-- SDD §3.6 Convenções de API → "Padrão Geral" + "Convenções de Rotas" + "Paginação" + "Filtros" + "Respostas de Erro"
-- SDD §4.1 Endpoints (se houver em first-run, ex: health check, auth) → "Catálogo"
-
-ATUALIZAÇÃO (feature): /sf-merge-docs aplica SDD §11 ADDED/MODIFIED/REMOVED
-quando feature adiciona endpoints (do SDD §4.1) ao catálogo.
-
-COMO GERAR (first-run):
-1. Ler SDD §3.6 Convenções de API — estilo, formato, versionamento, paginação, erros
-2. Padrão geral e convenções são FIXOS após first-run — definidos uma vez
-3. Catálogo de endpoints é DINÂMICO — cresce a cada feature via /sf-merge-docs
-4. Formatos de paginação, filtro e resposta de erro são FIXOS
-
-O QUE NÃO VAI AQUI:
-- Autenticação detalhada (hash, refresh, fluxo) → conventions.md
-- Autorização, roles, matriz de permissões → conventions.md
-- Códigos de erro do domínio → conventions.md
-- Rate limiting → conventions.md
-- CORS → conventions.md
-
-REGRAS:
-- Convenções são LEI — todo SDD §5 (endpoints) deve seguir
-- Catálogo atualizado a cada /sf-merge-docs
-- Mudanças em convenções (raro) devem gerar registro em decisions.md
-
-=============================================================================
--->
-
-## Padrão Geral
-
-| Aspecto | Padrão |
-|---------|--------|
-| Estilo | <!-- REST / GraphQL / gRPC --> |
-| Formato | <!-- JSON / Protobuf --> |
-| Versionamento | <!-- /api/v1/ no path? Header? --> |
-| Content-Type | <!-- application/json --> |
-| Encoding | <!-- UTF-8 --> |
-
-> **Autenticação**: definida em [conventions.md → Autenticação](./conventions.md#autenticação).
-
-## Convenções de Rotas
-
-| Operação | Método | Rota | Exemplo |
-|----------|--------|------|---------|
-| Listar | GET | `/api/v1/{recurso}` | |
-| Detalhar | GET | `/api/v1/{recurso}/:id` | |
-| Criar | POST | `/api/v1/{recurso}` | |
-| Atualizar completo | PUT | `/api/v1/{recurso}/:id` | |
-| Atualizar parcial | PATCH | `/api/v1/{recurso}/:id` | |
-| Remover/Inativar | DELETE | `/api/v1/{recurso}/:id` | |
-
-### Convenções de nomenclatura
-
-| Regra | Exemplo |
-|-------|---------|
-| Recursos no plural, kebab-case | `/api/v1/order-items` |
-| Ações não-CRUD como sub-recurso | `/api/v1/users/:id/activate` |
-| Filtros via query params | `/api/v1/users?status=active` |
-| Relações aninhadas (max 2 níveis) | `/api/v1/users/:id/orders` |
-
-## Paginação
-
-```json
-{
-  "data": [],
-  "meta": {
-    "page": 1,
-    "per_page": 20,
-    "total": 0,
-    "total_pages": 0
-  }
-}
-```
-
-Query params: `?page=1&per_page=20&sort=campo&order=asc`
-
-| Parâmetro | Default | Máximo | Descrição |
-|-----------|---------|--------|-----------|
-| `page` | 1 | — | Página atual |
-| `per_page` | 20 | <!-- Ex: 100 --> | Itens por página |
-| `sort` | — | — | Campo para ordenação |
-| `order` | `asc` | — | `asc` ou `desc` |
-
-## Filtros
-
-Query params: `?busca=termo&campo=valor`
-
-| Tipo de filtro | Formato | Exemplo |
-|----------------|---------|---------|
-| Igualdade | `?campo=valor` | `?status=ativo` |
-| Busca textual | `?busca=termo` | `?busca=joao` |
-| Range de data | `?de=YYYY-MM-DD&ate=YYYY-MM-DD` | `?de=2026-01-01&ate=2026-12-31` |
-| Múltiplos valores | `?campo=a,b,c` | `?status=ativo,pendente` |
-
-## Respostas de Erro
-
-```json
-{
-  "error": {
-    "code": "ERROR_CODE",
-    "message": "Mensagem legível para o usuário",
-    "details": [
-      { "field": "campo", "message": "Detalhe do erro" }
-    ]
-  }
-}
-```
-
-### Códigos HTTP
-
-| Código | Quando usar | Exemplo |
-|--------|-------------|---------|
-| 200 | Sucesso (GET, PUT, PATCH) | Recurso retornado/atualizado |
-| 201 | Criado com sucesso (POST) | Recurso criado, retorna o objeto |
-| 204 | Sucesso sem conteúdo (DELETE) | Recurso removido |
-| 400 | Dados inválidos (formato) | JSON malformado |
-| 401 | Não autenticado | Token ausente ou expirado |
-| 403 | Sem permissão | Papel sem acesso ao recurso |
-| 404 | Recurso não encontrado | ID inexistente |
-| 409 | Conflito (duplicidade) | Email já cadastrado |
-| 422 | Validação de negócio falhou | CPF inválido, regra RN-XXX violada |
-| 429 | Rate limit excedido | Muitas requisições |
-| 500 | Erro interno | Bug não tratado |
-
-> **Códigos de erro do domínio**: definidos em [conventions.md → Códigos de Erro do Domínio](./conventions.md#códigos-de-erro-do-domínio).
-
-## Catálogo de Endpoints
-
-> Atualizado a cada feature via /sf-merge-docs. Visão consolidada de todas as APIs.
-> Pra detalhe de um endpoint específico (request/response schemas), ver SDD §4.1 do scope: `workspace/Output/{scope}/sdd.md`.
-
-| Método | Rota | Feature | Descrição |
-|--------|------|---------|-----------|
-|        |      |         |           |
-
----
-
-## Changelog
-
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-|      |         |      |           |
+# Contratos de API
+
+> Padrões de endpoint, convenções de rotas, paginação, filtros, respostas de erro
+> e catálogo global. Contratos HTTP do sistema.
+> Autenticação detalhada e códigos de erro do domínio vivem em conventions.md.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+PAPEL: Síntese das convenções globais de API + catálogo de endpoints cross-feature.
+Fonte única pra "como são as rotas, paginação, erros neste projeto?".
+Features novas consultam este doc; novos endpoints entram no catálogo via /sf-merge-docs.
+
+ORIGEM (first-run, via /sf-design):
+- TRD §2 §Área-Backend (convenções de rota) → "Padrão Geral" + "Convenções de Rotas" + "Paginação" + "Filtros" + "Respostas de Erro"
+- TRD §2.1 Endpoints (se houver em first-run, ex: health check, auth) → "Catálogo"
+
+ATUALIZAÇÃO (feature): /sf-merge-docs faz diff semântico PRD+TRD ↔ docs/
+e aplica ADDED/MODIFIED/REMOVED quando feature adiciona endpoints
+(do TRD §2.1) ao catálogo.
+
+COMO GERAR (first-run):
+1. Ler TRD §2 §Área-Backend — estilo, formato, versionamento, paginação, erros
+2. Padrão geral e convenções são FIXOS após first-run — definidos uma vez
+3. Catálogo de endpoints é DINÂMICO — cresce a cada feature via /sf-merge-docs
+4. Formatos de paginação, filtro e resposta de erro são FIXOS
+
+O QUE NÃO VAI AQUI:
+- Autenticação detalhada (hash, refresh, fluxo) → conventions.md
+- Autorização, roles, matriz de permissões → conventions.md
+- Códigos de erro do domínio → conventions.md
+- Rate limiting → conventions.md
+- CORS → conventions.md
+
+REGRAS:
+- Convenções são LEI — todo TRD §2.1 (endpoints) deve seguir
+- Catálogo atualizado a cada /sf-merge-docs
+- Mudanças em convenções (raro) devem gerar registro em decisions.md
+
+=============================================================================
+-->
+
+## Padrão Geral
+
+| Aspecto | Padrão |
+|---------|--------|
+| Estilo | <!-- REST / GraphQL / gRPC --> |
+| Formato | <!-- JSON / Protobuf --> |
+| Versionamento | <!-- /api/v1/ no path? Header? --> |
+| Content-Type | <!-- application/json --> |
+| Encoding | <!-- UTF-8 --> |
+
+> **Autenticação**: definida em [conventions.md → Autenticação](./conventions.md#autenticação).
+
+## Convenções de Rotas
+
+| Operação | Método | Rota | Exemplo |
+|----------|--------|------|---------|
+| Listar | GET | `/api/v1/{recurso}` | |
+| Detalhar | GET | `/api/v1/{recurso}/:id` | |
+| Criar | POST | `/api/v1/{recurso}` | |
+| Atualizar completo | PUT | `/api/v1/{recurso}/:id` | |
+| Atualizar parcial | PATCH | `/api/v1/{recurso}/:id` | |
+| Remover/Inativar | DELETE | `/api/v1/{recurso}/:id` | |
+
+### Convenções de nomenclatura
+
+| Regra | Exemplo |
+|-------|---------|
+| Recursos no plural, kebab-case | `/api/v1/order-items` |
+| Ações não-CRUD como sub-recurso | `/api/v1/users/:id/activate` |
+| Filtros via query params | `/api/v1/users?status=active` |
+| Relações aninhadas (max 2 níveis) | `/api/v1/users/:id/orders` |
+
+## Paginação
+
+```json
+{
+  "data": [],
+  "meta": {
+    "page": 1,
+    "per_page": 20,
+    "total": 0,
+    "total_pages": 0
+  }
+}
+```
+
+Query params: `?page=1&per_page=20&sort=campo&order=asc`
+
+| Parâmetro | Default | Máximo | Descrição |
+|-----------|---------|--------|-----------|
+| `page` | 1 | — | Página atual |
+| `per_page` | 20 | <!-- Ex: 100 --> | Itens por página |
+| `sort` | — | — | Campo para ordenação |
+| `order` | `asc` | — | `asc` ou `desc` |
+
+## Filtros
+
+Query params: `?busca=termo&campo=valor`
+
+| Tipo de filtro | Formato | Exemplo |
+|----------------|---------|---------|
+| Igualdade | `?campo=valor` | `?status=ativo` |
+| Busca textual | `?busca=termo` | `?busca=joao` |
+| Range de data | `?de=YYYY-MM-DD&ate=YYYY-MM-DD` | `?de=2026-01-01&ate=2026-12-31` |
+| Múltiplos valores | `?campo=a,b,c` | `?status=ativo,pendente` |
+
+## Respostas de Erro
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Mensagem legível para o usuário",
+    "details": [
+      { "field": "campo", "message": "Detalhe do erro" }
+    ]
+  }
+}
+```
+
+### Códigos HTTP
+
+| Código | Quando usar | Exemplo |
+|--------|-------------|---------|
+| 200 | Sucesso (GET, PUT, PATCH) | Recurso retornado/atualizado |
+| 201 | Criado com sucesso (POST) | Recurso criado, retorna o objeto |
+| 204 | Sucesso sem conteúdo (DELETE) | Recurso removido |
+| 400 | Dados inválidos (formato) | JSON malformado |
+| 401 | Não autenticado | Token ausente ou expirado |
+| 403 | Sem permissão | Papel sem acesso ao recurso |
+| 404 | Recurso não encontrado | ID inexistente |
+| 409 | Conflito (duplicidade) | Email já cadastrado |
+| 422 | Validação de negócio falhou | CPF inválido, regra RN-XXX violada |
+| 429 | Rate limit excedido | Muitas requisições |
+| 500 | Erro interno | Bug não tratado |
+
+> **Códigos de erro do domínio**: definidos em [conventions.md → Códigos de Erro do Domínio](./conventions.md#códigos-de-erro-do-domínio).
+
+## Catálogo de Endpoints
+
+> Atualizado a cada feature via /sf-merge-docs. Visão consolidada de todas as APIs.
+> Pra detalhe de um endpoint específico (request/response schemas), ver TRD §2.1 do scope: `workspace/Output/{scope}/TRD.md` ou `specs/{scope}/contracts.md`.
+
+| Método | Rota | Feature | Descrição |
+|--------|------|---------|-----------|
+|        |      |         |           |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |