- Consent.beforeDelete bloqueia delete com referências (APIError 409 composto
por coleção), fim do 23502 cru no admin (contagens com overrideAccess).
- submitWhatsapp/submitPetitionSignature delegam o ciclo de transação ao dono
withPayloadTransaction (rollback no commit-falho, AggregateError, after-commit),
preservando os contratos { ok: true } / { ok: true, signatureNumber }.
- contactStateSchema exportado + contactCitySchema/contactCityFieldSchema
consolidados; as 4 fichas usam os exports únicos (fim das cópias inline do
predicate value in CitiesByState). withMutableConsentFixture purga consent
via raw SQL para bypassar o hook no harness de teste.
Co-Authored-By: opencode <noreply@opencode.ai>
18 KiB
Impl: Escala/DRY pós-S9 — integridade e alinhamento das ações públicas
Status: rascunho Atualizado em: 2026-08-24 Issue: #771 Intenção: docs/plans/escala-dry-pos-s9-acoes-publicas.md Appetite restante: herdado (~0,5–1 dia eng; 3 fases pequenas, lock primeiro) — nada além do que a intenção já corta
Leitura da intenção
- Outcome: 3 fases de higiene/integridade pós-S9, sem mudança de contrato: (1) deletar
Consentem uso passa a falhar com erro admin-amigável (não mais23502cru); (2)submitWhatsapp/submitPetitionSignaturedelegam o transaction lifecycle ao donowithPayloadTransaction(rollback também no commit-falho,AggregateError, after-commit flush); (3) as 4 fichas decontact.tspassam a usar os exports únicos de estado/cidade — DRY de conhecimento no dono. - O que NÃO negociar: comportamento protetivo de consent LGPD fail-closed (recusa de gravar/consumir enquanto a chave configurada falta); contratos públicos das actions (
{ ok: true },{ ok: true, signatureNumber }); migrations congeladas (nunca editar20260715_163458_initialnem re-derivar FKs); contratos pinned deonPayloadTransactionCommit/notificação (notificationPushScheduleConventions.unit.spec.ts:15-16); invariante de escrita multi-collection em transação comreq: { transactionID }. - O que reavaliar: o brief afirma "mesma mensagem, mesmo comportamento" para a cidade — falso (o explorador e a leitura do código provam divergência, ver Fase 3); o guard da Fase 1 precisa decidir escopo (só os NOT NULL blockers vs todos os usos semânticos) com o caso
petition.form_consent_idNULLABLE como armadilha silenciosa; na Fase 2, a única mutação observável é a mensagem de begin-failure (não há teste que a pinea) — decisão de preservá-la por action ou aceitar o default PT; na Fase 3, exportar ocontactStateSchemaREQUIRED (não ooptionalContactStateSchema) e ocontactCityFieldSchemadifere das cópias também na colapsagem que exclui''— não só na mensagem.
Abordagem recomendada
flowchart LR
subgraph F1["Fase 1 — Consent delete guard (collection hook)"]
C1["Consent.hooks.beforeDelete"] --> C2["count refs (overrideAccess:true, depth:0, req)"]
C2 --> C3{"alguma ref? sub/sig/push/petition/lead/support"}
C3 -- "nenhuma" --> C4["segue o delete"]
C3 -- "N,M,... > 0" --> C5["APIError(409) msg composta por coleção"]
C2 -. "form.consent" .-> P["petition é NULLABLE: sem o count, NULL silencioso → TypeError no submitPetitionSignature"]
C3 -. "nulable lead/supporter" .-> L["sem count, link legal audit é NULL-ado em silêncio"]
end
subgraph F2["Fase 2 — ações irmãs → withPayloadTransaction"]
A1["submitWhatsapp (begin/commit/rollback)"] --> T["withPayloadTransaction(payload, cb, { beginFailureMessage } )"]
A2["submitPetitionSignature (idem + count no txn)"] --> T
T --> TV["rollback tb no commit-falho + AggregateError + flush after-commit"]
T -. "count permanece DENTRO do callback" .-> CT["contagem pré-commit preservada"]
end
subgraph F3["Fase 3 — DRY contact.ts"]
S1["export const contactStateSchema (required)"] --> F["4 fichas usam o export (state continua REQUIRED)"]
S2["contactCitySchema required + contactCityFieldSchema composto sobre ele"] --> F
F --> U["contactSchemas.unit.spec verde + novos pins ('Cidade muito longa', colapso de '')"]
end
Opções consideradas (por fase): ver decisões abaixo — F1: A/B; F2: A/B/C; F3: estado A/B, cidade a/b/c/d.
Recomendação: F1 guard cobre todos os usos semânticos (409, hook beforeDelete inline no Consent); F2 preserva as mensagens de begin-failure via { beginFailureMessage }; F3 exporta contactStateSchema e padroniza as mensagens de cidade no próprio contactCityFieldSchema (min 'Cidade inválida', max 'Cidade muito longa') — porque é a única opção que unifica mensagem E comportamento no dono do concern, sem custo novo de superfície.
Rejeitadas: guard só-NOT NULL (deixa os NULL silenciosos, exatamente o tipo de bug que esta issue quer eliminar); default PT de begin-failure (muda comportamento observável na mesma diff mecânica); per-field message params de cidade (mais API, mantém a divergência); manter divórcio de mensagens documentado (derrota a intenção DRY).
Componentes / mudanças
Consent(src/collections/Consent.ts): adicionarhooks: { beforeDelete: [...] }. Hook conta referências empayload.countparalelo (Promise.all) comwhere: { consent: { equals: id } }(+where: { 'form.consent': { equals: id } }empetition;where: { voteIntentionConsent: { equals: id } }emsupporter),depth: 0,overrideAccess: true,req. Se total > 0,throw new APIError(msg, 409)com contagem por coleção (subscription,signature,pushSubscription,petition,leadership,supporter). Reusa o padrão deCampaignUser.ts:336-343(CollectionBeforeDeleteHook com overrideAccess) e depersonDelete.ts:113-130para o count. Hook fica inline (convenção do repo: hooks dentro do arquivo da collection).- Migration: sem migration — nenhuma mudança de schema; as colunas já existem (
subscription.consent_id/signature.consent_id/push_subscription.consent_idNOT NULL;petition.form_consent_id,leadership.consent_id,supporter.consent_id/vote_intention_consent_idnullable). submitWhatsapp.ts/submitPetitionSignature.ts(src/app/(frontend)/actions/): trocar o hand-rollbeginTransaction/try/commit/rollbackporreturn withPayloadTransaction(payload, async ({ req }) => {...}, { beginFailureMessage }). Reads pré-transação (requireConsentByKeyde whatsapp L17-22;findByIDdo petition L25-31) ficam FORA do helper, como hoje. Conta designatureNumbere oPromise.allparalelo permanecem DENTRO do callback (lê dentro da txn não commitada — comportamento atual preservado). Retornos intocados.payloadTransaction.tsnão muda (codebaseConventions.unit.spec.ts:487pina).contact.ts(src/lib/schemas/contact.ts):contactStateSchemadeixa de ser privado (export) e as 4 fichas trocam oz.custom<StateKey>inline por ele;optionalContactStateSchemapermanece composto sobre ele. NovocontactCitySchema(required:trim().min(3,'Cidade inválida').max(100,'Cidade muito longa')) econtactCityFieldSchemaredefinido como composição sobre ele (união com''+ colapso p/undefined+.optional()). Comentário L31-35 atualizado (remover "consolidating them is a follow-up").- Teste helper (
tests/helpers/testDatabaseLease.ts:643-647): o delete "re-create re-verify" dowithMutableConsentFixturepassa depayload.deletepara raw SQL — a única chamada de lifecycle que podia derrubar a janela D10. - Access / Consent: guard com
overrideAccess: trueno count é bypass intencional (o delete já é admin-only; o hook é autorização própria do padrãoCampaignUser). Fail-closed preservado: recusa é a proteção, não um canal novo. Sem chave nova de consentimento. - UI: nenhuma nova; no admin o efeito é o erro amigável no delete (a mensagem do
APIErrorchega à superfície do painel).
Fases verificáveis
- Fase 1 (schema+server) — hook
beforeDeletenoConsent+ contagem multi-collection +APIError(409); teste helper D10 migrado para raw SQL. Fase 2 (server) — refactor das duas actions parawithPayloadTransaction. Fase 3 (lib pura) — exportscontactStateSchema/contactCitySchema;contactCityFieldSchemarecomposição; 4 fichas consolidadas. - UI — nenhuma; verificação é a mensagem admin (superfície da Fase 1) via int spec e o painel e2e de newsletter seguindo verde.
- Gates —
pnpm migrate:createnão é necessário (sem schema);pnpm gate:fast(curated: unitcontactSchemas; intsubmitWhatsapp,submitPetitionSignature,payloadTransaction, novoconsentDeleteGuard,onda0Provision, supporter D10; e2ecampaignNewsletter); push viapnpm push.
Rabbit holes / Não escopo (engenharia)
- "Arquivamento" de Consent (soft-delete/flag protegida) — é a decisão de produto/jurídico que a intenção já resolveu pela mensagem; refatorar isso vira issue própria.
- Editar migrations congeladas ou rever FKs
ON DELETE SET NULL— fora (migrations congeladas são invariante). payload_locked_documents_rels— cascade OK (migration20260715_163458_initial:286), não conta.onPayloadTransactionCommit/notificações — pinned, não tocar; as duas actions não registram after-commit (semLeadainda).- Procurar outros hand-rolls de transação — não existem (
beginTransactionsó empayloadTransaction.tse nas duas actions desta Fase 2). - Consolidar mensagens além de estado/cidade (ex.: sequences postais) — não é a intenção.
- Gatilho defasado: quando S10 precisar de
onPayloadTransactionCommitparaLead, Fase 2 vira requisito — aqui só a higiene.
Riscos e mitigação
petition.form_consent_idNULLABLE (NULL silencioso): deletar consent referenciado por petição hoje NULL-za a coluna sem erro e osubmitPetitionSignature.ts:30-31estoura TypeError depois. Mitigação: o count da Fase 1 inclui petition viawhere: { 'form.consent': { equals } }, então nunca chega ao NULL silencioso.- Lifecycles de teste que deletam consent via
payload.delete(hook roda, bypass natural p/ SQL raw):deleteWhatsappConsentRows(int whatsapp L26-33) e a purga do e2e newsletter já ordenam consumidores antes (comentáriocampaignNewsletter.e2e.spec.ts:32-33é a evidência do bug original);deletionOrderdocampaignE2EFixtures.ts:46-63e ocampaignFixtures.ts:1020-1045já põemconsentpenúltimo. O único conflito real é owithMutableConsentFixture(janela D10,testDatabaseLease.ts:643-647), que pode apagar a chave canônica com consumers vivos — mitigado trocando esse ponto para raw SQL (já é o padrão local do setup/restore, linhas 575/680;removeOnda0ConsentAndPrivacyDbtambém é raw e segue intacto). - Mensagens divergentes da cidade (Fase 3): o brief dizia "mesma mensagem" e não é — as cópias dão
'Cidade muito longa'no max;contactCityFieldSchemadá'Cidade inválida'nas duas bordas. Decisão abaixo padroniza no schema exportado; consumidorcampaignNewslettermuda o texto de "cidade longa demais" (melhoria, não pinada em teste). contactCityFieldSchemacolapsa''→undefined, cópias não: a troca nas fichas passa a aceitar''como ausente (antes'Cidade inválida'); é o comportamento que S9 já definiu como canônico (combobox limpa para''), econtactSchemapúblico mantém cidade required via o novocontactCitySchema. Bordas: string só-de-espaços vira erro em vez de colapso — divergência aceita, sem teste pinado, forms enviam''.contactStateSchemaknip: o export S9 declarou-o privado ("só 1 consumidor"); com a Fase 3 ele tem 4 consumidores — exportar não acende knip.- Count no hook antes do delete precisa de
depth: 0(evita popular relações — custo) eoverrideAccess: true(oreaddeConsentépayloadAdminOnly; o padrão casa com os hooks deCampaignUser).
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (3 fases, zero mudança de contrato público).
- Invariantes AGENTS/engineering-standards: editar o dono (Consent, payloadTransaction, contact.ts), sem twin; sem módulo novo top-level em
src/utilities/; multi-collection sempre em transação; migrations intactas.
Painel de teste/verificação por fase
- F1 —
tests/int/consentDeleteGuard.int.spec.ts(novo): cria consent + refs em cada consumidor (subscription, signature, pushSubscription, petition viaform.consent, leadership, supporterconsent/voteIntentionConsent); assertapayload.delete({ collection: 'consent', id })rejeitando comAPIError409 e mensagem com as contagens por coleção; asserta que remove refs → delete OK; que delete de consent sem refs passa; e queDELETEraw SQL bypassa o guard (espelho doremoveOnda0ConsentAndPrivacyDb). Fixture descarta refs próprias antes do cleanup (controla a ordem por si). - F1 — regressão dos lifecycles:
submitWhatsapp.int.spec.ts(comdeleteWhatsappConsentRows),campaignNewsletter.e2e.spec.ts(purga emissão 32-33),campaignMunicipalities.e2e.spec.ts(lease),onda0Provision.int.spec.ts(provision/remove) verdes;testDatabaseLease.ts:643-647→ raw SQL. - F2 —
tests/int/submitWhatsapp.int.spec.ts(fail-closed com a mensagem exata + path feliz com subscription linkada ao consent) etests/int/submitPetitionSignature.int.spec.ts(signatureNumberpré-commit preservado) verdes;tests/int/payloadTransaction.int.spec.tsverde (helper intocado);pnpm gate:fast. - F3 —
tests/unit/contactSchemas.unit.spec.ts: mantém verdes os pins existentes (state REQUIRED L20-30; city L64-71); adicionar pins novos: mensagem'Cidade muito longa'no contato docontactFieldUpdateSchema/contactCreateSchemaapós a consolidação;''emcitycolapsa paraundefinednos schemas das fichas;contactStateSchemaexportado aceita'BA'e rejeita'XX'. HomônimocontactCityMigration.unit.spec.tsé de migration — não tocar.
Conclusão
Toda decisão não trivial vem com opções/recomendação/rejeitadas (uma por fase abaixo). Self-score decision-quality: 4,5/5 — decisões caras têm rejeitadas explicitadas (escopo do guard, mensagem da cidade, kind de teste D10), a abordagem cabe no appetite ~0,5–1 dia, rabbit holes nomeados (arquivamento, locked_documents, S10/Lead), depth-check reusa próprios donos (payloadTransaction, hooks inline, exports S9), e a intenção (o outcome das 3 fases) é satisfeita sem mudar contrato.
Decisões de engenharia (uma por fase)
F1 — Escopo do guard + status + lifecycles de teste.
Opções: A) contar só os NOT NULL blockers (subscription/signature/pushSubscription) → cobre o sintoma 23502; B) contar todos os usos semânticos (A + petition via form.consent + leadership + supporter×2) → também elimina os NULL silenciosos.
Recomendação: B — porque o concern é o texto legal versionado: petition.form_consent_id NULLABLE hoje NULL-za silencioso e quebra o submitPetitionSignature (TypeError), e leadership/supporter têm consentContentHash/consentedAt que ficariam órfãos do link; multicount em Promise.all custa nada e a mensagem composta orienta o admin. Alternativas rejeitadas: A) deixa exatamente a classe de bug que a issue quer matar (NULL silencioso em público), e um guard de "uso parcial" é mais confuso que um de "uso".
Status HTTP: Opções: 400 | 409 | 500. Recomendação: 409 (APIError(msg, 409)) — conflito com estado existente, com precedente real no repo (CampaignDemand.ts:144/278, Activity.ts:92, Organization.ts:27, VotePledge.ts:78). Rejeitadas: 400 (semântica errada; erro não é do payload) e 500 (erro cru é o sintoma).
Integração com lifecycles: os fixtures já ordenam consumidores antes do consent (campaignFixtures.ts:1020-1045, campaignE2EFixtures.ts:46-63); o único ponto em conflito é o delete do withMutableConsentFixture (janela D10, testDatabaseLease.ts:643-647), que pode ter consumers vivos. Opções: A) mudar esse ponto para raw SQL; B) overrideAccess/flag de contorno no hook; C) fragilizar fixtures. Recomendação: A — hook beforeDelete NÃO roda para SQL raw (bypass natural do próprio harness), casa com o setup/restore raw já existente (575, 680) e com removeOnda0ConsentAndPrivacyDb. Rejeitadas: B) contorno no hook é um buraco de segurança que vaza para o admin; C) delegar ordem aos tests quebrados é mais fraco.
F2 — Mensagem de begin-failure.
Opções: A) { beginFailureMessage: 'failed to start transaction' } no whatsapp e { beginFailureMessage: 'Failed to begin transaction' } no petition; B) aceitar o default PT 'Não foi possível iniciar a transação.'; C) criar uma PT compartilhada nova.
Recomendação: A — o refactor é preservação de contrato; a mensagem de begin-failure é o único output observável que muda e a opção existe exatamente para isso; zero risco de regressão oculta na mesma diff. Rejeitadas: B) altera comportamento observável (EN→PT) sem requisito por trás — limpeza desacoplada da Mecânica; C) strings novas só para "uniformizar" sem ganho, menos DRY que A. Nota: reads pré-transação (consent/petition) ficam fora do helper; count e Promise.all dentro (pré-commit).
F3 — Estado: exportar o schema required.
Opções: A) exportar contactStateSchema (required, atual privado) e usar nas 4 fichas; B) compor optionalContactStateSchema (ou união ad-hoc) nas fichas.
Recomendação: A — todas as 4 fichas exigem state (contactCreateSchema tem pin "rejects a missing state" em contactSchemas.unit.spec.ts:25-30); o optional é só o público S9. B) mudaria validação (state deixa de ser obrigatório) e quebraria o pin. Rejeitadas: B. O comentário L31-35 ("follow-up") é a dívida exatamente desta Fase 3 — atualizar ao exportar.
F3 — Cidade: padronizar mensagens no schema canônico.
Opções: a) padronizar em contactCityFieldSchema (min 'Cidade inválida', max 'Cidade muito longa'), mudando o max dos consumidores atuais (incl. campaignNewsletter); b) manter mensagens distintas nas fichas via message params; c) padronizar num base required contactCitySchema e recompor contactCityFieldSchema sobre ele (união '' + colapso); d) aceitar a divergência e documentar.
Recomendação: c, em coerência com o padrão do state — um base required (contactCitySchema, com as mensagens que as cópias já estabelecem) e o field schema como composição (união com '', colapso, .optional()); isso unifica as 4 fichas e mantém o colapso '' dos consumidores S9. A mensagem de cidade-muito-longa do campaignNewsletter muda 'Cidade inválida' → 'Cidade muito longa' (melhoria informativa, não pinada). Rejeitadas: a) muda comportamento de refs S9 sem base requerida e duplica o pred do contactSchema; b) amplia a superfície de contactCityFieldSchema com params e preserva a divergência que a intenção quer matar; d) derrota o motivo da Fase 3. contactSchema.city (público, via whatsAppFormSchema/petitionFormSchema) continua required — usar contactCitySchema, nunca o field optional.