mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-21 02:53:06 +00:00
238 lines
16 KiB
Markdown
238 lines
16 KiB
Markdown
# Impl: C120 — race de append de telefone em findOrCreateContactByPhone (lock de ficha)
|
|
|
|
Status: aprovado
|
|
Atualizado em: 2026-08-24
|
|
Issue: #663
|
|
Intenção: body da Issue (fonte única — não há `docs/plans/c120-*.md` de intenção; o body é a spec)
|
|
Appetite restante: herdar sem appetite declarado (P2)
|
|
|
|
## Leitura da intenção
|
|
|
|
- **Outcome (aceite):** dois fluxos concorrentes contra a MESMA ficha nunca perdem um
|
|
telefone digitado — ou, na alternativa, uma decisão documentada de aceitar a perda com
|
|
rationale. O alvo nomeado é `findOrCreateContactByPhone`
|
|
(`src/utilities/contactIdentity.ts`).
|
|
- **O que NÃO negociar:** granularidade de lock por ficha (não trocar o modelo de
|
|
identidade); sem mudança de schema (nenhuma migration; `contact_phones` relacional
|
|
intocado); sem mudança de Access/Consent; editar o dono que já possui o concern
|
|
(locks de contato), não criar caminho paralelo.
|
|
- **Por que não foi no C112:** a granularidade por-telefone é herdada do C111; o C112
|
|
alargou a janela ao introduzir o append-on-reuse (re-registro/import da MESMA pessoa
|
|
com 1 ficha e primário inambíguo). Dois fluxos que resolvam a mesma ficha por primários
|
|
DIFERENTES (ficha com 2+ números) não disputam nenhum `contact-phone:*` em comum — os
|
|
locks por-telefone disjuntos não os serializam, os dois leem o array pré-mudança e o
|
|
last-writer-wins perde um append. O lock por ficha é o ponto de serialização correto.
|
|
- **O que reavaliar:** (a) o MECANISMO — lock de ficha+re-read (A) vs escrita
|
|
determinística SQL (B) vs aceitar/documentar (C); (b) se o RMW do sync conta→ficha
|
|
(`CampaignUser.ts`) entra no escopo mesmo com o custo CI de `src/collections/`
|
|
(HIGH_RISK); (c) os editors full-replace de staff — entrarem ou serem documentados
|
|
como fora do aceite; (d) se a chave do invite redemption (`invite-redemption-contact:<id>`)
|
|
é unificada agora ou vira débito; (e) a forma do spec int (chamada direta da unidade vs
|
|
através dos flows de action, que exigem consent/municipality etc.).
|
|
|
|
## Abordagem recomendada
|
|
|
|
O núcleo é lock de ficha `contact-ficha:<id>` AO REDOR do read-modify-write **com
|
|
re-leitura da ficha DENTRO do lock**. Sem a re-leitura o lock não resolve nada: o array
|
|
lido no `find` pré-lock pode estar stale e o append ainda se perde. Os locks de telefone
|
|
de hoje são mantidos (são a serialização cruzada entre fichas distintas no create-path e
|
|
a proteção de dedupe de criações concorrentes); o ficha-lock é sempre adquirido POR
|
|
ÚLTIMO e sozinho (uma chave de entidade por RMW), então não existe ciclo de lock-order.
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant A as Fluxo A (tx₁)
|
|
participant P as Postgres
|
|
participant B as Fluxo B (tx₂)
|
|
|
|
Note over A,P: locks de telefone disjuntos: P1,P3 (A) vs P2,P4 (B)
|
|
A->>P: acquire(contact-phone:P1, contact-phone:P3)
|
|
B->>P: acquire(contact-phone:P2, contact-phone:P4)
|
|
A->>P: find contact where phones.value=P1 → ficha F
|
|
B->>P: find contact where phones.value=P2 → ficha F
|
|
Note over A,B: gate segura os DOIS finds → ambos leem [P1,P2] pré-mudança
|
|
A->>P: acquire(contact-ficha:F) %% NOVO — lock de ficha, por último
|
|
A->>P: findByID F (re-read, select phones) → [P1,P2]
|
|
A->>P: update F phones=[P1,P2,P3]
|
|
B->>P: acquire(contact-ficha:F) %% bloqueia até o commit de A (xact lock)
|
|
A->>P: commit → libera o lock
|
|
B->>P: findByID F (re-read fresco) → [P1,P2,P3]
|
|
B->>P: update F phones=[P1,P2,P3,P4]
|
|
B->>P: commit
|
|
Note over P: F = {P1,P2,P3,P4} — nenhum telefone digitado perdido
|
|
```
|
|
|
|
Sem o fix, A e B escrevem `[P1,P2,P3]` e `[P1,P2,P4]` a partir do MESMO array lido
|
|
`[P1,P2]` e o último commit vence — final com 3 números, P3 ou P4 perdido
|
|
(last-writer-wins). O lock de xact garante commit-then-release: o segundo fluxo a entrar
|
|
sempre re-lê o append do primeiro (que já está commitado) e só acrescenta os seus
|
|
faltantes.
|
|
|
|
**Opções consideradas:**
|
|
|
|
- **A — lock de ficha `contact-ficha:<id>` + re-read dentro do lock (recomendada):**
|
|
após o `find` retornar exatamente 1 ficha (`totalDocs === 1`), adquirir o lock, re-ler
|
|
a ficha via `findByID` (depth 0, `select: { phones: { value: true } }`) dentro do lock e
|
|
montar o append de faltantes sobre essa leitura fresca; `update` só se `missing > 0`.
|
|
Mantém os phone locks e o `find` de dedupe intactos. Custo: 1 round-trip de lock + 1
|
|
`findByID` seletivo, só no branch de reuso (caminho raro).
|
|
- **B — escrita determinística via SQL (rejeitada):** append direto na tabela relacional
|
|
`contact_phones` (`_parent_id`/`_order`/`value`) sem read prévio. Rejeitada porque:
|
|
`contact_phones` não tem índice UNIQUE nem validação própria — a dedupe intraficha vive
|
|
só em memória (`normalizeContactPhones`, `Contact.ts:22-59`); um insert SQL burlaria o
|
|
adapter/hook do Payload (validation, `overrideAccess`, transação única) e o commit
|
|
atômico com o resto do flow; a mesma garantia custaria algo razoável, mas com blast
|
|
radius de camada inteira (SQL + ordenação `_order` + validação), para um problema que um
|
|
advisory lock resolve com 3 linhas no padrão já existente do repo.
|
|
- **C — aceitar e documentar (rejeitada):** a perda não é benigna em escopo: é um número
|
|
digitado que SOME silenciosamente num cadastro de rotina (dois registros da mesma pessoa
|
|
via canais/arquivos diferentes é uso real do apoiador/liderança flow, não janela
|
|
desprezível), o dado é PII recém-coletado e o custo do fix (A) é baixo e in-pattern.
|
|
Aceitar exigiria além disso um rationale de produto que não existe.
|
|
|
|
**Recomendação:** A.
|
|
|
|
**Rejeitadas:** B (camada errada — contorna o dono), C (dado coletado some), e também o
|
|
lock de ficha SEM re-read (insuficiente por construção: serializa a escrita mas não o
|
|
conteúdo — a re-leitura dentro do lock é a parte que torna o append correto).
|
|
|
|
### Componentes / mudanças
|
|
|
|
- **~ `src/utilities/contactPhoneLocks.ts`** — adicionar `contactFichaLockKey(id)` →
|
|
`contact-ficha:${id}` e `acquireContactFichaLock(payload, req, id)` (um wrapper de
|
|
`acquireTextAdvisoryLocks`). Fica no dono dos locks de contato; a chave segue o padrão
|
|
das locks por entidade existentes (`campaign-demand:<id>`, `activity:<id>`,
|
|
`contact-name:<normalized>`, `person-delete:<id>`).
|
|
- **~ `src/utilities/contactIdentity.ts:68-87`** — no branch `totalDocs === 1`, após
|
|
resolver a ficha: `await acquireContactFichaLock(payload, req, existing.id)`; re-ler a
|
|
ficha com `payload.findByID` (depth 0, `select: { phones: { value: true } }`,
|
|
`overrideAccess: true`, `req`) DENTRO do lock; montar `missing` e o array final sobre a
|
|
RE-LEITURA (não sobre `docs[0]` do find); `update` só com `missing > 0`. Atualizar o
|
|
doc-comment do módulo (mencionar a serialização por ficha no reuso).
|
|
- **~ `src/collections/CampaignUser.ts:270-291`** — no RMW do sync conta→ficha
|
|
(account phone mudou e a ficha existe), adquirir `contact-ficha:<id>` antes do `findByID`
|
|
existente (que já é a leitura do RMW: lock antes do read serializa read+write com um lock
|
|
só). **DECISÃO: ENTRA no escopo.** Mesma classe de perda (append perdido → número
|
|
digitado some no sync), mesmo padrão/dono, e o hook já roda em transação no postgres
|
|
(C99/int exercita phone locks dentro desses hooks — `req.transactionID` existe). Custo:
|
|
2 linhas vs 1 camada de risco real no mesmo defeito silencioso. O custo CI (collections =
|
|
HIGH_RISK) está registrado em Riscos e em Fases.
|
|
- **+ `tests/int/contactPhoneAppendRace.int.spec.ts`** — spec de concorrência (ver Fase 2).
|
|
- **Full-replace editors (`updateSupporterContactRecord` em `actions/supporter.ts:216-223`,
|
|
`contact.ts`, `leadership.ts` field `phones`/wizard, `advisor.ts`, tombstones e o branch
|
|
`phone` do `leadership.ts` inline) — FORA do aceite (documentado, não alterado):**
|
|
a semântica de um editor é "o array é agora exatamente isto" — a ficha lock não muda o
|
|
last-writer-wins de um replace; e o branch `phone` inline (reorderWithPrimaryPhone) é
|
|
edição explícita de staff que define o primário, não append implícito. O lock só faz
|
|
sentido onde dois fluxos appendam sem intenção de sobrescrever. Documentar no header do
|
|
`contactPhoneLocks.ts` (quem serializa o quê) e no commit.
|
|
- **Invite redemption (`invite-redemption-contact:<id>`, `campaignInviteRepository.ts:127-132`)**
|
|
— RMW do profile JÁ serializado, mas por chave DIFERENTE → ficha não fica globalmente
|
|
serializada entre create-flow e redemption-flow. **DECISÃO: capturar como débito**, não
|
|
unificar agora (unificar é renomear a chave e revalidar os specs de redemption — escopo
|
|
e risco extras sem relação com o aceite de C120). Nova Issue de débito.
|
|
- **Migration:** sem migration (nenhuma mudança de schema; `contact_phones` continua
|
|
`_parent_id`/`_order`/`value`, sem índice UNIQUE, dedupe intraficha segue em memória).
|
|
- **Access/Consent:** n/a (sem mudança de acesso; `overrideAccess: true` inalterado nos
|
|
pontos tocados, coberto pelos gates de fluxo existentes).
|
|
- **UI:** n/a.
|
|
|
|
## Fases verificáveis
|
|
|
|
1. **Schema+server** — editar `contactPhoneLocks.ts`, `contactIdentity.ts` e
|
|
`CampaignUser.ts`, conforme Componentes. Nenhuma migration; nenhum tipo novo
|
|
(`generate:types` desnecessário — não há campo novo). Verificação local: `tsc --noEmit`.
|
|
2. **Teste int** — criar `tests/int/contactPhoneAppendRace.int.spec.ts` (formato abaixo) e
|
|
rodar com o db de teste do worktree (`pnpm test:int contactPhoneAppendRace`). **Prova em
|
|
duas direções:** rodar o spec contra o código ATUAL (sem o fix) e ver a asserção
|
|
`{P1,P2,P3,P4}` falhar com 3 números (prova a perda — o teste não é tautológico); com o
|
|
fix, a mesma spec passa (prova a sobrevivência). O teste fixa a regressão.
|
|
3. **Gates de CI** — com `src/collections/` no diff (CampaignUser), o CI `checks` roda
|
|
int FULL + e2e CURATED + build + unidades changed (OPS86: diff high-risk nunca zero);
|
|
`contactIdentity.ts`/`contactPhoneLocks.ts` não têm entrada no manifest nem em
|
|
`E2E_RISK_PREFIXES` — mas o HIGH_RISK de collections sobrepõe o fallback
|
|
`campaignHomeActions`. Rodar full cascade local: guards → lint → format → typecheck →
|
|
knip → cycles → unit → int → build.
|
|
|
|
**Formato do spec int de concorrência (Fase 2):**
|
|
|
|
- Plantar a ficha alvo `F = {P1, P2}` via `campaignFixtures().createContact({ phones:
|
|
[{ value: P1 }, { value: P2 }] })` (P1/P2 de `campaignFixtures().phone()`).
|
|
- Dos fluxos CONCORRENTES com primários DIFERENTES e conjuntos de telefone DISJUNTOS
|
|
(requisito — se os phone locks se sobrepõem, a serialização por-telefone mascara a race):
|
|
fluxo A `[P1, P3]`, fluxo B `[P2, P4]`, cada um chamando `findOrCreateContactByPhone`
|
|
direto dentro de `withPayloadTransaction` (que abre transação real e fornece o `req` com
|
|
`transactionID` — exigência do advisory lock). Forma DECIDIDA: chamada direta da unidade,
|
|
não via `createSupporterRecord`/`createLeadershipRecord` — os flows de action adicionam
|
|
consent + municipality + dedupe de liderança/supporter (outras unidades sob teste e mais
|
|
fixtures), enquanto a unidade sob teste é exatamente `findOrCreateContactByPhone` e ambos
|
|
os flows reais a chamam de forma idêntica dentro das suas transações.
|
|
- Gate com `findSpy` sobre `payload.find` segurando o 1º find de AMBOS os fluxos
|
|
(`firstReadGate`/`firstReadReached`, padrão de `campaignLeadership.int.spec.ts:181-285`,
|
|
porém com gate nos DOIS reads) — garante que ambos leem o estado `[P1,P2]` antes de
|
|
qualquer escrita, tornando a perda determinística sem o fix e a sobrevivência
|
|
determinística com o fix (o xact lock garante: quem entrou por último re-lê o append já
|
|
commitado do primeiro). Disparar via `Promise.allSettled`.
|
|
- Asserções: ambos resolvem com `reused: true` e `contactID === F.id`; a ficha F final tem
|
|
EXATAMENTE {P1,P2,P3,P4} (comparação por conjunto). O assert do waiter de pg_locks
|
|
(`waitForAdvisoryLockWaiter` + PID via `beginSpy`, que funciona no existing spec porque o
|
|
waiter vira determinístico quando os dois reads estão gated) pode reforçar o mecanismo,
|
|
mas não é exigido pelo aceite — o state final basta.
|
|
- Cleanup: `installCampaignFixtures` (markers + owned) cuida do teardown.
|
|
|
|
## Rabbit holes / Não escopo
|
|
|
|
- **Lock ordering:** em `findOrCreateContactByPhone`, phone locks são adquiridos em batch
|
|
ordenado ANTES de qualquer lock de entidade; o ficha-lock é adquirido por ÚLTIMO e sempre
|
|
SOZINHO (uma chave de ficha por RMW; o branch `totalDocs !== 1` não faz RMW e não ganha
|
|
lock). Nenhum fluxo segura 2 chaves de entidade de contato simultaneamente
|
|
(`person-delete:<id>` e `contact-name:<normalized>`, `invite-redemption-contact:<id>`
|
|
seguem com chaves próprias e nunca são combinadas com `contact-ficha:*`) — sem ciclo.
|
|
- **Escrita determinística SQL:** rejeitada (opção B) — exigiria validar/ordenar/
|
|
deduplicar fora do hook e do adapter.
|
|
- **Full-replace/reorder editors:** fora do aceite, documentados (ver Componentes).
|
|
- **Unificar a chave do invite redemption:** débito capturado, não no escopo.
|
|
- **Branch de criação (`totalDocs === 0` / `2+`):** sem mudança — a identidade na criação é
|
|
a ficha recém-escrita e os phone locks já serializam as criações concorrentes.
|
|
- **Não mexer em `supporterImport.ts`** (modelo de "todos os phones locked up front" intacto).
|
|
- **Não adicionar lock em `updateSupporterContactRecord`** nem nos demais editors.
|
|
|
|
## Riscos e mitigação
|
|
|
|
- **Lock de ficha sem re-read ser insuficiente contra a intenção:** não — a re-leitura é
|
|
parte integrante do componente (fora do lock o fix seria inócuo). O spec int cobre os dois
|
|
fluxos re-lendo dentro do lock.
|
|
- **`CampaignUser.ts` sem transação ativa em algum chamador do hook:** no postgres o
|
|
adapter envolve cada mutation numa transação e expõe `transactionID` aos hooks (evidência
|
|
C99/int: os phone locks já rodam dentro desses hooks). Se um chamador futuro invocar o
|
|
update sem transação, `acquireTextAdvisoryLocks` lança com a mensagem fail-closed padrão
|
|
— nunca perde dado silenciosamente. Residual baixo.
|
|
- **Deadlock entre fluxos:** chaves de ficha e telefone disjuntas entre os fluxos do aceite
|
|
(A usa P1,P3 e F; B usa P2,P4 e F — só F em comum, e a ficha é sempre a última); nenhum
|
|
fluxo adquire uma chave de outro fluxo depois de segurar a própria. A invariante de
|
|
ordenação é única no código (documentada no comment do módulo).
|
|
- **Custo CI (collections = HIGH_RISK):** int full + e2e curated + build no PR. Patch
|
|
pequeno e de padrão já coberto; o custo é o preço da camada de serialização no sync
|
|
conta→ficha (C99 já paga esse preço hoje por incluir o hook em collections).
|
|
- **Re-read extra (perf):** 1 `findByID` seletivo a mais, só no branch de reuso;
|
|
desprezível vs. o round-trip de lock já existente no mesmo caminho.
|
|
- **Ficha deletada entre o `find` e o lock (`person-delete` concorrente):** a re-leitura
|
|
falha com erro claro → rollback da transação (fail-closed), sem corrupção. Fora do aceite.
|
|
- **Flakiness do spec:** telefones únicos por fixture (`phone()`), gate determinístico nos
|
|
dois reads, transações via `withPayloadTransaction` (commit/rollback corretos);
|
|
`waitForAdvisoryLockWaiter` só reforça o mecanismo e usa espera ativa com timeout (padrão
|
|
já usado no repo).
|
|
|
|
## Aceite de engenharia
|
|
|
|
- [ ] Aceite da intenção: dois fluxos concorrentes contra a mesma ficha nunca perdem um
|
|
telefone digitado (spec int prova a perda sem o fix e a sobrevivência com o fix)
|
|
- [ ] Decisão de concorrência registrada (A recomendada) com B e C rejeitadas e rationale
|
|
- [ ] Invariantes AGENTS/engineering-standards: sem migration, sem schema, sem
|
|
Access/Consent; edita o dono (`contactPhoneLocks.ts`); sem paralelismo de caminho
|
|
- [ ] Testes de domínio previstos: `tests/int/contactPhoneAppendRace.int.spec.ts`
|
|
(concorrência por ficha, primários distintos, gate nos dois reads)
|
|
- [ ] CI previsto: int full + e2e curated + build + unidades changed (blast de
|
|
`src/collections/CampaignUser.ts`) — gates verdes antes do merge
|
|
- [ ] Débitos registrados em Issue: unificação da chave `invite-redemption-contact:*`
|
|
vs `contact-ficha:*`; full-replace/reorder editors documentados como fora do aceite
|