teqo-backup/docs/plans/c165-f1-update-access-municipality-impl.md

Impl: C165-F1 — Activity: update access fecha município nulo/fora da carteira (bypass REST)

Status: aprovado Atualizado em: 2026-09-15 Issue: #1030 Intenção: docs/plans/c165-f1-update-access-municipality.md Appetite restante: herdado — ~0,25 dia eng

Leitura da intenção

• Outcome: canUpdateActivity deixa de cobrir só a linha e passa a inspecionar data.municipality para um advisor (staff não-unrestricted): null (ou malformado) → recusa; id fora do write scope da carteira → recusa; chave ausente → mantém o Where de linha atual. Coordenador/candidato/admin intocados; editing: 'tudo' segue alcançando qualquer atividade com município, mas limpar para null vira coordenação/candidato-only. Fecha o bypass REST/Local (PATCH /api/activity/:id com JWT de campanha).
• O que NÃO negociar: simetria com canCreateActivity (que já é data-aware); action mantém guard/UX (Decisão G do C165) como defesa em profundidade, sem mensagem nova; sem field access por valor; sem migration/Consent/UI; touchpoint único no collection access.
• O que reavaliar: nada estrutural — a intenção deixa o eixo de valor no collection access e o Where de linha intocado. Fica em aberto apenas a forma de detectar a presença de municipality no patch (resolvida abaixo).

Abordagem recomendada

flowchart TD
  A[update activity] --> B{admin / unrestricted?}
  B -- sim --> OK[true]
  B -- não --> C[getFreshCampaignUser]
  C --> D{advisor staff?}
  D -- não --> NO[false]
  D -- sim --> E{editingAccess}
  E -- none --> NO
  E -- carteira / tudo --> F{data.municipality !== undefined?}
  F -- não --> G[carteira: advisorActivityScopeWhere / tudo: municipality exists]
  F -- sim --> H{relationshipId = null?}
  H -- sim --> NO
  H -- não --> I{editingAccess = tudo?}
  I -- sim --> G
  I -- carteira --> J{id ∈ getAccessibleMunicipalityIds?}
  J -- não --> NO
  J -- sim --> G

Opções consideradas: A) guard de valor no collection access update (data-aware, reusando getAccessibleMunicipalityIds memoizado) | B) usar getWritableMunicipalityIds no access | C) field-level access em municipality.

Recomendação: A — porque o bypass é do valor e o dono do eixo de access de update já é esta função; data chega ao access (node_modules/payload/dist/collections/operations/updateByID.js:42-46 passa { id, data, req }), então o guard fecha por construção sem tocar a action. Para editing === 'carteira' o conjunto de ids coincide com a carteira (getAccessibleMunicipalityIds), que advisorActivityScopeWhere já chama no mesmo request — logo a checagem extra é memoizada e não adiciona query.

Rejeitadas:

• B (getWritableMunicipalityIds): faz um find não-memoizado por request no caminho quente (todo update de activity passa pelo access) e, para carteira, devolve o mesmo conjunto do memoizado; para tudo devolve null (catálogo todo), já coberto por não checar escopo no branch tudo.
• C (field access): fora de escopo pela intenção; field access recebe valor/sibling data, não o documento, e a assimetria do modelo pertence ao collection access.

Decisão	Caro / Barato	Escolha
Onde mora o guard de valor	field access (caro, fora de escopo) vs collection access update (barato)	collection access
Fonte dos ids da carteira	getWritableMunicipalityIds (find extra/request) vs getAccessibleMunicipalityIds (memoizado)	memoizado
Detectar presença de municipality	'municipality' in data (recusa undefined explícito) vs data?.municipality !== undefined + relationshipId	!== undefined (só a chave ausente cai no Where)

Componentes / mudanças

• canUpdateActivity (src/utilities/access/activities.ts:104): trocar a assinatura para async ({ data, req }); após if (editingAccess === 'none') return false, inserir o guard de valor antes dos retornos de linha:

  if (data?.municipality !== undefined) {
    const municipalityID = relationshipId(data.municipality)
    if (municipalityID === null) return false
    if (editingAccess === 'carteira') {
      const writableIDs = await getAccessibleMunicipalityIds(req, currentUser)
      if (writableIDs !== null && !writableIDs.includes(municipalityID)) return false
    }
  }
  

  Preservar intactos os retornos seguintes (tudo → { municipality: { exists: true } }; senão → advisorActivityScopeWhere). relationshipId já devolve null para null/undefined/malformado e id para número/{id}; o !== undefined externo garante que chave ausente não seja recusada. Comentar com C165-F1 explicando o eixo valor vs linha.

