synapos 2.5.0

package/.synapos/core/best-practices/dev/api-design.md

@@ -0,0 +1,274 @@
+---
+id: api-design
+version: "1.0.0"
+domain: [backend, fullstack]
+whenToUse: "Quando o squad projeta ou documenta APIs REST ou GraphQL"
+---
+
+# Design de API
+
+> Convenções para criar APIs REST e GraphQL consistentes, versionadas e fáceis de consumir.
+
+---
+
+## REST
+
+### Nomenclatura de Recursos
+
+Use **substantivos no plural** para recursos, nunca verbos:
+
+```
+✅ GET  /users
+✅ GET  /users/:id
+✅ POST /users
+✅ PUT  /users/:id
+✅ DELETE /users/:id
+
+❌ GET  /getUser
+❌ POST /createUser
+❌ DELETE /deleteUser/:id
+```
+
+### Hierarquia de Recursos
+
+```
+GET  /projects/:id/tasks          → lista tasks de um projeto
+POST /projects/:id/tasks          → cria task no projeto
+GET  /projects/:id/tasks/:taskId  → detalhe de task específica
+```
+
+Evite hierarquias com mais de 2 níveis — sinalize com `?filter=` ou recurso separado.
+
+### Métodos HTTP
+
+| Método | Uso | Idempotente? | Body? |
+|--------|-----|-------------|-------|
+| GET | Leitura | ✅ | ❌ |
+| POST | Criação | ❌ | ✅ |
+| PUT | Substituição total | ✅ | ✅ |
+| PATCH | Atualização parcial | ✅ | ✅ |
+| DELETE | Remoção | ✅ | ❌ |
+
+---
+
+## Códigos de Status HTTP
+
+### Sucesso (2xx)
+| Status | Quando usar |
+|--------|-------------|
+| `200 OK` | GET, PUT, PATCH bem-sucedidos |
+| `201 Created` | POST que cria recurso — inclua `Location` header |
+| `204 No Content` | DELETE bem-sucedido, PATCH sem corpo de resposta |
+
+### Erro do cliente (4xx)
+| Status | Quando usar |
+|--------|-------------|
+| `400 Bad Request` | Dados inválidos, validação falhou |
+| `401 Unauthorized` | Não autenticado — token ausente ou inválido |
+| `403 Forbidden` | Autenticado mas sem permissão |
+| `404 Not Found` | Recurso não existe |
+| `409 Conflict` | Conflito de estado — ex: email já cadastrado |
+| `422 Unprocessable Entity` | Sintaxe válida mas semanticamente incorreto |
+| `429 Too Many Requests` | Rate limit atingido |
+
+### Erro do servidor (5xx)
+| Status | Quando usar |
+|--------|-------------|
+| `500 Internal Server Error` | Erro inesperado no servidor |
+| `503 Service Unavailable` | Serviço temporariamente indisponível |
+
+---
+
+## Formato de Resposta
+
+### Sucesso — lista
+```json
+{
+  "data": [
+    { "id": "uuid", "name": "Ana", "email": "ana@example.com" }
+  ],
+  "pagination": {
+    "page": 1,
+    "pageSize": 20,
+    "total": 143,
+    "totalPages": 8
+  }
+}
+```
+
+### Sucesso — item único
+```json
+{
+  "data": {
+    "id": "uuid",
+    "name": "Ana",
+    "email": "ana@example.com",
+    "createdAt": "2026-03-23T10:00:00Z"
+  }
+}
+```
+
+### Erro
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Dados inválidos",
+    "details": [
+      { "field": "email", "message": "Email inválido" },
+      { "field": "name", "message": "Nome é obrigatório" }
+    ]
+  }
+}
+```
+
+### Convenções de campos
+- Datas: **ISO 8601** (`2026-03-23T10:00:00Z`)
+- IDs: **UUID v4** (evite IDs numéricos sequenciais expostos)
+- Campos monetários: **inteiro em centavos** (`1999` = R$ 19,99)
+- Case: **camelCase** para JSON
+
+---
+
+## Paginação
+
+### Offset-based (padrão)
+```
+GET /users?page=2&pageSize=20
+```
+
+Resposta inclui `pagination.total` para calcular páginas.
+
+### Cursor-based (grandes volumes, feeds em tempo real)
+```
+GET /notifications?cursor=eyJpZCI6MTIzfQ&limit=20
+```
+
+Resposta inclui `nextCursor` (null quando última página).
+
+### Quando usar cada um
+| Situação | Tipo |
+|----------|------|
+| Tabelas admin, relatórios | Offset |
+| Feeds, timelines, grande volume | Cursor |
+| Itens que mudam frequentemente | Cursor |
+
+---
+
+## Filtros e Ordenação
+
+```
+GET /users?role=admin&status=active
+GET /users?sort=createdAt&order=desc
+GET /users?search=ana
+GET /products?minPrice=100&maxPrice=500
+```
+
+---
+
+## Versionamento
+
+### Estratégia recomendada: URL path
+
+```
+/api/v1/users
+/api/v2/users
+```
+
+### Regras
+- Versão **MAJOR** na URL apenas quando há breaking change
+- Mantenha v-anterior ativa por pelo menos **6 meses** após lançamento da nova
+- Documente o que mudou entre versões
+- Comunique deprecation via header: `Deprecation: 2026-09-23`
+
+### Breaking changes (exigem nova versão)
+- Remoção de campo obrigatório
+- Mudança de tipo de campo
+- Remoção de endpoint
+- Mudança de comportamento de autenticação
+
+### Non-breaking changes (não exigem nova versão)
+- Adicionar campo opcional à resposta
+- Adicionar novo endpoint
+- Adicionar novo parâmetro de filtro opcional
+
+---
+
+## GraphQL
+
+### Convenções de Schema
+
+```graphql
+type User {
+  id: ID!
+  name: String!
+  email: String!
+  role: UserRole!
+  createdAt: DateTime!
+  posts: [Post!]!
+}
+
+enum UserRole {
+  ADMIN
+  MEMBER
+  VIEWER
+}
+
+type Query {
+  user(id: ID!): User
+  users(filter: UserFilter, pagination: PaginationInput): UserConnection!
+}
+
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
+}
+```
+
+### Padrões obrigatórios
+- Use **Input types** para mutations (não argumentos avulsos)
+- Use **Payload types** para retorno de mutations (permite adicionar campos sem breaking change)
+- Use **Connection pattern** para listas paginadas
+- Nunca exponha campos de senha ou dados sensíveis no schema
+
+### Erros em GraphQL
+```json
+{
+  "errors": [
+    {
+      "message": "Email já cadastrado",
+      "extensions": {
+        "code": "EMAIL_ALREADY_EXISTS",
+        "field": "email"
+      }
+    }
+  ],
+  "data": null
+}
+```
+
+### N+1 em GraphQL
+- Use **DataLoader** para batch de queries relacionadas
+- Implemente **query depth limiting** (máx 5–7 níveis)
+- Monitore queries lentas com APM
+
+---
+
+## Segurança
+
+- **Sempre use HTTPS** — sem exceções
+- **Autentique todos os endpoints** exceto os explicitamente públicos
+- **Rate limiting**: 100 req/min para usuários autenticados, 20 req/min para anônimos
+- **Valide e sanitize** todos os inputs no servidor
+- **Não exponha stack traces** em respostas de erro em produção
+- **Versione segredos** fora do código (env vars / secret manager)
+
+---
+
+## Documentação
+
+- Use **OpenAPI 3.x** para documentar REST
+- Inclua exemplos reais de request e response
+- Documente todos os códigos de erro possíveis
+- Mantenha docs atualizadas junto com o código (code-first ou schema-first)
+- Ferramentas: Swagger UI, Redoc, Scalar

package/.synapos/core/best-practices/dev/code-review.md

@@ -0,0 +1,138 @@
+---
+id: code-review
+version: "1.0.0"
+domain: [frontend, backend, fullstack, mobile]
+whenToUse: "Quando o squad faz review de código em qualquer linguagem"
+---
+
+# Guia de Code Review
+
+> Referência para conduzir reviews construtivos, eficientes e consistentes.
+
+---
+
+## Princípios
+
+- **Review é colaboração, não crítica pessoal** — o alvo é o código, não o autor
+- **Clareza sobre completude** — um review útil é melhor que um review perfeito que demora dias
+- **Contexto sempre** — entenda o objetivo do PR antes de avaliar as escolhas
+- **Automatize o óbvio** — lint, formatação e testes devem ser verificados por CI, não por humanos
+
+---
+
+## Categorias de Comentário
+
+Use prefixos para indicar a gravidade e intenção de cada comentário:
+
+| Prefixo | Significado | Bloqueia merge? |
+|---------|-------------|-----------------|
+| `BLOCKER:` | Problema que deve ser corrigido antes do merge | ✅ Sim |
+| `SUGGESTION:` | Melhoria recomendada, mas não obrigatória | ❌ Não |
+| `QUESTION:` | Dúvida legítima — pode ser falta de contexto | ❌ Não |
+| `PRAISE:` | Algo que merece reconhecimento explícito | ❌ Não |
+| `NITPICK:` | Preferência pessoal, baixíssima prioridade | ❌ Não |
+
+### Exemplos
+
+```
+BLOCKER: Esta query não tem índice em `user_id`. Em produção com volume vai travar.
+
+SUGGESTION: Extrair esse bloco para um custom hook `useFormValidation` melhoraria
+a legibilidade e facilitaria os testes.
+
+QUESTION: Por que optou por `useEffect` aqui em vez de `useMemo`? Há alguma
+dependência externa que precisa de side effect?
+
+PRAISE: Boa escolha em usar `AbortController` — o tratamento de cancelamento
+de fetch estava faltando há tempo.
+
+NITPICK: Prefiro `const` ao invés de `let` aqui, mas ambos funcionam.
+```
+
+---
+
+## Checklist do Reviewer
+
+### Lógica e Corretude
+- [ ] O código faz o que o PR descreve?
+- [ ] Edge cases e valores nulos são tratados?
+- [ ] Condições de corrida ou problemas de concorrência?
+- [ ] Reversibilidade: o PR pode ser revertido sem efeitos colaterais?
+
+### Qualidade e Manutenibilidade
+- [ ] O código é legível sem precisar de comentário explicativo?
+- [ ] Funções/métodos têm responsabilidade única?
+- [ ] Há duplicação que poderia ser extraída?
+- [ ] Nomes de variáveis e funções são descritivos e consistentes?
+
+### Performance
+- [ ] Há chamadas N+1 em loops?
+- [ ] Queries ao banco são otimizadas (índices, projeção de campos)?
+- [ ] Há operações custosas que poderiam ser cacheadas?
+
+### Segurança
+- [ ] Inputs do usuário são validados e sanitizados?
+- [ ] Dados sensíveis não são logados ou expostos?
+- [ ] Autenticação e autorização verificadas nos novos endpoints?
+
+### Testes
+- [ ] Os testes cobrem o caminho feliz?
+- [ ] Os testes cobrem casos de erro e edge cases relevantes?
+- [ ] Os testes são legíveis e descrevem o comportamento esperado?
+
+### Documentação
+- [ ] Mudanças de API estão documentadas?
+- [ ] Decisões não óbvias têm comentário ou ADR?
+
+---
+
+## Tom Construtivo
+
+### Faça
+- Explique o **porquê** da sua sugestão
+- Ofereça alternativas concretas quando apontar problemas
+- Reconheça explicitamente boas escolhas
+- Pergunte antes de assumir que é um erro
+
+### Evite
+- Comentários vagos: ~~"Isso está errado"~~ → diga o que está errado e por quê
+- Tom imperativo sem explicação: ~~"Muda isso"~~ → "Sugiro mudar X porque Y"
+- Reviews exaustivas sobre estilo que o linter deveria pegar
+- Ignorar o contexto do PR (deadline, constraint técnica, débito aceito)
+
+---
+
+## Fluxo de Review
+
+```
+Autor abre PR
+    ↓
+CI roda (lint + testes) — falha aqui bloqueia review
+    ↓
+Reviewer lê descrição + contexto
+    ↓
+Reviewer comenta com categorias claras
+    ↓
+Autor responde / corrige / justifica
+    ↓
+Reviewer aprova ou abre nova rodada (max 2 rodadas para BLOCKERs)
+    ↓
+Merge
+```
+
+### Tempo esperado
+- PRs pequenos (< 200 linhas): review em até 24h
+- PRs médios (200–500 linhas): review em até 48h
+- PRs grandes (> 500 linhas): considere quebrar o PR
+
+---
+
+## Tamanho de PR
+
+| Tamanho | Linhas | Qualidade do review |
+|---------|--------|---------------------|
+| Ótimo | < 200 | Alta — fácil de revisar completamente |
+| Aceitável | 200–500 | Média — revisor pode perder detalhes |
+| Problemático | > 500 | Baixa — dividir em PRs menores |
+
+> PRs grandes não são mais produtivos — são mais difíceis de revisar, mais difíceis de reverter e têm maior chance de conflito.

package/.synapos/core/best-practices/dev/git-workflow.md

@@ -0,0 +1,256 @@
+---
+id: git-workflow
+version: "1.0.0"
+domain: [frontend, backend, fullstack, mobile, devops]
+whenToUse: "Quando o squad trabalha com branches, commits e PRs"
+---
+
+# Git Workflow
+
+> Convenções de branching, commits semânticos, PRs e estratégia de merge.
+
+---
+
+## Branch Strategy
+
+### Modelo: GitHub Flow (recomendado para a maioria dos projetos)
+
+```
+main
+ ├── feat/auth-login
+ ├── feat/checkout-v2
+ ├── fix/payment-timeout
+ └── chore/upgrade-deps
+```
+
+**Regras:**
+- `main` é sempre deployável
+- Todo trabalho acontece em feature branches
+- Merge via PR com ao menos 1 aprovação
+- Branch de curta duração (idealmente < 3 dias)
+
+### Modelo: Git Flow (projetos com releases cadenciadas)
+
+```
+main        ← produção
+develop     ← integração contínua
+ ├── feat/  ← features
+ ├── fix/   ← bugfixes
+ ├── hotfix/← correções urgentes em prod
+ └── release/← preparação de release
+```
+
+Use quando: produto mobile com release na loja, projetos com janelas de deploy fixas.
+
+---
+
+## Nomenclatura de Branches
+
+```
+{tipo}/{descricao-curta}
+```
+
+| Tipo | Uso |
+|------|-----|
+| `feat/` | Nova funcionalidade |
+| `fix/` | Correção de bug |
+| `chore/` | Manutenção, deps, configs |
+| `refactor/` | Refatoração sem mudança de comportamento |
+| `test/` | Adição ou melhoria de testes |
+| `docs/` | Documentação |
+| `hotfix/` | Correção urgente em produção |
+
+### Exemplos
+
+```
+feat/user-authentication
+feat/checkout-pix-payment
+fix/cart-total-calculation
+fix/login-redirect-loop
+chore/upgrade-react-19
+refactor/extract-payment-service
+hotfix/payment-gateway-timeout
+```
+
+---
+
+## Commits Semânticos
+
+Formato: `{tipo}({escopo}): {descrição}`
+
+```
+feat(auth): adicionar autenticação via Google OAuth
+fix(cart): corrigir cálculo de desconto com cupom
+chore(deps): atualizar react para v19
+refactor(api): extrair camada de serviço de pagamentos
+test(checkout): adicionar testes E2E do fluxo de compra
+docs(api): documentar endpoints de usuário
+perf(dashboard): lazy load de gráficos pesados
+ci: configurar deploy automático para staging
+```
+
+### Tipos válidos
+
+| Tipo | Quando usar |
+|------|-------------|
+| `feat` | Nova funcionalidade |
+| `fix` | Correção de bug |
+| `chore` | Tarefas de manutenção, deps, scripts |
+| `refactor` | Refatoração sem mudança de comportamento |
+| `test` | Testes novos ou melhorados |
+| `docs` | Documentação |
+| `perf` | Melhoria de performance |
+| `ci` | Mudanças em CI/CD |
+| `build` | Build system, packaging |
+| `revert` | Reversão de commit anterior |
+
+### Regras para a mensagem
+- **Imperativo presente**: "adicionar" não "adicionei" ou "adicionando"
+- **Sem ponto final**
+- **Máx 72 caracteres** na primeira linha
+- Body opcional para contexto: o quê, por quê (não o como)
+
+```
+fix(auth): corrigir expiração de token em fuso UTC-3
+
+O token era validado em UTC mas comparado com timestamp local,
+causando logout prematuro para usuários no Brasil.
+
+Closes #342
+```
+
+---
+
+## Pull Requests
+
+### Antes de abrir o PR
+- [ ] Branch está atualizada com `main` (ou `develop`)
+- [ ] CI local passa (testes + lint)
+- [ ] Código auto-revisado (leia seu próprio diff antes de pedir review)
+- [ ] PR é pequeno e focado em um objetivo
+
+### Descrição do PR
+
+```markdown
+## O que esse PR faz
+Implementa autenticação via Google OAuth usando a estratégia Passport.js.
+
+## Por que
+Usuários solicitaram login social — reduz fricção de cadastro.
+
+## Como testar
+1. Configurar `.env` com `GOOGLE_CLIENT_ID` e `GOOGLE_CLIENT_SECRET`
+2. Acessar `/auth/google`
+3. Completar fluxo OAuth
+4. Verificar redirecionamento para dashboard
+
+## Checklist
+- [x] Testes passando
+- [x] Sem console.log esquecidos
+- [x] Variáveis de ambiente documentadas no .env.example
+```
+
+### Tamanho do PR
+
+| Tamanho | Linhas | Recomendação |
+|---------|--------|--------------|
+| Ideal | < 200 | Revisar no mesmo dia |
+| Aceitável | 200–400 | Revisar em até 24h |
+| Problemático | > 400 | Quebrar em PRs menores |
+
+---
+
+## Squash vs Merge vs Rebase
+
+| Estratégia | Quando usar | Resultado |
+|------------|-------------|-----------|
+| **Squash merge** | Feature branches | 1 commit limpo no main |
+| **Merge commit** | Release branches, histórico importante | Todos os commits preservados |
+| **Rebase** | Branches próprias antes do PR | Histórico linear, sem merge commits |
+
+### Recomendação padrão
+- Feature branches → **Squash merge** (histórico limpo no main)
+- Hotfixes → **Merge commit** (rastreabilidade de emergência)
+- Nunca force-push em `main` ou `develop`
+
+---
+
+## Proteção de Branch
+
+Configure no GitHub/GitLab:
+
+```yaml
+main:
+  - Require PR before merging
+  - Require at least 1 approval
+  - Require status checks: CI, lint, tests
+  - Dismiss stale approvals on new commits
+  - Restrict force-push
+```
+
+---
+
+## Git Hooks Recomendados
+
+Use **Husky** + **lint-staged**:
+
+```json
+{
+  "pre-commit": "lint-staged",
+  "commit-msg": "commitlint --edit $1"
+}
+```
+
+```json
+{
+  "lint-staged": {
+    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+    "*.{json,md,yaml}": ["prettier --write"]
+  }
+}
+```
+
+---
+
+## Resolução de Conflitos
+
+```bash
+# Atualizar branch com main antes do PR
+git fetch origin
+git rebase origin/main
+
+# Se conflito: resolver manualmente, depois
+git add .
+git rebase --continue
+
+# Em caso de confusão, abortar e recomeçar
+git rebase --abort
+```
+
+**Regras:**
+- Resolva conflitos na sua branch, não em `main`
+- Nunca resolva conflito em `main` diretamente
+- Em caso de conflito complexo, pair com o autor do código conflitante
+
+---
+
+## Fluxo Resumido
+
+```
+git checkout -b feat/minha-feature
+
+# ... trabalho ...
+
+git add src/feature.ts
+git commit -m "feat(feature): implementar nova funcionalidade"
+
+git fetch origin
+git rebase origin/main
+
+git push origin feat/minha-feature
+# → Abre PR no GitHub
+# → CI passa
+# → Code review aprovado
+# → Squash merge em main
+# → Branch deletada automaticamente
+```