Apply the /simplify cleanup to the C6 commit (identity maps, dead branches, relationshipId reuse, native base64url, rowCount fix, canManageCampaignUsers reuse) and register the unimplemented debits as roadmap item C8 with its plan.
12 KiB
Escala e DRY pós-C6 (apoiadores / import / listas)
Status: rascunho Atualizado em: 2026-07-19 Item do roadmap: docs/roadmap.md (Trilha C, item C8) Responsável: —
Contexto
O C6 (escala-dry-pos-c2.md) entregou a escala do cadastro nominal de apoiadores: import bulk via drizzle na txn Payload, KPI agregado em SQL, token HMAC de import single-use, e shells compartilhados (campaignListUrl, CampaignListPagination, campaignFormFields, mapCampaignFormActionError). A passagem /simplify de 2026-07-19 aplicou limpezas pontuais (identity maps, dead branches, relationshipId, base64url nativo, rowCount ?? 0, reuso de canManageCampaignUsers) mas deixou de fora débitos que os revisores (quality / reuse / performance) marcaram como importantes e maiores que cleanup. Este plano é o registro canônico desses follow-ups — precedente direto de B5 (pós-B2) e C7 (pós-C3).
Sem este item, a importação funciona em volume baixo, mas: (a) o gargalo de import em escala volta a ser a aquisição de locks advisory (um round-trip por telefone), não o insert bulk; (b) a página de lista de apoiadores faz dois COUNTs filtrados por navegação; (c) a busca por nome/cidade é ILIKE '%q%' não-sargable; (d) o scaffold de tipos drizzle do bulk apaga a tipagem de colunas (já causou um bug contactId → contact); (e) o helper de erro de form adotado só por 2 forms permanece duplicado em ~6 formActions legados.
Objetivos
- Import bulk de 5k apoiadores adquire todos os locks advisory de telefone em um round-trip (hoje até 5k round-trips sequenciais).
- O insert bulk de contacts recupera IDs via
.returning()(hoje re-payload.findpor chunk). - Leituras de existência (contacts/supporters existentes) no bulk usam drizzle direto na mesma txn, sem o scaffolding do Local API.
- A página de lista de apoiadores não faz dois COUNTs filtrados por navegação; o
totaldo overview vem dototalDocsda lista, ou o overview é cacheado por(user, filterState)com TTL curto. - Busca por
qem nome/cidade usa índicepg_trgmGIN (ou restringe a prefix/telefone) — deixa de ser seq scan por página. - O lookup de núcleos acessíveis do coordenador é memoizado por request (lista + overview compartilham uma query).
chunk/requireTable/INSERT_CHUNK_SIZE/ scaffold de tipos drizzle vivem num helper compartilhado, reusado porsupporterImportBulk.tseelectionResultsImport.ts(import TSE).- O scaffold de tipos drizzle não apaga a tipagem de colunas: assertion runtime dos nomes de coluna em
payload.db.tables.supporterao init ouPostgresTransactionDatabaseexpõe uminserttipado. getAccessibleNucleusIdsganha uma variante semPayloadRequest(ousupporterListOverviewAggregatereusa a existente), eliminando o lookup duplicado de escopo coordenador.- Todos os
formActions.tsde/campanharestantes migram paramapCampaignFormActionError+campaignFormFields(hoje duplicados em ~6 arquivos). - Guardrails:
overrideAccess: falsecomuser; escritas multi-step continuam emwithPayloadTransaction; locks advisory continuam xact-level; sem novoConsent; sem mudança de comportamento visível.
Decisões travadas
- Um item C8, fases ordenadas. Mesmo racional do C6/C7: um ID de roadmap, PRs por fase. Ordem: perf do caminho quente (import) → perf de leitura (lista) → DRY de helpers → DRY de forms.
- Dependência dura de C6 (merge). O código que C8 otimiza é o código do C6; não reabre o escopo de v1 do
supporter/supporterImportBatch. - Cortável se a base nominal permanecer pequena. Fases 1–2 (perf de import/lista) só rendem com base real em volume; se a base ficar pequena até 16/08, adiar para Janela 3. Fases 3–4 (DRY) são baratas e reduzem drift — manter se houver folga.
- Sem migration de schema em Fases 1–3. Fase 2 pode exigir uma migration pequena (
pg_trgmGIN emcontact.name/contact.city) — única migration do item. postgresTransactionLocks.tsé pré-existente e compartilhado com o path single-create (upsertContactByPhone,enforceUniqueContactPhone). A Fase 1 troca o loop de locks por uma query única sem mudar o contratoacquireContactPhoneLocks(payload, req, phones[])— callers não mudam.- i18n e naming (AGENTS.md): identificadores em inglês (
acquireContactPhoneLocksmantido,drizzleBulk.ts,getAccessibleNucleusIdsvariant, etc.), strings visíveis em pt-BR.
Questões em aberto
pg_trgmvs prefix-only para busca de nome?ILIKE '%q%'precisa de trigram para ser sargable; prefix-only (ILIKE 'q%') usa btree mas perde busca infix. Recomendação:pg_trgmGIN (a busca infix é o comportamento esperado pela UI hoje); migration pequenaadd_contact_trgm_index.- Overview
totalderivado dototalDocsda lista vs cache? Derivar elimina um COUNT mas acopla overview ao carregamento da lista (overview some se lista não carrega). Recomendação: derivartotalderesult.totalDocs(já computado pela lista) e rodar só os doisFILTERno overview; cache só se houver reclamação de latency. - Assertion runtime de colunas vs widen
PostgresTransactionDatabase? Assertion é barata e pega o bug na inicialização; widen é mais limpo mas tocapostgresTransactionLocks.ts(pré-existente). Recomendação: assertion runtime emsupporterImportBulk.ts(escopo do item); widen fica como follow-up de plataforma. - Migrar formActions de planos aqui (C8) ou em C7? O plano do C6 anotou "mapper de form actions de planos ficou para C7". Recomendação: consolidar TODOS os formActions restantes em C8 Fase 4 (C8 é o "DRY pós-C6" e C6 introduziu os helpers); C7 Fase 3 continua dono dos helpers FormData/URL de território do actionPlan. Atualizar a nota cruzada no plano do C6 na hora do PR.
Abordagem proposta
flowchart TD
F1["Fase 1 — Perf import<br/>locks em 1 RT · .returning · drizzle reads"]
F2["Fase 2 — Perf lista<br/>1 COUNT · trgm · memo accessible nuclei"]
F3["Fase 3 — DRY helpers<br/>drizzleBulk · getAccessibleNucleusIds variant · DrizzleTx assertion"]
F4["Fase 4 — DRY forms<br/>migrar formActions restantes"]
C6["C6 apoiadores ✓"] --> F1
F1 --> F2
F2 --> F3
F3 --> F4
Fase 1 — Perf do caminho quente de import
acquireContactPhoneLocks(src/utilities/contactPhoneInvariant.ts/postgresTransactionLocks.ts): trocar o loopfor (const key of sortedKeys) await database.execute(...)por uma query únicaSELECT pg_advisory_xact_lock(hashtextextended(k, 0)) FROM unnest(ARRAY[...]) AS k(ordenar para evitar deadlock). ContratoacquireContactPhoneLocks(payload, req, phones[])inalterado — callers (bulk, single-create, hook) não mudam.bulkInsertSupporterImport(src/utilities/supporterImportBulk.ts):tx.insert(contactTable).values(...).returning({ id: true, phone: true })em vez do re-payload.findpor chunk para recuperar IDs (elimina ~10 round-trips no cap de 5k). Widen o tipoDrizzleTxlocal para tipar.returning().- Substituir os dois
payload.findde existência (contacts por phone, supporters por contact_id) porSELECT ... FROM contact WHERE phone = ANY($)/SELECT contact_id FROM supporter WHERE contact_id = ANY($) AND nucleus_id IS NULLna mesma sessão drizzle da txn.
Fase 2 — Perf de leitura da lista
loadSupporterListOverviewData(src/utilities/supporterPageData.ts): derivartotaldoresult.totalDocsda lista (já computado por Payload); o overview roda só os doisCOUNT(*) FILTER(certo+tende, indeciso). Elimina um COUNT filtrado completo por navegação.computeSupporterListOverviewAggregate(src/utilities/supporterListOverviewAggregate.ts): memoizar oresolveAccessConstraint(lookup de núcleos acessíveis do coordenador) por request — lista e overview compartilham a mesma queryelectoralNucleus.- Migration
add_contact_trgm_index:CREATE EXTENSION IF NOT EXISTS pg_trgm+CREATE INDEX ... USING gin (name gin_trgm_ops)e(city gin_trgm_ops)emcontact. TornaILIKE '%q%'sargable. Única migration do item. - Avaliar restringir
qa mínimo 2–3 chars no cliente (reduz seq scans inúteis) — opcional, sem migration.
Fase 3 — DRY de helpers
src/utilities/drizzleBulk.ts(novo): extrairchunk,requireTable,INSERT_CHUNK_SIZE, e o scaffold de tiposDrizzleTx/PayloadDbdesupporterImportBulk.tseelectionResultsImport.ts(hoje byte-idênticos). Importar de ambos.getAccessibleNucleusIds(src/utilities/campaignAccess.ts): adicionar variante semPayloadRequest(ou parametrizar a existente com cache opcional) para quesupporterListOverviewAggregatereuse em vez de re-implementar o lookupcoordinators contains user.id.- Type safety do bulk: assertion runtime em
supporterImportBulk.tsqueObject.keys(payload.db.tables.supporter)contém as colunas esperadas (contact,nucleus,consent,createdBy, …) no init do módulo — pega o bugcontactIdvscontactantes do runtime. (Widen dePostgresTransactionDatabasefica como follow-up de plataforma.)
Fase 4 — DRY de forms
- Migrar os
formActions.tsrestantes paramapCampaignFormActionError+campaignFormFields(hoje o ladderFormDataBoundaryError→ZodError→validationFieldErrors→ safe-message está inlined em ~6 arquivos):src/app/(campaign)/campanha/(app)/nucleos/formActions.tssrc/app/(campaign)/campanha/(app)/nucleos/[slug]/voteEstimateFormActions.tssrc/app/(campaign)/campanha/(app)/nucleos/[slug]/nucleusIntelligenceFormActions.tssrc/app/(campaign)/campanha/(app)/nucleos/[slug]/nucleusUpdateFormActions.tssrc/app/(campaign)/campanha/(app)/nucleos/[slug]/coordinatorAssignmentFormActions.tssrc/app/(campaign)/campanha/convite/[token]/formActions.tssrc/app/(campaign)/campanha/(app)/apoiadores/[id]/formActions.tssrc/app/(campaign)/campanha/(app)/planos/formActions.tseplanos/[slug]/updateFormActions.ts
- Migrar
fieldError/firstErrorlocal emsrc/components/campaign/NucleusUpdateForm.tsxeCampaignInviteForm.tsxpara importar decampaignFormFields.ts.
Migration: Fases 1, 3, 4 sem schema. Fase 2: pnpm migrate:create add_contact_trgm_index (extensão + 2 GIN indexes). Sem Consent novo.
Dependências
- Dura: C6 Escala e DRY pós-C2 (código em
supporterImportBulk.ts/supporterListOverviewAggregate.ts/supporterPageData.ts/campaignFormActionError.ts). - Reusa:
src/utilities/contactPhoneInvariant.ts,postgresTransactionLocks.ts,getPostgresTransactionDatabase,relationshipId,campaignAccess.ts(getAccessibleNucleusIds,canManageCampaignUsers),electionResultsImport.ts(paradrizzleBulk.ts), C6 plano escala-dry-pos-c2.md.
Não escopo
- Reabrir decisões de v1 do C6 (token HMAC vs opaque,
supporterImportBatchcomo staging,skipContactPhoneInvariantfail-closed) — escala-dry-pos-c2.md. - Helpers FormData/URL de território do actionPlan — C7 Fase 3 / escala-dry-pos-c3.md.
- Camada de zonas no mapa, coroplético — B3/B4.
- Widen de
PostgresTransactionDatabasepara exporinserttipado — follow-up de plataforma (a assertion runtime da Fase 3 cobre o bug). - Notificações / push — D2.
Referências
docs/roadmap.md— Trilha C, item C8; sequência Janela 2- escala-dry-pos-c2.md — C6 entregue; precedente do formato
- escala-dry-pos-b2.md — precedente B5 (pós-B2 simplify)
- escala-dry-pos-c3.md — precedente C7 (pós-C3 simplify)
- Review
/simplify2026-07-19 (quality / reuse / performance) — origem das fases src/utilities/supporterImportBulk.ts— bulk insert (locks, .returning, drizzle reads)src/utilities/postgresTransactionLocks.ts—acquireContactPhoneLocks(loop por telefone)src/utilities/supporterListOverviewAggregate.ts— aggregate SQL +resolveAccessConstraintsrc/utilities/supporterPageData.ts—loadSupporterListOverviewData(duplo COUNT)src/utilities/electionResultsImport.ts—chunk/requireTable/INSERT_CHUNK_SIZEduplicadossrc/utilities/campaignAccess.ts—getAccessibleNucleusIdssrc/utilities/campaignFormActionError.ts/campaignFormFields.ts— helpers adotados por 2 forms- AGENTS.md —
overrideAccess: false, transações, locks advisory xact-level, naming