mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-18 22:33:05 +00:00
Migration 20260823_161905_add_municipality_update_deliberation + access por mutationKind + ilha client nas 3 superfícies + specs unit/int/e2e.
25 KiB
25 KiB
Impl: Deliberação na atualização (responsável, thread, resolvido)
Status: rascunho Atualizado em: 2026-08-23 Issue: #397 (C88) Intenção: docs/plans/deliberacao-atualizacao-responsavel-thread.md Appetite restante: herdado (~1–1,5 dia eng) — um outcome verificável (coordenação atribui, discute e fecha uma atualização)
Leitura da intenção
- Outcome: a coordenação delibera na própria atualização — atribui UM responsável (staff do município), discute num fio visível para quem já lê atualizações daquele município, e marca Resolvido (com reabertura explícita). Atualização resolvida permanece legível no histórico com estado aberto/resolvido óbvio no card; liderança não vê nem participa; modelo unificado de C87 intacto (sem reintroduzir kinds/tipos de sinal).
- O que NÃO negociar:
- Leader lockdown na raiz:
resolveProfileScopedReadjá resolve leader →false(src/utilities/access/shared.ts:219). O fio vive DENTRO do doc e herda o read escopado — nenhuma superfície nova (loader, action, select de staff) pode expor dado deliberativo a leader. - Sem reintroduzir kinds/tipos de sinal (C87): deliberação é estado e atividade sobre o doc unificado, nunca um novo tipo.
- Imutabilidade do fato registrado: comentário/atribuição/resolvido NÃO editam
body/polarity/urgent/adversarySignal(correção = nova atualização ou comentário). - Quem atribui responsável e marca resolvido: só coordinator/candidate (
isCampaignUnrestricted) + admin. Responsável nunca é liderança. - Atualização sem responsável pode ter fio e resolvido (campos independentes).
- Leader lockdown na raiz:
- O que reavaliar:
- "Colunas na collection" (hipótese da intenção): confirmada, MAS o caminho de escrita não é um update aberto —
MunicipalityUpdate.updateé admin-only hoje (canMutateMunicipalityUpdate,access/municipalityUpdates.ts:39). A deliberação exige um canal de update restrito porcontext.mutationKind(precedente ActivityisActivityMutationShortcut) — decisão D5. - "Fio = array dentro do doc" (precedente
Activity.updates): confirmado, mas cria tabela nova (municipality_update_comments) + hook derivador que carimba author/createdAt dos itens novos (precedentederiveActivityFields, Activity.ts:316-329). authoré FK escalar (municipality_update.author_id, não_rels): as novas rels single de deliberação (responsible,resolvedBy) seguem o MESMO formato (coluna_id+ FK + índice), NÃO o padrão_relsdaCampaignDemand(que é polymorphic/hasMany).- Notificações: a intenção permite "badge interno no máximo"; existe infra pronta (
notificationEvents/createCampaignNotifications) — cortada nesta fatia (ver Rabbit holes) para caber no appetite, com gatilho de revisitação.
- "Colunas na collection" (hipótese da intenção): confirmada, MAS o caminho de escrita não é um update aberto —
Abordagem recomendada
flowchart LR
C["Card server-rendered (VM escopada por access)"]
I["Ilha client por card<br/>(select responsável · composer · Resolvido/Reabrir)"]
A["Server actions (zod + runCampaignFormAction)<br/>transaction + advisory lock por doc"]
U["payload.update<br/>context.mutationKind = deliberação"]
G["Collection access: gate por mutationKind<br/>+ FieldAccess por campo"]
H["beforeChange derivador: carimba<br/>comentários novos, barra campos staff"]
VM["loadMunicipalityUpdatesFeed: VM + staff elegível<br/>+ capabilities do ator"]
C --> VM --> I --> A --> U --> G
U --> H
Opções consideradas / Recomendação / Rejeitadas (formato decision-quality, caro de reverter decidido aqui):
- D1 — Onde vive o estado deliberativo (responsável/resolvido): A (rels single
responsible/resolvedBy+ colunaresolvedAtna própriaMunicipalityUpdate) | B (collectionMunicipalityUpdateDeliberationseparada) | C (subsumir emCampaignDemand). Recomendação: A — um doc = um estado; o fio dentro do doc herda o read escopado (leader lockdown grátis, sem access novo na superfície); zero join/loaders adicionais; o aceite "depende do modelo unificado de C87" é satisfeito sem segundo registro. B cria fronteira cara (access/loaders/consistência/cleanup) para guardar 3 campos; C mistura domínios e é anti-goal explícito da intenção ("sem abrir demanda para cada fato"). - D2 — Onde vive o fio: A (array
commentsdentro do doc, precedenteActivity.updatesL646-688) | B (collectionMunicipalityUpdateCommentcom relationship parent). Recomendação: A — precedente exato de append atômico (read→append→update com lock), herda read do pai automaticamente (leader bloqueado na raiz), página já carrega o doc com depth. B exige collection nova com access próprio, cleanup de órfãos e N+1 no load do feed. Custo futuro aceito: editar/excluir comentário individual, mentions e reações ficam mais difíceis — barato adiar, gatilho de revisitação anotado. - D3 — Forma do autor do comentário: A (campo
authorrel campaignUser DENTRO do array — Payload materializaauthor_idescalar na tabela do array, precedenteactivity_updates.author_id+ índice) | B (campo number puro e resolver nome no VM). Recomendação: A — espelhaActivity.updatesitem a item (body/author/createdAt); o hook derivador carimba;loadCampaignUserNamesByIdsjá resolve nomes em lote. B economiza nada (o VM precisa do nome do mesmo jeito) e diverge do precedente. - D4 — Representação do estado resolvido: A (
resolvedAtdate +resolvedByrel; resolvido ⇔resolvedAtnão-nulo) | B (booleanresolved). Recomendação: A — o timestamp é a auditoria natural (quem/quando), elimina estado booleano flapping, e a reabertura é simplesmente limpar os dois campos. B guarda menos informação e precisaria de coluna extraresolvedAtde qualquer forma para o card. - D5 — Canal de escrita da deliberação (o caro): A (estender o dono:
canMutateMunicipalityUpdatevira gate porcontext.mutationKinddeliberativo —assignResponsible/appendComment/resolve/reopen— + FieldAccess preciso em cada campo novo; delete continua admin-only) | B (payload.updatecomoverrideAccess: truedentro das actions) | C (endpoints REST próprios fora da Local API). Recomendação: A — "edit the owner, don't twin": a collection access continua sendo o único portão;overrideAccess: falsepreserva o invariante do repo (nenhumoverrideAccess: truenovo); o precedente exato écanUpdateActivity+isActivityMutationShortcut. B quebra o invariante de acesso e o fail-closed; C cria superfície paralela à convenção transactions/advisory locks do repo. Defesa em profundidade: o gate por mutationKind é o coarse gate (staff não consegue tocarbody), a FieldAccess é o precise gate (quem pode tocar cada campo). - D6 — Predicados de acesso por perfil: A (novas funções em
src/utilities/access/municipalityUpdates.tsreusando primitivos deshared.ts:canAssignUpdateResponsible/canResolveMunicipalityUpdate=isCampaignUnrestricted+admin;canCommentOnMunicipalityUpdate= mesmo predicado decanCreateMunicipalityUpdate— "quem pode criar naquele município comenta"; delegação para evitar duplicação) | B (predicados inline nas actions) | C (helper genérico de mutationKind fora do módulo de acesso). Recomendação: A — o vocabulário RBAC do repo é por módulo de domínio emaccess/*com barrelcampaignAccess; a regra de comentar é literalmente a regra de criar (gate da intenção "qualquer staff que já pode criar atualização naquele município — B pode comentar"), entãocanCommentOnMunicipalityUpdateDELEGA ao corpo decanCreateMunicipalityUpdate(DRY de conhecimento). B espalha regra de acesso em actions; C cria pass-through raso (depth check: não criar). - D7 — Lista de staff elegível do select: A (loader server
loadAssignableUpdateStaff(payload, municipalityID):where: or [ { id: { in: advisors } }, coordinator, candidate ]sobrecampaignUser— advisors do município (Municipality.advisors) + unrestricted, espelhandoeligibleCampaignStaffWhere) | B (sóMunicipality.advisors) | C (client busca via endpoint novo). Recomendação: A — o aceite fixa "staff do município (advisors + unrestricted)"; o where é declarativo e reusa o filtro do admin;filterOptions: eligibleCampaignStaffWhereno camporesponsiblealinha admin e ferramenta. B quebraria o aceite (coordinator não apareceria como responsável elegível); C cria endpoint novo onde server action já existe. - D8 — Feed global multi-município (
/campanha/atualizacoes): A (o loader do feed carrega, por página, os staff elegíveis dos municípios presentes — batch: 1 find emmunicipality(id+advisors) + 1 find emcampaignUsercom o where or — e capabilities do ator; o card é a mesma ilha) | B (select carrega sob demanda via endpoint) | C (fio não interativo no feed global, só no detalhe). Recomendação: A — o fluxo da intenção abre a atualização "no feed/detalhe"; o card compartilhado mantém consistência (dossier ganha grátis) e o batch de 2 queries por página cabe no appetite. B viola a convenção (sem endpoints novos); C quebra o fluxo principal do aceite. - D9 — Serialização do append/comentário: A (advisory lock por doc
municipality-update:<id>na action, ANTES dopayload.update; obeforeChangemantém o lock por município existentemunicipality-updates:<municipalityID>como segunda camada) | B (confiar só no lock por município). Recomendação: A — lock por doc é a granularidade do read-modify-write do array (comentários em atualizações diferentes do mesmo município não se serializam) e é o padrão da casa (activity:<id>). Ordem de aquisição consistente em todos os escritores (doc → município) evita deadlock — ver Riscos. B é correto mas coarsa (fila por município para todo append).
Rejeitadas: D1-B/C, D2-B, D3-B, D4-B, D5-B/C, D6-B/C, D7-B/C, D8-B/C, D9-B (justificativas acima).
Componentes / mudanças
src/collections/MunicipalityUpdate.ts(estender o dono):- Novos fields:
responsible(relationship campaignUser single,index: true,filterOptions: eligibleCampaignStaffWhere, label "Responsável", accesscreate/update: canAssignUpdateResponsible);resolvedBy(relationship campaignUser single,index: true, label "Resolvido por",admin.readOnly, accesscreate/update: canResolveMunicipalityUpdate);resolvedAt(date,index: true, label "Resolvido em",admin.readOnly, accesscreate/update: canResolveMunicipalityUpdate);comments(array, label "Comentários", fields:bodytextarea required maxLength 4000 (espelhaActivity.updates.body),authorrel campaignUseradmin.readOnly+ accesscanSetMunicipalityUpdateSystemField(= payloadAdminOnly — o hook deriva, não chega pela entrada),createdAtdateadmin.readOnly+ mesma access). beforeChangeganha ramo deliberativo: secontext.mutationKind∈{assignResponsible, appendComment, resolve, reopen}→ (a) allowlist de campos alteráveis{responsible, resolvedBy, resolvedAt, comments}— chave fora da allowlist presente emdata→APIError 403(fail-closed: nem admin-texto passa); (b) paraappendComment, preserva itens antigos e carimbaauthor/createdAtnos itens novos (precedentederiveActivityFields); pararesolve, carimbaresolvedBy = req.user.ideresolvedAt = now; parareopen, limpa ambos. Fora do ramo → comportamento atual intacto (admin).beforeValidate(admin path) continua validando body/polarity sem mudança;defaultColumnsganharesponsible(opcional).
- Novos fields:
- Migration:
20260823_<HHMM>_add_municipality_update_deliberation(serializada após20260820_003426, viapnpm migrate:create+ ajuste manual, commitando.ts+.json+index.ts;pnpm migratelocal):ALTER TABLE "municipality_update" ADD COLUMN "responsible_id" integer;+ FKmunicipality_update_responsible_id_campaign_user_id_fk(campaign_user(id),onDelete: set null,onUpdate: no action— espelhaauthor_id) + índicemunicipality_update_responsible_idx.- Idem para
resolved_by_id(+ FK..._resolved_by_id_...+ índicemunicipality_update_resolved_by_idx). ALTER TABLE "municipality_update" ADD COLUMN "resolved_at" timestamp(3) with time zone;(nullable — sem backfill; nada existente é deliberado) + índicemunicipality_update_resolved_at_idx.CREATE TABLE "municipality_update_comments"espelhandoactivity_updates:_orderinteger,_parent_idinteger (FKmunicipality_update_comments_parent_id_fk→municipality_update(id)onDelete: cascade),idvarchar (PK),bodyvarchar,author_idinteger (índicemunicipality_update_comments_author_idx),created_attimestamp(3) with time zone. (Sem_rels: author é escalar no array, precedenteactivity_updates.author_id.)
down: drop das 3 colunas/índices/FKs + drop da tabela de comentários.
- Access —
src/utilities/access/municipalityUpdates.ts:MUNICIPALITY_UPDATE_DELIBERATION_MUTATIONS(const set compartilhada com as actions — exportada do módulo de acesso).canMutateMunicipalityUpdate→ split:canUpdateMunicipalityUpdate(admin → true; senão gate por mutationKind:assignResponsible|resolve|reopen→isCampaignUnrestricted;appendComment→ leader false → unrestricted true → advisor comadvisorEditingAccess !== 'none'resolve Where de escopoadvisorMunicipalityScopeWhere('municipality', ids)(espelhacanUpdateActivity); fora → false) ecanDeleteMunicipalityUpdate(admin-only, comportamento atual).- Novos:
canAssignUpdateResponsible: FieldAccess(admin → true; senãoisCampaignUnrestricted(freshUser));canResolveMunicipalityUpdate: FieldAccess(idem);canCommentOnMunicipalityUpdate: Access/FieldAccess(delega ao corpo decanCreateMunicipalityUpdate);canSetMunicipalityUpdateSystemField: FieldAccess(payloadAdminOnly— para author/createdAt dos comentários). - Barrel
src/utilities/campaignAccess.tsreexporta os novos nomes.
- Server actions —
src/app/(campaign)/campanha/actions/municipalityUpdateDeliberation.ts(novo; padrãocreateMunicipalityUpdateRecord+ wrappers FormData viarunCampaignFormAction, retornandoCampaignFormActionState):assignUpdateResponsible(updateId, responsibleId): zod (lib/schemas/municipalityUpdate.tsganhamunicipalityUpdateDeliberationSchemas) →withPayloadTransaction→reloadCampaignActor→acquireTextAdvisoryLocks(payload, req, ['municipality-update:<id>'])→findByID(overrideAccess: false — read escopado, fail-closed) → valida elegibilidade do alvo (advisors do município + coordinator/candidate; não-liderança) →updatecomdata: { responsible },context: { mutationKind: 'assignResponsible' },overrideAccess: false.addUpdateComment(updateId, body): trim, vazio → erro, >4000 → erro → transaction + lock por doc →findByID(selectcomments,municipality) → append{ body }(hook carimba author/createdAt) → updatecontext: { mutationKind: 'appendComment' }.markUpdateResolved(updateId)/markUpdateReopened(updateId): transaction + lock por doc → update{ resolvedBy, resolvedAt }/{ resolvedBy: null, resolvedAt: null }, mutationKindresolve/reopen. Nenhuma das quatro valida estado em nível de action além do access (resolve em já-resolvido e reopen em aberto são idempotentes por construção).
- UI (Impeccable C — fluxo novo sobre feed existente; shape→craft→critique→polish):
src/utilities/municipality/municipalityUpdatePageData.ts:MunicipalityUpdateViewModelganharesponsibleId/responsibleName,resolvedAt/resolvedByName,comments: UpdateCommentViewModel[](authorName/createdAt/body) e o feed state ganhaeligibleStaff: {id, name, role}[]+capabilities: { canAssign, canComment, canResolve }(calculadas server-side com os predicados de access — o client não decide permissão; leader nunca chega aqui porque o read já falha na raiz).- Loader batchado (D8): 1 find
municipality(id+advisors) por município presente na página + 1 findcampaignUsercom o where or de elegibilidade. MunicipalityUpdateFeed.tsx→ card vira ilha clientMunicipalityUpdateDeliberationCard(mantém o layout atual: Badge polaridade/urgente/adversário + autor + data + body + voluntários/apoios) + bloco deliberativo: linha de estado ("Aberta" outline / "Resolvida" + "por X em " + card muted), select responsável (NativeSelect do ui kit) quandocanAssign, fio (comentários em ordem cronológica crescente + composer Textarea + botão "Comentar" quandocanComment), botões "Marcar como resolvido" / "Reabrir" quandocanResolve;useActionState+CampaignFormActionMessagenas três ações; enquantopending, desabilita só o controle disparador (otimismo barato = botão com spinner).- Superfícies: tab Updates do detalhe do município, feed global
/campanha/atualizacoeseMunicipalityDossierreusam o MESMO card (consistência grátis; dossier herda a ilha). WrappersupdateFormActions.tsganham as três actions FormData (assignUpdateResponsibleFormAction,addUpdateCommentFormAction,markUpdateResolvedFormAction/markUpdateReopenedFormAction).
pnpm generate:typesapós schema; semConsentnovo (deliberação é uso interno staff, não LGPD de cidadão).
Dados → forma (se aplicável)
- Fio em ordem cronológica crescente (leitura de conversa; composer no fim) — o feed de atualizações permanece decrescente (mais recente primeiro); a ordem do fio é o ponto de leitura, não competição com o feed.
- Estado no card: aberto = visual ativo atual + badge outline "Aberta" quando houver fio/responsável (sinal de "em deliberação"); resolvido = badge "Resolvido" (secondary) + corpo com opacidade reduzida + linha de autoria "Resolvido por X". Polimento fino (variants/opacidade) é barato — decidido na fase UI, semântica fixada aqui.
- "Atualização sem responsável ainda pode ter fio e resolvido": nenhum campo exige o outro; o card renderiza o bloco que existe.
Fases verificáveis
- Schema + migration (~0,3d): fields na collection →
pnpm migrate:create add-municipality-update-deliberation→ ajuste manual (FKs set null, tabelacommentsespelhandoactivity_updates, down simétrico) →pnpm migratelocal →pnpm generate:types→tsc --noEmit+ int specs existentes de schema (campaignMunicipalityUpdate.int.spec.ts, fixturecampaignFixtures.ts:715) verdes. Serializada: próxima migration após20260820_003426— nenhuma outra migration entra no PR. - Access + server actions (~0,4d): split
canUpdateMunicipalityUpdate/canDeleteMunicipalityUpdate, novos predicados D6, allowlist nobeforeChange+ derivação de comentários; as quatro actions com transaction/lock/elegibilidade; wrappers FormData. Unit specs dos predicados (por perfil: coordinator/candidate/advisor carteira/tudo/somente_leitura/leader/admin) + int novocampaignMunicipalityUpdateDeliberation.int.spec.ts(happy paths, leader bloqueado na raiz, advisor fora do escopo negado, elegibilidade do responsável, allowlist 403, append preserva itens). - VM + page data (~0,2d): campos novos no VM,
loadAssignableUpdateStaffbatchado, capabilities; int do page data (campaignMunicipalityUpdatePageData.int.spec.ts,campaignUpdatesFeedData.int.spec.ts) atualizados. - UI (~0,4d): ilha client no card (select/composer/botões/badges) nas três superfícies; verificação visual no browser (shape→craft); estados pending/erro.
- Gates + e2e (~0,3d): e2e afetados (
campaignMunicipalities.e2e.spec.ts,campaignUpdatesMobile.e2e.spec.ts) + novos (coordinator atribui → advisor comenta → resolve → badge; reopen; leader não vê card);pnpm gate:fast(incluicodebaseConventions.unit.spec.ts— sem re-espelhar where de escopo); push viapnpm push.
Rabbit holes / Não escopo (engenharia)
- Notificações (push OU badge interno) — cortado; gatilho de revisitação: infra pronta (
notifyMunicipalityUpdateCommented/...ResolvedsobrecreateCampaignNotifications+resolveMunicipalityStaffRecipientIds), ~0,1d depois se o produto pedir. - Editar/apagar comentário; mentions @; anexos; rich text; reações (exigem id estável por comentário fora do padrão array — D2-B seria o pré-requisito).
- Unificar com Demandas/Atividades; SLA/kanban; status intermediários (em andamento etc.) — o aceite tem exatamente um estado binário aberto/resolvido.
- Mudar
body/polarity/urgentvia deliberação (allowlist bloqueia; correção = nova atualização/comentário). - Ordenação/remoção de responsável com histórico (reassign sobrescreve; sem trilha de mudanças).
- Paginação do fio (arrays não paginam; limite de comentários: fora de escopo, revisitar se abusar).
- Adiado com gatilho (pós-simplify): a projeção deliberativa do feed global (
campaignUpdatesFeedData.ts) e a do feed do município (municipalityUpdatePageData.ts) têm donos distintos — 2 call sites com display divergente (avatar vs names) é intencional; unificar quando surgir o 3º consumidor ou um campo novo que force editar os dois (também absorve a coleta de IDs author+responsible+resolvedBy+comentários).
Riscos e mitigação
- Leader lockdown vazando: fio dentro do doc herda
resolveProfileScopedRead(leader → false na raiz) e as actions usamfindByIDcomoverrideAccess: false(fail-closed: quem não lê não comenta/atribui). Int spec pina leader negado nas quatro actions. - Deadlock entre locks: a action adquire
municipality-update:<id>(doc) ANTES do update; obeforeChangeadquiremunicipality-updates:<municipalityID>(município) DENTRO do update. Ordem consistente doc→município em todos os escritores (create/delete só tocam o lock de município) — sem inversão possível; documentar no hook. - Perda de append (read-modify-write): o lock por doc serializa o par read→update dentro da mesma transaction;
overrideAccess: falsemantém os filtros de escopo no read. - Testes que asserem fields exatos:
campaignMunicipalityUpdate.int.spec.ts:195usaarrayContaining(novos fields não quebram); fixturecampaignFixtures.ts:715cria com defaults — campos novos nullable/array vazio; verificarcodebaseConventions.unit.spec.ts:684(export paths do barrel). - Reintroduzir kind/tipo de sinal: nenhum enum novo; estado =
resolvedAt+ rels; UI usa apenas badges derivados. - Select de responsável com portfólio: o where de elegibilidade é server-side (advisors do município + unrestricted) — assessor nunca vê staff fora do município; int spec pina o conteúdo do select.
- Update admin-only preservado: admin path do
beforeChange/beforeValidateintacto fora do ramomutationKind; delete segue admin-only (split explícito).
Aceite de engenharia
- Aceite de produto da intenção ainda coberto: UM responsável atribuível (staff do município, nunca liderança); fio visível para quem lê atualizações do município; Resolvido + reabertura explícita; resolvida permanece legível com estado óbvio no card; leader não vê nem participa; modelo C87 intacto (sem kinds)
- Invariantes AGENTS/engineering-standards: sem
overrideAccess: truenovo; migration commitada serializada (topo da cadeia, próxima após20260820_003426);push: false; access por perfil emsrc/utilities/access/*reexportado no barrel; identificadores em inglês, labels/copy pt-BR;admin.group: 'Campanha'; "edit the owner" (collection existente + access module existente, sem twin) - Testes de domínio previstos: unit (predicados de acesso, allowlist, derivação de comentários) + int novo de deliberação + ints de page data atualizados + e2e afetados/novos; gates completos (
tsc, lint, format, knip, cycles, unit+int, build)
Self-score decision-quality
- Decisões caras têm rejeitadas? Sim — D1–D9 com A/B/C e justificativas; as duas fronteiras caras (onde vive o estado, como se escreve num doc admin-only) são as mais deliberadas (D1, D5). (1/1)
- Abordagem cabe no appetite? Sim — reuso integral de precedentes (
Activity.updates,canUpdateActivity,deriveActivityFields,acquireTextAdvisoryLocks,runCampaignFormAction); ~1,6d estimado em fases com cortes nomeados (notificações fora). (1/1) - Rabbit holes nomeados? Sim — 7 itens com gatilhos de revisitação (notificações, edição de comentário). (1/1)
- Depth check: reusa shells/helpers existentes? Sim — collection/access/VM/card são os donos atuais (edit-the-owner); novos símbolos mínimos (1 módulo de actions, 1 card client); sem provider/contexto novo; sem endpoint novo. (1/1)
- Intenção permanece satisfeita? Sim — outcome do aceite mapeado 1:1 em fases; nenhuma decisão de engenharia reescreve regra de produto (atribuição/resolvido só unrestricted; comentar = criar; leader fora). (1/1)
Self-score: 5/5 (gate ≥4).