• Pin int (tests/int/campaignActivity.int.spec.ts): novo it(...) perto do bloco :485-498; com o advisor da carteira e um município fora (fixtures.getMunicipality()), exercitar via payload.update({ collection: 'activity', id, data, user, overrideAccess: false }):

  • { municipality: null } → rejects.toThrow(/permissão/i);
  • { municipality: outside.id } → rejeita;
  • { locality: '...' } (só outro campo) → sucesso, municipality inalterado;
  • advisor editing: 'tudo' (createCampaignUser('advisor', { editing: 'tudo' })): apontar para outside.id é permitido, mas { municipality: null } é recusado.

  Manter :485-498 verde (sem data → Where exato inalterado).

• Migration: sem migration.

• Access / Consent: só o eixo de access de activity.update; nenhum Consent/opt-in envolvido.

• UI: N/A — sem UI.

Fases verificáveis

1. Editar canUpdateActivity em src/utilities/access/activities.ts (guard de valor; retornos de linha intactos).
2. Adicionar o pin int em tests/int/campaignActivity.int.spec.ts e confirmar :485-498 intacto.
3. Rodar pnpm gate:fast (inclui int) verde; checar que nenhum outro teste de activity quebrou.

Rabbit holes / Não escopo (engenharia)

• Field-level access por valor em municipality — fora de escopo (intenção).
• Hardening equivalente em outras collections — fora de escopo; só activity.update.
• Memoização global de getWritableMunicipalityIds no módulo — não pedido; o branch tudo não precisa de ids.
• Mensagem nova/ajuste de copy da action — fora de escopo; a recusa vira o erro genérico de permissão (mesmo comportamento do bypass do create).
• Ajuste no manifest e2e (scripts/lib/e2e-affected-manifest.mjs:116-118) — já mapeado, nenhum toque.

Riscos e mitigação

• Advisor editing: 'tudo' hoje limpa município pela action — já era recusado no C165; o access só fecha a mesma regra por outra porta. Teste do branch tudo cobre null recusado e remanejamento permitido.
• Custo por request no caminho quente: getAccessibleMunicipalityIds é memoizado por request (resolveAccessibleIds, shared.ts:249) e só é chamado quando editing === 'carteira' e data.municipality presente; deduplica com a chamada de advisorActivityScopeWhere.
• Regressão do pin existente (:485-498 compara o Where exato sem data): data?.municipality === undefined cai direto nos retornos atuais — comportamento idêntico.
• Falso permitido para id malformado: coberto pelo relationshipId === null no mesmo guard.
• Erro do access: false em update vira Forbidden (executeAccess.js:10-14) → mensagem de permissão, sem tocar names/copy (/permissão/i como no restante da suíte).

Aceite de engenharia

• canUpdateActivity é data-aware: null/malformado → false; fora da carteira (carteira) → false; ausente → Where de linha inalterado.
• editing: 'tudo' permite qualquer município com municipality presente, mas recusa null.
• Pin int novo verde em tests/int/campaignActivity.int.spec.ts; :485-498 segue verde.
• pnpm gate:fast verde.
• Sem migration, sem Consent, sem UI; URL/slug intactos.

Débitos da revisão (triage 2026-09-15)

Já resolvido na sessão (não reabrir): nome writableIDs → accessibleIDs (a fonte é o escopo de leitura; na carteira coincide com o write scope); comentário do tudo reescrito; borda positiva coberta (repoint dentro da carteira permitido) e perfil misto visibility:'tudo' + editing:'carteira' pinado (a Visão "Tudo" não alarga a fronteira de escrita) — trava o invariante read==write da carteira sem nova query; impl doc commitado.

Explicitamente fora / descartado deste lote:

• C90 leg responsible × valor do município (pré-existente, sinalizado pelos dois revisores): um advisor responsável por atividade fora da carteira edita por update parcial que omita municipality (pin :684), mas o overlay de edição reenvia o município e a recusa por valor fora da carteira fecha o save inteiro. Já era o comportamento da action do C165 (não é regressão desta entrega) e não há Issue aberta. Gatilho: primeiro relato de assessor responsável que não consegue salvar pelo overlay, ou curadoria futura do leg responsible (C90/C141) — aí revisar action + access juntos.
• Hardening de valor em outras collections: cada domínio tem seu dono; fora do appetite.

Self-score (decision-quality)

5/5.

• Problema, owner e assimetria nomeados (activities.ts:104 collection access vs action em activity.ts:300; data chega ao access conforme Payload).
• Decisão principal com trade-off explícito (memoizado vs getWritableMunicipalityIds) e critério de correção para o branch tudo (não reaproveitar a carteira).
• Borda de presença (undefined ausente vs null presente) resolvida com justificativa e coberta por teste.
• Aceite verificável e enxuto dentro do appetite (~0,25 dia): uma função, um teste, gate.