forjajs 1.1.6 → 1.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/.claude/settings.json +7 -7
- package/CHANGELOG.md +62 -0
- package/README.en.md +33 -5
- package/README.md +35 -4
- package/boilerplates/06-clean-arch/README.md +48 -0
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +42 -0
- package/boilerplates/06-clean-arch/backend/package.json +43 -0
- package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/main.ts +10 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -0
- package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -0
- package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -0
- package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -0
- package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -0
- package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -0
- package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -0
- package/boilerplates/README.md +20 -0
- package/dist/bin/create-memory-nest-kit.d.ts +2 -0
- package/dist/bin/create-memory-nest-kit.js +110 -0
- package/dist/bin/forja.d.ts +13 -0
- package/dist/bin/forja.js +136 -0
- package/dist/bin/init-project.d.ts +2 -0
- package/dist/bin/init-project.js +516 -0
- package/dist/lib/audit.d.ts +67 -0
- package/dist/lib/audit.js +143 -0
- package/dist/lib/context-builder.d.ts +58 -0
- package/dist/lib/context-builder.js +233 -0
- package/dist/lib/core/checks.d.ts +91 -0
- package/dist/lib/core/checks.js +119 -0
- package/dist/lib/core/doc-graph.d.ts +60 -0
- package/dist/lib/core/doc-graph.js +235 -0
- package/dist/lib/core/health.d.ts +103 -0
- package/dist/lib/core/health.js +538 -0
- package/dist/lib/core/registry.d.ts +296 -0
- package/dist/lib/core/registry.js +317 -0
- package/dist/lib/core/release.d.ts +334 -0
- package/dist/lib/core/release.js +465 -0
- package/dist/lib/generators/memory-generator.d.ts +83 -0
- package/{lib → dist/lib}/generators/memory-generator.js +107 -178
- package/dist/lib/generators/nest-generator.d.ts +15 -0
- package/{lib → dist/lib}/generators/nest-generator.js +47 -71
- package/dist/lib/generators/readme-generator.d.ts +15 -0
- package/{lib → dist/lib}/generators/readme-generator.js +9 -14
- package/dist/lib/governance-report.d.ts +49 -0
- package/dist/lib/governance-report.js +170 -0
- package/dist/lib/templates/harness/code-intel.d.mts +2 -0
- package/dist/lib/templates/harness/code-intel.mjs +126 -0
- package/dist/lib/utils/file-helpers.d.ts +9 -0
- package/dist/lib/utils/file-helpers.js +34 -0
- package/dist/lib/validators/structure-validator.d.ts +48 -0
- package/dist/lib/validators/structure-validator.js +232 -0
- package/dist/lib/workspace.d.ts +40 -0
- package/dist/lib/workspace.js +174 -0
- package/dist/scripts/agent-harness.d.ts +2 -0
- package/dist/scripts/agent-harness.js +556 -0
- package/dist/scripts/agent-router.d.ts +30 -0
- package/dist/scripts/agent-router.js +208 -0
- package/dist/scripts/audit-query.d.ts +2 -0
- package/dist/scripts/audit-query.js +43 -0
- package/dist/scripts/audit-sync.d.ts +2 -0
- package/dist/scripts/audit-sync.js +19 -0
- package/dist/scripts/build-smart-context.d.ts +1 -0
- package/dist/scripts/build-smart-context.js +75 -0
- package/dist/scripts/check-standards.d.ts +1 -0
- package/dist/scripts/check-standards.js +87 -0
- package/dist/scripts/compress-memory.d.ts +16 -0
- package/dist/scripts/compress-memory.js +157 -0
- package/dist/scripts/compress-project-memory.d.ts +1 -0
- package/dist/scripts/compress-project-memory.js +48 -0
- package/dist/scripts/context-ops.d.ts +2 -0
- package/dist/scripts/context-ops.js +464 -0
- package/dist/scripts/dev.d.ts +96 -0
- package/dist/scripts/dev.js +312 -0
- package/dist/scripts/extract-global-knowledge.d.ts +1 -0
- package/dist/scripts/extract-global-knowledge.js +43 -0
- package/dist/scripts/generate-dashboard.d.ts +1 -0
- package/dist/scripts/generate-dashboard.js +48 -0
- package/dist/scripts/governance-dashboard.d.ts +2 -0
- package/dist/scripts/governance-dashboard.js +36 -0
- package/dist/scripts/hook-guard-paths.d.ts +17 -0
- package/dist/scripts/hook-guard-paths.js +68 -0
- package/dist/scripts/hook-post-edit.d.ts +20 -0
- package/dist/scripts/hook-post-edit.js +70 -0
- package/dist/scripts/hook-session-start.d.ts +17 -0
- package/dist/scripts/hook-session-start.js +108 -0
- package/dist/scripts/hook-user-prompt.d.ts +22 -0
- package/dist/scripts/hook-user-prompt.js +193 -0
- package/dist/scripts/memory-schema.d.ts +6 -0
- package/{scripts/memory-schema.mjs → dist/scripts/memory-schema.js} +27 -20
- package/dist/scripts/query-universal-memory.d.ts +1 -0
- package/dist/scripts/query-universal-memory.js +44 -0
- package/dist/scripts/release-check.d.ts +14 -0
- package/dist/scripts/release-check.js +48 -0
- package/dist/scripts/spec-cli.d.ts +29 -0
- package/dist/scripts/spec-cli.js +261 -0
- package/dist/scripts/sprint-manager.d.ts +1 -0
- package/dist/scripts/sprint-manager.js +187 -0
- package/dist/scripts/sync-universal-memory.d.ts +1 -0
- package/dist/scripts/sync-universal-memory.js +277 -0
- package/dist/scripts/token-benchmark.d.ts +20 -0
- package/dist/scripts/token-benchmark.js +181 -0
- package/dist/scripts/tools-doctor.d.ts +20 -0
- package/dist/scripts/tools-doctor.js +120 -0
- package/docs/personas/architect/README.md +4 -4
- package/docs/personas/developer/README.md +3 -3
- package/docs/personas/qa/README.md +3 -3
- package/docs/quick-reference.md +9 -9
- package/docs/structure.md +3 -3
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
- package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
- package/memory/90-decisions/0028-governanca-visivel.md +84 -0
- package/package.json +60 -56
- package/specs/clean-arch-boilerplate/plan.md +137 -0
- package/specs/clean-arch-boilerplate/spec.md +121 -0
- package/specs/clean-arch-boilerplate/tasks.md +70 -0
- package/specs/coerencia-do-sistema/plan.md +155 -0
- package/specs/coerencia-do-sistema/spec.md +15 -14
- package/specs/coerencia-do-sistema/tasks.md +115 -0
- package/specs/governanca-visivel/plan.md +122 -0
- package/specs/governanca-visivel/spec.md +112 -0
- package/specs/governanca-visivel/tasks.md +60 -0
- package/specs/ts-migration/plan.md +199 -0
- package/specs/ts-migration/spec.md +119 -0
- package/specs/ts-migration/tasks.md +110 -0
- package/bin/create-memory-nest-kit.js +0 -125
- package/bin/forja.mjs +0 -143
- package/bin/init-project.js +0 -612
- package/lib/context-builder.js +0 -257
- package/lib/core/checks.mjs +0 -138
- package/lib/core/health.mjs +0 -475
- package/lib/core/registry.mjs +0 -289
- package/lib/core/release.mjs +0 -452
- package/lib/templates/harness/code-intel.mjs +0 -119
- package/lib/templates/harness/mcp.json +0 -10
- package/lib/utils/file-helpers.js +0 -40
- package/lib/validators/structure-validator.js +0 -253
- package/lib/workspace.mjs +0 -213
- package/scripts/agent-harness.mjs +0 -578
- package/scripts/agent-router.mjs +0 -189
- package/scripts/build-smart-context.js +0 -87
- package/scripts/check-standards.js +0 -98
- package/scripts/compress-memory.mjs +0 -198
- package/scripts/compress-project-memory.js +0 -58
- package/scripts/context-ops.mjs +0 -463
- package/scripts/dev.mjs +0 -349
- package/scripts/extract-global-knowledge.js +0 -52
- package/scripts/generate-dashboard.js +0 -59
- package/scripts/hook-guard-paths.mjs +0 -75
- package/scripts/hook-post-edit.mjs +0 -79
- package/scripts/hook-session-start.mjs +0 -104
- package/scripts/hook-user-prompt.mjs +0 -185
- package/scripts/pre-commit.sh +0 -102
- package/scripts/query-universal-memory.js +0 -50
- package/scripts/release-check.mjs +0 -56
- package/scripts/spec-cli.mjs +0 -260
- package/scripts/sprint-manager.js +0 -200
- package/scripts/sync-universal-memory.js +0 -286
- package/scripts/token-benchmark.mjs +0 -203
- package/scripts/tools-doctor.mjs +0 -132
package/.claude/settings.json
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
"hooks": [
|
|
7
7
|
{
|
|
8
8
|
"type": "command",
|
|
9
|
-
"command": "node $CLAUDE_PROJECT_DIR/scripts/hook-session-start.
|
|
9
|
+
"command": "node $CLAUDE_PROJECT_DIR/scripts/hook-session-start.ts",
|
|
10
10
|
"timeout": 5000
|
|
11
11
|
}
|
|
12
12
|
]
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
"hooks": [
|
|
18
18
|
{
|
|
19
19
|
"type": "command",
|
|
20
|
-
"command": "node $CLAUDE_PROJECT_DIR/scripts/hook-user-prompt.
|
|
20
|
+
"command": "node $CLAUDE_PROJECT_DIR/scripts/hook-user-prompt.ts",
|
|
21
21
|
"timeout": 3000
|
|
22
22
|
}
|
|
23
23
|
]
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
"hooks": [
|
|
30
30
|
{
|
|
31
31
|
"type": "command",
|
|
32
|
-
"command": "node $CLAUDE_PROJECT_DIR/scripts/hook-guard-paths.
|
|
32
|
+
"command": "node $CLAUDE_PROJECT_DIR/scripts/hook-guard-paths.ts",
|
|
33
33
|
"timeout": 5000
|
|
34
34
|
}
|
|
35
35
|
]
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
"hooks": [
|
|
42
42
|
{
|
|
43
43
|
"type": "command",
|
|
44
|
-
"command": "node $CLAUDE_PROJECT_DIR/scripts/hook-post-edit.
|
|
44
|
+
"command": "node $CLAUDE_PROJECT_DIR/scripts/hook-post-edit.ts",
|
|
45
45
|
"timeout": 60000
|
|
46
46
|
}
|
|
47
47
|
]
|
|
@@ -50,9 +50,9 @@
|
|
|
50
50
|
},
|
|
51
51
|
"permissions": {
|
|
52
52
|
"allow": [
|
|
53
|
-
"Bash(node bin/forja.
|
|
54
|
-
"Bash(node scripts/spec-cli.
|
|
55
|
-
"Bash(node scripts/agent-router.
|
|
53
|
+
"Bash(node bin/forja.ts *)",
|
|
54
|
+
"Bash(node scripts/spec-cli.ts *)",
|
|
55
|
+
"Bash(node scripts/agent-router.ts *)",
|
|
56
56
|
"Bash(npm run spec:*)",
|
|
57
57
|
"Bash(npm run memory:*)",
|
|
58
58
|
"Bash(npm run sprint:*)",
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,68 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [1.3.0] — 2026-07-19 — Governança visível e o núcleo em TypeScript
|
|
8
|
+
|
|
9
|
+
Duas frentes que amadurecem o framework: a governança sai do arquivo que ninguém abre para
|
|
10
|
+
**consultável e visível**, e o motor de invariantes (`lib/core/`) passa a ser **TypeScript de
|
|
11
|
+
verdade**, com o pacote publicando `dist/` compilado.
|
|
12
|
+
|
|
13
|
+
### Adicionado
|
|
14
|
+
- **Auditoria consultável + painel de governança** (SPEC-014, ADR-0028): `audit:sync` projeta o
|
|
15
|
+
`.context/forja-runs.jsonl` na tabela `audit_runs` (idempotente por `line_hash` — o `.jsonl` segue
|
|
16
|
+
sendo a fonte de verdade); `audit:query` filtra a trilha por `--failed`/`--cmd`/`--since`/`--gate`;
|
|
17
|
+
`governance:dashboard` gera um HTML **estático e self-contained** (sem servidor — a lição do
|
|
18
|
+
ADR-0022) com o estado de specs, ADRs, gates e métricas.
|
|
19
|
+
- **`lib/core/` em TypeScript** (SPEC-012 Fase 2, leaf-first): `checks`, `health`, `release`,
|
|
20
|
+
`doc-graph` e `registry` viram `.ts` com `interface Check/Probe/Result` reais. Dev roda `.ts`
|
|
21
|
+
nativo (Node ≥22.6); o publicado embarca `dist/*.js` (Node ≥20).
|
|
22
|
+
|
|
23
|
+
### Alterado
|
|
24
|
+
- **O pacote publica `dist/` compilado** (SPEC-012 Fase 3): `bin`/`files[]` apontam para `dist/`. O
|
|
25
|
+
`release:check` **builda o `dist/` antes de empacotar**, então o tarball provado é exatamente o
|
|
26
|
+
publicado — sem step de build no CI, sem `dist/` no git, sem janela de staleness.
|
|
27
|
+
- **CI**: o job `test` roda em Node 22.x/24.x (a fonte `.ts` exige strip-types ≥22.6). O suporte a
|
|
28
|
+
Node 20 do pacote publicado (que é `dist/*.js`) segue provado pelo job `release-gate`.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## [1.2.0] — 2026-07-18 — Boilerplate Clean Architecture, coerência de doc e correções
|
|
33
|
+
|
|
34
|
+
Feature nova (um boilerplate), o terceiro gate de invariante (coerência da documentação), e
|
|
35
|
+
**correções de dois bugs vivos na 1.1.6** que o TypeScript achou. A migração TS avançou até o
|
|
36
|
+
pipeline de build provado — mas continua publicando a fonte `.mjs` (a troca para `dist/` é interna
|
|
37
|
+
e fica para uma release futura).
|
|
38
|
+
|
|
39
|
+
### Corrigido
|
|
40
|
+
- **`npm run dev` estava quebrado** na 1.1.6: `scripts/dev.mjs` chamava `spawn()` sem importar —
|
|
41
|
+
`ReferenceError` em três caminhos (agent-harness, compress-memory, create-memory-nest-kit).
|
|
42
|
+
- **`context:budget` / `catalog:assets` estavam quebrados** na 1.1.6: `scripts/context-ops.mjs`
|
|
43
|
+
importava `dbPath` (inexistente; só há `getDbPath`) e o usava em `new Database(dbPath)`.
|
|
44
|
+
- Typedefs `Check`/`Result` duplicados e divergentes em `health.mjs` (resíduo da extração do runner).
|
|
45
|
+
- 22 links relativos quebrados em docs legadas (personas, quick-reference, structure).
|
|
46
|
+
|
|
47
|
+
### Adicionado
|
|
48
|
+
- **Boilerplate `06-clean-arch`** (SPEC-013, ADR-0027): DDD por camadas onde se paga, caminho enxuto
|
|
49
|
+
onde não. Fatia rica (Orders) com inversão de dependência e invariante testável sem subir o Nest;
|
|
50
|
+
caminho enxuto (Products) lado a lado; `WHEN-CLEAN-WHEN-LEAN.md` com o critério; memória por
|
|
51
|
+
bounded context. A economia de token é reportada com honestidade (argumentada, não provada — o
|
|
52
|
+
benchmark é follow-up).
|
|
53
|
+
- **Gate de coerência da documentação** (SPEC-011, ADR-0025): `lib/core/doc-graph.mjs` + três checks
|
|
54
|
+
no `health.mjs` — `docs-commands` (critical: todo `forja <cmd>` citado existe no registry),
|
|
55
|
+
`commands-documented` e `docs-links` (warn). Rodam no `tools:doctor` e no CI.
|
|
56
|
+
- **Resolver de script agnóstico de extensão** (SPEC-012): `resolveScript` desacopla o registry da
|
|
57
|
+
extensão (`.ts → .js → .mjs`), preparando a migração TS. Backward-compatible.
|
|
58
|
+
|
|
59
|
+
### Interno
|
|
60
|
+
- **TypeScript como gate** (SPEC-012, Fases 0-1): `checkJs` estrito sobre a fonte `.mjs`,
|
|
61
|
+
`types:check` no CI, contratos do núcleo (`Check`/`Probe`/`Result`) tipados. Pipeline de build
|
|
62
|
+
(`tsc → dist`) provado; a publicação de `dist/` e a renomeação `.mjs → .ts` ficam para depois.
|
|
63
|
+
|
|
64
|
+
### Nota
|
|
65
|
+
- O `docs-links` pegou o **próprio autor**: um erro de profundidade relativa (`../../` vs `../../../`)
|
|
66
|
+
na correção dos links foi detectado pelo doctor antes do commit. E o `release:check` pegou o
|
|
67
|
+
acoplamento do dist-publish (código em `dist/scripts`, não `scripts/`) antes de qualquer publish.
|
|
68
|
+
|
|
7
69
|
## [1.1.6] — 2026-07-14 — README em inglês
|
|
8
70
|
|
|
9
71
|
A vitrine do pacote passa a ter versão em inglês, para alcançar quem chega pelo npm.
|
package/README.en.md
CHANGED
|
@@ -196,12 +196,18 @@ forja sync:universal # reindex the workspace SQLite FTS5
|
|
|
196
196
|
forja query:universal "<query>" # FTS5 search
|
|
197
197
|
forja context:smart # smart-context (3 modes, ADR-0003)
|
|
198
198
|
forja memory:compress # archive old runs + VACUUM
|
|
199
|
+
forja memory:extract # extract global knowledge from memory
|
|
199
200
|
|
|
200
201
|
# Quality & release
|
|
201
202
|
forja project:check # framework standards (pre-commit)
|
|
202
203
|
forja tools:doctor # core X-ray; exit 1 if broken
|
|
203
204
|
forja release:check --publish # tarball gate before publishing
|
|
204
205
|
forja project:dashboard # static status report
|
|
206
|
+
|
|
207
|
+
# Governance & audit
|
|
208
|
+
forja audit:sync # project the audit trail into a queryable table
|
|
209
|
+
forja audit:query --failed # query: --failed, --cmd <x>, --since 7d
|
|
210
|
+
forja governance:dashboard # static HTML panel (gates, SDD, audit) — no server
|
|
205
211
|
```
|
|
206
212
|
|
|
207
213
|
## Framework vs workspace separation
|
|
@@ -269,11 +275,33 @@ output, code, and ADRs are readable regardless of language.
|
|
|
269
275
|
|
|
270
276
|
## Roadmap
|
|
271
277
|
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
278
|
+
The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
|
|
279
|
+
below either closes a framework frontier with a gate, or carries that pattern into generated projects.
|
|
280
|
+
|
|
281
|
+
**Recently shipped** (v1.2.0)
|
|
282
|
+
|
|
283
|
+
- [x] **Core gate** — `tools:doctor` fails (exit 1) when what blocks the framework is broken (ABI,
|
|
284
|
+
memory, runtime deps) — ADR-0023.
|
|
285
|
+
- [x] **Tarball gate** — `release:check` proves a clean install works before `npm publish`; the three
|
|
286
|
+
historical release bugs fail the gate — ADR-0024.
|
|
287
|
+
- [x] **Doc coherence gate** — docs can't cite a ghost command or a link to nowhere; checked in CI — ADR-0025.
|
|
288
|
+
- [x] **TypeScript as a gate** — strict `checkJs` in CI; core contracts typed. Found three latent bugs
|
|
289
|
+
no test caught (SPEC-012, in progress).
|
|
290
|
+
- [x] **Calibrated Clean Architecture boilerplate** — layers where they pay off, lean where they don't
|
|
291
|
+
(`boilerplates/06-clean-arch`, ADR-0027).
|
|
292
|
+
|
|
293
|
+
**Next** (by dependency, not by wish)
|
|
294
|
+
|
|
295
|
+
- [ ] **Finish the TypeScript migration** — publish `dist/` and rename `.mjs → .ts`. Pipeline proven;
|
|
296
|
+
source stays `.mjs` (Node ≥ 20) until then.
|
|
297
|
+
- [ ] **Token benchmark for clean-arch** — the saving is argued, not proven (ADR-0027): measure the
|
|
298
|
+
same feature in both architectures via `context:smart`. Prove it or recalibrate.
|
|
299
|
+
- [ ] **`release-auditor` consumes the gate** — the third surface from ADR-0024: the agent runs
|
|
300
|
+
`release:check` instead of reimplementing the procedure in prose.
|
|
301
|
+
- [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow.
|
|
302
|
+
- [ ] **Queryable audit + generated dashboard** — promote `.context/forja-runs.jsonl` to an FTS5
|
|
303
|
+
table, and generate a **static** governance page on demand (read-only, no server — the ADR-0022
|
|
304
|
+
lesson that froze the server-dashboard).
|
|
277
305
|
|
|
278
306
|
Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.
|
|
279
307
|
|
package/README.md
CHANGED
|
@@ -186,12 +186,18 @@ forja sync:universal # reindexa SQLite FTS5 do workspace
|
|
|
186
186
|
forja query:universal "<query>" # busca FTS5
|
|
187
187
|
forja context:smart # smart-context (3 modos, ADR-0003)
|
|
188
188
|
forja memory:compress # arquiva runs antigos + VACUUM
|
|
189
|
+
forja memory:extract # extrai conhecimento global da memória
|
|
189
190
|
|
|
190
191
|
# Qualidade & release
|
|
191
192
|
forja project:check # standards do framework (pre-commit)
|
|
192
193
|
forja tools:doctor # raio-x do núcleo; exit 1 se quebrou
|
|
193
194
|
forja release:check --publish # gate do tarball antes de publicar
|
|
194
195
|
forja project:dashboard # relatório estático de status
|
|
196
|
+
|
|
197
|
+
# Governança & auditoria
|
|
198
|
+
forja audit:sync # projeta a trilha de auditoria numa tabela consultável
|
|
199
|
+
forja audit:query --failed # consulta: --failed, --cmd <x>, --since 7d
|
|
200
|
+
forja governance:dashboard # painel HTML estático (gates, SDD, auditoria) — sem servidor
|
|
195
201
|
```
|
|
196
202
|
|
|
197
203
|
## Separação framework × workspace
|
|
@@ -255,10 +261,35 @@ projects/ LEGADO — não usar; projetos vivem no workspace externo
|
|
|
255
261
|
|
|
256
262
|
## Roadmap
|
|
257
263
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
264
|
+
O fio condutor: **converter conhecimento que vive em convenção em invariante executável.** Cada
|
|
265
|
+
item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
|
|
266
|
+
gerados.
|
|
267
|
+
|
|
268
|
+
**Recém-entregue** (v1.2.0)
|
|
269
|
+
|
|
270
|
+
- [x] **Gate do núcleo** — `tools:doctor` reprova (exit 1) quando o que impede o framework de
|
|
271
|
+
trabalhar está quebrado (ABI, memória, deps de runtime) — ADR-0023.
|
|
272
|
+
- [x] **Gate do tarball** — `release:check` prova que uma instalação limpa funciona antes do
|
|
273
|
+
`npm publish`; os três bugs históricos de release reprovam o gate — ADR-0024.
|
|
274
|
+
- [x] **Gate de coerência da doc** — a documentação não pode citar comando fantasma nem link para o
|
|
275
|
+
nada; verificado no CI — ADR-0025.
|
|
276
|
+
- [x] **TypeScript como gate** — `checkJs` estrito no CI; os contratos do núcleo tipados. Achou três
|
|
277
|
+
bugs latentes que nenhum teste pegava (SPEC-012, em curso).
|
|
278
|
+
- [x] **Boilerplate Clean Architecture calibrado** — DDD por camadas onde se paga, enxuto onde não
|
|
279
|
+
(`boilerplates/06-clean-arch`, ADR-0027).
|
|
280
|
+
|
|
281
|
+
**Próximos passos** (por dependência, não por desejo)
|
|
282
|
+
|
|
283
|
+
- [ ] **Fechar a migração TypeScript** — publicar `dist/` e renomear `.mjs → .ts`. Pipeline provado;
|
|
284
|
+
a fonte segue `.mjs` (Node ≥ 20) até lá.
|
|
285
|
+
- [ ] **Benchmark de token do clean-arch** — a economia é argumentada, não provada (ADR-0027):
|
|
286
|
+
medir a mesma feature nas duas arquiteturas via `context:smart`. Provar ou recalibrar.
|
|
287
|
+
- [ ] **`release-auditor` consome o gate** — a terceira superfície do ADR-0024: o agente roda
|
|
288
|
+
`release:check` em vez de reimplementar o procedimento em prosa.
|
|
289
|
+
- [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás.
|
|
290
|
+
- [ ] **Auditoria consultável + painel gerado** — promover `.context/forja-runs.jsonl` a tabela
|
|
291
|
+
FTS5, e gerar um painel de governança **estático** por comando (leitura, sem servidor — a lição
|
|
292
|
+
do ADR-0022, que congelou o dashboard-servidor).
|
|
262
293
|
|
|
263
294
|
Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.
|
|
264
295
|
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# 06 — Clean Architecture Calibrada
|
|
2
|
+
|
|
3
|
+
Boilerplate NestJS + TypeScript com **DDD e Clean Architecture onde se paga, e caminho enxuto onde
|
|
4
|
+
não** — a calibração é o ponto, não as camadas.
|
|
5
|
+
|
|
6
|
+
## A ideia em uma frase
|
|
7
|
+
|
|
8
|
+
Camadas custam arquivos e tokens; você paga por elas quando protegem uma regra de negócio, e evita
|
|
9
|
+
quando é CRUD. Este boilerplate mostra **os dois padrões lado a lado** para você ver o critério, não
|
|
10
|
+
decorar dogma. Leia o [`WHEN-CLEAN-WHEN-LEAN.md`](WHEN-CLEAN-WHEN-LEAN.md) — é o coração.
|
|
11
|
+
|
|
12
|
+
## Estrutura
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
backend/src/
|
|
16
|
+
modules/orders/ # FATIA RICA — 4 camadas, porque há invariante de negócio
|
|
17
|
+
domain/ # agregado + value objects + PORTA (interface). Puro: zero @nestjs/ORM
|
|
18
|
+
application/ # use-cases (contratos tipados, legíveis sem a implementação)
|
|
19
|
+
infrastructure/ # adapter TypeORM (implementa a porta) + mapper domínio↔persistência
|
|
20
|
+
presentation/ # controller fino + DTOs HTTP
|
|
21
|
+
modules/products/ # CAMINHO ENXUTO — 1 camada, porque é CRUD sem regra
|
|
22
|
+
shared/ # Result, base de domínio
|
|
23
|
+
backend/test/ # a invariante testada SEM subir o Nest
|
|
24
|
+
memory/30-domains/ # o contexto de cada domínio na linguagem ubíqua (leia antes do código)
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## A regra de dependência
|
|
28
|
+
|
|
29
|
+
Tudo aponta para **dentro**: `presentation` e `infrastructure` → `application` → `domain`. O domínio
|
|
30
|
+
não importa nada de fora. A infra **implementa** portas que o domínio declara. A inversão acontece no
|
|
31
|
+
módulo, numa linha: `{ provide: ORDER_REPOSITORY, useClass: TypeOrmOrderRepository }`.
|
|
32
|
+
|
|
33
|
+
## Economia de token (ADR-0009)
|
|
34
|
+
|
|
35
|
+
O agente lê `memory/30-domains/<ctx>/context.md` e a **assinatura** do use-case — e sabe o que a
|
|
36
|
+
feature faz sem carregar a implementação. As camadas dão pontos de entrada previsíveis (regra no
|
|
37
|
+
agregado, orquestração no use-case, persistência na infra). Arquitetura como compressão de contexto.
|
|
38
|
+
|
|
39
|
+
## Rodando
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
npm install
|
|
43
|
+
npm run start:dev # sobe o Nest (precisa de DATABASE_URL Postgres)
|
|
44
|
+
npm test # roda os testes de domínio — sem Postgres, sem Nest
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
O `npm test` prova a premissa: a invariante do domínio (`test/orders/place-order.spec.ts`) roda
|
|
48
|
+
instanciando só o agregado. Se um teste de regra precisar do framework, o domínio vazou.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Quando Clean Architecture, quando enxuto
|
|
2
|
+
|
|
3
|
+
Este boilerplate tem **os dois padrões lado a lado, de propósito**:
|
|
4
|
+
|
|
5
|
+
- `modules/orders/` — as quatro camadas (domain / application / infrastructure / presentation).
|
|
6
|
+
- `modules/products/` — uma camada só (controller → repositório direto).
|
|
7
|
+
|
|
8
|
+
Não é inconsistência. É a decisão mais importante da arquitetura, materializada em código: **camadas
|
|
9
|
+
custam tokens e arquivos; você paga por elas quando compram algo, e evita quando não.**
|
|
10
|
+
|
|
11
|
+
## O critério
|
|
12
|
+
|
|
13
|
+
Use o padrão de `orders/` (camadas + porta + use-case) quando **pelo menos uma** for verdade:
|
|
14
|
+
|
|
15
|
+
- Há **invariante de negócio** — uma regra que não pode ser violada em estado nenhum ("não envia sem
|
|
16
|
+
pagamento", "saldo não fica negativo"). A regra precisa de um lar único: o domínio.
|
|
17
|
+
- Há **máquina de estados** — o objeto tem transições legais e ilegais.
|
|
18
|
+
- A regra precisa ser **testada sem subir o framework**, ou sobreviver a troca de infraestrutura.
|
|
19
|
+
- Múltiplos casos de uso operam o mesmo conceito de formas diferentes.
|
|
20
|
+
|
|
21
|
+
Use o padrão de `products/` (uma camada) quando **todas** forem verdade:
|
|
22
|
+
|
|
23
|
+
- É **CRUD** — criar, ler, atualizar, apagar, sem regra além de validação de formato.
|
|
24
|
+
- O "modelo" é a tabela: não há comportamento a proteger.
|
|
25
|
+
- Não há transição de estado que importe.
|
|
26
|
+
|
|
27
|
+
## Por que isso é economia de token, não estética
|
|
28
|
+
|
|
29
|
+
Um agente que vai adicionar uma regra ao contexto `orders` lê o `context.md` do domínio (linguagem
|
|
30
|
+
ubíqua) e a **assinatura** do use-case — e sabe o que fazer sem carregar a implementação inteira. As
|
|
31
|
+
camadas dão pontos de entrada previsíveis: a regra vai no agregado, o caso de uso na aplicação, o
|
|
32
|
+
mapeamento na infra. Menos exploração, menos tokens.
|
|
33
|
+
|
|
34
|
+
O mesmo agente, num CRUD, não deveria pagar esse preço de leitura. Por isso `products/` é raso: para
|
|
35
|
+
um `GET /products`, quatro camadas seriam quatro arquivos a mais para ler, sem nada a proteger — o
|
|
36
|
+
**oposto** de economia de token, com nome de arquitetura.
|
|
37
|
+
|
|
38
|
+
## A regra de ouro
|
|
39
|
+
|
|
40
|
+
**Comece enxuto. Promova quando a primeira invariante aparecer.** Um `products/` que ganha uma regra
|
|
41
|
+
de negócio de verdade (ex.: "não pode desativar produto com pedido aberto") é o sinal de promover
|
|
42
|
+
para o padrão de `orders/` — não antes. Arquitetura antecipada é dívida de token paga adiantado.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "clean-arch-backend",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"private": true,
|
|
5
|
+
"scripts": {
|
|
6
|
+
"build": "nest build",
|
|
7
|
+
"start": "nest start",
|
|
8
|
+
"start:dev": "nest start --watch",
|
|
9
|
+
"start:prod": "node dist/main",
|
|
10
|
+
"lint": "eslint \"src/**/*.ts\" --max-warnings=0",
|
|
11
|
+
"test": "jest",
|
|
12
|
+
"test:watch": "jest --watch",
|
|
13
|
+
"test:cov": "jest --coverage",
|
|
14
|
+
"test:e2e": "jest --config test/jest-e2e.json"
|
|
15
|
+
},
|
|
16
|
+
"dependencies": {
|
|
17
|
+
"@nestjs/common": "^11.0.0",
|
|
18
|
+
"@nestjs/core": "^11.0.0",
|
|
19
|
+
"@nestjs/platform-express": "^11.0.0",
|
|
20
|
+
"@nestjs/typeorm": "^11.0.0",
|
|
21
|
+
"class-transformer": "^0.5.1",
|
|
22
|
+
"class-validator": "^0.14.1",
|
|
23
|
+
"pg": "^8.13.0",
|
|
24
|
+
"reflect-metadata": "^0.2.2",
|
|
25
|
+
"rxjs": "^7.8.1",
|
|
26
|
+
"typeorm": "^0.3.20"
|
|
27
|
+
},
|
|
28
|
+
"devDependencies": {
|
|
29
|
+
"@nestjs/testing": "^11.0.0",
|
|
30
|
+
"@types/jest": "^29.5.0",
|
|
31
|
+
"@types/node": "^22.0.0",
|
|
32
|
+
"jest": "^29.7.0",
|
|
33
|
+
"ts-jest": "^29.2.0",
|
|
34
|
+
"typescript": "^5.6.0"
|
|
35
|
+
},
|
|
36
|
+
"jest": {
|
|
37
|
+
"moduleFileExtensions": ["js", "json", "ts"],
|
|
38
|
+
"rootDir": ".",
|
|
39
|
+
"testRegex": ".*\\.spec\\.ts$",
|
|
40
|
+
"transform": { "^.+\\.ts$": "ts-jest" },
|
|
41
|
+
"testEnvironment": "node"
|
|
42
|
+
}
|
|
43
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { Module } from '@nestjs/common';
|
|
2
|
+
import { TypeOrmModule } from '@nestjs/typeorm';
|
|
3
|
+
import { OrdersModule } from './modules/orders/orders.module';
|
|
4
|
+
import { ProductsModule } from './modules/products/products.module';
|
|
5
|
+
import { OrderOrmEntity } from './modules/orders/infrastructure/order.orm-entity';
|
|
6
|
+
import { Product } from './modules/products/product.entity';
|
|
7
|
+
|
|
8
|
+
@Module({
|
|
9
|
+
imports: [
|
|
10
|
+
TypeOrmModule.forRoot({
|
|
11
|
+
type: 'postgres',
|
|
12
|
+
url: process.env.DATABASE_URL,
|
|
13
|
+
entities: [OrderOrmEntity, Product],
|
|
14
|
+
synchronize: process.env.NODE_ENV !== 'production', // dev only
|
|
15
|
+
}),
|
|
16
|
+
OrdersModule,
|
|
17
|
+
ProductsModule,
|
|
18
|
+
],
|
|
19
|
+
})
|
|
20
|
+
export class AppModule {}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { NestFactory } from '@nestjs/core';
|
|
2
|
+
import { ValidationPipe } from '@nestjs/common';
|
|
3
|
+
import { AppModule } from './app.module';
|
|
4
|
+
|
|
5
|
+
async function bootstrap() {
|
|
6
|
+
const app = await NestFactory.create(AppModule);
|
|
7
|
+
app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
|
|
8
|
+
await app.listen(process.env.PORT ?? 3000);
|
|
9
|
+
}
|
|
10
|
+
bootstrap();
|
package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { Inject, Injectable } from '@nestjs/common';
|
|
2
|
+
import { randomUUID } from 'node:crypto';
|
|
3
|
+
import { Order, OrderLine } from '../domain/order.entity';
|
|
4
|
+
import { Money } from '../domain/money.vo';
|
|
5
|
+
import { ORDER_REPOSITORY, OrderRepository } from '../domain/order.repository';
|
|
6
|
+
import { Result } from '../../../shared/result';
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Contratos de entrada/saída — tipados e legíveis. Um agente entende o que o use-case faz pela
|
|
10
|
+
* assinatura, **sem ler o corpo** (AC-5). É a compressão de contexto: o tipo é o resumo.
|
|
11
|
+
*/
|
|
12
|
+
export interface PlaceOrderInput {
|
|
13
|
+
customerId: string;
|
|
14
|
+
items: Array<{ productId: string; unitPriceCents: number; quantity: number }>;
|
|
15
|
+
}
|
|
16
|
+
export interface PlaceOrderOutput {
|
|
17
|
+
orderId: string;
|
|
18
|
+
totalCents: number;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* PlaceOrder — orquestra o domínio + a porta. O use-case não tem regra de negócio própria: ele
|
|
23
|
+
* traduz o input, chama o agregado (que decide), e persiste via porta. A regra ("precisa de itens")
|
|
24
|
+
* é do `Order`, não daqui.
|
|
25
|
+
*/
|
|
26
|
+
@Injectable()
|
|
27
|
+
export class PlaceOrderUseCase {
|
|
28
|
+
// Injeta a PORTA (token), nunca o adapter concreto — a inversão de dependência.
|
|
29
|
+
constructor(@Inject(ORDER_REPOSITORY) private readonly orders: OrderRepository) {}
|
|
30
|
+
|
|
31
|
+
async execute(input: PlaceOrderInput): Promise<Result<PlaceOrderOutput>> {
|
|
32
|
+
const lines: OrderLine[] = input.items.map((i) => ({
|
|
33
|
+
productId: i.productId,
|
|
34
|
+
unitPrice: Money.of(i.unitPriceCents),
|
|
35
|
+
quantity: i.quantity,
|
|
36
|
+
}));
|
|
37
|
+
|
|
38
|
+
const created = Order.place(randomUUID(), input.customerId, lines);
|
|
39
|
+
if (created.isFailure) return Result.fail(created.error!);
|
|
40
|
+
|
|
41
|
+
const order = created.value;
|
|
42
|
+
order.confirm(); // rascunho → confirmado (a máquina de estados do domínio valida)
|
|
43
|
+
await this.orders.save(order);
|
|
44
|
+
|
|
45
|
+
return Result.ok({ orderId: order.id, totalCents: order.total.cents });
|
|
46
|
+
}
|
|
47
|
+
}
|
package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { Inject, Injectable } from '@nestjs/common';
|
|
2
|
+
import { ORDER_REPOSITORY, OrderRepository } from '../domain/order.repository';
|
|
3
|
+
import { Result } from '../../../shared/result';
|
|
4
|
+
|
|
5
|
+
export interface ShipOrderInput {
|
|
6
|
+
orderId: string;
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* ShipOrder — demonstra a invariante-chave passando pelo domínio: `order.ship()` **falha** se o
|
|
11
|
+
* pedido não estiver PAID. O use-case não reimplementa a regra; ele confia no agregado e propaga a
|
|
12
|
+
* falha. A regra "não envia sem pagamento" existe num lugar só: `Order`.
|
|
13
|
+
*/
|
|
14
|
+
@Injectable()
|
|
15
|
+
export class ShipOrderUseCase {
|
|
16
|
+
constructor(@Inject(ORDER_REPOSITORY) private readonly orders: OrderRepository) {}
|
|
17
|
+
|
|
18
|
+
async execute(input: ShipOrderInput): Promise<Result<void>> {
|
|
19
|
+
const order = await this.orders.byId(input.orderId);
|
|
20
|
+
if (!order) return Result.fail('pedido não encontrado');
|
|
21
|
+
|
|
22
|
+
const shipped = order.ship(); // domínio decide: só sai de PAID
|
|
23
|
+
if (shipped.isFailure) return Result.fail(shipped.error!);
|
|
24
|
+
|
|
25
|
+
await this.orders.save(order);
|
|
26
|
+
return Result.ok(undefined);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Money — value object. Imutável, comparado por valor, valida a si mesmo na criação.
|
|
3
|
+
* Zero dependência de framework: é TypeScript puro (o ponto do domínio isolado).
|
|
4
|
+
*/
|
|
5
|
+
export class Money {
|
|
6
|
+
private constructor(public readonly cents: number) {}
|
|
7
|
+
|
|
8
|
+
static of(cents: number): Money {
|
|
9
|
+
if (!Number.isInteger(cents) || cents < 0) {
|
|
10
|
+
throw new Error('Money exige inteiro não-negativo em centavos');
|
|
11
|
+
}
|
|
12
|
+
return new Money(cents);
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
static zero(): Money {
|
|
16
|
+
return new Money(0);
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
plus(other: Money): Money {
|
|
20
|
+
return new Money(this.cents + other.cents);
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
times(qty: number): Money {
|
|
24
|
+
return Money.of(this.cents * qty);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
isZero(): boolean {
|
|
28
|
+
return this.cents === 0;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* OrderStatus — value object que é uma máquina de estados. As transições legais moram AQUI, no
|
|
3
|
+
* domínio, não num `if` espalhado pelos services. Um estado inválido é impossível de construir.
|
|
4
|
+
*
|
|
5
|
+
* DRAFT ──confirm──► CONFIRMED ──pay──► PAID ──ship──► SHIPPED
|
|
6
|
+
* └──────────────── cancel ──────────────► CANCELLED (de qualquer não-enviado)
|
|
7
|
+
*/
|
|
8
|
+
export type OrderStatusValue = 'DRAFT' | 'CONFIRMED' | 'PAID' | 'SHIPPED' | 'CANCELLED';
|
|
9
|
+
|
|
10
|
+
const TRANSITIONS: Record<OrderStatusValue, OrderStatusValue[]> = {
|
|
11
|
+
DRAFT: ['CONFIRMED', 'CANCELLED'],
|
|
12
|
+
CONFIRMED: ['PAID', 'CANCELLED'],
|
|
13
|
+
PAID: ['SHIPPED', 'CANCELLED'],
|
|
14
|
+
SHIPPED: [],
|
|
15
|
+
CANCELLED: [],
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
export class OrderStatus {
|
|
19
|
+
private constructor(public readonly value: OrderStatusValue) {}
|
|
20
|
+
|
|
21
|
+
static draft(): OrderStatus {
|
|
22
|
+
return new OrderStatus('DRAFT');
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
static from(value: OrderStatusValue): OrderStatus {
|
|
26
|
+
return new OrderStatus(value);
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
canTransitionTo(next: OrderStatusValue): boolean {
|
|
30
|
+
return TRANSITIONS[this.value].includes(next);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
is(value: OrderStatusValue): boolean {
|
|
34
|
+
return this.value === value;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import { Result } from '../../../shared/result';
|
|
2
|
+
import { Money } from './money.vo';
|
|
3
|
+
import { OrderStatus } from './order-status.vo';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Order — o agregado. **Toda invariante de negócio mora aqui**, em TypeScript puro:
|
|
7
|
+
*
|
|
8
|
+
* - não confirma um pedido sem itens;
|
|
9
|
+
* - não paga o que não foi confirmado; não envia o que não foi pago;
|
|
10
|
+
* - o total é derivado das linhas, nunca setado de fora.
|
|
11
|
+
*
|
|
12
|
+
* Nenhum import de `@nestjs` ou de ORM. É isso que torna `place-order.spec.ts` capaz de testar a
|
|
13
|
+
* regra instanciando só este objeto — sem subir o Nest. Se um dia precisar do framework para testar
|
|
14
|
+
* a invariante, o domínio vazou.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
export interface OrderLine {
|
|
18
|
+
readonly productId: string;
|
|
19
|
+
readonly unitPrice: Money;
|
|
20
|
+
readonly quantity: number;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export class Order {
|
|
24
|
+
private constructor(
|
|
25
|
+
public readonly id: string,
|
|
26
|
+
public readonly customerId: string,
|
|
27
|
+
private _lines: OrderLine[],
|
|
28
|
+
private _status: OrderStatus,
|
|
29
|
+
) {}
|
|
30
|
+
|
|
31
|
+
/** Cria um pedido em rascunho. Regra: precisa de ao menos uma linha. */
|
|
32
|
+
static place(id: string, customerId: string, lines: OrderLine[]): Result<Order> {
|
|
33
|
+
if (lines.length === 0) {
|
|
34
|
+
return Result.fail('um pedido precisa de ao menos um item');
|
|
35
|
+
}
|
|
36
|
+
if (lines.some((l) => l.quantity <= 0)) {
|
|
37
|
+
return Result.fail('quantidade de item deve ser positiva');
|
|
38
|
+
}
|
|
39
|
+
return Result.ok(new Order(id, customerId, [...lines], OrderStatus.draft()));
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Reconstrói do estado persistido (usado pelo mapper da infra — sem revalidar regra de criação). */
|
|
43
|
+
static rehydrate(id: string, customerId: string, lines: OrderLine[], status: OrderStatus): Order {
|
|
44
|
+
return new Order(id, customerId, lines, status);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
get status(): OrderStatus {
|
|
48
|
+
return this._status;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
get lines(): readonly OrderLine[] {
|
|
52
|
+
return this._lines;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** Total derivado das linhas — nunca um campo setável de fora. */
|
|
56
|
+
get total(): Money {
|
|
57
|
+
return this._lines.reduce((acc, l) => acc.plus(l.unitPrice.times(l.quantity)), Money.zero());
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
confirm(): Result<void> {
|
|
61
|
+
return this.transition('CONFIRMED');
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Invariante-chave: só paga o confirmado. */
|
|
65
|
+
pay(): Result<void> {
|
|
66
|
+
return this.transition('PAID');
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** Invariante-chave: **não envia sem pagamento**. A transição só é legal a partir de PAID. */
|
|
70
|
+
ship(): Result<void> {
|
|
71
|
+
return this.transition('SHIPPED');
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
cancel(): Result<void> {
|
|
75
|
+
return this.transition('CANCELLED');
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
private transition(to: Parameters<OrderStatus['canTransitionTo']>[0]): Result<void> {
|
|
79
|
+
if (!this._status.canTransitionTo(to)) {
|
|
80
|
+
return Result.fail(`transição inválida: ${this._status.value} → ${to}`);
|
|
81
|
+
}
|
|
82
|
+
this._status = OrderStatus.from(to);
|
|
83
|
+
return Result.ok(undefined);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { Order } from './order.entity';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* OrderRepository — a **PORTA** (Clean Architecture / Hexagonal). É uma `interface` no domínio: o
|
|
5
|
+
* domínio declara o que precisa de persistência, sem saber *como*. O adapter (TypeORM, in-memory,
|
|
6
|
+
* outro) a implementa na camada de infraestrutura.
|
|
7
|
+
*
|
|
8
|
+
* `ORDER_REPOSITORY` é o token de injeção do NestJS — porque interface não existe em runtime, o Nest
|
|
9
|
+
* injeta por token. O use-case pede o token; o módulo faz o bind token→adapter. É assim que a
|
|
10
|
+
* dependência aponta para DENTRO: application → domain, e a infra implementa a porta do domínio.
|
|
11
|
+
*/
|
|
12
|
+
export const ORDER_REPOSITORY = Symbol('OrderRepository');
|
|
13
|
+
|
|
14
|
+
export interface OrderRepository {
|
|
15
|
+
save(order: Order): Promise<void>;
|
|
16
|
+
byId(id: string): Promise<Order | null>;
|
|
17
|
+
}
|