mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-19 08:03:06 +00:00
- Contact.phone (text único) → phones (array field Payload, subcampo value): fonte única; principal = phones[0]; beforeValidate normaliza, filtra vazios, rejeita inválido e duplicado DENTRO da ficha (C111 entre fichas preservado) - migration add_contact_phones_array: backfill phone → phones[0] (gen_random_uuid) antes do drop da coluna + índice em value (hand-edit documentado; snapshot .json gerado mantém as colunas C99/C100 já existentes) - primaryPhoneOf / phoneValuesOf / reorderWithPrimaryPhone em src/lib/phone.ts (ordem = prioridade; inline edit = seta o principal preservando o resto) - findOrCreateContactByPhone aceita phones[] (dedupe pelo primário; reuse faz append dos faltantes; locks em todos os números digitados) - sync conta→ficha (CampaignUser): phone da conta faz APPEND quando a ficha não tem (nunca reordena nem remove); tombstone LGPD substitui TODOS os telefones - convite redemption: telefone digitado vira principal, demais preservados - import CSV: preview sinaliza compartilhado também por número secundário; bulk insere contact_phones (JOIN nas leituras, uuid no insert) - busca por telefone (apoiadores, pickers, combobox) casa qualquer número - UI: PhonesFieldEditor compartilhado (repetível mascarado, remover, ↑/↓, modo inline com Salvar) nas 5 superfícies — liderança (form/ficha/lista), apoiador (form/ficha), dobradinha (ficha), assessor (ficha), wizard - UI pública (petição/WhatsApp) intocada: zod e forms ficam com phone; as ações mapeiam phone → phones[0] - testes: spec novo campaignMultiPhones (aceite completo), specs C111/C99 atualizados, e2e wizard/apoiador ajustados
8.9 KiB
8.9 KiB
Impl: Múltiplos telefones por pessoa
Status: aprovado Atualizado em: 2026-08-11 Issue: #626 Intenção: docs/plans/multiplos-telefones-por-pessoa.md Appetite restante: ~1–2 dias eng (intenção); sem cortes de aceite
Leitura da intenção
- Outcome: toda pessoa (liderança, apoiador, dobradinha, assessor) tem N telefones na ficha; listas mostram 1 (o principal); ficha mostra todos; WhatsApp/convite/import usam o principal; busca por telefone acha por qualquer número; guardrail C111 (números compartilhados entre pessoas) preservado.
- O que NÃO negociar: ordem = prioridade sem flag explícita; sem rótulos/tipos de telefone; import CSV com uma coluna; login da liderança continua o
username(não muda); dedupe dentro da MESMA ficha bloqueia salvar; UI pública intocada — formulários de petição/WhatsApp (e o componentePhoneInput) não mudam; a mudança de dados entra só no mapeamento server-side das ações públicas. - O que reavaliar: a hipótese da intenção listava
src/lib/phone.ts, view models e import — ok; mas assessor tem camada extra (o telefone mora emcampaignUser.phone, espelhado na ficha) eContact.phoneé lido pelo site público (petição/WhatsApp) e por export — a intenção não citava esses dois.
Abordagem recomendada
flowchart LR
C[Contact] -->|array field| P[phones: {value}[]]
P -->|primary| H[primaryPhoneOf]
H --> VM[view models / listas / wa.me / convite]
W[formulários criação/edição] -->|PhonesFieldEditor| P
S[busca/import/findOrCreate] -->|where phones.value| P
Opções consideradas: A | B | C
Recomendação: A — array field Payload phones com subcampo value na Contact, removendo phone (fonte única). Payload onde com 'phones.value': { equals/contains } resolve busca/dedupe com JOIN nativo, _order preserva ordem = prioridade, e o admin UI ganha a edição de graça.
Rejeitadas:
- B —
jsonb phones: string[](custom/JSON): perde query/index Payload;supporterListSqlFiltersesupporterImportBulkteriam que viver de SQL cru e a busca Payload (supporter filters, pickers) ficaria sem where nativo. Pior contrato para o caso de uso mais comum. - C — collection join
contactPhone: entidade demais para um campo sem rótulos/tipos; clareza zero de "principal" (teria_orderescondido do mesmo jeito); admin group extra. - D — manter
phone+phonesdesnormalizados: duas fontes de verdade sincronizando em N write paths; rejeitado por invariante (uma fonte).
Componentes / mudanças
phones(src/collections/Contact.ts): array fieldphones(label "Telefones", subcampovaluetext 11 dígitos,required: false); remove o campophone.beforeValidateda collection normaliza cada item (normalizeBrazilianPhone/ regex 11 dígitos), filtra vazios, rejeita inválido comBRAZILIAN_PHONE_INVALID_MESSAGEe rejeita duplicado dentro da ficha (nova copy:BRAZILIAN_PHONE_DUPLICATE_MESSAGE= "Telefone repetido na ficha.").- Migration
add_contact_phones_array: tabela geradacontact_phones(_parent_id, _order, value) + backfill manualINSERT ... SELECT id, phone, 0 FROM contact WHERE phone IS NOT NULL+DROP COLUMN contact.phone(derrubacontact_phone_idxjunto) + índice manualcontact_phones (value)(Payload não indexa subcampo de array; o equals/in da busca precisa). primaryPhoneOf(src/lib/phone.ts):phones[0]?.value ?? null— o único tradutor array→principal. Todos os readers de lista/ficha passam por ele (view modelsleadershipData,stateDeputyData,peopleData,supporterViewModels,leaderContactsPageData,campaignInvitePageData,activityViewModels, home search,MunicipalityDossier,ContactCombobox,wizardLeadershipContract).setContactPhones(nova utilitysrc/utilities/contactPhones.ts): read-modify-write transacional do array (usada pelas actions de edição inline "seta principal preservando o resto" e pelos editors de ficha);normalizeContactPhones(pure, compartilhada com o hook e com o zod).PhonesFieldEditor(novo componentesrc/components/campaign/shared/PhonesFieldEditor.tsx): inputs mascarados repetíveis (reusaFormattedInput+formatBrazilianPhoneInput), remover por linha, "+ Adicionar telefone", setas ↑/↓ de reordenação (ordem = prioridade; sem arrasto — anti-goal). Serializaphonesrepetido no FormData (padrãorepeatedRelationshipFormValues; novorepeatedPhoneFormValuesemsrc/lib/formData.ts).- Schemas (
src/lib/schemas/):contactSchemapermanece comphone(só o público usa — petição/WhatsApp); as ações públicas mapeiamphone → phones: [{ value }]ao gravar aContact(UI e zod públicos intocados). Nos schemas de campanha:leadershipCreateSchema/wizard/supporter/leaderSupporter/invitetrocamphoneporphones(array, min 1 nos fluxos que exigiam);contactFieldUpdateSchema: branchfield: 'phone'passa a significar "escrever principal preservando o resto" e novo branchfield: 'phones'(array completo) para os editors de ficha. - Access / Consent: nenhum (campo interno de
Contact; sem Consent novo). - UI: Impeccable B — formulários de criação/edição + ficha + listas existentes; shape→craft→critique→polish no editor compartilhado; shells e células inline existentes (
CampaignInlineEditableCell) permanecem para as listas (mostram o principal, editam o principal).
Fases verificáveis
- Tracer schema+server — campo array + hook + migration (backfill+drop+índice) +
primaryPhoneOf+findOrCreateContactByPhoneviaphones.value+ view models trocando para o principal + ações públicas mapeandophone → phones[0](sem tocar UI/zod públicos) +signatureExport+ seed/fixtures. Spike aqui: confirmar semântica dowhere: { 'phones.value': { equals/contains } }em Payload 3.82 (int spec) — se falhar, fallback é JOIN cru nos poucos sites Payload-where. - Write paths — zod/schemas das 5 superfícies + actions (leadership create/wizard/inline, supporter create/tombstone LGPD, stateDeputy inline, leaderSupporter, convite redemption, sync
CampaignUser(append se faltar), import CSV preview+bulk) + where de busca (supporterListFilters,supporterListSqlFilters, pickers de atividade, combobox). - UI —
PhonesFieldEditor+ forms de criação (LeadershipForm, SupporterForm, LeaderContactForm, WizardLeadershipForm) + fichas (LeadershipContactSection, StateDeputyContactSection, "Dados de contato" do apoiador com editor novo, assessor ganha seção "Telefones" na ficha) + células inline inalteradas na lista. - Gates — unit (primaryPhoneOf, normalize/dedupe, schemas, formData) + int (multi-telefone nas 5 superfícies, dedupe bloqueia, principal preservado no inline, import, convite, busca por qualquer número, tombstone substitui TODOS os telefones, sync append) +
pnpm gate:fast+pnpm push.
Rabbit holes / Não escopo (engenharia)
- Não adicionar busca por telefone nas listas que hoje só buscam por nome (lideranças, dobradinhas, pessoas, assessores) — o aceite é "a busca por telefone encontra por qualquer número" onde busca por telefone existe (apoiadores, pickers); adicionar nas outras é item futuro se a mesa pedir. Gatilho de revisitação: mesa perguntar "por que não acho a liderança pelo número na lista de lideranças".
- Sem cap de quantidade de telefones; sem flag "principal"; sem arrasto (setas são suficientes para trocar prioridade).
campaignUser.phonepermanece campo único da conta (canal de contato/login); não vira array.- Sem espelho ficha→conta (conta continua espelhando UNICAMENTE via sync existente conta→ficha, agora append).
Riscos e mitigação
- Payload onde em subcampo de array (
'phones.value'): spike na Fase 1 com int spec; fallback JOIN cru documentado nos poucos sites. - Migration destrutiva em prod (PII real): backfill roda ANTES do drop no mesmo migration;
migrate:statuslocal + revisão do SQL no checklist de deploy. - Churn de testes (muitos specs leem
contact.phone): helper de fixturecreateContactcontinua aceitandophonee mapeia internamente paraphones— maioria dos specs int fica intocada; asserts comwhere: { phone }viramwhere: { 'phones.value': … }. - Race do sync conta→ficha (append): sem transação garantida no hook; se o append colidir com edição concorrente, o dedupe fail-closed rejeita o save da conta (raro, mensagem clara).
- Inline edit de lista apagar principal: "limpar o campo" remove o index 0 (o resto sobe); nunca zera os demais.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (N telefones, lista=principal, ficha=todos, wa.me/convite/import=principal, busca por qualquer, C111 preservado, dedupe interno)
- Invariantes AGENTS/engineering-standards (fonte única em
Contact; transação+req nas escritas multi-collection; copy pt-BR; identificadores inglês) - Testes de domínio previstos (unit/int) onde access/write paths mudam — acima