forjajs 5.0.0 → 5.1.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 +68 -2
- package/README.md +4 -2
- package/README.pt-BR.md +4 -1
- 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/bin/create-memory-nest-kit.js +0 -0
- package/dist/bin/forja.js +0 -0
- package/dist/bin/init-project.js +1 -0
- package/dist/lib/core/journey.js +10 -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-upgrade.d.ts +0 -4
- package/dist/lib/project-upgrade.js +19 -1
- package/dist/lib/project-wiring.d.ts +8 -0
- package/dist/lib/project-wiring.js +74 -2
- package/dist/lib/validators/structure-validator.js +0 -1
- package/dist/packages/llm/src/index.js +12 -2
- package/dist/scripts/llm-fit.js +23 -1
- package/dist/scripts/project-upgrade.js +9 -6
- package/docs/init-project.md +1 -1
- package/docs/llm-fit-loop.md +16 -0
- package/memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md +1 -1
- 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/package.json +2 -2
- 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/templates/project/AGENTS.md +9 -0
- 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,143 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: commit-message
|
|
3
|
+
description: Use quando fazer commit de mudanças ou escrever uma mensagem de commit: lê o diff em stage, o nome do branch e o histórico do repositório, escreve uma mensagem no padrão Conventional Commits com tipo, escopo e assunto no imperativo, e faz o commit só depois da aprovação.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Mensagem de Commit
|
|
7
|
+
|
|
8
|
+
Uma mensagem de commit explica **por que** uma mudança existe. O diff já mostra **o que** mudou. Um bom histórico permite a qualquer pessoa descobrir quando e por que um comportamento apareceu, e permite que ferramentas gerem changelogs e versões a partir dele.
|
|
9
|
+
|
|
10
|
+
A saída padrão é uma **mensagem proposta**. Rode `git commit` só depois que o usuário aprovar.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Formato: [Conventional Commits](https://www.conventionalcommits.org/).
|
|
15
|
+
- Idioma: o usado no histórico recente (`git log`). Inglês quando não houver histórico.
|
|
16
|
+
- As regras do repositório prevalecem sobre esta skill: `commitlint.config.*`, `.gitmessage`, `.czrc`, `CONTRIBUTING.md`, ou um padrão claro no `git log`.
|
|
17
|
+
|
|
18
|
+
## Reúna o contexto
|
|
19
|
+
|
|
20
|
+
Somente leitura, antes de redigir:
|
|
21
|
+
|
|
22
|
+
1. `git status` e `git diff --staged`. Se nada estiver em stage, mostre o `git diff` e pergunte o que colocar em stage. Nunca rode `git add -A` por conta própria.
|
|
23
|
+
2. `git branch --show-current`: a finalidade do branch.
|
|
24
|
+
3. `git log --oneline -20`: idioma, tipos e escopos já usados, e se o repositório segue Conventional Commits.
|
|
25
|
+
4. `git log <base>..HEAD --oneline` (a base costuma ser `main`): o que o branch já contém, para o commit novo se encaixar na história.
|
|
26
|
+
5. Os arquivos de configuração do repositório listados em Convenções, se existirem.
|
|
27
|
+
|
|
28
|
+
## Finalidade do branch → sugestão de tipo
|
|
29
|
+
|
|
30
|
+
| Prefixo do branch | Tipo padrão |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `feat/`, `feature/` | `feat` |
|
|
33
|
+
| `fix/`, `bugfix/` | `fix` |
|
|
34
|
+
| `hotfix/` | `fix` (diga no corpo o que estava quebrado em produção) |
|
|
35
|
+
| `refactor/` | `refactor` |
|
|
36
|
+
| `docs/` | `docs` |
|
|
37
|
+
| `test/` | `test` |
|
|
38
|
+
| `perf/`, `build/`, `ci/`, `chore/` | o mesmo do prefixo |
|
|
39
|
+
| `release/` | `chore(release)` |
|
|
40
|
+
|
|
41
|
+
O branch é uma **sugestão**; o diff manda. Um commit que só acrescenta testes em `feat/login` é `test`, não `feat`.
|
|
42
|
+
|
|
43
|
+
Um ID de ticket no nome do branch (`feat/ABC-123-login`) vai no rodapé como `Refs: ABC-123`. Nunca invente um.
|
|
44
|
+
|
|
45
|
+
## Tipos
|
|
46
|
+
|
|
47
|
+
| Tipo | Use quando |
|
|
48
|
+
|---|---|
|
|
49
|
+
| `feat` | Adiciona uma capacidade que o usuário ou quem chama consegue observar. |
|
|
50
|
+
| `fix` | Corrige um bug observável. |
|
|
51
|
+
| `refactor` | Muda a estrutura sem mudar o comportamento. |
|
|
52
|
+
| `perf` | Mesmo comportamento, mensuravelmente mais rápido ou mais leve. |
|
|
53
|
+
| `docs` | Só documentação. |
|
|
54
|
+
| `test` | Só adiciona ou corrige testes. |
|
|
55
|
+
| `build` | Sistema de build, dependências, empacotamento. |
|
|
56
|
+
| `ci` | Pipelines de CI e seus scripts. |
|
|
57
|
+
| `style` | Só formatação, sem mudar o significado do código. |
|
|
58
|
+
| `chore` | Manutenção que não se encaixa em nada acima. |
|
|
59
|
+
| `revert` | Reverte um commit anterior; referencie o hash dele no corpo. |
|
|
60
|
+
|
|
61
|
+
Quando dois tipos servirem, escolha o que descreve o efeito visível ao usuário: uma correção que exigiu uma refatoração é `fix`.
|
|
62
|
+
|
|
63
|
+
## Escopo
|
|
64
|
+
|
|
65
|
+
- O módulo, pacote ou pasta predominante na mudança (`auth`, `api`, `quality`).
|
|
66
|
+
- Reutilize escopos que já existem no histórico antes de criar um novo.
|
|
67
|
+
- Omita o escopo quando a mudança abranger o repositório inteiro. Nunca invente um só para preencher.
|
|
68
|
+
|
|
69
|
+
## Formato
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
<tipo>(<escopo>)!: <assunto>
|
|
73
|
+
|
|
74
|
+
<corpo>
|
|
75
|
+
|
|
76
|
+
BREAKING CHANGE: <o que quebra e como migrar>
|
|
77
|
+
Refs: <ticket>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- **Assunto**: no imperativo, ≤ 50 caracteres (limite rígido de 72), minúsculo depois dos dois-pontos, a menos que o histórico diga outra coisa, sem ponto final. Teste: "Se aplicado, este commit vai *<assunto>*".
|
|
81
|
+
- **Corpo**: só quando o porquê não fica óbvio pelo assunto. Motivação, trade-offs, efeitos colaterais. Quebre em 72 colunas. Não é uma lista de arquivos.
|
|
82
|
+
- **Mudança incompatível**: `!` depois do tipo/escopo **e** um rodapé `BREAKING CHANGE:`, para qualquer quebra em API, contrato, esquema, configuração ou CLI.
|
|
83
|
+
- **Trailers**: mantenha os que o repositório ou a ferramenta exigem (`Co-Authored-By`, `Signed-off-by`).
|
|
84
|
+
|
|
85
|
+
## Commits atômicos
|
|
86
|
+
|
|
87
|
+
Um commit, um motivo para mudar. Sinais de que o diff em stage deveria ser dividido:
|
|
88
|
+
|
|
89
|
+
- escopos não relacionados no mesmo diff;
|
|
90
|
+
- uma funcionalidade misturada com uma refatoração ou com formatação;
|
|
91
|
+
- o assunto precisa de "e" para ser honesto.
|
|
92
|
+
|
|
93
|
+
Proponha os grupos, cada um com sua mensagem e o comando para colocá-lo em stage (`git add <caminhos>`, ou `git add -p` para trechos no mesmo arquivo). O usuário decide; não coloque nada em stage por conta própria.
|
|
94
|
+
|
|
95
|
+
## Fluxo
|
|
96
|
+
|
|
97
|
+
1. Reúna o contexto.
|
|
98
|
+
2. Classifique tipo e escopo; verifique se cabe uma divisão.
|
|
99
|
+
3. Mostre a mensagem proposta (e a divisão, se houver).
|
|
100
|
+
4. Com a aprovação, faça o commit com um heredoc para o corpo manter a formatação:
|
|
101
|
+
```sh
|
|
102
|
+
git commit -F - <<'EOF'
|
|
103
|
+
<mensagem>
|
|
104
|
+
EOF
|
|
105
|
+
```
|
|
106
|
+
5. Mostre `git log -1 --stat`.
|
|
107
|
+
|
|
108
|
+
Nunca `--amend`, `--no-verify` ou push, a menos que peçam. Se um hook falhar, reporte, corrija a causa e crie um commit novo.
|
|
109
|
+
|
|
110
|
+
## Próximo
|
|
111
|
+
|
|
112
|
+
`pull-request` descreve os commits do branch para revisão; `release-notes` os transforma numa versão e num changelog.
|
|
113
|
+
|
|
114
|
+
## Exemplos
|
|
115
|
+
|
|
116
|
+
| Situação | Mensagem |
|
|
117
|
+
|---|---|
|
|
118
|
+
| `feat/ABC-42-export` adiciona exportação em CSV | `feat(reports): add CSV export` + rodapé `Refs: ABC-42` |
|
|
119
|
+
| `hotfix/login-timeout` | `fix(auth): renew session before token expiry` + corpo com o sintoma em produção |
|
|
120
|
+
| Skills movidas para pastas de categoria | `refactor: group skills into category folders` |
|
|
121
|
+
| Endpoint renomeado | `feat(api)!: rename /users to /accounts` + `BREAKING CHANGE: clients must call /accounts` |
|
|
122
|
+
|
|
123
|
+
Num repositório com histórico em português, as mesmas mensagens seriam, por exemplo, `feat(reports): adiciona exportação em CSV`.
|
|
124
|
+
|
|
125
|
+
Proposta de divisão, quando uma skill nova e uma movimentação de pastas estão em stage juntas:
|
|
126
|
+
|
|
127
|
+
```
|
|
128
|
+
1. git add design/ quality/ compliance/ requirements/
|
|
129
|
+
refactor: group skills into category folders
|
|
130
|
+
2. git add git/commit-message/
|
|
131
|
+
feat(git): add commit-message skill
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Evite
|
|
135
|
+
|
|
136
|
+
- Passado ou terceira pessoa no assunto ("added", "adds", "adicionado").
|
|
137
|
+
- Assuntos vagos: "atualiza arquivos", "fixes", "wip", "mudanças".
|
|
138
|
+
- Listar arquivos no corpo.
|
|
139
|
+
- Misturar mudanças não relacionadas num commit.
|
|
140
|
+
- Inventar escopos ou IDs de ticket.
|
|
141
|
+
- Afirmar que os testes passam sem rodá-los.
|
|
142
|
+
- Fazer commit sem aprovação.
|
|
143
|
+
- Sobrepor as convenções do próprio repositório com os padrões desta skill.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: data-migrations
|
|
3
|
+
description: Use quando desenhar um esquema relacional ou alterá-lo em produção: mapeia agregados para tabelas, garante invariantes com constraints, deriva índices dos padrões de consulta e planeja migrações sem downtime com um rollback por passo.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Migrações de Dados
|
|
7
|
+
|
|
8
|
+
O esquema é a parte mais longeva de um sistema: o código é substituído, os dados ficam. Esta skill desenha o esquema a partir do modelo de domínio e planeja as mudanças para que a aplicação em execução nunca encontre um banco com que não consiga lidar.
|
|
9
|
+
|
|
10
|
+
A saída padrão é um **esquema e um plano de migração ordenado**. Escreva arquivos de migração só quando o usuário pedir, usando a ferramenta de migração do projeto.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: agregados, objetos de valor e invariantes de `domain-modeling`; padrões de consulta de `api-design`; retenção e classificação de `lgpd-compliance`.
|
|
15
|
+
- Siga o código existente: o banco, a ferramenta de migração (Prisma Migrate, Drizzle Kit, TypeORM, Knex, `node-pg-migrate`, Flyway…), o estilo de nomes e a organização dos arquivos. Nunca misture ferramentas.
|
|
16
|
+
- O dialeto padrão é PostgreSQL. Diga quando um recurso é específico do dialeto.
|
|
17
|
+
- Volumes de dados ou tráfego desconhecidos vão para **Perguntas em aberto**: eles decidem se um passo precisa de lotes.
|
|
18
|
+
|
|
19
|
+
## Do modelo de domínio às tabelas
|
|
20
|
+
|
|
21
|
+
- **Agregado** → uma tabela raiz mais tabelas para as entidades internas, com chave estrangeira para a raiz e `ON DELETE CASCADE` só dentro do agregado. Um agregado é salvo numa transação.
|
|
22
|
+
- **Entre agregados**: referência por ID. Uma chave estrangeira serve dentro do mesmo banco; nunca faça cascata entre agregados.
|
|
23
|
+
- **Objeto de valor** → colunas na tabela do dono (`period_start`, `period_end`), ou uma coluna JSON só quando ele nunca é consultado pelas partes.
|
|
24
|
+
- **Invariantes** que o banco consegue garantir viram constraints: `NOT NULL`, `CHECK (period_end >= period_start)`, `UNIQUE`, chaves estrangeiras, exclusion constraints. O domínio também as verifica; a constraint é a última linha de defesa.
|
|
25
|
+
- **Concorrência otimista** (`ETag` em `api-design`) → uma coluna `version` incrementada a cada atualização.
|
|
26
|
+
- **Dinheiro**: `numeric(19,4)` mais uma coluna de moeda. **Tempo**: `timestamptz` em UTC.
|
|
27
|
+
- **Dados pessoais**: marque as colunas classificadas por `lgpd-compliance`; planeje como a retenção as exclui ou anonimiza.
|
|
28
|
+
|
|
29
|
+
## Índices
|
|
30
|
+
|
|
31
|
+
- Derive dos padrões de consulta reais (cada lista, filtro e ordenação em `api-design`), não de palpites.
|
|
32
|
+
- Chaves primárias e constraints únicas já são indexadas. Chaves estrangeiras não são no PostgreSQL: indexe-as quando você faz join ou exclusão por elas.
|
|
33
|
+
- Ordem das colunas num índice composto: colunas de igualdade primeiro, depois as de intervalo/ordenação.
|
|
34
|
+
- Todo índice deixa as escritas mais lentas. Cada um nomeia a consulta que atende.
|
|
35
|
+
|
|
36
|
+
## Mudanças sem downtime: expandir → migrar → contrair
|
|
37
|
+
|
|
38
|
+
As versões antiga e nova da aplicação rodam juntas durante um deploy. Todo passo precisa funcionar com as duas.
|
|
39
|
+
|
|
40
|
+
1. **Expandir**: adicione o que o código novo precisa, de forma retrocompatível (coluna nova anulável, tabela nova, índice novo criado de forma concorrente).
|
|
41
|
+
2. **Migrar**: implante código que escreve no antigo e no novo; preencha as linhas existentes em lotes; depois passe as leituras para a estrutura nova.
|
|
42
|
+
3. **Contrair**: depois que o código antigo sumir, remova a coluna ou tabela antiga numa release posterior.
|
|
43
|
+
|
|
44
|
+
Receitas:
|
|
45
|
+
|
|
46
|
+
| Mudança | Sequência segura |
|
|
47
|
+
|---|---|
|
|
48
|
+
| Adicionar uma coluna obrigatória | Adicionar anulável (ou com default constante) → preencher → `CHECK (col IS NOT NULL) NOT VALID` → `VALIDATE` → `SET NOT NULL` (o PostgreSQL 12+ pula a varredura completa) |
|
|
49
|
+
| Renomear uma coluna | Adicionar a nova → escrita dupla → preencher → ler a nova → remover a antiga. Nunca `RENAME` com tráfego ativo. |
|
|
50
|
+
| Mudar um tipo | Igual ao renomear, com uma coluna convertida |
|
|
51
|
+
| Adicionar um índice | `CREATE INDEX CONCURRENTLY` (fora de uma transação) |
|
|
52
|
+
| Adicionar uma chave estrangeira | `NOT VALID`, depois `VALIDATE CONSTRAINT` |
|
|
53
|
+
| Remover uma coluna | Parar de ler → parar de escrever → remover numa release posterior |
|
|
54
|
+
|
|
55
|
+
- Os preenchimentos rodam em lotes de tamanho limitado, são idempotentes e retomáveis, e nunca rodam dentro da transação da migração de esquema.
|
|
56
|
+
- Defina `lock_timeout` nas migrações para que um `ALTER` bloqueado falhe rápido em vez de enfileirar todo o tráfego atrás dele.
|
|
57
|
+
|
|
58
|
+
## Rollback
|
|
59
|
+
|
|
60
|
+
Cada passo declara o seu rollback. Passos de expansão se revertem removendo o que adicionaram. Passos de contração destroem dados: **não têm rollback** além de uma restauração, então só rodam depois que a versão nova estiver estável, e o plano diz isso.
|
|
61
|
+
|
|
62
|
+
## Formato
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
## Esquema
|
|
66
|
+
<DDL ou lista de tabelas: colunas, tipos, constraints, índices (cada um com a consulta que atende)>
|
|
67
|
+
|
|
68
|
+
## Plano de migração
|
|
69
|
+
| # | Release | Passo | Tipo (expandir/migrar/contrair) | Locks / risco de duração | Rollback |
|
|
70
|
+
|---|---|---|---|---|---|
|
|
71
|
+
|
|
72
|
+
## Perguntas em aberto
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Próximo
|
|
76
|
+
|
|
77
|
+
- `testing`: os testes de integração rodam as migrações contra um banco real e testam as constraints que espelham invariantes.
|
|
78
|
+
- `architecture-decision-record` para escolhas de banco ou de ferramenta de migração.
|
|
79
|
+
|
|
80
|
+
## Evite
|
|
81
|
+
|
|
82
|
+
- Uma migração que muda esquema e código no mesmo deploy de forma incompatível.
|
|
83
|
+
- Editar uma migração que já rodou em algum lugar. Escreva uma nova.
|
|
84
|
+
- Preencher milhões de linhas numa transação só.
|
|
85
|
+
- Floats para dinheiro; timestamps sem fuso horário.
|
|
86
|
+
- Índices sem uma consulta que precise deles.
|
|
87
|
+
- Exclusões em cascata entre agregados.
|
|
88
|
+
- Remover colunas na mesma release que deixa de usá-las.
|
|
@@ -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.
|