@puca/puca-core 15.0.1 → 15.0.2
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/dist/core/services/mcp/mcp-server.service.d.ts +0 -9
- package/dist/core/services/mcp/mcp-server.service.js.map +1 -1
- package/dist/helpers/json-stringify-omitting-transaction.js +2 -2
- package/dist/helpers/json-stringify-omitting-transaction.js.map +1 -1
- package/dist/tsconfig.tsbuildinfo +1 -1
- package/package.json +1 -1
- package/analise-dual-write-vs-outbox-original.md +0 -146
package/package.json
CHANGED
|
@@ -1,146 +0,0 @@
|
|
|
1
|
-
# Análise: dual-write que a outbox (mqService / JobExecutor / secondaryDatabase) não resolve sozinha
|
|
2
|
-
|
|
3
|
-
**Data:** 2026-09-04
|
|
4
|
-
**Fonte:** `relatorio-dual-write-notificacoes.md` (snapshot git `9ee973c`; o arquivo não está no working tree atual de `master`).
|
|
5
|
-
**Mecanismo avaliado:** `TransactionOutboxService.enqueue` via
|
|
6
|
-
|
|
7
|
-
- `mqService.publish` / `sendToQueue` (`engine: mqService`)
|
|
8
|
-
- `JobExecutor.add` (`engine: jobExecutor`)
|
|
9
|
-
- `secondaryDatabase.publish` (`engine: secondaryDatabase`)
|
|
10
|
-
|
|
11
|
-
**Critério:** dual-write banco ↔ Rabbit/Bull/Redis pub some só quando o INSERT em `transaction_outbox` entra na **mesma** transação Postgres da mutação. Sem `options.transaction`, o enqueue usa `getPseudoTransaction()` (autocommit separado) e o dual-write continua.
|
|
12
|
-
|
|
13
|
-
Este arquivo lista o que **não fecha** só com esse envelope, ou que **precisa de mais alteração** além de “passar `{ transaction }` na chamada”. A lista do que **fecha** está no chat desta análise.
|
|
14
|
-
|
|
15
|
-
---
|
|
16
|
-
|
|
17
|
-
## 1. Não são esses três engines (outbox desta tarefa não aplica)
|
|
18
|
-
|
|
19
|
-
| Ocorrência no relatório | Por quê |
|
|
20
|
-
|---|---|
|
|
21
|
-
| `emitChange` + handlers (`cache-repository-redis.ts`) | Fan-out **in-process** depois do Redis `.change`. Não publica para fora. |
|
|
22
|
-
| `notification.service` / `followers.service` | Canal **HTTP** próprio. |
|
|
23
|
-
| `email.service` (Elastic Email) | HTTP. |
|
|
24
|
-
| `web-socket.service` | UI efêmera; publicar antes do commit mostraria estado que pode dar rollback. |
|
|
25
|
-
| `monitor.ts` (Influx / Discord) | Telemetria. |
|
|
26
|
-
| Hooks CRUD `afterUpdate` / `afterCommit` **em si** | Orquestração in-process. Dual-write só se o app daí chamar MQ/job/Redis pub. |
|
|
27
|
-
| §5.4 overrides `afterCommit` sem MQ/job (phone, email, address, indicator, interaction, etc.) | Outro canal (HTTP CRM, e-mail). |
|
|
28
|
-
|
|
29
|
-
**Mais alteração possível (fora deste envelope):** outbox de HTTP, ou mover o side-effect para um job/MQ já envelopado.
|
|
30
|
-
|
|
31
|
-
---
|
|
32
|
-
|
|
33
|
-
## 2. São MQ/Bull/Redis pub, mas o envelope sozinho não fecha
|
|
34
|
-
|
|
35
|
-
### 2.1 Hook CRUD `afterCommit` zera a transação
|
|
36
|
-
|
|
37
|
-
**Relatório:** §5.1 e §5.2 (rule, posting-fin/contract/sale `callFlowOnEntityChange`, person, task, product, card).
|
|
38
|
-
|
|
39
|
-
`CrudBaseService` anula `afterUpdateArgs.args.transaction` antes de `afterCommit` (TX já commitou). Qualquer `publish`/`add` aí cai em pseudo-TX.
|
|
40
|
-
|
|
41
|
-
**O que falta:** tirar o enqueue do `afterCommit` e fazê-lo com a TX **ainda aberta** (`afterUpdate`, ou código antes de `commit()`). Não recolocar `{ transaction }` no afterCommit esperando `after.args.transaction`.
|
|
42
|
-
|
|
43
|
-
Delete CRUD **não tem** `afterCommit`.
|
|
44
|
-
|
|
45
|
-
### 2.2 Fechamento async de exercício (`close-exercise-{pid}`)
|
|
46
|
-
|
|
47
|
-
**Relatório:** §5.1 hop `FinancialExercisesService.afterCommit` → `scheduleCloseExerciseJob` → `closeExerciseJob.add`.
|
|
48
|
-
|
|
49
|
-
O path async só existe quando **não há** TX na request. Enqueue no afterCommit = pseudo-TX. Enqueue no `beforeUpdate` = job fantasma se o save falhar.
|
|
50
|
-
|
|
51
|
-
**O que falta:** wrap de TX própria (`async-close-exercise`), persistir `closed` + outbox no mesmo commit, job no `afterUpdate`. Não é só `add({ transaction })`.
|
|
52
|
-
|
|
53
|
-
### 2.3 `callFlowOnEntityChange` em `DEVELOPMENT`
|
|
54
|
-
|
|
55
|
-
**Relatório:** posting-fin, contract, sale.
|
|
56
|
-
|
|
57
|
-
Em DEV o afterCommit chama `callFlowOnEntityChangeProcess` **in-process**, não `JobExecutor.add`.
|
|
58
|
-
|
|
59
|
-
**O que falta:** aceitar dual-write leve em DEV, ou unificar DEV com o job/outbox (muda timing e deixa o flow dentro do commit se for síncrono na TX).
|
|
60
|
-
|
|
61
|
-
### 2.4 Payload de job com a TX viva (`RuleService`)
|
|
62
|
-
|
|
63
|
-
`onAfterUpdateJob.add(after)` serializava o objeto `After` inteiro, inclusive `args.transaction`.
|
|
64
|
-
|
|
65
|
-
**O que falta:** no enqueue, TX só em `opts.transaction`; no payload do Bull, `transaction: null` (como o afterCommit antigo, que já zerava).
|
|
66
|
-
|
|
67
|
-
### 2.5 `crud-front-base`: fila `${table}.update` **antes** do write
|
|
68
|
-
|
|
69
|
-
**Relatório:** seção 2.
|
|
70
|
-
|
|
71
|
-
`sendToQueue` dispara o comando **sem** a entidade ter sido gravada neste processo; o write é no consumer. Outbox com TX da request atual não acopla a um INSERT que ainda não aconteceu.
|
|
72
|
-
|
|
73
|
-
**O que falta:** outro desenho (gravar intenção na mesma TX, ou tratar como command-queue e não como dual-write pós-persistência).
|
|
74
|
-
|
|
75
|
-
### 2.6 Incremental Search / Typesense (`JobExecutor.add`)
|
|
76
|
-
|
|
77
|
-
**Relatório:** seção 2 — pode ocorrer antes do commit se houver `transactionId` externo.
|
|
78
|
-
|
|
79
|
-
`incremental-search.service.ts` / `v2` não aceitam `transaction` no `update`/`delete`. O envelope existe, mas o caller não tem como acoplar.
|
|
80
|
-
|
|
81
|
-
**O que falta:** plumbear `transaction` (e `key`) da mutação até o `add`.
|
|
82
|
-
|
|
83
|
-
### 2.7 Clients `flow.service.onEntityChange` e `crm.service.addInteraction`
|
|
84
|
-
|
|
85
|
-
**Relatório:** seção 2 e §5.3 (`billing-document` chama `flowService.onEntityChange` no afterCommit).
|
|
86
|
-
|
|
87
|
-
Hoje `sendToQueue` **sem** `transaction`. O envelope resolve só se a API do client receber a TX do caller.
|
|
88
|
-
|
|
89
|
-
**O que falta:** `onEntityChange({ ..., transaction })` / `addInteraction(..., { transaction })` e todos os call sites relevantes. O `onEntityChange` no cancelamento de NF (~1860) continua afterCommit/HTTP+MQ sem TX.
|
|
90
|
-
|
|
91
|
-
### 2.8 `PersonService.enforceType` (`on-person-change`)
|
|
92
|
-
|
|
93
|
-
**Relatório:** o publish do hook CRUD está em §5.2; estes outros publishes (~1492 / ~1506) **não** estavam na lista.
|
|
94
|
-
|
|
95
|
-
**O que falta:** passar a TX do caller quando existir; senão documentar como gap. Não mistura com o publish do CRUD.
|
|
96
|
-
|
|
97
|
-
### 2.9 E-mail de cobrança e boleto no posting-fin
|
|
98
|
-
|
|
99
|
-
**Relatório:** §5.3 `afterConfirmation` (o mesmo afterCommit que publicava `on-posting-fin-created`).
|
|
100
|
-
|
|
101
|
-
`sendEmail` e `paymentDocumentService.createPaymentDocument` não são mq/job/Redis pub.
|
|
102
|
-
|
|
103
|
-
**O que falta:** outbox HTTP/plugin, ou job envelopado **depois** de persistir o documento interno na mesma TX. Não mover e-mail/boleto para dentro da TX aberta (efeito no mundo externo com rollback possível).
|
|
104
|
-
|
|
105
|
-
### 2.10 Jobs no **consumer** do card (não dual-write da TX original)
|
|
106
|
-
|
|
107
|
-
**Relatório:** §5.2 — `createSubCards` / `replyChangesOnCrm` / `notifyCardParent` / `etl` depois de `card-service.afterCommit`.
|
|
108
|
-
|
|
109
|
-
São encadeamento de fila. Se o `sendToQueue` original for para a outbox na TX do card, esses `.add` no worker são outro ciclo (o worker já está fora da TX da entidade).
|
|
110
|
-
|
|
111
|
-
**O que falta (só se quiser atomicidade worker ↔ Bull):** o processamento do consumer precisaria de TX própria + outbox; não é o dual-write do save do card.
|
|
112
|
-
|
|
113
|
-
### 2.11 `cache.service.invalidate` (Redis `${prefix}-invalidate`)
|
|
114
|
-
|
|
115
|
-
**Relatório:** seção 2 / tabela §3 — “soft”, fora da tarefa.
|
|
116
|
-
|
|
117
|
-
Agora `secondaryDatabase.publish` **entra** na outbox, mas o invalidate usa overload com **callback** e **sem** `transaction`. Continua dual-write (mutação vs INSERT outbox autocommit), e o callback assume publish síncrono no Redis.
|
|
118
|
-
|
|
119
|
-
**O que falta:** API async + TX nos call sites; aceitar latência do relay; revisar callers que esperam invalidate imediato no mesmo tick.
|
|
120
|
-
|
|
121
|
-
### 2.12 `report.service` e `llm/token-budget` (cron)
|
|
122
|
-
|
|
123
|
-
**Relatório:** não são dual-write de entidade.
|
|
124
|
-
|
|
125
|
-
Repeat/cron no `JobExecutor.add` via outbox é outro problema (job recorrente vs row única de outbox / `jobId` estável). Não usar o envelope como se fosse “gravei entidade X”.
|
|
126
|
-
|
|
127
|
-
---
|
|
128
|
-
|
|
129
|
-
## 3. Ajustes transversais (não são ocorrências do relatório, mas bloqueiam o objetivo)
|
|
130
|
-
|
|
131
|
-
| Tema | Por quê importa |
|
|
132
|
-
|---|---|
|
|
133
|
-
| **`key` de idempotência** | `ON CONFLICT (idempotency_key) DO NOTHING` + Bull `jobId`. `key` só com `puca_pid` impede o **segundo** update da mesma entidade enquanto a row existir. `pid + transaction.getID()` é o formato para “todo save dispara”. Sem schema, o dual-write some e a regra de negócio muda. |
|
|
134
|
-
| **Não serializar `Transaction` no payload** | Além da rule: qualquer `add(after)` / `sendToQueue(after)` no `afterUpdate` (TX viva) precisa omitir a TX do JSON. |
|
|
135
|
-
| **Timing vs afterCommit local** | Enqueue na TX + drain no relay: consumidores MQ podem correr **antes** de e-mail/WS/sync que ainda estão no afterCommit do mesmo pod (person sync, task WS, posting-fin e-mail). |
|
|
136
|
-
|
|
137
|
-
---
|
|
138
|
-
|
|
139
|
-
## 4. Lembrete: o que já está no caminho certo no core
|
|
140
|
-
|
|
141
|
-
Não é gap do envelope, desde que continue **antes** do `commit()` com `{ transaction }`:
|
|
142
|
-
|
|
143
|
-
- `repository` insert/update/delete → `OnTableChangeService.publish` (Rabbit `table-event-listener` **e** Redis `${table}.change` via outbox).
|
|
144
|
-
- `migration.service` (incluindo `_alterTableDropColumn`): o publish “na hora” deixa de ser dual-write inverso porque a row de outbox dá rollback junto com o DDL.
|
|
145
|
-
|
|
146
|
-
`OnTableChange` ignora `tableName === 'transaction_outbox'` para não recircular.
|