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

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

@@ -1,168 +1,169 @@
-# Arquitetura
-
-> Arquitetura do sistema: containers, componentes, stack tecnológica, ambientes e deploy.
-> C4 Níveis 2-3 + camadas da stack + infraestrutura de runtime.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-PAPEL: Síntese cross-feature estável sobre arquitetura do sistema.
-Onboarding rápido + visão C4 Níveis 2-3 + stack + ambientes + deploy.
-Quando detalhe for necessário, referenciar SDDs de scopes específicos
-(ex: "fluxo completo em workspace/Output/feat_X/sdd.md §8").
-
-ORIGEM (first-run, via /sf-design):
-- SDD §3.1 Stack → seção "Stack Principal"
-- SDD §3.2 Arquitetura → "Diagrama de Containers" + "Containers" + "Padrões"
-- SDD §3.3 Ambientes → seção "Ambientes"
-- SDD §3.4 Infraestrutura → seção "Deploy" (estratégia, CI/CD, rollback)
-
-ATUALIZAÇÃO (feature): /sf-merge-docs aplica SDD §11 ADDED/MODIFIED/REMOVED
-quando feature adiciona containers, componentes, dependências de stack,
-ou muda ambientes/deploy. Não regenerar inteiro — apenas aplicar delta.
-
-COMO GERAR (first-run):
-1. Ler SDD §3.2 Arquitetura — containers, padrões de comunicação, padrões de design
-2. Ler SDD §3.1 Stack — tecnologias por camada, versões exatas
-3. Ler SDD §3.3 Ambientes + §3.4 Infra — ambientes, deploy, CI/CD, rollback
-4. Montar diagrama C4 Nível 2 mostrando TODOS os containers e conexões
-5. Para cada container relevante, listar componentes internos (C4 Nível 3)
-6. Documentar stack principal com versões EXATAS (não "latest")
-7. Documentar ambientes (URLs, bancos, branches) e pipeline CI/CD concreto
-
-O QUE NÃO VAI AQUI:
-- Variáveis de ambiente → conventions.md
-- Monitoramento e observabilidade → conventions.md
-- Segurança (auth, CORS, rate limiting) → conventions.md
-- Alternativas descartadas de stack → conventions.md
-- Entidades e modelo de dados → domain.md
-
-REGRAS:
-- Versões fixadas (18.3.1, não ^18.0.0)
-- Cada container tem: tecnologia, responsabilidade, porta, tipo de comunicação
-- Padrões de design precisam de justificativa (não apenas nome)
-- Pipeline CI/CD deve ser concreto — passos reais e ferramentas
-- Rollback strategy obrigatória — "como voltar se der errado?"
-
-=============================================================================
--->
-
-## Diagrama de Containers (C4 Nível 2)
-
-```
-<!-- Representação textual dos containers e suas conexões -->
-<!-- Usar formato: [Container] --protocolo--> [Container] -->
-```
-
-## Containers
-
-| Container | Tecnologia | Responsabilidade | Porta | Comunicação |
-|-----------|-----------|-----------------|-------|-------------|
-|           |           |                 |       |             |
-
-## Componentes Principais (C4 Nível 3)
-
-<!-- Repetir esta seção para cada container que tenha componentes internos relevantes -->
-
-### {{Container}}
-
-| Componente | Responsabilidade | Dependências internas | Dependências externas |
-|------------|-----------------|----------------------|----------------------|
-|            |                 |                      |                      |
-
-## Padrões de Comunicação
-
-### Síncrona (request/response)
-
-| De | Para | Protocolo | Formato | Observações |
-|----|------|-----------|---------|-------------|
-|    |      |           |         |             |
-
-### Assíncrona (eventos/filas)
-
-| Produtor | Tópico/Fila | Consumer | Formato | Garantia |
-|----------|-------------|----------|---------|----------|
-|          |             |          |         | at-least-once / exactly-once |
-
-## Padrões de Design Adotados
-
-| Padrão | Onde é usado | Justificativa | Ref decisão |
-|--------|-------------|---------------|-------------|
-|        |             |               |             |
-
-## Stack Principal
-
-| Camada | Tecnologia | Versão | Justificativa |
-|--------|-----------|--------|---------------|
-| Frontend | | | |
-| Backend | | | |
-| Banco de Dados | | | |
-| ORM/Query Builder | | | |
-| Autenticação | | | |
-| Testes | | | |
-| CI/CD | | | |
-
-<!-- Adicionar camadas conforme necessidade: Mobile, Cache, Fila, Monitoramento, etc. -->
-
-## Bibliotecas e Dependências por Camada
-
-<!-- Repetir bloco para cada camada com dependências relevantes -->
-
-### {{Camada}}
-
-| Pacote | Versão | Para quê |
-|--------|--------|----------|
-|        |        |          |
-
-## Ambientes
-
-| Ambiente | URL | Banco | Propósito | Branch |
-|----------|-----|-------|-----------|--------|
-| Local | `localhost:{{PORT}}` | local | Desenvolvimento | qualquer |
-| Staging | | | Testes e homologação | develop |
-| Produção | | | Usuários finais | main |
-
-## Deploy
-
-### Estratégia
-
-| Aspecto | Decisão |
-|---------|---------|
-| Plataforma | <!-- Docker? Serverless? VPS? Cloud provider? --> |
-| Orquestração | <!-- Kubernetes? ECS? PM2? --> |
-| Build | <!-- Docker multi-stage? Build nativo? --> |
-| Estratégia de deploy | <!-- Rolling? Blue-green? Canary? --> |
-
-### Pipeline CI/CD
-
-```
-push → lint → test → build → deploy(staging) → aprovação → deploy(prod)
-```
-
-| Etapa | Ferramenta | Trigger | Timeout |
-|-------|-----------|---------|---------|
-| Lint | <!-- eslint, ruff --> | push | |
-| Testes | <!-- jest, pytest --> | push | |
-| Build | <!-- docker build --> | push em main/develop | |
-| Deploy staging | <!-- CD tool --> | push em develop | |
-| Deploy produção | <!-- CD tool --> | aprovação manual | |
-
-### Rollback
-
-| Cenário | Procedimento | Responsável |
-|---------|-------------|-------------|
-| Bug em produção | <!-- Reverter deploy? Hotfix? --> | |
-| Migration com erro | <!-- Rollback da migration? --> | |
-| Serviço externo fora | <!-- Fallback? Circuit breaker? --> | |
-
----
-
-## Changelog
-
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-|      |         |      |           |
+# Arquitetura
+
+> Arquitetura do sistema: containers, componentes, stack tecnológica, ambientes e deploy.
+> C4 Níveis 2-3 + camadas da stack + infraestrutura de runtime.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+PAPEL: Síntese cross-feature estável sobre arquitetura do sistema.
+Onboarding rápido + visão C4 Níveis 2-3 + stack + ambientes + deploy.
+Quando detalhe for necessário, referenciar TRDs de scopes específicos
+(ex: "fluxo completo em workspace/Output/feat_X/TRD.md §2").
+
+ORIGEM (first-run, via /sf-design):
+- TRD §1.1 Stack → seção "Stack Principal"
+- TRD §1.2 Arquitetura → "Diagrama de Containers" + "Containers" + "Padrões"
+- TRD §1.3 Ambientes → seção "Ambientes"
+- TRD §1.4 Deploy baseline + §5 §Área-Infra → seção "Deploy" (estratégia, CI/CD, rollback)
+
+ATUALIZAÇÃO (feature): /sf-merge-docs faz diff semântico PRD+TRD ↔ docs/
+e aplica ADDED/MODIFIED/REMOVED quando feature adiciona containers,
+componentes, dependências de stack, ou muda ambientes/deploy.
+Não regenerar inteiro — apenas aplicar delta.
+
+COMO GERAR (first-run):
+1. Ler TRD §1.2 Arquitetura — containers, padrões de comunicação, padrões de design
+2. Ler TRD §1.1 Stack — tecnologias por camada, versões exatas
+3. Ler TRD §1.3 Ambientes + §1.4 Deploy baseline + §5 §Área-Infra — ambientes, deploy, CI/CD, rollback
+4. Montar diagrama C4 Nível 2 mostrando TODOS os containers e conexões
+5. Para cada container relevante, listar componentes internos (C4 Nível 3)
+6. Documentar stack principal com versões EXATAS (não "latest")
+7. Documentar ambientes (URLs, bancos, branches) e pipeline CI/CD concreto
+
+O QUE NÃO VAI AQUI:
+- Variáveis de ambiente → conventions.md
+- Monitoramento e observabilidade → conventions.md
+- Segurança (auth, CORS, rate limiting) → conventions.md
+- Alternativas descartadas de stack → conventions.md
+- Entidades e modelo de dados → domain.md
+
+REGRAS:
+- Versões fixadas (18.3.1, não ^18.0.0)
+- Cada container tem: tecnologia, responsabilidade, porta, tipo de comunicação
+- Padrões de design precisam de justificativa (não apenas nome)
+- Pipeline CI/CD deve ser concreto — passos reais e ferramentas
+- Rollback strategy obrigatória — "como voltar se der errado?"
+
+=============================================================================
+-->
+
+## Diagrama de Containers (C4 Nível 2)
+
+```
+<!-- Representação textual dos containers e suas conexões -->
+<!-- Usar formato: [Container] --protocolo--> [Container] -->
+```
+
+## Containers
+
+| Container | Tecnologia | Responsabilidade | Porta | Comunicação |
+|-----------|-----------|-----------------|-------|-------------|
+|           |           |                 |       |             |
+
+## Componentes Principais (C4 Nível 3)
+
+<!-- Repetir esta seção para cada container que tenha componentes internos relevantes -->
+
+### {{Container}}
+
+| Componente | Responsabilidade | Dependências internas | Dependências externas |
+|------------|-----------------|----------------------|----------------------|
+|            |                 |                      |                      |
+
+## Padrões de Comunicação
+
+### Síncrona (request/response)
+
+| De | Para | Protocolo | Formato | Observações |
+|----|------|-----------|---------|-------------|
+|    |      |           |         |             |
+
+### Assíncrona (eventos/filas)
+
+| Produtor | Tópico/Fila | Consumer | Formato | Garantia |
+|----------|-------------|----------|---------|----------|
+|          |             |          |         | at-least-once / exactly-once |
+
+## Padrões de Design Adotados
+
+| Padrão | Onde é usado | Justificativa | Ref decisão |
+|--------|-------------|---------------|-------------|
+|        |             |               |             |
+
+## Stack Principal
+
+| Camada | Tecnologia | Versão | Justificativa |
+|--------|-----------|--------|---------------|
+| Frontend | | | |
+| Backend | | | |
+| Banco de Dados | | | |
+| ORM/Query Builder | | | |
+| Autenticação | | | |
+| Testes | | | |
+| CI/CD | | | |
+
+<!-- Adicionar camadas conforme necessidade: Mobile, Cache, Fila, Monitoramento, etc. -->
+
+## Bibliotecas e Dependências por Camada
+
+<!-- Repetir bloco para cada camada com dependências relevantes -->
+
+### {{Camada}}
+
+| Pacote | Versão | Para quê |
+|--------|--------|----------|
+|        |        |          |
+
+## Ambientes
+
+| Ambiente | URL | Banco | Propósito | Branch |
+|----------|-----|-------|-----------|--------|
+| Local | `localhost:{{PORT}}` | local | Desenvolvimento | qualquer |
+| Staging | | | Testes e homologação | develop |
+| Produção | | | Usuários finais | main |
+
+## Deploy
+
+### Estratégia
+
+| Aspecto | Decisão |
+|---------|---------|
+| Plataforma | <!-- Docker? Serverless? VPS? Cloud provider? --> |
+| Orquestração | <!-- Kubernetes? ECS? PM2? --> |
+| Build | <!-- Docker multi-stage? Build nativo? --> |
+| Estratégia de deploy | <!-- Rolling? Blue-green? Canary? --> |
+
+### Pipeline CI/CD
+
+```
+push → lint → test → build → deploy(staging) → aprovação → deploy(prod)
+```
+
+| Etapa | Ferramenta | Trigger | Timeout |
+|-------|-----------|---------|---------|
+| Lint | <!-- eslint, ruff --> | push | |
+| Testes | <!-- jest, pytest --> | push | |
+| Build | <!-- docker build --> | push em main/develop | |
+| Deploy staging | <!-- CD tool --> | push em develop | |
+| Deploy produção | <!-- CD tool --> | aprovação manual | |
+
+### Rollback
+
+| Cenário | Procedimento | Responsável |
+|---------|-------------|-------------|
+| Bug em produção | <!-- Reverter deploy? Hotfix? --> | |
+| Migration com erro | <!-- Rollback da migration? --> | |
+| Serviço externo fora | <!-- Fallback? Circuit breaker? --> | |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |