synapos 2.5.0

package/.synapos/core/best-practices/dev/testing-strategy.md

@@ -0,0 +1,213 @@
+---
+id: testing-strategy
+version: "1.0.0"
+domain: [frontend, backend, fullstack, mobile]
+whenToUse: "Quando o squad escreve ou define estratégia de testes"
+---
+
+# Estratégia de Testes
+
+> Referência para definir cobertura, pirâmide de testes e abordagem por domínio.
+
+---
+
+## Pirâmide de Testes
+
+```
+        /\
+       /  \
+      / E2E \          ← Poucos, lentos, caros — validam fluxos críticos
+     /────────\
+    /Integration\      ← Médio volume — validam contratos e integrações reais
+   /──────────────\
+  /   Unit Tests   \   ← Muitos, rápidos, baratos — validam lógica isolada
+ /──────────────────\
+```
+
+### Distribuição recomendada
+
+| Nível | % do total | Foco |
+|-------|-----------|------|
+| Unit | 70% | Lógica pura, transformações, validações |
+| Integration | 20% | Módulos integrados, banco de dados real, APIs internas |
+| E2E | 10% | Fluxos críticos de negócio (login, checkout, onboarding) |
+
+---
+
+## Testes Unitários
+
+### Quando usar
+- Funções puras com lógica complexa
+- Transformações e cálculos
+- Validações de domínio
+- Componentes de UI isolados (comportamento, não visual)
+
+### Princípios
+- Um teste = um comportamento
+- Nomes descritivos: `deve retornar erro quando email é inválido`
+- Estrutura **AAA**: Arrange → Act → Assert
+- Sem dependências externas (use mocks para I/O)
+
+### Exemplo (TypeScript / Vitest)
+```typescript
+describe('calcularDesconto', () => {
+  it('deve aplicar 10% para compras acima de R$100', () => {
+    // Arrange
+    const valor = 150
+
+    // Act
+    const resultado = calcularDesconto(valor)
+
+    // Assert
+    expect(resultado).toBe(135)
+  })
+
+  it('deve retornar valor original para compras abaixo de R$100', () => {
+    expect(calcularDesconto(80)).toBe(80)
+  })
+})
+```
+
+---
+
+## Testes de Integração
+
+### Quando usar
+- Endpoints de API (request → response completo)
+- Queries ao banco de dados
+- Integrações com serviços externos (mockados ou reais em ambiente de teste)
+- Fluxos entre módulos do sistema
+
+### Princípios
+- Use banco de dados real em ambiente de teste (não mocks de DB)
+- Isole o estado entre testes (truncate tables, transactions rollback)
+- Teste o contrato (status code, formato da resposta, efeitos colaterais)
+
+### Exemplo (supertest / Node.js)
+```typescript
+describe('POST /api/users', () => {
+  it('deve criar usuário e retornar 201 com id', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ name: 'Ana', email: 'ana@test.com' })
+
+    expect(response.status).toBe(201)
+    expect(response.body).toMatchObject({
+      id: expect.any(String),
+      name: 'Ana',
+      email: 'ana@test.com',
+    })
+  })
+
+  it('deve retornar 400 quando email já existe', async () => {
+    await createUser({ email: 'ana@test.com' })
+
+    const response = await request(app)
+      .post('/api/users')
+      .send({ name: 'Ana 2', email: 'ana@test.com' })
+
+    expect(response.status).toBe(400)
+    expect(response.body.error).toMatch(/email já cadastrado/i)
+  })
+})
+```
+
+---
+
+## Testes de Contrato
+
+> Garantem que produtor e consumidor de uma API concordam com o formato dos dados.
+
+### Quando usar
+- APIs consumidas por múltiplos clientes (mobile + web + parceiros)
+- Microsserviços com contratos inter-serviço
+- Quando mudanças de API têm alto impacto
+
+### Ferramentas
+- **Pact** — consumer-driven contract testing
+- **OpenAPI + spectral** — validação de schema estático
+- **Zod / io-ts** — validação de schema em runtime
+
+### Estratégia mínima
+1. Documente o contrato esperado (OpenAPI / JSON Schema)
+2. Valide o contrato nos testes de integração
+3. Versione o contrato junto com o código
+
+---
+
+## Testes E2E
+
+### Quando usar
+- Fluxos críticos de negócio (autenticação, pagamento, onboarding)
+- Regressões de alto impacto
+- Smoke tests em produção
+
+### Princípios
+- Teste comportamento do usuário, não implementação
+- Use seletores semânticos (`getByRole`, `getByLabel`), nunca classes CSS
+- Cada teste deve ser independente (sem compartilhar estado)
+- Mantenha suíte pequena — E2E lento desincentiva uso
+
+### Ferramentas
+- **Playwright** — browser automation (recomendado)
+- **Cypress** — alternativa popular para web
+- **Detox** — testes E2E mobile (React Native)
+
+---
+
+## Cobertura de Código
+
+### Metas por tipo de projeto
+
+| Tipo | Cobertura mínima | Foco |
+|------|-----------------|------|
+| Biblioteca / SDK | 90%+ | Toda a superfície pública |
+| API crítica (pagamentos, auth) | 85%+ | Caminho feliz + erros |
+| Feature de produto | 70%+ | Lógica de negócio |
+| Prototipagem / PoC | Sem meta | Valor sobre cobertura |
+
+### Importante
+- Cobertura alta ≠ qualidade de teste
+- 80% com testes que validam comportamento real > 100% com testes triviais
+- Foque em cobertura de **branches**, não só de linhas
+
+---
+
+## Testes de Frontend
+
+### Componentes React (Testing Library)
+```typescript
+it('deve exibir mensagem de erro quando formulário é submetido vazio', async () => {
+  render(<LoginForm />)
+
+  await userEvent.click(screen.getByRole('button', { name: /entrar/i }))
+
+  expect(screen.getByText(/email obrigatório/i)).toBeInTheDocument()
+})
+```
+
+### Princípios
+- Teste comportamento visível ao usuário, não detalhes de implementação
+- Evite testar state interno do componente
+- Use `userEvent` em vez de `fireEvent` (mais realista)
+- Não teste implementação de bibliotecas de terceiros
+
+---
+
+## O que NÃO testar
+
+- Configuração de bibliotecas externas
+- Código gerado automaticamente
+- Simples getters/setters sem lógica
+- Detalhes de implementação que podem mudar
+
+---
+
+## Ferramentas por Stack
+
+| Stack | Unit | Integration | E2E |
+|-------|------|-------------|-----|
+| Node.js / TypeScript | Vitest / Jest | Supertest + Vitest | Playwright |
+| React | Vitest + Testing Library | — | Playwright |
+| React Native | Jest + RNTL | — | Detox |
+| Python | pytest | pytest + SQLAlchemy | — |

