13 KiB
Impl: Perfis de permissão por assessor (visão × edição), configuráveis pelo coordenador/candidato
Status: aprovado Atualizado em: 2026-08-19 Issue: #105 (C141) Intenção: docs/plans/permissao-granular-assessores.md Appetite restante: herdado (~2–3 dias eng) — cortes abaixo no "Rabbit holes / Não escopo"
Leitura da intenção
- Outcome: coordenador/candidato define por assessor Visão (
Tudo | Carteira) e Edição (Tudo | Carteira | Somente leitura) em/campanha/assessores(lista + detalhe + novo), com enforcement fail-closed no servidor; default = comportamento atual (Carteira · Edita carteira). - O que NÃO negociar:
- Default Carteira·Carteira para contas novas e existentes — zero mudança até configurar.
- Demandas ficam FORA dos eixos: Visão "Tudo" não abre demandas (regra de responsáveis = C143; aqui: carteira segue sendo o teto).
- Apoiadores (PII) capados na carteira para todo staff abaixo de candidato/coordenador, mesmo com Visão "Tudo" — e por simetria, mesmo com Edição "Tudo".
- Edição "Tudo" não libera escritas de coordenação (contas,
municipality.advisors, nível de envolvimento E14, decisão de demandas escaladas). - Combinação incoerente (editar o que não vê) não é oferecida — e é rejeitada no servidor.
- Leader lockdown e assimetria de votos (estimativas staff-only) intactos.
- O que reavaliar: a hipótese de direção apontava "perfis na conta + enforcement nos módulos de acesso + gates nas actions + UI nos três pontos" — confirma-se, com duas correções de engenharia: (a)
getAccessibleMunicipalityIdsNÃO pode virar o escopo de visão (ele alimenta superfícies PII — apoiadores, telefones, feeds — que o gate capa na carteira); (b) o prologueresolveActorScopedReadcompartilhado com demandas não pode alargar em bloco (vazaria demandas com Visão Tudo) — prologue irmão, profile-aware, para as coleções não sensíveis.
Abordagem recomendada
flowchart LR
F["CampaignUser.visibility/editing<br/>(default carteira/carteira, hook coerência)"]
L["src/lib/campaignAdvisorProfile.ts<br/>(opções, rótulos, coerência — client-safe)"]
R["Leitura: resolveProfileScopedRead + branches<br/>municípios, lideranças, updates, pledges, atividades, contatos"]
W["Escrita: eixo Edição nos access (canUpdate*/canCreate*)<br/>+ giro check write-scoped"]
A["actions/advisor.ts: updateAdvisorPermission<br/>+ createAdvisor com perfil"]
U["UI: coluna Permissão + popover editor + detalhe + draft row"]
M["Migration: add_campaign_user_advisor_permission_profile"]
F --> R; F --> W
L --> U
A --> U
M --> F
Opções consideradas: A (perfis sobre o papel advisor em dois selects na conta) | B (role novo viewer) | C (matriz por coleção) | D (alargar getAccessibleMunicipalityIds por visão)
Recomendação: A — dois selects (visibility, editing) em campaignUser + eixo de leitura profile-aware nos access de coleção + eixo de escrita por editing; UI em três pontos com o mesmo editor. Mantém o modelo de papéis congelado, enforcement centralizado onde o código já decide escopo (overrideAccess: false + user), e as superfícies PII intactas.
Rejeitadas:
- B porque recria seed/modelo de papéis (rabbit hole do gate).
- C porque explode em matriz N×M (anti-goal do gate).
- D porque
getAccessibleMunicipalityIdsalimenta apoiadores, telefones de contas e feeds — alargá-lo abriria PII além da carteira, violando o gate; o escopo "carteira" continua sendo O escopo de operação, e a visão ampla é um eixo separado.
Componentes / mudanças
Modelo — src/collections/CampaignUser.ts
visibility: select'carteira' | 'tudo', default'carteira', label "Visão" (pt-BR no admin),admin.conditionsó p/role === 'advisor',access.update: canManageCampaignUserRole(unrestricted/admin).editing: select'carteira' | 'tudo' | 'somente_leitura', default'carteira', mesma condição/access.beforeValidatenovoenforceCoherentAdvisorProfile:role === 'advisor' && editing === 'tudo' && visibility !== 'tudo'→ APIError (fail-closed também via REST/admin, não só na action).preventSelfServicePrivilegedFields: adicionarvisibility,editingao strip.- Migration:
add_campaign_user_advisor_permission_profile(duas colunas select com default'carteira'; sem backfill — default cobre linhas existentes).
Lib — src/lib/campaignAdvisorProfile.ts (novo, client-safe)
- Tipos
AdvisorVisibility/AdvisorEditing;ADVISOR_VISIBILITY_OPTIONS/ADVISOR_EDITING_OPTIONS(value + label + description pt-BR do draft: "Tudo — enxerga todos os municípios e lideranças.", "Somente leitura — nenhum controle de edição em lugar nenhum.", …);advisorProfileLabel(v, e)("Carteira · Edita carteira", "Tudo · Somente leitura", "Tudo · Edita tudo");isCoherentAdvisorProfile(v, e)(e === 'tudo' ⇒ v === 'tudo'). Combinar comcampaignRoles.ts(papéis), não duplicar.
Access — src/utilities/access/
shared.ts:resolveProfileScopedRead(req, scopeField, loadAccessibleIds)— mesmo prólogo deresolveActorScopedRead, mas advisor comvisibility === 'tudo'→true.resolveActorScopedReadfica como está (demandas continuam carteira — C143 substitui depois).advisorEditingAccess(currentUser)→'none' | 'carteira' | 'tudo'a partir deediting(somente_leitura → none; tudo → tudo; senão carteira; não-assessor → none).resolveAccessibleIds: permitircomputeretornarnull(= "tudo") — necessário paragetAccessibleLeadershipIds/getAccessibleContactIdsampliarem sem virartrue(que abriria PII).
municipalities.ts:canReadMunicipality— advisor comvisibility === 'tudo'→true;canUpdateMunicipality— eixo: none →false, tudo →true, carteira →{ advisors: { contains: self } }(where atual inalterado).leaderships.ts:canReadLeadership→resolveProfileScopedRead;getAccessibleLeadershipIds— advisor com visão tudo →null;canCreateLeadership/canManageLeadership— eixo de escrita.municipalityUpdates.ts(+ aliasallocationDecisions.ts):canReadMunicipalityUpdate/canReadAllocationDecision→resolveProfileScopedRead;canCreateMunicipalityUpdate— eixo.votePledges.ts:canReadVotePledge→resolveProfileScopedRead;canCreateVotePledge/canUpdateVotePledge— eixo (tudo →true; none →false; carteira → fragmento atual).activities.ts:canReadActivity— advisor com visão tudo →true;canCreateActivity/canUpdateActivity— eixo (carteira mantém o or-whereresponsible/municipality; tudo →true; none →false).demands.ts: inalterado na leitura (carteira — C143 dono). SócanUpdateCampaignDemand/canCreateCampaignDemand: eixo none →false; tudo/carteira → comportamento atual (carteira; C143 substitui a regra depois).supporters.ts:canCreateSupporter/canManageSupporter— eixo none →false; senão comportamento atual (carteira SEMPRE; PII cap nos dois eixos).canReadSupporterinalterado.organizations.ts/stateDeputies.ts: booleans staff → eixo (none →falsepara advisor; senão comportamento atual).contacts.ts:getAccessibleContactIds— ramo lideranças: advisor com visão tudo →where: {}(dobradinhas já são todas); ramo apoiadores: SEMPRE carteira (PII cap).canReadContactssegue derivando ids.calendarFeeds.ts,campaignUsers.ts(phone): inalterados — feeds são superfície pessoal (contrato C96 re-deriva escopo na leitura) e telefone é PII; continuam carteira.
Actions — src/app/(campaign)/campanha/actions/
advisor.ts:updateAdvisorPermission(novo) —reloadUnrestrictedActor+assertTargetAdvisor+payload.update({ visibility, editing }, user, overrideAccess: false)(field accesscanManageCampaignUserRolere-checa);createAdvisorRecordaceitavisibility/editingopcionais (default carteira).revalidateAdvisorPaths.activity.tscreateTourDraftActivitiesRecord: trocar o check de escopo do giro de leitura para escrita — hoje lê municípios com access (com visão tudo o read alargaria e um assessor "Carteira" comporia giro fora da carteira). UsargetWritableMunicipalityIds(novo helper emmunicipalities.ts: unrestricted/tudo →null; none →[]; carteira → ids da carteira).formActions.ts(assessores):updateAdvisorPermissionFormAction;createAdvisorFormActionlêvisibility/editingdo FormData.
Dados/view models — src/utilities/advisorData.ts
AdvisorRowViewModel/AdvisorDetailViewModelganhamvisibility/editing;loadAdvisorListPageData/loadAdvisorDetailincluem os campos noselect.
UI — src/components/campaign/advisor/ (Impeccable B — encaixe na superfície existente)
AdvisorPermissionEditor(novo, client): doisNativeSelect(Visão/Edição) + nota de demandas + Cancelar/Salvar; ao escolher Edição "Tudo" com Visão "Carteira", auto-eleva Visão para "Tudo" (só combos coerentes são oferecidos); salva via formAction +router.refresh().AdvisorPermissionBadge(novo, client): badge "Carteira · Edita carteira" etc. (botão) abrindo Popover com o editor — reusado na lista e no draft row.AdvisorsTable: colunapermission(mandatory,headerClassName~w-48) com o badge; draft row ganha célula de permissão (estado local, default carteira/carteira) esaveDraftenvia os campos;DraftAdvisorganhavisibility/editing.- Detalhe
[id]/page.tsx: seção "Permissão da conta" (título + editor inline + nota de demandas/coordenação), mesma formAction. - Coluna participa do picker como mandatory (contrato B197+ — body sempre renderiza).
Dados → forma (se aplicável)
- Sem KPI/dado novo: superfície de configuração. Rótulo "Permissão" em badge curto (coluna) e textos descritivos no editor — forma do draft do gate, reutilizada como vocabulário único (
campaignAdvisorProfile.ts).
Fases verificáveis
- Tracer — schema + leitura (~0,5 dia): campos + hook + migration +
campaignAdvisorProfile.ts+resolveProfileScopedRead/advisorEditingAccess+ leitura dos access (municípios, lideranças, updates, pledges, atividades, contatos) +generate:types+ int spec de leitura (visão tudo alarga; carteira não; demandas/apoiadores continuam carteira). - Escrita (~0,5–0,75 dia): eixo
editingnoscanUpdate*/canCreate*+getWritableMunicipalityIds+ giro + int spec (somente_leitura nega tudo; tudo permite fora da carteira exceto PII/coordenação; carteira = hoje). - Actions + dados (~0,25 dia):
updateAdvisorPermission, create com perfil, zod, form actions, view models/loaders. - UI (~0,75–1 dia): editor + badge + coluna + draft row + detalhe; shape→craft→critique→polish; unit specs dos componentes/labels.
- Gates:
pnpm migrate:create+pnpm migrate(local),generate:types(comS3_*dummy setados),tsc --noEmit,pnpm lint,format:check,knip,check:cycles,pnpm test(unit+int),pnpm build. e2e roda no CI.
Rabbit holes / Não escopo (engenharia)
- Redesenho mobile da lista de assessores em cards (draft cena 2) — a tabela atual rola; apresentação por perfil é o item irmão C142. Não escopo aqui.
- Mudar a regra de demandas (responsáveis) — C143 é o dono; aqui só o bloqueio "somente leitura" e o teto carteira.
- Histórico/auditoria de mudanças de perfil; autoatendimento; perfil para coordinator/candidate/leader.
saveToJWTpara os campos novos — desnecessário:getFreshCampaignUserrecarrega por ID.- Migration de backfill — default cobre linhas existentes.
Riscos e mitigação
- Mapa/quantis/dashboard leem
loadMunicipalityScope(access-driven) — alargam automaticamente com visão tudo; esperado e desejado ("mesa de trabalho completa"). Mitigação: int spec pina que o escopo do mapa acompanha o perfil. getAccessibleLeadershipIdsalargada abre convites para todas as lideranças com visão tudo — coerente com a visão; registrar no resumo (C142 apresenta; se a mesa discordar, item sucessor).- Sollinha usa as mesmas queries/access — segue automaticamente; conferir B185/B186 (fragmentos allowlistados por escopo já resolvido) em fase 2.
- Contatos: a lista de pessoas deriva de lideranças (alarga) + apoiadores (carteira) — composição por ids, nunca
true(evita abrir PII). Teste pina o ramo apoiadores. - Combinação incoerente via API — hook no
beforeValidate+ zod; teste pina o 400. - Giro (tour) — o check read→write é a única correção fora dos access; teste específico.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (dois eixos, default carteira, fail-closed, PII/demandas/coordenação intocados)
- Invariantes AGENTS/engineering-standards: Local API com
user→overrideAccess: false; sem re-escrita do fragmento P3-D (guarda emcodebaseConventions); identificadores em inglês, valores/UI pt-BR - Testes de domínio previstos (unit/int) onde access/write paths mudam:
campaignAdvisorPermission.int.spec.ts+ unit dos helpers de perfil