- Pure helpers: advisorEditingScope, rowEditingAllowed in campaignAdvisorProfile.ts - gate: 'writable' in requireCampaignPageActor for route-level enforcement - Shared cells accept readOnly prop: CampaignInlineEditableCell, MunicipalityRelationEditor, PhonesFieldEditor, DemandDescriptionEditor, etc. - Municipality pages compute editingScope via resolveMunicipalityWriteScope and thread it to list/detail/edit surfaces - Home actions, FAB mount rule, quick actions registry accept editingScope parameter - Demands, activities, supporters, organizations create buttons gated - E2E spec: campaignPermissionProfile.e2e.spec.ts covering 3 profiles - Unit tests: campaignAdvisorProfile, accessShared, campaignComponents updated - gate:fast passed (tsc, lint, format, knip, cycles, unit)
16 KiB
Impl: Interface respeita o perfil de permissão (somente-leitura sem controles de edição; visão Tudo no escopo completo)
Status: aprovado Atualizado em: 2026-08-21 Issue: #770 (C142) Intenção: docs/plans/ui-respeita-perfil-permissao.md Appetite restante: herdado (~1–2 dias eng) — passada mecânica sobre superfícies existentes; cortes no "Rabbit holes / Não escopo"
Leitura da intenção
- Outcome: as superfícies staff do
/campanharefletem o perfil C141 do ator: assessorsomente_leituranão encontra NENHUM controle de escrita (células autosave, chips, "Registrar atualização", FAB/ações rápidas, wizards, sheets, status de demandas); assessortudonavega listas/detalhes/mapa no escopo completo com contagens coerentes;carteira · edita carteira= comportamento de hoje; nada muda para coordinator/candidate/leader. - O que NÃO negociar:
- Presença/ausência dos controles é a única linguagem — sem banner de "modo leitura", sem cinza-fantasma/disabled em massa (decisões do gate B/A).
- O enforcement do servidor (C141) não é relaxado nem substituído — a apresentação acompanha, nunca antecede.
- Sem redesenho de layout; sem mudança de modelo/permissão (fora de escopo do item irmão).
editing === 'tudo'não libera controles de coordenação (contas,advisors, nível E14, escaladas) — já role-gated; a passada não os abre.
- O que reavaliar: a hipótese da intenção dizia "predicados client-safe de perfil em
src/lib/campaignRoles.ts(ou o helper do item irmão)". A realidade pós-C141:campaignRoles.tsé só papel (role); o helper do item irmão (advisorEditingAccess) é server-only (access/shared.ts); nenhum componente conhece o perfil do próprio ator (zero ocorrências deediting/visibilityno front além da gestão de assessores). O front só receberole+ dados já escopados pelos loaders. Precisamos de um canal de apresentação do perfil — decisão D1 abaixo. Confirmou-se o precedente C116 (propsreadOnlyderivadas na página server) como padrão a generalizar; confirmou-se quetudojá flui por dados (access-driven) — o mapa/contagens não precisam de mudança de dados, só de um texto de readout honesto.
Abordagem recomendada
flowchart LR
P["Páginas server (requireCampaignPageActor) — user fresco"]
L["campaignAdvisorProfile.ts (client-safe)<br/>advisorEditingScope + rowEditingAllowed<br/>(spell único do eixo — server delega)"]
E["editingScope 'none|carteira|tudo' + portfolioIDs<br/>→ props (padrão C116/isStaffView)"]
C["Células/controles compartilhados ganham readOnly<br/>(estender dono — precedente B156)"]
B["Botões/forms/FAB/wizards:<br/>ocultar no call site (none) + gate 'writable' nas rotas"]
S["Server: advisorEditingAccess delega ao puro;<br/>requireCampaignPageActor ganha gate 'writable'"]
P --> E --> C
E --> B
S --> B
Opções consideradas:
- D1 — canal do perfil ao front: A (páginas server calculam
editingScope+portfolioIDse passam como props — padrão C116/isStaffView) | B (contexto/provider client serializando o perfil no layout) | C (boolean por controle, ex.canEditVotes/canEditTrend). - D2 — semântica do eixo no cliente: A (funções puras client-safe em
campaignAdvisorProfile.ts;advisorEditingAccessserver delega para elas no ramo advisor) | B (duplicar a regra no front) | C (exporvisibility/editingcrus e cada call site interpretar). - D3 — células sem
readOnly: A (estender o dono com propreadOnly, precedenteRelationChipCellB156) | B (não montar o controle e renderizar célula de leitura no call site) | C (wrapper novo). - D4 — gates de destino de escrita: A (novo
gate: 'writable'emrequireCampaignPageActor+ filtro dos municípios do wizard pelo writable scope) | B (gate inline por rota) | C (só esconder botões, rota continua acessível).
Recomendação:
- D1 → A. Páginas já têm o user fresco (
requireCampaignPageActor) e o padrão de props de permissão é o do repo (C116,municipios/page.tsx). B cria abstração nova (provider+serialização) onde o canal props já chega a cada call site; C explode em N×M. - D2 → A. O vocabulário do perfil já vive em
campaignAdvisorProfile.ts(client-safe, C141). As funções purasadvisorEditingScope(v, e)erowEditingAllowed(scope, portfolio, rowIds)são o spell único; o serveradvisorEditingAccessdelega (DRY de conhecimento, invariante P3-D — o fragmento de escopo continua vivendo uma vez). - D3 → A. A célula sabe a apresentação de leitura dela;
readOnlyno dono é o precedente exato (B156/C116). Botões/forms (que não têm "célula") são ocultados no call site. - D4 → A. O prologue centralizado (P3-I) ganha o gate; o wizard filtra os municípios oferecidos pelo
getWritableMunicipalityIds(sem ele, um assessortudo · edita carteiraescolheria município fora da carteira → 403 — exatamente o anti-goal "nenhum caminho leva a 403").
Rejeitadas: D1-B (nova abstração de permissão no cliente onde o padrão props já domina; a convenção P3-D prefere o fragmento server-side com flags de página); D1-C (booleans por controle); D2-B (duplicação de regra com risco de deriva fail-open); D2-C (interpretação crua em N call sites); D3-B (célula duplicada por call site); D3-C (wrapper inútil); D4-B (gate inline reabre o espalhamento que o P3-I consolidou); D4-C (rota viva = caminho de escrita visível, viola a decisão A do gate).
Componentes / mudanças
Núcleo — src/lib/campaignAdvisorProfile.ts (estender o dono do perfil)
advisorEditingScope(visibility: AdvisorVisibility | null | undefined, editing: AdvisorEditing | null | undefined): 'none' | 'carteira' | 'tudo'— client-safe, espelha o ramo advisor do serveradvisorEditingAccess(undefined →'carteira').rowEditingAllowed(editingScope, portfolioIDs: readonly number[] | null, rowMunicipalityIDs: readonly number[] | null): boolean— a regra por linha:none→ false;tudo→ true;carteira→ interseção linha∩carteira (portfolionull= tudo editável). Usada por listas com visão ampla + edição de carteira (municípios, lideranças, pessoas, dobradinhas).src/utilities/access/shared.ts:advisorEditingAccessdelega ao puro no ramo advisor (comportamento idêntico, teste pina).
Prologues — src/utilities/campaignPageActor.ts
CampaignPageGateganha'writable':advisorEditingAccess(user) === 'none'→redirect('/campanha')(o mesmo denyRedirect default do P3-I). Aplicado em:acoes/[slug]/page.tsx(5 slugs — hoje 4 deles nem têm gate de staff),municipios/[slug]/editar,liderancas/nova,demandas/nova,dobradinhas/nova,organizacoes/nova,atividades/giros. (Register-demand mantém o gatestaffexistente; o gatewritableé aditivo.)- Rota do wizard (
acoes/[slug]): para advisor, os municípios oferecidos no passo de busca passam porgetWritableMunicipalityIds(null → todos;[]→ redirect; ids → filtro) — o destino de escrita só oferece o que é gravável.
Atalhos de escrita — FAB, home actions, busca
src/lib/campaignHomeActions.ts:homeActionsForRole(role, editingScope)eresolveStaffHomeQuickActions(role, editingScope, returnPath)— advisornonemantém sóuncovered-municipalities(navegação); os 4 wizards somem.(app)/page.tsxe o registry passam o scope.src/lib/campaignQuickActionMount.ts+CampaignQuickActionsHost/useQuickActionsChromeActive:shouldMountQuickActionsFab(pathname, role, editingScope)— advisornone→falseem superfícies staff (todas as ações do drawer são destinos de escrita; a superfície de leader não é afetada). O layout(app)/layout.tsxcalculaeditingScopeuma vez (user fresco que ele já tem) e passa ao host/scroll chrome.- Busca global: os modos
wizard-*só são consumidos pelos passos de wizard (rotas gateadas) — sem mudança; verificado no sweep.
Células/controles compartilhados — prop readOnly (D3-A)
CampaignInlineEditableCell:readOnly→ renderiza a apresentação de leitura (valor + copy sereadBehavior='copy'), sem lápis/input/permanent.MunicipalityListTrendControl/MunicipalityListExpectedVotesControl/MunicipalityListLeadershipsControl/MunicipalityListUpdateControl/LeadershipListSupportStatusControl/MunicipalityV2DeclaredVotesCell/MunicipalityV2EstimatedVotesCell/MunicipalityV2LocalAccountSection/MunicipalityGoalAccountCard(conta da cadeira):readOnly→ badge/valor sem overlay/autosave/trigger.MunicipalityStateDeputyRelationCell/LeadershipStateDeputyRelationCell/MunicipalityPortfolioCell(call sites que não passamreadOnlyhoje): passarreadOnlyderivado.PhonesFieldEditor:readOnly(lista sem remover/↑↓/salvar).DemandDescriptionEditor/DemandResponsiblesCard/DemandWorkflowCard:readOnly→ texto/badges sem "Editar", sem multi-select, sem botões de transição/custo/comprovante (o branch escalado segue role-gated).SuggestionCard/SuggestionsPanel: sem ações de decisão paranone.MunicipalityV2StatusStrip: nível/tendência/atualização embutidos —readOnly(sem endpoints, sem overlay). (Nível continua role-gated para unrestricted.)ActivityTaskChecklist: checkboxes/inputs sem edição paranone.
Superfícies — páginas server calculam e passam (D1-A)
- Padrão por página:
const editingScope = user.role === 'advisor' ? advisorEditingScope(user.visibility, user.editing) : 'tudo';portfolioIDs = editingScope === 'carteira' ? await getAdvisorMunicipalityIds(payload, user.id) : null. - Municípios (
municipios/page.tsx,MunicipalityList,MunicipalityListMobileCards/MunicipalityMobileCard): colunas tendência/votos/lideranças/dobradinhas/atualização por-linha (rowEditingAllowed(scope, portfolio, [row.id]));MunicipalityListUpdateControloculto paranone; detail (MunicipalityDetailTabs):canEditdeixa de sertruehardcoded (linha 91) → flag da página (botão "Editar" +MunicipalityUpdateForm+PledgeEstimateForm+DeclareVotesForm+ sugestões); página[slug]/editarcom gatewritable+ checagem do município (getWritableMunicipalityIdscontém o id, senão redirect). - v2 (
municipio/[slug]/v2):StatusStrip/LocalAccountSection/NetworkSectioncomreadOnly/ocultos conforme scope. - Lideranças (lista +
[id]): células (CampaignInlineEditableCell), status, municípios, dobradinhas, convites (ocultar paranone), "Nova liderança" (ocultar paranone);[id]— contato/ficha internareadOnly, convite oculto. - Pessoas/Contatos: matriz
buildPeopleEditability(C116) ANDeditingScope !== 'none'; células textreadOnlyparanone; convites ocultos;ContactCreateRow/ContactCreateFabocultos paranone(contatos). - Dobradinhas: células text/
MunicipalityPortfolioCell/LeadershipStateDeputyRelationCellreadOnlyparanone+ por-linha (rowEditingAllowed) quandotudo · edita carteira. - Demandas: "Nova demanda" oculto para
none; detail — descrição/workflow/responsáveisreadOnly. - Atividades: lista — "Nova atividade"/"Planejar giro" ocultos para
none; detail — overlay de edição, "Nova atualização", lifecycle, checklist, update form, "Adicionar demanda", result form ocultos/readOnlyparanone. - Atualizações (
atualizacoes): modal de criação (CampaignUpdatesFilters) oculto paranone. - Apoiadores: "Novo" oculto;
PhonesFieldEditor/VoteIntentionControlreadOnly;RemoveSupporterDataButtonoculto (o server exige admin; a UI não pode oferecer caminho morto). - Organizações: "Nova organização" oculto para
none; verificar o form do detalheorganizacoes/[slug]no sweep (mesma regra). - Quadro/Início:
CampaignHomeActionsfiltrado (acima);SuggestionsPanelsem ações de decisão paranone. - Mapa (
MunicipalityMapPanel): o dado já é scope-coerente (access-driven); trocaractorRole→actorScope: 'carteira' | 'tudo'derivado (visibility === 'tudo' || isUnrestrictedCampaignRole(role)→'tudo'), para o readout/legenda ("no seu escopo") dizer a verdade quando o assessor vê tudo.
Dados → forma (se aplicável)
- Sem KPI/dado novo: passada de apresentação. A "forma" aqui é a regra de apresentação (controles presentes/ausentes) — decidida no gate (opção B: ausência é a linguagem; sem aviso). Textos novos pt-BR apenas onde um controle some e o valor precisa de apresentação de leitura (ex.: placeholder de célula).
Fases verificáveis
- Núcleo (~0,25d): funções puras em
campaignAdvisorProfile.ts+ delegação doadvisorEditingAccess+gate: 'writable'+ unit specs (advisorEditingScope,rowEditingAllowed, gate).tsc+pnpm testverdes. - Células compartilhadas (~0,5d):
readOnlynos controles listados; unit specs dos que têm comportamento condicional. - Superfície municípios + mapa (~0,5d): lista (desktop/mobile) + detail + v2 + editar + readout do mapa. Verificar visualmente no browser (shape→craft).
- Pessoas/contatos/lideranças/dobradinhas (~0,5d): matriz AND + células + convites + criação.
- Demandas/atividades/atualizações/apoiadores/organizações/sugestões/giros (~0,5d): ocultar/
readOnly+ gates das rotas de criação. - Atalhos (~0,25d): home actions, FAB, wizard gate + busca writable-scoped.
- E2E + gates (~0,5d): spec novo
campaignPermissionProfile.e2e.spec.ts(3 perfis: somente_leitura sem controles em municipios/lideranças/demandas/atividades + FAB ausente + wizard redireciona; tudo·edita carteira com linhas fora da carteira read-only; tudo·edita tudo com controles) usandocampaignFixtures(já suportavisibility/editing); rodar e2e afetado local;pnpm gate:fast+pnpm push.
Rabbit holes / Não escopo (engenharia)
- Redesenho de qualquer superfície (layout intacto; só presença/ausência).
- Banner/aviso de modo leitura (decisão B do gate).
- Mudar o modelo/enforcement (C141 dono) — a passada só apresenta.
saveToJWTdo perfil — desnecessário: páginas leem user fresco.- Gate de per-município em TODAS as rotas de detail — só
[slug]/editare o wizard precisam; os demais detalhes apresentam read-only (o servidor já rejeita escrita fora do escopo). - Auditoria de quem viu o quê; relatório de acessibilidade extra (a11y P3 do controle oculto segue o padrão existente).
Riscos e mitigação
- Ripple de assinatura (
role→role + editingScope) em shells client (FAB, home actions, map): mitigar com default'tudo'/parametros opcionais onde não-advisor; unit specs pina o comportamento por scope. - Caminho de escrita esquecido (o sweep é o cerne do item): inventário por categoria já feito (autosave/sheets/FAB/wizards/forms/status); e2e pin por superfície (municipios/lideranças/demandas/atividades/home) cobre os principais; o resto aparece no aceite do item (rabbit hole da intenção) — registrar débito se escapar.
- Matriz C116 quebrada para coordinator/candidate: o AND só afeta advisor com
none; unrestricted permanece idêntico (unit spec da matriz? a matriz vive na página — cobrir via e2e). - Giro/
atividades/giros: gatewritable+getWritableMunicipalityIdsjá usado nas actions (C141) — só o gate de rota falta; teste e2e opcional. - Mapa com quantis: os quantis já seguem o escopo real (access); só o texto muda — int spec existente (
bahiaGeometries/map bundle) continua passando; verificar o readout no browser.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (sem controle de escrita para
somente_leituraem nenhuma superfície staff; visãotudocoerente; nada muda para os demais perfis/roles) - Invariantes AGENTS/engineering-standards: sem
overrideAccess: truenovo; fragmento de escopo continua uma vez só (P3-D); identificadores em inglês, copy pt-BR; props como canal de permissão (padrão C116), sem provider novo - Testes de domínio: unit dos helpers puros + gate
writable; e2e novo por perfil/superfície; gates completos (tsc, lint, format, knip, cycles, unit+int, build)