package/.synapos/core/best-practices/product/product-spec.md

@@ -0,0 +1,235 @@
+---
+id: product-spec
+version: "1.0.0"
+domain: [produto]
+whenToUse: "Quando o squad de produto escreve especificações"
+---
+
+# Product Spec
+
+> Estrutura padrão para especificações de produto: do problema à solução pronta para desenvolvimento.
+
+---
+
+## Estrutura Completa
+
+```
+1. Contexto e Problema
+2. Objetivo e Métricas de Sucesso
+3. Usuários Afetados
+4. Solução Proposta
+5. Requisitos Funcionais
+6. Requisitos Não Funcionais
+7. Critérios de Aceite
+8. Casos de Borda
+9. Fora de Escopo
+10. Dependências e Riscos
+11. Open Questions
+```
+
+---
+
+## 1. Contexto e Problema
+
+Responda:
+- **Situação atual**: como o usuário resolve esse problema hoje?
+- **Problema**: o que está errado ou faltando?
+- **Evidência**: dados, feedback de usuários, suporte, analytics
+
+```markdown
+## Contexto e Problema
+
+Usuários que esquecem a senha precisam contatar o suporte via email,
+o que gera ~200 tickets/mês e demora em média 4h para resolução.
+
+**Evidência:**
+- 200 tickets/mês de reset de senha (12% do total de suporte)
+- NPS de usuários que passaram pelo suporte: 28 (vs 72 geral)
+- Churn de 15% dos usuários que esperaram mais de 2h
+```
+
+---
+
+## 2. Objetivo e Métricas de Sucesso
+
+### Formato OKR mínimo
+
+```markdown
+## Objetivo
+Permitir que usuários recuperem acesso à conta sem intervenção humana.
+
+## Métricas de Sucesso (3 meses após lançamento)
+- Tickets de reset de senha: reduzir de 200 para < 20/mês
+- Tempo médio de recuperação de conta: de 4h para < 5min
+- NPS de usuários que usaram o fluxo: > 60
+```
+
+---
+
+## 3. Usuários Afetados
+
+```markdown
+## Personas Afetadas
+
+**Primária: Ana — usuária casual**
+- Acessa o app 1–2x por semana
+- Frequentemente esquece senhas
+- Baixa tolerância a fricção no login
+
+**Secundária: Carlos — usuário enterprise**
+- Gerencia 5 contas diferentes
+- Prefere segurança à conveniência
+- Usa autenticador 2FA
+```
+
+---
+
+## 4. Solução Proposta
+
+Descreva **o quê**, não o **como** (evite detalhes de implementação nesta seção).
+
+```markdown
+## Solução
+
+Fluxo self-service de recuperação de senha via email:
+
+1. Usuário clica em "Esqueci minha senha" na tela de login
+2. Informa o email cadastrado
+3. Recebe link de redefinição válido por 30 minutos
+4. Define nova senha e é autenticado automaticamente
+```
+
+Inclua wireframes ou referências visuais quando disponíveis.
+
+---
+
+## 5. Requisitos Funcionais
+
+Liste **o que o sistema deve fazer**, não como:
+
+```markdown
+## Requisitos Funcionais
+
+RF-01: O sistema deve enviar email de recuperação para o endereço cadastrado
+RF-02: O link de recuperação deve expirar em 30 minutos
+RF-03: Um link usado não pode ser reutilizado
+RF-04: O usuário deve ser autenticado automaticamente após redefinir a senha
+RF-05: O sistema deve mostrar indicador de força de senha durante a redefinição
+RF-06: O sistema deve bloquear tentativas após 5 links enviados em 1 hora
+```
+
+---
+
+## 6. Requisitos Não Funcionais
+
+```markdown
+## Requisitos Não Funcionais
+
+RNF-01: Email entregue em até 60 segundos (p95)
+RNF-02: Fluxo completo acessível (WCAG 2.1 AA)
+RNF-03: Links de recuperação com token criptograficamente seguro (min 32 bytes)
+RNF-04: Sem exposição de informação sobre existência de email no sistema
+```
+
+---
+
+## 7. Critérios de Aceite
+
+Formato: **Dado** [contexto], **quando** [ação], **então** [resultado esperado].
+
+```markdown
+## Critérios de Aceite
+
+**CA-01:** Dado usuário com email cadastrado,
+quando solicitar recuperação de senha,
+então deve receber email com link em até 60s.
+
+**CA-02:** Dado link de recuperação gerado,
+quando acessado após 30 minutos,
+então deve exibir mensagem "link expirado" e oferecer gerar novo.
+
+**CA-03:** Dado link de recuperação válido já utilizado,
+quando acessado novamente,
+então deve exibir mensagem "link já utilizado".
+
+**CA-04:** Dado email não cadastrado no sistema,
+quando usuário solicitar recuperação,
+então deve exibir mensagem genérica sem confirmar ou negar existência do email.
+
+**CA-05:** Dado usuário que tentou 5x em 1 hora,
+quando tentar solicitar nova recuperação,
+então deve ser bloqueado por 60 minutos com mensagem informativa.
+```
+
+---
+
+## 8. Casos de Borda
+
+Itens que precisam de comportamento definido, mas não são o caminho principal:
+
+```markdown
+## Casos de Borda
+
+- Email digitado com espaços ou letras maiúsculas → normalizar antes de buscar
+- Usuário clica no link em dispositivo diferente do que solicitou → permitido
+- Usuário solicita 2 links em sequência → apenas o mais recente deve ser válido
+- Email do usuário mudou desde o cadastro → usar email atual cadastrado no sistema
+- Conta desativada/bloqueada → não enviar email, exibir mensagem de suporte
+- Domínio de email com ponto extra (usuario@gmail..com) → validar formato antes de enviar
+```
+
+---
+
+## 9. Fora de Escopo
+
+Deixe explícito o que **não** está incluído para alinhar expectativas:
+
+```markdown
+## Fora de Escopo (v1)
+
+- Recuperação via SMS / WhatsApp (próxima versão)
+- Autenticação biométrica como fallback
+- Histórico de senhas anteriores
+- Notificação de segurança por email ao alterar senha
+```
+
+---
+
+## 10. Dependências e Riscos
+
+```markdown
+## Dependências
+- Serviço de email (SendGrid) deve estar configurado para o novo template
+- Backend precisa de nova tabela `password_reset_tokens`
+- Design system: componente de "força de senha" ainda não existe
+
+## Riscos
+| Risco | Probabilidade | Impacto | Mitigação |
+|-------|--------------|---------|-----------|
+| Emails caindo em spam | Média | Alto | Configurar SPF/DKIM antes do lançamento |
+| Rate limit insuficiente (abuse) | Baixa | Médio | Monitorar nas primeiras 2 semanas |
+```
+
+---
+
+## 11. Open Questions
+
+```markdown
+## Open Questions
+
+- [ ] Devemos notificar o usuário por email quando a senha for alterada com sucesso? (segurança vs ruído)
+- [ ] Qual o comportamento para usuários que fazem login via Google OAuth? (não têm senha cadastrada)
+- [ ] Precisamos de log de auditoria dos resets? (compliance)
+```
+
+---
+
+## Checklist Antes de Enviar para Dev
+
+- [ ] Critérios de aceite cobrem o caminho feliz?
+- [ ] Casos de borda mapeados e com comportamento definido?
+- [ ] "Fora de escopo" explícito para evitar scope creep?
+- [ ] Métricas de sucesso são mensuráveis?
+- [ ] Open questions resolvidas ou com responsável definido?
+- [ ] Design (wireframe/protótipo) linkado ou anexado?
+- [ ] Revisado por alguém de eng antes de enviar?

