forjajs 5.0.1 → 5.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +114 -2
- package/README.md +40 -5
- package/README.pt-BR.md +42 -4
- package/boilerplates/02-saas-starter/README.md +58 -293
- package/boilerplates/02-saas-starter/backend/.env.example +13 -0
- package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
- package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
- package/boilerplates/02-saas-starter/backend/package.json +32 -73
- package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
- package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
- package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
- package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
- package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
- package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
- package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
- package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
- package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
- package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
- package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
- package/boilerplates/README.md +9 -10
- package/dist/apps/cli/src/index.d.ts +0 -1
- package/dist/apps/cli/src/index.js +43 -32
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
- package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
- package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
- package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
- package/dist/apps/server/src/forja-nest.module.js +55 -0
- package/dist/apps/server/src/main.d.ts +21 -4
- package/dist/apps/server/src/main.js +79 -57
- package/dist/apps/server/src/task-planning-service.d.ts +29 -0
- package/dist/apps/server/src/task-planning-service.js +195 -0
- package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
- package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
- package/dist/bin/forja.js +3 -2
- package/dist/bin/init-project.js +1 -0
- package/dist/lib/agent-evals.d.ts +138 -0
- package/dist/lib/agent-evals.js +349 -0
- package/dist/lib/cli-output.js +14 -2
- package/dist/lib/code-context.d.ts +33 -5
- package/dist/lib/code-context.js +70 -5
- package/dist/lib/context-builder.d.ts +49 -4
- package/dist/lib/context-builder.js +114 -47
- package/dist/lib/core/coverage-gate.d.ts +59 -0
- package/dist/lib/core/coverage-gate.js +58 -0
- package/dist/lib/core/doc-graph.d.ts +38 -0
- package/dist/lib/core/doc-graph.js +83 -0
- package/dist/lib/core/health.js +286 -5
- package/dist/lib/core/journey.js +36 -0
- package/dist/lib/core/registry.js +81 -6
- package/dist/lib/docs-reference.d.ts +35 -0
- package/dist/lib/docs-reference.js +57 -0
- package/dist/lib/generators/memory-generator.d.ts +0 -11
- package/dist/lib/generators/memory-generator.js +5 -161
- package/dist/lib/generators/readme-generator.js +1 -1
- package/dist/lib/llm/json-output.d.ts +14 -0
- package/dist/lib/llm/json-output.js +77 -0
- package/dist/lib/project-wiring.d.ts +8 -0
- package/dist/lib/project-wiring.js +79 -3
- package/dist/lib/session-memory.d.ts +38 -0
- package/dist/lib/session-memory.js +206 -0
- package/dist/lib/spec-trace.d.ts +46 -0
- package/dist/lib/spec-trace.js +184 -0
- package/dist/lib/validators/structure-validator.js +0 -1
- package/dist/packages/adapter-nest/src/index.d.ts +2 -1
- package/dist/packages/adapter-nest/src/index.js +59 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
- package/dist/packages/adapter-sqlite/src/index.js +61 -1
- package/dist/packages/context/src/index.d.ts +2 -0
- package/dist/packages/context/src/index.js +36 -15
- package/dist/packages/contracts/src/index.d.ts +64 -0
- package/dist/packages/core/src/index.d.ts +9 -1
- package/dist/packages/core/src/index.js +28 -3
- package/dist/packages/graph/src/index.js +14 -5
- package/dist/packages/llm/src/index.js +12 -2
- package/dist/packages/mcp/src/index.d.ts +8 -0
- package/dist/packages/mcp/src/index.js +12 -1
- package/dist/packages/observability/src/index.d.ts +11 -0
- package/dist/packages/observability/src/index.js +3 -0
- package/dist/packages/orchestration/src/index.d.ts +15 -1
- package/dist/packages/orchestration/src/index.js +127 -21
- package/dist/packages/planner/src/index.d.ts +7 -1
- package/dist/packages/planner/src/index.js +67 -10
- package/dist/packages/planner/src/proposal-store.d.ts +30 -0
- package/dist/packages/planner/src/proposal-store.js +109 -0
- package/dist/packages/policy/src/index.d.ts +9 -16
- package/dist/packages/policy/src/index.js +114 -31
- package/dist/packages/runtime/src/index.d.ts +16 -2
- package/dist/packages/runtime/src/index.js +176 -61
- package/dist/scripts/build-smart-context.d.ts +2 -0
- package/dist/scripts/build-smart-context.js +12 -3
- package/dist/scripts/code-context.d.ts +3 -1
- package/dist/scripts/code-context.js +13 -3
- package/dist/scripts/coverage-gate.d.ts +2 -0
- package/dist/scripts/coverage-gate.js +101 -0
- package/dist/scripts/eval-agents.d.ts +11 -0
- package/dist/scripts/eval-agents.js +96 -0
- package/dist/scripts/gen-commands-doc.d.ts +2 -0
- package/dist/scripts/gen-commands-doc.js +18 -0
- package/dist/scripts/hook-session-memory.d.ts +9 -0
- package/dist/scripts/hook-session-memory.js +20 -0
- package/dist/scripts/hook-session-start.js +34 -0
- package/dist/scripts/llm-fit.js +23 -1
- package/dist/scripts/spec-trace.d.ts +10 -0
- package/dist/scripts/spec-trace.js +73 -0
- package/dist/scripts/sync-universal-memory.js +69 -4
- package/dist/scripts/token-benchmark.d.ts +33 -1
- package/dist/scripts/token-benchmark.js +179 -5
- package/dist/scripts/token-economy.js +3 -1
- package/dist/scripts/tools-doctor.d.ts +16 -1
- package/dist/scripts/tools-doctor.js +58 -17
- package/docs/commands.md +155 -0
- package/docs/fluxo.md +11 -7
- package/docs/init-project.md +3 -1
- package/docs/llm-fit-loop.md +36 -0
- package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
- package/docs/produto/factsheet-marketing.md +7 -5
- package/docs/produto/roteiro-demo.md +14 -5
- package/docs/quick-reference.md +3 -3
- package/docs/token-optimization.md +10 -6
- package/memory/90-decisions/0088-templates-validados.md +3 -0
- package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
- package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
- package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
- package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
- package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
- package/package.json +4 -2
- package/specs/avaliacoes-de-agentes/spec.md +52 -0
- package/specs/criterios-ligados-a-testes/spec.md +42 -0
- package/specs/memoria-de-sessao/spec.md +48 -0
- package/specs/skills-do-projeto/plan.md +40 -0
- package/specs/skills-do-projeto/spec.md +63 -0
- package/specs/skills-do-projeto/tasks.md +27 -0
- package/specs/v6-agent-runtime-portable/spec.md +83 -0
- package/specs/v6-core-consolidation/spec.md +70 -0
- package/specs/v6-docs-drift/spec.md +85 -0
- package/specs/v6-quality-gates/spec.md +99 -0
- package/specs/v6-token-economy/spec.md +84 -0
- package/templates/evals/agents/adr.json +25 -0
- package/templates/evals/agents/memoria.json +32 -0
- package/templates/evals/agents/proxima-acao.json +29 -0
- package/templates/evals/agents/spec-nova.json +26 -0
- package/templates/evals/agents/teste-do-criterio.json +29 -0
- package/templates/project/AGENTS.md +16 -0
- package/templates/project/CLAUDE.md +3 -2
- package/templates/project/agents/context-engineer.md +3 -0
- package/templates/project/agents/governance.md +3 -0
- package/templates/project/agents/marketing.md +3 -0
- package/templates/project/agents/orchestrator.md +3 -0
- package/templates/project/agents/product.md +3 -0
- package/templates/project/agents/sdd-architect.md +3 -0
- package/templates/project/skills/README.md +14 -0
- package/templates/project/skills/accessibility-review/SKILL.md +89 -0
- package/templates/project/skills/api-design/SKILL.md +77 -0
- package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
- package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
- package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
- package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
- package/templates/project/skills/commit-message/SKILL.md +143 -0
- package/templates/project/skills/data-migrations/SKILL.md +88 -0
- package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
- package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
- package/templates/project/skills/domain-modeling/SKILL.md +120 -0
- package/templates/project/skills/event-storming/SKILL.md +95 -0
- package/templates/project/skills/executive-writing/SKILL.md +99 -0
- package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
- package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
- package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
- package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
- package/templates/project/skills/observability/SKILL.md +93 -0
- package/templates/project/skills/product-evaluation/SKILL.md +130 -0
- package/templates/project/skills/prompt-spec/SKILL.md +83 -0
- package/templates/project/skills/pull-request/SKILL.md +101 -0
- package/templates/project/skills/query-performance/SKILL.md +83 -0
- package/templates/project/skills/release-checklist/SKILL.md +106 -0
- package/templates/project/skills/release-notes/SKILL.md +87 -0
- package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
- package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
- package/templates/project/skills/technical-spike/SKILL.md +101 -0
- package/templates/project/skills/testing/SKILL.md +109 -0
- package/templates/project/skills/threat-modeling/SKILL.md +87 -0
- package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
- package/templates/project/skills/ts-code-review/SKILL.md +121 -0
- package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
- package/templates/project/skills/ts-testing/SKILL.md +89 -0
- package/templates/project/skills/web-performance/SKILL.md +72 -0
- package/boilerplates/02-saas-starter/.env.example +0 -25
- package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
- package/boilerplates/02-saas-starter/INFO.md +0 -252
- package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
- package/boilerplates/02-saas-starter/START-HERE.md +0 -259
- package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
- package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
- package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
- package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
- package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
- package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
- package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
- package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
- package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
- package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
- package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
- package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
- package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
- package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
- package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
- package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
- package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
- package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
- package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
- package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
- package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
- package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
- package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
- package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
- package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
- package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
- package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
- package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dependency-upgrade
|
|
3
|
+
description: Use quando atualizar dependências de um projeto (pacotes npm, runtime, frameworks): inventaria o que está desatualizado e vulnerável, separa atualizações compatíveis das incompatíveis, lê os changelogs, aplica um major por vez com os testes como gate, resolve conflitos de peer sem forçar, e registra o que ficou para trás e por quê.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Atualização de Dependências
|
|
7
|
+
|
|
8
|
+
Atualizar dependências é trocar código que você não escreveu por outro código que você não escreveu. Feito de uma vez, um erro no meio de vinte atualizações não tem culpado. Feito um major por vez, com os testes rodando entre cada um, toda quebra tem endereço.
|
|
9
|
+
|
|
10
|
+
A saída padrão é um **plano de atualização**. Instale e altere arquivos só quando o usuário pedir.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: `package.json`, o lockfile, `engines`, o CI e a suíte de testes (`testing`).
|
|
15
|
+
- O gerenciador de pacotes do projeto (npm, pnpm, yarn) e o lockfile dele. Nunca misture gerenciadores.
|
|
16
|
+
- Toda atualização incompatível tem o changelog ou o guia de migração lido antes, não depois de quebrar.
|
|
17
|
+
|
|
18
|
+
## Inventarie
|
|
19
|
+
|
|
20
|
+
1. `npm outdated` (ou `pnpm outdated`): atual, desejada (dentro do intervalo) e mais recente.
|
|
21
|
+
2. `npm audit` (ou `osv-scanner`): vulnerabilidades, com severidade e se há correção.
|
|
22
|
+
3. Para cada major disponível: o changelog ou guia de migração, e as dependências que exigem uma versão específica (peer dependencies).
|
|
23
|
+
4. O runtime: a versão de Node em `engines`, no CI e nos ambientes; as versões que o framework exige.
|
|
24
|
+
|
|
25
|
+
## Classifique
|
|
26
|
+
|
|
27
|
+
| Tipo | Exemplo | Como tratar |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| Patch/minor dentro do intervalo | `5.90.5 → 5.104.1` | Em lote, com a suíte completa |
|
|
30
|
+
| Correção de segurança | `npm audit fix` | Prioridade; sem `--force` |
|
|
31
|
+
| Major isolado | `typescript 6 → 7` | Um por vez: ler o guia, atualizar, corrigir, testar, commitar |
|
|
32
|
+
| Major em cadeia | framework que exige outro major (`@nestjs/* 11 → 12` junto com `rxjs`, `typeorm`) | Juntos, na ordem que o guia indicar, num commit |
|
|
33
|
+
| Mudança de paradigma | pacote que virou ESM-only, troca de executor de testes | Tratar como migração planejada, com spike se necessário (`technical-spike`) |
|
|
34
|
+
|
|
35
|
+
## Aplique
|
|
36
|
+
|
|
37
|
+
1. **Linha de base verde**: rode build, testes e lint antes de mexer. Uma suíte vermelha antes da atualização esconde o que a atualização quebrou.
|
|
38
|
+
2. **Compatíveis em lote**: atualize os patches e minors, rode a suíte, commit.
|
|
39
|
+
3. **Majors um a um**, cada um com o próprio commit: leia o guia, atualize, corrija o que o compilador e os testes apontarem, rode a suíte completa (inclusive os testes de integração e o build de produção).
|
|
40
|
+
4. **Conflitos de peer**: entenda quem exige o quê (`npm ls <pacote>`, `npm explain <pacote>`). Prefira esperar a versão compatível, ou declarar um `overrides` explícito e comentado, a usar `--force` ou `--legacy-peer-deps`, que escondem o conflito.
|
|
41
|
+
5. **Ferramentas que não acompanharam**: quando um ecossistema ainda não suporta o major novo (por exemplo, um executor de testes que exige o compilador anterior), fique na última versão suportada e registre o motivo e o gatilho para revisitar.
|
|
42
|
+
6. **Scripts de instalação**: verifique se pacotes nativos ainda instalam onde scripts de instalação estão bloqueados (npm 11+), e se trazem binários prontos.
|
|
43
|
+
7. **Teste o que o usuário roda**: além da suíte, o build de produção, a aplicação subindo e o fluxo principal funcionando. Para bibliotecas, instale o pacote empacotado num projeto limpo.
|
|
44
|
+
|
|
45
|
+
## Formato
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
## Inventário
|
|
49
|
+
| Pacote | Atual | Alvo | Tipo | Notas (changelog, peer, segurança) |
|
|
50
|
+
|
|
51
|
+
## Plano
|
|
52
|
+
| # | Passo | Pacotes | Verificação | Commit |
|
|
53
|
+
|
|
54
|
+
## Ficou para trás
|
|
55
|
+
| Pacote | Versão mantida | Motivo | Gatilho para revisitar |
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Próximo
|
|
59
|
+
|
|
60
|
+
- `testing`: a suíte completa é o gate de cada passo.
|
|
61
|
+
- `commit-message`: um commit `build(deps)` por passo; `!` quando a atualização muda o contrato do projeto.
|
|
62
|
+
- `release-notes`: atualizações que os usuários percebem (runtime mínimo, comportamento) entram nas notas.
|
|
63
|
+
|
|
64
|
+
## No Forja
|
|
65
|
+
|
|
66
|
+
No Forja, depois de cada passo rode também `forja tools:doctor` e `forja project:wire --check` (atualizações podem mudar o runtime que os hooks e o MCP usam). Uma mudança de paradigma (pacote que virou ESM-only, troca do executor de testes) vira ADR em `memory/90-decisions/`, e o que ficou para trás entra na seção "Evidências e estado real" da spec da atualização.
|
|
67
|
+
|
|
68
|
+
## Evite
|
|
69
|
+
|
|
70
|
+
- Atualizar tudo de uma vez e depurar o resultado.
|
|
71
|
+
- `npm audit fix --force` ou `--legacy-peer-deps` para calar um conflito.
|
|
72
|
+
- Atualizar major sem ler o guia de migração.
|
|
73
|
+
- Partir de uma suíte que já estava vermelha.
|
|
74
|
+
- Considerar pronto porque o `npm install` terminou sem erro.
|
|
75
|
+
- Deixar uma dependência para trás sem registrar o motivo.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: docker-compose-review
|
|
3
|
+
description: Use quando escrever ou revisar arquivos do Docker Compose e Dockerfiles: verifica healthchecks e ordem de inicialização, redes e portas expostas, volumes, segredos, limites de recursos, higiene das imagens e paridade entre desenvolvimento e produção.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Revisão de Docker Compose
|
|
7
|
+
|
|
8
|
+
Arquivos Compose costumam começar como conveniência do desenvolvedor e, sem alarde, viram o mais próximo que existe de uma especificação de produção. A revisão verifica se os serviços sobem na ordem certa, expõem só o que devem, guardam os dados onde é seu lugar e se comportam em desenvolvimento como vão se comportar em produção.
|
|
9
|
+
|
|
10
|
+
A saída padrão é uma **tabela de achados e uma matriz de paridade**. Edite arquivos só quando o usuário pedir.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Escopo: `compose.yaml` / `docker-compose*.yml`, arquivos de override, os Dockerfiles que eles constroem, `.env.example`, e o que descreve a produção (manifests Kubernetes, um compose de produção, a documentação de deploy).
|
|
15
|
+
- Sintaxe da Compose Specification (sem `version:` no topo).
|
|
16
|
+
- Todo achado cita `arquivo:linha` e um motivo.
|
|
17
|
+
- Configuração de produção desconhecida vai para **Perguntas em aberto**; sem ela, a paridade não pode ser avaliada.
|
|
18
|
+
|
|
19
|
+
## Checklist
|
|
20
|
+
|
|
21
|
+
**Inicialização e saúde**
|
|
22
|
+
- Cada serviço de longa duração tem um `healthcheck` que testa a prontidão (por exemplo, `pg_isready`, um `/healthz` HTTP), com `interval`, `timeout`, `retries` e `start_period`.
|
|
23
|
+
- `depends_on` usa `condition: service_healthy` (ou `service_completed_successfully` para jobs de migração). `depends_on` simples só ordena a subida, não espera.
|
|
24
|
+
- As migrações rodam como um serviço ou passo de execução única, não dentro do entrypoint da aplicação em toda réplica.
|
|
25
|
+
- A aplicação continua tentando reconectar: healthchecks não substituem resiliência.
|
|
26
|
+
- Política de `restart:` declarada.
|
|
27
|
+
|
|
28
|
+
**Redes e portas**
|
|
29
|
+
- Só os pontos de entrada publicam portas. Bancos e caches ficam em redes internas.
|
|
30
|
+
- Portas publicadas ligadas a `127.0.0.1` em desenvolvimento quando a exposição não é necessária.
|
|
31
|
+
- Redes separadas quando grupos de serviços não devem se falar.
|
|
32
|
+
|
|
33
|
+
**Volumes e dados**
|
|
34
|
+
- Volumes nomeados para dados (bancos); bind mounts só para código-fonte em desenvolvimento.
|
|
35
|
+
- Nenhum dado gravado na camada do container.
|
|
36
|
+
- Scripts de inicialização e dados de seed são idempotentes.
|
|
37
|
+
|
|
38
|
+
**Configuração e segredos**
|
|
39
|
+
- Configuração por ambiente, com `.env.example` documentando cada variável. O `.env` real fica fora do git.
|
|
40
|
+
- Segredos via `secrets:` ou o cofre de segredos da plataforma, nunca embutidos em imagens, `ARG`s ou arquivos versionados.
|
|
41
|
+
- Nada de credenciais de produção em arquivos de desenvolvimento.
|
|
42
|
+
|
|
43
|
+
**Imagens**
|
|
44
|
+
- Imagens base fixadas numa versão (e num digest em produção). Nada de `latest`.
|
|
45
|
+
- Builds multi-stage; imagem final mínima (distroless ou slim); para Node, só o build gerado e as dependências de produção (`npm ci --omit=dev`), nunca o toolchain de desenvolvimento nem source maps que você não distribui.
|
|
46
|
+
- Roda como um `USER` não root. Sistema de arquivos raiz somente leitura onde for possível.
|
|
47
|
+
- `.dockerignore` exclui `.git`, arquivos de ambiente locais e saídas de build.
|
|
48
|
+
- Ordem das camadas maximiza o cache: `package.json` + lockfile e o passo de instalação antes do código-fonte.
|
|
49
|
+
|
|
50
|
+
**Recursos**
|
|
51
|
+
- Limites de memória e CPU nos serviços que podem disparar. Rotação de logs configurada no driver de log.
|
|
52
|
+
|
|
53
|
+
## Paridade dev/prod
|
|
54
|
+
|
|
55
|
+
A mesma imagem (construída uma vez) roda em todo lugar; só a configuração muda. Os acréscimos de desenvolvimento (hot reload, depuradores, bind mounts, painéis de administração) ficam em `compose.override.yaml` ou em profiles, não no arquivo base. Os serviços de apoio usam a mesma versão principal da produção (Postgres 16 localmente se a produção roda 16).
|
|
56
|
+
|
|
57
|
+
## Formato
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
## Achados
|
|
61
|
+
| # | Arquivo:linha | Categoria | Severidade | Problema | Correção |
|
|
62
|
+
|---|---|---|---|---|---|
|
|
63
|
+
|
|
64
|
+
## Matriz de paridade
|
|
65
|
+
| Serviço | Dev (imagem/versão, config) | Prod | Diferença | Risco |
|
|
66
|
+
|
|
67
|
+
## Perguntas em aberto
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Severidade: Bloqueador (exposição de segredo, perda de dados, falha só em produção) · Maior · Menor · Detalhe.
|
|
71
|
+
|
|
72
|
+
## Próximo
|
|
73
|
+
|
|
74
|
+
- `ci-pipeline-review` quando o CI constrói essas imagens ou sobe o stack.
|
|
75
|
+
- `release-checklist` para diferenças de configuração e versão antes de um deploy.
|
|
76
|
+
- `threat-modeling` para serviços expostos.
|
|
77
|
+
|
|
78
|
+
## Evite
|
|
79
|
+
|
|
80
|
+
- Tags `latest`.
|
|
81
|
+
- Publicar portas de banco em `0.0.0.0`.
|
|
82
|
+
- Segredos em `environment:` versionados no repositório.
|
|
83
|
+
- `sleep` em entrypoints para esperar dependências.
|
|
84
|
+
- Rodar como root por padrão.
|
|
85
|
+
- Um stack de desenvolvimento em versões principais diferentes da produção.
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: domain-modeling
|
|
3
|
+
description: Use quando modelar um domínio a partir de dados e funcionalidades propostos: sugere agregados, entidades e objetos de valor com propriedades tipadas, métodos derivados e invariantes.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Modelagem de Domínio
|
|
7
|
+
|
|
8
|
+
Transforma dados e funcionalidades propostos num modelo tático de domínio: agregados, entidades, objetos de valor, propriedades tipadas, comportamentos e regras de consistência.
|
|
9
|
+
|
|
10
|
+
A saída é uma **especificação do modelo**, não uma implementação. Não gere código além de assinaturas de tipos, a menos que o usuário peça.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Sempre escreva os termos de modelagem em pt-BR seguidos do en-US: Agregado (Aggregate), Raiz do Agregado (Aggregate Root), Entidade (Entity), Objeto de Valor (Value Object), Invariante (Invariant), Política (Policy), Evento de Domínio (Domain Event), Contexto Delimitado (Bounded Context), Linguagem Ubíqua (Ubiquitous Language).
|
|
15
|
+
- Nomeie tipos, propriedades e métodos na linguagem ubíqua do usuário (no idioma em que o domínio do usuário fala).
|
|
16
|
+
- Use os tipos da linguagem do código existente por padrão, a menos que o usuário indique outra linguagem. Os mapeamentos abaixo são para TypeScript.
|
|
17
|
+
|
|
18
|
+
## Princípio central
|
|
19
|
+
|
|
20
|
+
Não dá para modelar o que você não entende. Uma regra de negócio errada não é salva por padrão nenhum. Antes de classificar qualquer coisa, entenda o domínio; o que não foi dito precisa ser marcado como **suposição** ou **pergunta**, nunca inventado como fato.
|
|
21
|
+
|
|
22
|
+
## Processo
|
|
23
|
+
|
|
24
|
+
### 1. Extrair a linguagem ubíqua
|
|
25
|
+
A partir dos dados e funcionalidades informados, liste os substantivos (candidatos a conceitos), os verbos (candidatos a comportamentos) e as regras explícitas ou implícitas. Identifique termos ambíguos (por exemplo, um "usuário" que é ao mesmo tempo credencial, cliente e funcionário) e separe-os.
|
|
26
|
+
|
|
27
|
+
### 2. Delimitar contextos
|
|
28
|
+
Agrupe conceitos em Contextos Delimitados quando o mesmo termo carrega significados ou regras diferentes. Um contexto é uma fronteira de **modelo**, não de implantação: pode viver num monólito como pasta/módulo. Não proponha microsserviços por causa disso.
|
|
29
|
+
Quando o domínio ainda não estiver claro, rode `event-storming` antes. Para mapear como os contextos se relacionam (Kernel Compartilhado, Camada Anticorrupção, Cliente–Fornecedor…), use `bounded-context-mapping`.
|
|
30
|
+
|
|
31
|
+
### 3. Classificar cada conceito
|
|
32
|
+
|
|
33
|
+
| Conceito | Critério |
|
|
34
|
+
|---|---|
|
|
35
|
+
| Entidade | Tem uma identidade que persiste através das mudanças; tem ciclo de vida. |
|
|
36
|
+
| Objeto de Valor | Definido só pelos seus atributos; imutável; igualdade por valor; carrega a própria validação e comportamento. |
|
|
37
|
+
| Agregado | Fronteira de consistência transacional. A raiz é o único ponto de entrada para mudanças. |
|
|
38
|
+
|
|
39
|
+
Heurísticas:
|
|
40
|
+
- Mantenha os agregados pequenos. Se duas coisas não precisam estar consistentes na mesma transação, são agregados separados.
|
|
41
|
+
- Agregados referenciam outros agregados **por ID**, nunca pelo objeto.
|
|
42
|
+
- Promova um primitivo a Objeto de Valor quando houver uma regra, formato ou comportamento associado (por exemplo, CPF/CNPJ, Email, Dinheiro, Período). Sem regra, mantenha o primitivo; não crie objetos de valor por ritual.
|
|
43
|
+
- Pares de campos que só fazem sentido juntos (início/fim, valor/moeda, latitude/longitude) são fortes candidatos a Objeto de Valor.
|
|
44
|
+
|
|
45
|
+
### 4. Tipar as propriedades
|
|
46
|
+
Para cada propriedade, defina nome, tipo, se é obrigatória e sua origem (informada, derivada, gerada pelo sistema).
|
|
47
|
+
|
|
48
|
+
Mapeamentos padrão em TypeScript:
|
|
49
|
+
- Identificador: tipo com marca (branded) sobre `string` (por exemplo, `type ProjectId = string & { readonly __brand: 'ProjectId' }`), para que um `ProjectId` não seja aceito onde se espera um `CustomerId`.
|
|
50
|
+
- Data/hora: `Date` tratado como instante em UTC (ou `Temporal` onde o projeto já o usa); data sem horário, quando relevante, como objeto de valor próprio.
|
|
51
|
+
- Duração: objeto de valor ou número em milissegundos com a unidade no nome (`durationMs`).
|
|
52
|
+
- Dinheiro: objeto de valor `Money` com o valor em unidades menores (centavos) como `bigint` ou inteiro seguro, mais a moeda. Nunca número de ponto flutuante.
|
|
53
|
+
- Enumerações/estados: união de literais de string (`'open' | 'closed'`), ou o padrão que o código já usa.
|
|
54
|
+
- Opcional: `?`/`undefined` só quando a ausência tem significado no domínio.
|
|
55
|
+
|
|
56
|
+
### 5. Definir comportamentos
|
|
57
|
+
- **Métodos derivados**: calculados a partir das propriedades, nunca armazenados (por exemplo, `Period.durationMs(): number` = fim − início; `Period.contains(at: Date): boolean`).
|
|
58
|
+
- **Comportamentos de domínio**: verbos da linguagem ubíqua que mudam o estado (por exemplo, `Project.close(at: Date): Result<void, ProjectError>`, ou lançando um erro de domínio tipado, conforme o padrão do código), em vez de setters genéricos. Evite modelos anêmicos.
|
|
59
|
+
- Transições de estado: descreva a máquina de estados sempre que houver um status.
|
|
60
|
+
|
|
61
|
+
### 6. Definir invariantes
|
|
62
|
+
Para cada regra de consistência, enuncie:
|
|
63
|
+
- a regra em linguagem de negócio;
|
|
64
|
+
- onde ela é garantida (construtor do Objeto de Valor, método da Raiz do Agregado);
|
|
65
|
+
- quando é verificada (na criação, numa transição específica, sempre).
|
|
66
|
+
|
|
67
|
+
Exemplo: "O fim não pode ser antes do início" → garantida na criação de `Period`; um `Period` inválido não pode existir.
|
|
68
|
+
|
|
69
|
+
Prefira tornar os estados inválidos irrepresentáveis com Objetos de Valor a espalhar validações.
|
|
70
|
+
|
|
71
|
+
### 7. Extrair políticas
|
|
72
|
+
Regras de negócio que variam, são configuráveis ou tendem a mudar (percentuais, limites, critérios de elegibilidade) viram uma Política explícita e nomeada, em vez de condicionais enterradas nos métodos. Quem procurar "onde esse limite está definido" deve encontrá-lo pelo nome.
|
|
73
|
+
|
|
74
|
+
### 8. Eventos de domínio (opcional)
|
|
75
|
+
Sugira Eventos de Domínio só quando outra parte do sistema precisar reagir a um fato. Nomeie-os no passado (`ProjectClosed`). Não proponha Event Sourcing ou CQRS sem uma necessidade concreta.
|
|
76
|
+
|
|
77
|
+
## Formato de saída
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
## Contexto: <Nome>
|
|
81
|
+
|
|
82
|
+
### Agregado: <Nome> (raiz: <Entidade>)
|
|
83
|
+
Responsabilidade: <uma frase>
|
|
84
|
+
|
|
85
|
+
**Propriedades**
|
|
86
|
+
| Propriedade | Tipo | Obrigatória | Origem | Notas |
|
|
87
|
+
|
|
88
|
+
**Métodos derivados**
|
|
89
|
+
- `nome(): Tipo` — <cálculo>
|
|
90
|
+
|
|
91
|
+
**Comportamentos**
|
|
92
|
+
- `verbo(params): Result<…>` — <efeito e transição>
|
|
93
|
+
|
|
94
|
+
**Invariantes**
|
|
95
|
+
- <regra> — garantida em <onde>, verificada <quando>
|
|
96
|
+
|
|
97
|
+
#### Entidades internas / Objetos de Valor
|
|
98
|
+
<mesma estrutura, enxuta>
|
|
99
|
+
|
|
100
|
+
### Políticas
|
|
101
|
+
- <Nome>: <regra, parâmetros>
|
|
102
|
+
|
|
103
|
+
### Suposições e perguntas em aberto
|
|
104
|
+
- <o que foi suposto e precisa ser validado com o negócio>
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Sempre feche com **Suposições e perguntas em aberto**. Elas fazem parte do modelo, não são um apêndice: mostram onde ainda falta conhecimento do domínio.
|
|
108
|
+
|
|
109
|
+
## No Forja
|
|
110
|
+
|
|
111
|
+
No Forja, o modelo de cada contexto fica em `memory/30-domains/<contexto>/context.md` (agregados, invariantes, políticas e o mapa de onde cada um vive no código). Depois de gravar, rode `forja sync:universal`; `forja memory:audit` verifica se o mapa aponta para código que existe.
|
|
112
|
+
|
|
113
|
+
## Evite
|
|
114
|
+
|
|
115
|
+
- Inventar regras de negócio e apresentá-las como fato.
|
|
116
|
+
- Um agregado gigante que guarda tudo.
|
|
117
|
+
- Um Objeto de Valor para cada primitivo, sem regra que o justifique.
|
|
118
|
+
- Setters genéricos em vez de comportamentos nomeados.
|
|
119
|
+
- Padrões aplicados por obrigação. Saber onde usá-los importa mais do que saber como.
|
|
120
|
+
- Gerar uma implementação completa sem que peçam.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: event-storming
|
|
3
|
+
description: Use quando um domínio ainda não está claro antes de modelá-lo: conduz uma sessão de Event Storming com o usuário como especialista do domínio, descobrindo eventos de domínio, comandos, atores, políticas, modelos de leitura e pontos críticos, e propõe agregados e fronteiras de contexto candidatos.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Event Storming
|
|
7
|
+
|
|
8
|
+
Descobre como um negócio funciona contando a sua história como uma sequência de fatos que aconteceram. Eventos são mais fáceis de enunciar para os especialistas do domínio do que entidades ou tabelas, e as lacunas entre eles revelam as regras que ninguém escreveu.
|
|
9
|
+
|
|
10
|
+
O usuário é o especialista do domínio. Pergunte, não suponha. A saída é uma **linha do tempo de eventos estruturada**, não um modelo; os agregados vêm por último e são só candidatos.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Termos de modelagem em pt-BR seguidos do en-US, como em `domain-modeling`: Evento de Domínio (Domain Event), Comando (Command), Ator (Actor), Política (Policy), Modelo de Leitura (Read Model), Sistema Externo (External System), Ponto Crítico (Hotspot), Agregado (Aggregate).
|
|
15
|
+
- Nomes na linguagem ubíqua do usuário. Eventos no passado ("Pedido Confirmado", "Order Confirmed"); comandos no imperativo ("Confirmar Pedido", "Confirm Order").
|
|
16
|
+
- Entradas: achados brutos de `requirements-elicitation`, documentos ou as próprias palavras do usuário.
|
|
17
|
+
- Tudo o que o usuário não confirmou é um **ponto crítico**, nunca um fato.
|
|
18
|
+
|
|
19
|
+
## Níveis
|
|
20
|
+
|
|
21
|
+
| Nível | Pergunta | Use quando |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| Visão geral (big picture) | O que acontece no fluxo inteiro do negócio? | Iniciar um produto ou uma área grande; encontrar fronteiras de contexto |
|
|
24
|
+
| Processo | Como este processo funciona, regra a regra? | Desenhar uma funcionalidade ou um caso de uso |
|
|
25
|
+
| Design | Qual agregado aceita cada comando e garante qual regra? | Logo antes de `domain-modeling` |
|
|
26
|
+
|
|
27
|
+
Diga qual nível você está conduzindo. Não pule para o nível de design antes de a linha do tempo estar estável.
|
|
28
|
+
|
|
29
|
+
## Processo
|
|
30
|
+
|
|
31
|
+
Conduza em rodadas de perguntas com o usuário. Mostre a linha do tempo após cada rodada.
|
|
32
|
+
|
|
33
|
+
### 1. Exploração caótica
|
|
34
|
+
Peça todos os eventos que o usuário conseguir lembrar no escopo, em qualquer ordem. Estimule com: "O que acontece antes disso?", "O que acontece depois?", "O que pode dar errado?", "O que acontece no fim do dia / do mês?". Colete, não julgue.
|
|
35
|
+
|
|
36
|
+
### 2. Impor a linha do tempo
|
|
37
|
+
Ordene os eventos no tempo. Funda duplicados; separe eventos que escondem dois fatos. Marque os eventos pivô, onde o fluxo muda de fase ou de dono (por exemplo, "Pagamento Capturado"). Eles costumam marcar fronteiras de contexto.
|
|
38
|
+
|
|
39
|
+
### 3. Comandos e atores
|
|
40
|
+
Para cada evento: quem ou o que o causou? Um comando emitido por um **ator** (pessoa/papel), um **sistema externo**, uma **política** ou o tempo ("Fim do Mês Atingido").
|
|
41
|
+
|
|
42
|
+
### 4. Políticas
|
|
43
|
+
Reações que ligam eventos a comandos: "Sempre que <evento>, então <comando>". Pergunte se cada uma é automática, manual ou condicional. As políticas são onde moram as regras de negócio escondidas.
|
|
44
|
+
|
|
45
|
+
### 5. Modelos de leitura
|
|
46
|
+
De que informação o ator precisa para decidir emitir o comando? Esses são os modelos de leitura (telas, relatórios, consultas).
|
|
47
|
+
|
|
48
|
+
### 6. Pontos críticos
|
|
49
|
+
Marque cada conflito, incógnita, discordância, exceção ou dor. Cada um vira uma pergunta para o usuário ou um candidato a `RN-NN` para `requirements-gathering`.
|
|
50
|
+
|
|
51
|
+
### 7. Agregados e fronteiras candidatos (só no nível de design)
|
|
52
|
+
Agrupe comandos e eventos em torno da coisa que precisa estar consistente para aceitar o comando. Essa coisa é um agregado candidato. Agrupe a linha do tempo em áreas onde a linguagem e a propriedade permanecem as mesmas. Esses são os contextos delimitados candidatos.
|
|
53
|
+
|
|
54
|
+
## Formato
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
## Escopo e nível
|
|
58
|
+
<processo ou área> — <visão geral | processo | design>
|
|
59
|
+
|
|
60
|
+
## Linha do tempo
|
|
61
|
+
| # | Evento | Disparado por (comando) | Ator / sistema / política / tempo | Modelo de leitura necessário | Notas |
|
|
62
|
+
|---|---|---|---|---|---|
|
|
63
|
+
|
|
64
|
+
## Políticas
|
|
65
|
+
- Sempre que <evento>, então <comando> (<automática | manual | condicional: …>)
|
|
66
|
+
|
|
67
|
+
## Pontos críticos
|
|
68
|
+
| # | Onde | Pergunta / conflito | Quem responde |
|
|
69
|
+
|
|
70
|
+
## Agregados candidatos (nível de design)
|
|
71
|
+
| Agregado | Comandos aceitos | Eventos emitidos | Regras que protege |
|
|
72
|
+
|
|
73
|
+
## Contextos candidatos
|
|
74
|
+
<eventos pivô e mudanças de linguagem que sugerem fronteiras>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Um `flowchart LR` em Mermaid da linha do tempo é opcional, para fluxos com muitas ramificações.
|
|
78
|
+
|
|
79
|
+
## Próximo
|
|
80
|
+
|
|
81
|
+
- `bounded-context-mapping` com os contextos candidatos.
|
|
82
|
+
- `domain-modeling` com os agregados, regras e eventos candidatos.
|
|
83
|
+
- `requirements-gathering` com os pontos críticos e as políticas como regras a confirmar.
|
|
84
|
+
|
|
85
|
+
## No Forja
|
|
86
|
+
|
|
87
|
+
No Forja, grave a linha do tempo e os pontos críticos em `memory/30-domains/<contexto>/event-storming.md` e rode `forja sync:universal`. Os pontos críticos viram perguntas na spec (`specs/<slug>/spec.md`, §7) até serem respondidos.
|
|
88
|
+
|
|
89
|
+
## Evite
|
|
90
|
+
|
|
91
|
+
- Começar por entidades ou tabelas.
|
|
92
|
+
- Eventos no presente ou como CRUD ("Pedido Atualizado"). Pergunte o que de fato aconteceu.
|
|
93
|
+
- Preencher lacunas com regras plausíveis. Marque um ponto crítico.
|
|
94
|
+
- Desenhar agregados antes de a linha do tempo estar acordada.
|
|
95
|
+
- Eventos técnicos ("Linha Inserida", "Mensagem Enviada ao Kafka") nos níveis de visão geral ou de processo.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: executive-writing
|
|
3
|
+
description: Use quando uma análise consolidada precisa virar comunicação orientada à decisão para gestores, conselhos ou times: resumos executivos, pareceres, memorandos, apresentações e comunicados de decisão, com fatos, alternativas, recomendação, plano de ação e limitações.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Redação Executiva
|
|
7
|
+
|
|
8
|
+
Transforma análises complexas em comunicação clara, curta e orientada à decisão. Entrada: análises, diagnósticos e recomendações consolidados (de `requirements-gathering`, `architecture-decision-record`, `technical-spike`, `lgpd-compliance` ou do usuário). Saída: a versão final para gestores, o conselho ou os times operacionais.
|
|
9
|
+
|
|
10
|
+
O texto serve a uma decisão. Se o leitor termina e não sabe o que decidir ou o que fazer em seguida, o texto falhou.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Termos em pt-BR seguidos do en-US: Resumo Executivo (Executive Summary), Parecer (Opinion), Memorando (Memo), Comunicado de Decisão (Decision Announcement), Pirâmide de Minto (Minto Pyramid), Sumário Decisório (Decision Brief), Plano de Ação (Action Plan), Trade-off.
|
|
15
|
+
- Toda afirmação é marcada pela natureza quando isso importa: **fato** (com fonte), **hipótese**, **inferência**, **lacuna**.
|
|
16
|
+
- Escreva no vocabulário do leitor: executivo (impacto, custo, risco, prazo) ou operacional (quem faz o quê, quando, como).
|
|
17
|
+
|
|
18
|
+
## Princípio central
|
|
19
|
+
|
|
20
|
+
Resposta primeiro, sustentação depois (Pirâmide de Minto). Comece pela decisão ou recomendação, depois os poucos argumentos que a sustentam, depois a evidência. Sintetize, não resuma: corte redundância e jargão, mas nunca precisão ou rastreabilidade.
|
|
21
|
+
|
|
22
|
+
## Processo
|
|
23
|
+
|
|
24
|
+
### 1. Contexto e leitor
|
|
25
|
+
Qual é a situação, o que precisa ser decidido, quem decide e do que precisa para decidir. Leitores executivos e operacionais recebem textos diferentes.
|
|
26
|
+
|
|
27
|
+
### 2. Inventariar o material
|
|
28
|
+
Dados, documentos, regras e restrições disponíveis. Separe fatos, hipóteses, inferências e lacunas. Nada é acrescentado que o material não sustente.
|
|
29
|
+
|
|
30
|
+
### 3. Enquadrar a decisão
|
|
31
|
+
Uma frase: o que precisa ser decidido ou analisado. Se não há decisão, declare a finalidade (informar, alinhar, registrar).
|
|
32
|
+
|
|
33
|
+
### 4. Analisar
|
|
34
|
+
Diagnóstico estruturado: causas, impactos, relações. Distinga correlação de causalidade. Questione práticas mantidas só por hábito.
|
|
35
|
+
|
|
36
|
+
### 5. Comparar alternativas
|
|
37
|
+
Opções viáveis lado a lado, cada uma com benefícios, desvantagens, custo, risco e dependências. Explicite os trade-offs. Não fazer nada é uma alternativa quando é viável. Tecnologia nunca é a resposta automática.
|
|
38
|
+
|
|
39
|
+
### 6. Recomendar
|
|
40
|
+
Específica, priorizada, justificada. Ligue cada recomendação a um resultado mensurável.
|
|
41
|
+
|
|
42
|
+
### 7. Plano de ação e limitações
|
|
43
|
+
Ações com responsáveis sugeridos, prazos, prioridades, dependências e indicadores de sucesso. Depois: dados faltantes, incertezas e pontos que precisam de validação, e quem precisa validá-los.
|
|
44
|
+
|
|
45
|
+
### 8. Moldar para o entregável
|
|
46
|
+
Escolha o formato e enxugue para ele (veja abaixo). Linha narrativa: o título de cada seção enuncia a sua conclusão, de modo que ler só os títulos conte a história.
|
|
47
|
+
|
|
48
|
+
## Entregáveis
|
|
49
|
+
|
|
50
|
+
- **Resumo executivo**: uma página ou menos; recomendação, impacto, risco, próximos passos.
|
|
51
|
+
- **Parecer**: estrutura completa; raciocínio e limitações explícitos.
|
|
52
|
+
- **Memorando**: uma página; contexto, decisão necessária, recomendação, ações.
|
|
53
|
+
- **Apresentação**: linha narrativa, uma mensagem por slide, o título enuncia a conclusão.
|
|
54
|
+
- **Comunicado de decisão**: o que foi decidido, por quê, o que muda para quem, a partir de quando.
|
|
55
|
+
|
|
56
|
+
## Formato de saída
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
# <Título que enuncia a conclusão>
|
|
60
|
+
|
|
61
|
+
## Resumo
|
|
62
|
+
<Recomendação em 2–3 frases: decisão, impacto, risco, próximo passo.>
|
|
63
|
+
|
|
64
|
+
## Contexto
|
|
65
|
+
<Situação em poucas linhas.>
|
|
66
|
+
|
|
67
|
+
## Problema ou decisão
|
|
68
|
+
<O que precisa ser decidido.>
|
|
69
|
+
|
|
70
|
+
## Evidências
|
|
71
|
+
- <fato> — <fonte>
|
|
72
|
+
|
|
73
|
+
## Análise
|
|
74
|
+
<Causas, impactos, relações. Hipóteses marcadas como tal.>
|
|
75
|
+
|
|
76
|
+
## Alternativas
|
|
77
|
+
| Opção | Benefícios | Desvantagens | Custo | Risco | Dependências |
|
|
78
|
+
|
|
79
|
+
## Recomendação
|
|
80
|
+
<Específica, priorizada, justificada.>
|
|
81
|
+
|
|
82
|
+
## Plano de ação
|
|
83
|
+
| Ação | Responsável sugerido | Prazo | Prioridade | Depende de | Indicador |
|
|
84
|
+
|
|
85
|
+
## Limitações
|
|
86
|
+
- <dado faltante / incerteza> — validar com <quem>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Evite
|
|
90
|
+
|
|
91
|
+
- Inventar dados, fatos, números ou evidências.
|
|
92
|
+
- Apresentar uma hipótese como conclusão.
|
|
93
|
+
- Recomendações genéricas ("melhorar a comunicação", "investir em tecnologia").
|
|
94
|
+
- Propor tecnologia como solução automática.
|
|
95
|
+
- Omitir custos, riscos, restrições ou efeitos colaterais.
|
|
96
|
+
- Tratar correlação como causalidade.
|
|
97
|
+
- Enterrar a recomendação no fim.
|
|
98
|
+
- Redundância, jargão e rodeios que escondem a mensagem.
|
|
99
|
+
- Listar várias alternativas sem compará-las.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: frontend-architecture
|
|
3
|
+
description: Use quando organizar ou revisar um front-end React ou Next.js: estrutura por funcionalidade, fronteira entre Server e Client Components, estado do servidor vs. estado do cliente, busca de dados e cache, formulários com validação, fronteiras de erro e de carregamento, e um plano de mudança incremental.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Arquitetura de Front-end
|
|
7
|
+
|
|
8
|
+
Um front-end apodrece de dois jeitos: tudo vira estado global, ou cada tela reimplementa a busca de dados do seu jeito. A primeira pergunta para qualquer dado é **de quem ele é**: do servidor (vem de uma API e tem uma cópia mais nova em outro lugar) ou do cliente (existe só nesta tela, nesta sessão). Errar essa pergunta é a origem da maior parte dos bugs de sincronia.
|
|
9
|
+
|
|
10
|
+
A saída padrão é uma **avaliação e uma estrutura alvo com um plano de mudança**. Escreva componentes só quando o usuário pedir.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: as histórias de `backlog-slicing`, o contrato de `api-design`, a estrutura atual e o `package.json`.
|
|
15
|
+
- O framework e as bibliotecas que o projeto já usa prevalecem (Next.js App Router ou Pages Router, Vite, React Query, Zustand, Redux, React Hook Form…). Proponha trocar só por um problema concreto.
|
|
16
|
+
- Os nomes de pastas e componentes seguem a linguagem ubíqua do domínio, não os nomes técnicos.
|
|
17
|
+
|
|
18
|
+
## Avalie primeiro
|
|
19
|
+
|
|
20
|
+
Somente leitura:
|
|
21
|
+
|
|
22
|
+
1. Rotas e páginas: quais existem, o que cada uma carrega e de onde.
|
|
23
|
+
2. Onde os dados são buscados: em componentes, em hooks, num cliente central. `fetch` espalhado em `useEffect` é um mau sinal.
|
|
24
|
+
3. Estado global: o que está nele. Dados do servidor copiados para uma store global são o problema mais comum.
|
|
25
|
+
4. Pastas genéricas (`components/` com tudo, `utils/`, `hooks/` sem dono).
|
|
26
|
+
5. Ciclos e acoplamento: `npx madge --circular --extensions ts,tsx src` (veja `ts-module-layout`).
|
|
27
|
+
6. No Next.js: quais componentes são `'use client'` e por quê. Um `'use client'` no topo de uma árvore grande puxa tudo para o bundle do cliente.
|
|
28
|
+
|
|
29
|
+
## Estrutura alvo
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
src/
|
|
33
|
+
app/ (ou pages/) # roteamento do framework; páginas finas que compõem funcionalidades
|
|
34
|
+
features/<contexto>/ # uma por contexto ou funcionalidade do domínio
|
|
35
|
+
components/ # componentes desta funcionalidade
|
|
36
|
+
api.ts # chamadas à API e chaves de cache desta funcionalidade
|
|
37
|
+
hooks.ts # hooks de dados e de comportamento
|
|
38
|
+
schema.ts # schemas de validação (formulários, respostas)
|
|
39
|
+
shared/ui/ # componentes de design system sem regra de negócio (Button, Dialog)
|
|
40
|
+
shared/lib/ # infraestrutura com comportamento real: cliente HTTP, i18n, telemetria
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Regras:
|
|
44
|
+
|
|
45
|
+
- **Organize por funcionalidade.** Uma página compõe funcionalidades; uma funcionalidade não importa os arquivos internos de outra (use o que ela exporta).
|
|
46
|
+
- **Estado do servidor fica num cache de servidor** (React Query/TanStack Query, SWR, ou o cache do framework), não numa store global. Cada consulta tem uma chave estável e uma política de invalidação depois das mutações.
|
|
47
|
+
- **Estado do cliente o mais local possível**: no componente, depois na URL (filtros, paginação, abas), depois num contexto, e só então numa store global.
|
|
48
|
+
- **Server Components por padrão no Next.js App Router**; `'use client'` só nas folhas que precisam de interatividade, de estado ou de APIs do navegador. Dados sensíveis e segredos nunca chegam a um Client Component.
|
|
49
|
+
- **Valide nas fronteiras**: respostas da API e entradas de formulário passam por um schema (`zod`, `valibot`), não por uma anotação de tipo.
|
|
50
|
+
- **Formulários**: uma biblioteca de formulário quando há validação ou muitos campos; mensagens de erro ligadas aos campos; o servidor revalida sempre.
|
|
51
|
+
- **Carregamento e erro são estados de primeira classe**: cada tela define o que mostra carregando, vazia, com erro e com sucesso. No Next.js, `loading.tsx` e `error.tsx`; no React, `Suspense` e fronteiras de erro.
|
|
52
|
+
- **Sem regra de negócio em componente de UI.** Cálculos e decisões vão para funções puras testáveis (`ts-testing`).
|
|
53
|
+
|
|
54
|
+
## Plano de mudança
|
|
55
|
+
|
|
56
|
+
Cada passo funciona sozinho e pode ser um commit:
|
|
57
|
+
|
|
58
|
+
1. Introduza o cache de servidor numa funcionalidade e migre a busca de dados dela.
|
|
59
|
+
2. Tire da store global os dados de servidor que agora estão no cache.
|
|
60
|
+
3. Mova os componentes da funcionalidade para `features/<contexto>/`.
|
|
61
|
+
4. Empurre `'use client'` para as folhas.
|
|
62
|
+
5. Repita por funcionalidade; apague as pastas genéricas que esvaziaram.
|
|
63
|
+
|
|
64
|
+
## Formato
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
## Estado atual
|
|
68
|
+
| Problema | Onde | Efeito |
|
|
69
|
+
|
|
70
|
+
## Estrutura alvo
|
|
71
|
+
<árvore>
|
|
72
|
+
|
|
73
|
+
## Dados
|
|
74
|
+
| Dado | Dono (servidor/cliente) | Onde vive | Invalidação |
|
|
75
|
+
|
|
76
|
+
## Plano de mudança
|
|
77
|
+
| # | Passo | Arquivos | Commit |
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Próximo
|
|
81
|
+
|
|
82
|
+
- `accessibility-review` para cada tela nova ou alterada.
|
|
83
|
+
- `web-performance` quando houver metas de Core Web Vitals.
|
|
84
|
+
- `ts-code-review` revisa as mudanças; `ts-testing` para hooks e funções puras.
|
|
85
|
+
|
|
86
|
+
## No Forja
|
|
87
|
+
|
|
88
|
+
No Forja, a estrutura alvo e as regras de dados ficam em `memory/20-architecture/frontend.md`; trocas de biblioteca ou de estratégia de renderização viram ADR em `memory/90-decisions/`. Rode `forja sync:universal` depois de gravar.
|
|
89
|
+
|
|
90
|
+
## Evite
|
|
91
|
+
|
|
92
|
+
- Dados do servidor duplicados numa store global.
|
|
93
|
+
- `fetch` em `useEffect` espalhado pelos componentes.
|
|
94
|
+
- `'use client'` no topo de árvores grandes.
|
|
95
|
+
- Uma pasta `components/` com todos os componentes do app.
|
|
96
|
+
- Regra de negócio dentro de componentes.
|
|
97
|
+
- Reescrever o front-end inteiro de uma vez.
|