teqo-backup/docs/plans/liderancas-coluna-municipios.md
2026-08-04 00:22:19 -03:00

119 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Coluna de lideranças na tabela de municípios
Status: rascunho
Atualizado em: 2026-08-04
Issue: #359
Priority: P2
Model: composer-2.5
Impeccable: B — encaixe em `MunicipalityList` (`/campanha/municipios`), coluna nova ao lado de Assessores; sem rota nova de UI
Canvas UI: N/A — sem UI (o canvas da skill `canvas` não está disponível; a intenção visual é um espelho da coluna "Assessores" já existente — chips + Popover + Command, mesma máquina de interação)
Appetite: ~0,5–1 dia eng; uma coluna editável na tabela de municípios
Responsável: —
## Intenção
Hoje, na tabela de municípios (`/campanha/municipios`), a equipe de campanha vê e edita os assessores designados inline (coluna "Assessores"). Mas as **lideranças** vinculadas a cada município só são visíveis entrando na ficha individual da liderança — não há uma coluna que mostre "quais lideranças atuam neste município" na lista. Isso obriga a navegar para a lista de lideranças (`/campanha/liderancas`) ou abrir o detalhe do município para cruzar essa informação.
O pedido é espelhar a coluna "Assessores" com uma coluna "Lideranças": mesma affordance de edição inline (chips + typeahead + criar inline), mesma máquina de interação, mesma visibilidade por papel.
## Persona e fluxo
- **Persona / contexto:** Staff da campanha (coordenação, assessores) na mesa de operações, navegando a lista de municípios para decidir alocação, priorização e próximos passos.
- **Job principal:** Ver e editar quais lideranças estão vinculadas a cada município — diretamente na lista, sem sair da tabela.
- **Fluxo desejado:**
1. Staff abre `/campanha/municipios` e vê a coluna "Lideranças" ao lado de "Assessores".
2. Cada célula mostra chips com os nomes das lideranças vinculadas ao município (ou "Nenhuma" se vazio).
3. Staff clica na célula → abre Popover com typeahead (busca por nome do contato) + lista de chips removíveis.
4. Staff digita para buscar uma liderança existente → seleciona → chip aparece otimista (antes do servidor confirmar).
5. Se a liderança não existe ainda, staff pode **criar inline** (abre mini-form com nome do contato + telefone; cria no servidor como nova `leadership` vinculada a este município; erro faz rollback).
6. Staff remove um chip → ele some otimista. Se o servidor falhar, volta + toast de erro.
7. Lideranças adicionadas/removidas inline são refletidas imediatamente na lista (sem recarregar a página).
- **Anti-goals de produto:**
- Não é um formulário multi-campo de edição de liderança (status, exclusividade, organizações, dobradinhas) — isso continua na ficha `/campanha/liderancas/[id]`.
- Não é uma segunda lista de lideranças embutida na tabela de municípios — é uma coluna de vínculo rápido, igual a de assessores.
- Líder (papel `leader`) não vê esta coluna — lockdown permanece.
### Esboço de fluxo
```text
Lista de municípios (staff)
│
├─ Coluna "Lideranças"
│ ├─ Célula fechada: chips com nome da liderança (ou "Nenhuma")
│ └─ Célula aberta (Popover):
│ ├─ Typeahead (Command): busca por nome do contato
│ ├─ Chips removíveis: cada liderança vinculada
│ └─ "Criar liderança" inline (se não encontrada na busca)
│ └─ Mini-form: nome + telefone → cria → vincula
│
└─ Mutação otimista + rollback em erro (mesmo padrão de assessores)
```
## Objetivo e aceite
- Coluna "Lideranças" aparece na tabela de municípios para staff (coordenação + assessores), ao lado ou próxima da coluna "Assessores".
- Célula mostra chips com o nome do contato de cada liderança vinculada ao município. Município sem lideranças mostra "Nenhuma" (ou badge equivalente ao `MissingAdvisorBadge` quando prioritário).
- Staff pode adicionar/remover lideranças inline: typeahead busca por nome do contato (via `contact.name`), seleção otimista, rollback em erro de rede/servidor.
- Staff pode criar uma nova liderança inline vinculada ao município atual, sem sair da tabela.
- Assessor só vê e edita lideranças dos municípios que administra (mesmo escopo de `canReadLeadership` + filtro `advisors`).
- Coordenação e candidato veem e editam todas.
- Líder (`leader`) não vê a coluna (lockdown).
- **Guardrails:** sem migration fora do padrão, sem collection nova, sem alterar o schema de `leadership`; `Consent` permanece fail-closed para lideranças novas criadas inline (mesmo comportamento de criar liderança pelo form completo).
## Dados (intenção)
- **Vou apresentar dados?** Não — coluna qualitativa de vínculo. Sem métrica, contagem, série ou ranking.
- **Decisões desbloqueadas:** Staff decide "quem está conosco neste município" diretamente na lista, sem abrir ficha externa.
- **Forma:** _adiada ao plano de implementação_ — chips com nome do contato, igual a assessores.
## Direção no codebase (hipótese)
- **Áreas prováveis:**
- `src/collections/Municipality.ts` — novo field `leadership` (relationship → `leadership`, `hasMany`), mirror de `advisors` (linhas 298–310)
- `src/components/campaign/municipality/MunicipalityList.tsx` — nova coluna `leaderships` na definição de `municipalityListColumns`
- `src/components/campaign/municipality/MunicipalityListLeadershipsControl.tsx` — novo componente (espelho de `MunicipalityListAdvisorsControl.tsx`)
- `src/app/(campaign)/campanha/(app)/municipios/leaderships/route.ts` + `types.ts` — endpoint JSON de mutação (espelho de `advisors/`)
- `src/utilities/municipality/municipalityViewModels.ts` — estender `MunicipalityListViewModel` com `leadershipIDs` e `LeadershipSummary`
- `src/utilities/access/municipalities.ts` — funções de access (espelho de `canAssignMunicipalityAdvisors` / `canManageMunicipalityAdvisors`)
- `src/utilities/access/leaderships.ts` — já existe `canReadLeadership`; verificar se precisa de `canManageLeadershipMembership`
- **Precedente a olhar:**
- `MunicipalityListAdvisorsControl.tsx` — a máquina completa de interação (chips + Popover + Command + delta otimista + undo + aria-live)
- `src/app/(campaign)/campanha/(app)/municipios/advisors/route.ts` — contrato do endpoint JSON
- B154 (`docs/plans/criar-assessor-inline-municipio.md` se existir) — criar inline no popover
- `src/utilities/municipality/municipalityViewModels.ts` — `EligibleAdvisorOption`, `MunicipalityAdvisorSummary` como padrão para `EligibleLeadershipOption`, `MunicipalityLeadershipSummary`
- `RelationChipCell` genérico (`src/components/campaign/shared/RelationChipCell.tsx`) — se já cobre o caso de relação many-to-many com typeahead + undo, o controle de lideranças pode ser um wrapper fino em vez de duplicar a máquina
- **Risco de acoplamento:**
- Leader lockdown: `isCampaignStaff` / `isCoordinator` já controlam a visibilidade da coluna de assessores; a de lideranças deve usar o mesmo gate.
- Relação bidirecional: `leadership.municipalities` e `municipality.leaderships` precisam manter consistência — adicionar uma liderança ao município deve ser visível na lista de lideranças também.
- Migração: o novo field `leadership` no `Municipality` precisa de uma migration; se houver lideranças já vinculadas (via `leadership.municipalities`), a migration de reconciliação deve popular `municipality.leaderships` a partir dos dados existentes para não quebrar a relação reversa.
## Dependências
- Nenhuma (item auto-contido)
## Fora de escopo
- Editar campos da liderança (status, exclusividade, organizações, dobradinhas) inline — isso continua na ficha `/campanha/liderancas/[id]`.
- Coluna de lideranças em outras listas (dobradinhas, organizações) — só a tabela de municípios neste item.
- Criar contato (`Contact`) inline — criar uma liderança inline exige um `Contact` existente ou a criação de um novo `Contact` no mesmo fluxo (a decidir na implementação; se o mini-form inline criar `Contact` + `Leadership` em transação, é aceitável e segue o padrão de criar assessor do B154).
## Rabbit holes de produto
- **Sincronia bidirecional `leadership.municipalities` ↔ `municipality.leaderships`.** Se alguém "só adicionar o campo no Payload", as duas pontas da relação divergem (editar a liderança via `/liderancas/[id]` não atualiza `municipality.leaderships`, e vice-versa). **Corte neste item:** definir UMA ponta canônica de escrita (provável: `municipality.leaderships` como source of truth, com hook que sincroniza `leadership.municipalities`; ou manter `leadership.municipalities` como canônica e a coluna do município ser só leitura/atalho). A decisão é de implementação, mas o plano de intenção registra o risco.
- **Performance com muitas lideranças.** Um município pode ter dezenas de lideranças; carregar todos os nomes para todas as 435 linhas da tabela pode ser pesado. **Corte neste item:** seguir o mesmo padrão de assessores (batch de names por ID, carregado uma vez no server component). Se for lento, paginar ou virtualizar — mas não neste item.
## Questões em aberto (produto)
- ~~A coluna substitui ou complementa a seção de lideranças no detalhe do município (B152)?~~ **Resolvido:** A — a coluna é atalho de edição rápida; o detalhe do município continua mostrando lideranças com mais informação.
- ~~Criar liderança inline exige criar `Contact` junto?~~ **Resolvido:** B — mini-form cria `Contact` + `Leadership` no mesmo passo (igual B154).
- ~~A coluna deve aparecer antes ou depois de "Assessores"?~~ **Resolvido:** depois de "Assessores".
- ~~Sincronia bidirecional `leadership.municipalities` ↔ `municipality.leaderships`?~~ **Resolvido:** relação verdadeiramente bidirecional — editar a coluna do município atualiza `leadership.municipalities` também.
## Referências
- `src/collections/Municipality.ts` — field `advisors` (L298–310): padrão a espelhar
- `src/components/campaign/municipality/MunicipalityListAdvisorsControl.tsx` — máquina de interação completa
- `src/app/(campaign)/campanha/(app)/municipios/advisors/route.ts` — contrato do endpoint JSON
- `src/components/campaign/shared/RelationChipCell.tsx` — se aplicável como wrapper genérico
- `src/collections/Leadership.ts` — coleção de lideranças, field `municipalities` (relação reversa)
- `AGENTS.md` — "Campaign Municípios model", "Campaign auth" (lockdown de líder)