package/.synapos/core/best-practices/product/technical-writing.md

@@ -0,0 +1,264 @@
+---
+id: technical-writing
+version: "1.0.0"
+domain: [produto, backend, frontend]
+whenToUse: "Quando o squad produz documentação técnica ou de produto"
+---
+
+# Technical Writing
+
+> Guia para escrever ADRs, decisions logs, handoffs e documentação técnica com clareza e estrutura.
+
+---
+
+## Princípios
+
+- **Escreva para o leitor futuro** — você em 6 meses, novo membro do time, outro squad
+- **Contexto antes de decisão** — explique o problema antes de apresentar a solução
+- **Registre o que foi rejeitado** — alternativas descartadas são tão valiosas quanto a escolha feita
+- **Documentação boa é manutenível** — curta e atualizada > longa e desatualizada
+- **Estrutura facilita leitura** — use headers, listas e tabelas em vez de parágrafos densos
+
+---
+
+## ADR — Architecture Decision Record
+
+> Registra decisões arquiteturais significativas: contexto, opções consideradas e escolha feita.
+
+### Quando escrever
+- Mudança de stack ou biblioteca principal
+- Decisão de design de API ou banco de dados
+- Escolha de padrão arquitetural (ex: monolito → microsserviços)
+- Qualquer decisão que você terá que explicar para novos membros
+
+### Template
+
+```markdown
+# ADR-{NNN}: {Título da Decisão}
+
+**Data:** YYYY-MM-DD
+**Status:** Proposto | Aceito | Deprecado | Substituído por ADR-XXX
+**Decisores:** {nomes ou times envolvidos}
+
+## Contexto
+
+{Descreva o problema ou situação que forçou essa decisão.
+Inclua restrições técnicas, de negócio ou de time.}
+
+## Opções Consideradas
+
+### Opção 1: {nome}
+**Prós:** ...
+**Contras:** ...
+
+### Opção 2: {nome}
+**Prós:** ...
+**Contras:** ...
+
+### Opção 3: {nome}
+**Prós:** ...
+**Contras:** ...
+
+## Decisão
+
+Escolhemos a **Opção {N}** porque {justificativa principal}.
+
+## Consequências
+
+**Positivas:**
+- ...
+
+**Negativas / Trade-offs:**
+- ...
+
+**Neutras:**
+- ...
+
+## Notas
+
+{Referências, links, discussões relacionadas}
+```
+
+### Exemplo Real
+
+```markdown
+# ADR-003: Adotar PostgreSQL em vez de MongoDB
+
+**Data:** 2026-03-23
+**Status:** Aceito
+**Decisores:** Time de Backend, CTO
+
+## Contexto
+
+Nossa estrutura de dados para transações financeiras tem relacionamentos
+complexos entre usuários, cobranças e pagamentos. O schema variável do
+MongoDB está causando inconsistências de dados em produção e dificultando
+queries de relatório.
+
+## Opções Consideradas
+
+### Opção 1: PostgreSQL
+**Prós:** Transações ACID, joins eficientes, schema estrito evita dados inconsistentes
+**Contras:** Migração de dados existentes, curva de aprendizado para queries complexas
+
+### Opção 2: Manter MongoDB com schema validation
+**Prós:** Zero migração, time já conhece
+**Contras:** Validação fraca, joins custosos via $lookup, histórico de inconsistências
+
+## Decisão
+
+Escolhemos **PostgreSQL** porque a consistência de dados é crítica para
+produto financeiro e os problemas atuais com MongoDB são estruturais, não operacionais.
+
+## Consequências
+
+**Positivas:** Queries de relatório 10x mais simples, zero inconsistências de schema
+**Negativas:** 2 semanas de migração, 1 sprint de adaptação do time
+```
+
+---
+
+## Decisions Log
+
+> Registro contínuo de decisões do dia a dia — menos formal que ADR, mais rastreável que Slack.
+
+### Quando usar
+- Decisões de product que não chegam a ser ADR
+- Mudanças de escopo, priorização, trade-offs aceitos
+- Qualquer "por que fizemos assim?"
+
+### Template
+
+```markdown
+# Decisions Log — {Squad ou Projeto}
+
+---
+
+## {YYYY-MM-DD} — {Título da decisão}
+
+**Decidido por:** {nome(s)}
+**Contexto:** {1–3 linhas do problema}
+**Decisão:** {o que foi decidido}
+**Motivo:** {por que essa opção}
+**Trade-off aceito:** {o que deixamos de fora ou comprometemos}
+**Revisão:** {quando reavaliar, se aplicável}
+
+---
+```
+
+### Exemplo
+
+```markdown
+## 2026-03-23 — Lançar sem notificação por SMS na v1
+
+**Decidido por:** Priscila (PM), Bruno (Tech Lead)
+**Contexto:** SMS aumentaria cobertura para usuários sem acesso estável a email,
+mas o provedor de SMS custa R$0,15/msg e precisamos validar adoção primeiro.
+**Decisão:** Lançar v1 apenas com email. SMS entra no roadmap para v1.2.
+**Motivo:** Reduzir custo operacional antes de validar demanda real.
+**Trade-off aceito:** Usuários sem acesso a email não serão atendidos nesta versão.
+**Revisão:** Após 90 dias — avaliar volume de tickets pedindo SMS.
+```
+
+---
+
+## Handoff Document
+
+> Transfere contexto de um squad para o próximo (dev, QA, suporte, outro time).
+
+### Estrutura
+
+```markdown
+# Handoff — {Feature ou Projeto}
+
+**Data:** YYYY-MM-DD
+**De:** {squad / pessoa}
+**Para:** {squad / pessoa}
+**Versão:** {versão que está sendo entregue}
+
+## O que foi construído
+
+{Descrição clara e objetiva da feature ou sistema entregue}
+
+## Como funciona
+
+{Fluxo principal em passos ou diagrama}
+
+## Onde está
+
+| Artefato | Localização |
+|----------|-------------|
+| Código | {link ou path} |
+| Deploy | {ambiente, URL} |
+| Documentação | {link} |
+| Designs | {link Figma} |
+
+## O que testar (QA Checklist)
+
+- [ ] Caminho feliz: {descrever}
+- [ ] Casos de erro: {descrever}
+- [ ] Casos de borda: {listar}
+
+## Configurações necessárias
+
+{Env vars, feature flags, permissões, dependências externas}
+
+## Limitações conhecidas
+
+{Bugs conhecidos, débito técnico aceito, limitações de escopo}
+
+## Open Questions / Próximos passos
+
+- [ ] {item não resolvido com responsável}
+```
+
+---
+
+## Clareza e Estrutura
+
+### Escrita objetiva
+
+```markdown
+❌ "O sistema foi desenvolvido de forma a possibilitar que os usuários
+    possam realizar a recuperação de suas senhas de acesso através de
+    um processo automatizado via email."
+
+✅ "Usuários podem redefinir a senha via email sem interação do suporte."
+```
+
+### Use estrutura visual
+
+```markdown
+❌ "A feature tem três estados possíveis: ativo que significa que está
+    funcionando normalmente, pausado que significa que foi suspenso
+    temporariamente e inativo que foi encerrado."
+
+✅ **Estados da feature:**
+   - **Ativo** — funcionando normalmente
+   - **Pausado** — suspenso temporariamente
+   - **Inativo** — encerrado
+```
+
+### Hierarquia de headers
+
+```
+# Título do documento
+## Seção principal
+### Subseção
+#### Detalhe (usar com moderação)
+```
+
+---
+
+## Checklist de Qualidade
+
+Antes de entregar qualquer documento técnico:
+
+- [ ] O problema está claro antes da solução?
+- [ ] O documento responde "por quê", não só "o quê"?
+- [ ] Alternativas rejeitadas estão documentadas?
+- [ ] Está escrito para o leitor certo (eng? produto? suporte?)?
+- [ ] Sem jargão não explicado para o público-alvo?
+- [ ] Links e referências funcionam?
+- [ ] Data e autoria registrados?
+- [ ] Precisa de revisão por outra pessoa antes de publicar?