16 KiB
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_phonesrelacional 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 desrc/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.
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 ofindretornar exatamente 1 ficha (totalDocs === 1), adquirir o lock, re-ler a ficha viafindByID(depth 0,select: { phones: { value: true } }) dentro do lock e montar o append de faltantes sobre essa leitura fresca;updatesó semissing > 0. Mantém os phone locks e ofindde dedupe intactos. Custo: 1 round-trip de lock + 1findByIDseletivo, 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_phonesnã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— adicionarcontactFichaLockKey(id)→contact-ficha:${id}eacquireContactFichaLock(payload, req, id)(um wrapper deacquireTextAdvisoryLocks). 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 branchtotalDocs === 1, após resolver a ficha:await acquireContactFichaLock(payload, req, existing.id); re-ler a ficha compayload.findByID(depth 0,select: { phones: { value: true } },overrideAccess: true,req) DENTRO do lock; montarmissinge o array final sobre a RE-LEITURA (não sobredocs[0]do find);updatesó commissing > 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), adquirircontact-ficha:<id>antes dofindByIDexistente (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.transactionIDexiste). 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 (
updateSupporterContactRecordemactions/supporter.ts:216-223,contact.ts,leadership.tsfieldphones/wizard,advisor.ts, tombstones e o branchphonedoleadership.tsinline) — 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 branchphoneinline (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 docontactPhoneLocks.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_phonescontinua_parent_id/_order/value, sem índice UNIQUE, dedupe intraficha segue em memória). - Access/Consent: n/a (sem mudança de acesso;
overrideAccess: trueinalterado nos pontos tocados, coberto pelos gates de fluxo existentes). - UI: n/a.
Fases verificáveis
- Schema+server — editar
contactPhoneLocks.ts,contactIdentity.tseCampaignUser.ts, conforme Componentes. Nenhuma migration; nenhum tipo novo (generate:typesdesnecessário — não há campo novo). Verificação local:tsc --noEmit. - 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. - Gates de CI — com
src/collections/no diff (CampaignUser), o CIchecksroda int FULL + e2e CURATED + build + unidades changed (OPS86: diff high-risk nunca zero);contactIdentity.ts/contactPhoneLocks.tsnão têm entrada no manifest nem emE2E_RISK_PREFIXES— mas o HIGH_RISK de collections sobrepõe o fallbackcampaignHomeActions. 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}viacampaignFixtures().createContact({ phones: [{ value: P1 }, { value: P2 }] })(P1/P2 decampaignFixtures().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 chamandofindOrCreateContactByPhonedireto dentro dewithPayloadTransaction(que abre transação real e fornece oreqcomtransactionID— exigência do advisory lock). Forma DECIDIDA: chamada direta da unidade, não viacreateSupporterRecord/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 é exatamentefindOrCreateContactByPhonee ambos os flows reais a chamam de forma idêntica dentro das suas transações. - Gate com
findSpysobrepayload.findsegurando o 1º find de AMBOS os fluxos (firstReadGate/firstReadReached, padrão decampaignLeadership.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 viaPromise.allSettled. - Asserções: ambos resolvem com
reused: trueecontactID === 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 viabeginSpy, 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 branchtotalDocs !== 1não faz RMW e não ganha lock). Nenhum fluxo segura 2 chaves de entidade de contato simultaneamente (person-delete:<id>econtact-name:<normalized>,invite-redemption-contact:<id>seguem com chaves próprias e nunca são combinadas comcontact-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
updateSupporterContactRecordnem 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.tssem transação ativa em algum chamador do hook: no postgres o adapter envolve cada mutation numa transação e expõetransactionIDaos hooks (evidência C99/int: os phone locks já rodam dentro desses hooks). Se um chamador futuro invocar o update sem transação,acquireTextAdvisoryLockslanç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
findByIDseletivo a mais, só no branch de reuso; desprezível vs. o round-trip de lock já existente no mesmo caminho. - Ficha deletada entre o
finde o lock (person-deleteconcorrente): 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 viawithPayloadTransaction(commit/rollback corretos);waitForAdvisoryLockWaitersó 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:*vscontact-ficha:*; full-replace/reorder editors documentados como fora do aceite