Bulk import and list paths get single-round-trip locks, drizzle returning reads, pg_trgm search, shared drizzleBulk helpers, and consolidated campaign formActions; simplify debts land as C9 in the roadmap.
14 KiB
Escala e DRY pós-C6 (apoiadores / import / listas)
Status: implementado (pendente merge em main)
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
Simplify (2026-07-19)
Duas passagens /simplify sobre o diff do C8 (pré- e pós-rebase em main com C7) aplicaram limpezas pontuais sem mudar comportamento: safeMessages opcional em mapCampaignFormActionError, drizzleResultRows reutilizado em campaignInviteRepository, chunk de IN nas leituras drizzle do bulk import, select: { id: true } via DynamicFind em getCoordinatorNucleusIds, prefetch de núcleos do coordenador para o overview, errorProps no CampaignInviteForm/NucleusUpdateForm, e hoisting de erros de campo. Validado com tsc --noEmit, pnpm lint, pnpm test:int, pnpm build e scan Aikido.
Os débitos que os revisores marcaram como importantes e maiores que cleanup foram registrados como item C9 — escala-dry-pos-c8.md:
- Filtros duplicados —
buildSupporterListWhere(Payload) vsbuildAggregateSql(SQL cru); risco de drift entre KPIs e lista. contactSearchQuerynão wireado no aggregate — overview ainda disparaILIKEparaqde 1 caractere apesar dopg_trgme do guard de C7.- Lookup de núcleos do coordenador repetido — até 3× por navegação em
/campanha/apoiadores(list access + options + overview prefetch). apoiadores/[id]/formActions.tsfora do mapper — contratomessagevsfieldErrorsexige desenho antes de migrar.- Componentes de form com
fieldErrorlocal —NucleusForm,ActionPlanForm,NucleusTerritoryFields,VoteEstimateDialog, etc.
Explicitamente fora (tradeoffs aceitos no C8): waterfall lista→overview (precisa de totalDocs); unificar lista+aggregate numa query; widen de PostgresTransactionDatabase.