teqo/docs/plans/dobradinhas-coluna-municipios.md

142 lines
14 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 dobradinhas na lista de municípios (+ criação inline)
Status: rascunho
Atualizado em: 2026-08-04
Issue: #362
Priority: P1
Model: composer-2.5
Impeccable: B — encaixe no popover existente de Dobradinhas em `/campanha/municipios`
Canvas UI: /Users/francisco.solla/.cursor/projects/teqo/canvases/plan-b157-ui-draft.canvas.tsx
Appetite: ~1 dia eng; uma coluna nova na tabela + popover com combobox + criação inline de StateDeputy
Responsável: —
## Intenção
O coordenador e o candidato planejam a campanha **percorrendo a lista de municípios** — é o ponto de decisão da mesa. Depois de ver assessores atribuídos e tendência política, a próxima pergunta natural é: **"este município já tem dobradinha? Com quem?"**.
Hoje, para responder isso, é preciso sair da lista, ir para `/campanha/dobradinhas`, filtrar, e voltar. E se a dobradinha ainda **não existe** no sistema — porque o deputado estadual acabou de ser anunciado na reunião — o coordenador precisa ir ao Payload admin (`/admin`) ou ao menu de dobradinhas para criá-la antes de poder vinculá-la. Isso interrompe o fluxo da reunião.
A coluna de **Assessores** (B27 + B154) já provou que o caminho certo é **ver e editar sem sair da lista**. Este item replica esse padrão para dobradinhas:
- **Ver** as dobradinhas de cada município como chips com nome + partido, linkados para a ficha `/campanha/dobradinhas/<slug>`.
- **Adicionar/remover** dobradinhas via popover com combobox (busca por nome/partido, chip com × para remover, auto-save por delta).
- **Criar dobradinha nova no ato**, sem sair do popover — só nome (+ partido opcional), igual ao B154 fez para assessores.
## Persona e fluxo
- **Persona / contexto:** coordenador (ou candidato) em reunião de planejamento, percorrendo `/campanha/municipios` no desktop/tablet, verificando o estado de cada município e preenchendo o que falta.
- **Job principal:** ver e gerenciar as dobradinhas (deputados estaduais) vinculadas a um município, **sem interromper o fluxo da lista**, incluindo criar uma dobradinha nova se ela ainda não existir no sistema.
- **Fluxo desejado:**
1. Na lista de municípios, o coordenador vê uma coluna **"Dobradinhas"** (entre Assessores e Tendência), com chips mostrando nome + partido (ex.: "Fulaninho (PT)"), cada um linkando para `/campanha/dobradinhas/<slug>`.
2. Clica em um chip ou na área vazia da célula → abre popover com:
- Lista de chips das dobradinhas já atribuídas (removíveis via ×).
- Campo de busca (Command) para adicionar dobradinhas existentes, filtrando por nome e partido.
- Se a busca não casa com nenhuma dobradinha existente: **primeiro item = "+ Criar dobradinha '[texto digitado]'"**.
3. Seleciona uma existente → chip adicionado, gravação automática.
4. Remove via × no chip → gravação automática.
5. Escolhe "Criar dobradinha" → a dobradinha é criada com o nome digitado (+ partido se informado entre parênteses ou em campo auxiliar) e **automaticamente atribuída** ao município.
6. Fecha o popover e continua — sem navegação, sem reload da página.
- **Anti-goals de produto:**
- **Não** é um formulário completo de StateDeputy com notas, histórico e lista de municípios/lideranças vinculadas → `/campanha/dobradinhas/<slug>`.
- **Não** permite editar nome ou partido de uma dobradinha existente inline (nome é imutável, partido se edita na ficha).
- **Não** resolve duplicatas por similaridade ("Fulano" vs "Fulano de Tal") — o coordenador verifica.
- **Não** oferece filtro por dobradinha no header da lista neste item (gatilho para o B29).
- **Não** está disponível para assessores ou líderes — só coordenador/candidato (`isCampaignUnrestricted`), mesmo escopo do popover de assessores.
### Esboço de fluxo
```text
[Coordenador na lista de municípios]
→ vê coluna "Dobradinhas" com chips ou "—" (vazio)
→ clica na célula → popover abre
→ vê chips das dobradinhas atuais (removíveis) + campo "Buscar dobradinha…"
→ digita "Fulano"
→ resultados: "Fulaninho (PT)" ✓, "Fulana (PSB)" ✓
→ OU: se não casa com nenhuma → "+ Criar dobradinha 'Fulano'"
→ escolhe existente: chip adicionado, grava, busca limpa
→ escolhe criar: dobradinha criada + atribuída, chip aparece
→ remove via ×: chip some, grava
→ fecha popover, continua a reunião
```
## Objetivo e aceite
- Na lista `/campanha/municipios` (staff view), existe uma coluna **"Dobradinhas"** entre "Assessores" e "Tendência", visível apenas para coordenador/candidato.
- A coluna mostra chips com nome + partido da dobradinha (ex.: "Fulaninho (PT)"), cada um linkando para `/campanha/dobradinhas/<slug>`. Célula vazia mostra "—".
- Clicar na célula abre um popover com combobox que permite buscar, adicionar e remover dobradinhas do município — mesmo padrão de interação do popover de assessores (B27).
- Cada adição/remoção grava automaticamente (auto-save por delta), com estado otimista e rollback + toast em caso de erro.
- Se a busca não casa com nenhuma dobradinha existente, o primeiro item é **"+ Criar dobradinha '[texto]'"** — mesmo padrão do B154.
- Ao criar, o StateDeputy é criado com `name` = texto digitado, `party` = opcional (extraído de um campo auxiliar ou sintaxe `Nome (PARTIDO)`), e automaticamente vinculado ao município atual.
- O assessor (`advisor` role) **não vê** esta coluna — municípios na carteira já são visíveis, mas o popover de escrita é restrito a `isCampaignUnrestricted` (acesso que o assessor não tem).
- O líder (`leader` role) **não vê** esta coluna — líder nem acessa `/campanha/municipios`.
- `StateDeputy.name` é unique — se o nome digitado já existir, o endpoint retorna erro e a UI mostra o toast.
## Dados (intenção)
- **Vou apresentar dados?** Não. `Dados: N/A` — o item é affordance de **escrita** sobre `municipality.stateDeputies` via criação/consulta de `StateDeputy`; não introduz métrica, série, ranking ou mapa novo.
- **Decisões desbloqueadas:** coordenador decide quais dobradinhas operam em cada município **no momento da reunião**, sem sair da lista nem ir ao admin para criar o deputado.
## Direção no codebase (hipótese)
- **Áreas prováveis:**
- `src/utilities/municipality/municipalityViewModels.ts` — `MunicipalityListViewModel` ganha `stateDeputyIDs: number[]`; `municipalityListSelect` ganha `stateDeputies: true`.
- `src/utilities/municipality/municipalityPageData.ts` — `loadMunicipalityListPageBundle` carrega os summaries de state deputies (mesmo padrão de `advisorSummaries` na `page.tsx`).
- `src/app/(campaign)/campanha/(app)/municipios/page.tsx` — carrega `loadStateDeputyOptions` (catálogo) e `loadStateDeputySummaries` (nomes dos atribuídos), passa para o componente de lista.
- `src/components/campaign/municipality/MunicipalityList.tsx` — nova coluna `stateDeputies` no array `municipalityListColumns` (staff view, após `advisors`).
- `src/components/campaign/municipality/MunicipalityListStateDeputiesControl.tsx` (novo) — ilha cliente com chips + Popover + Command + criação inline, espelhando `MunicipalityListAdvisorsControl`.
- `src/app/(campaign)/campanha/(app)/municipios/state-deputies/route.ts` (novo) — endpoint `POST` para toggle de membership + criação inline de StateDeputy (campo opcional `name` + `party`).
- `src/app/(campaign)/campanha/actions/municipality.ts` — nova action `setMunicipalityStateDeputyMembershipRecord` com transação, lock e access check.
- `src/lib/schemas/municipality.ts` — schema zod para o input do endpoint.
- `src/utilities/municipality/municipalityLabels.ts` — `MunicipalityListColumnId` ganha `'stateDeputies'`; `municipalityColumnLabels` e `municipalityColumnDescriptions` ganham entradas.
- **Precedente a olhar:**
- B154 (`criar-assessor-inline-popover-municipios.md`) — criação inline de campaignUser no popover; mesmo padrão de endpoint sobrecarregado com `name`.
- B27 (`combobox-assessores-lista-municipios.md`) — popover de assessores com combobox, chips, auto-save, estado otimista.
- B31 (`dobradinhas-lista-liderancas.md`) — coluna de dobradinhas na lista de lideranças; chips com nome + partido, `loadStateDeputySummaries`.
- `src/collections/StateDeputy.ts` — a collection já existe com `name` (unique), `slug`, `party`, `notes`.
- `src/utilities/stateDeputyData.ts` — `loadStateDeputySummaries`, `StateDeputySummary`.
- **Risco de acoplamento:**
- A mutation de `municipality.stateDeputies` deve respeitar o access control existente (`canManageCampaignStaffField` — restrito a `isCampaignUnrestricted`). O assessor **não** pode escrever nessa relação.
- O `MunicipalityListViewModel` já é consumido por vários componentes — adicionar `stateDeputyIDs` não quebra consumidores existentes (campo novo, opcional para leitura).
- A criação de StateDeputy inline usa `payload.create` com `overrideAccess: true` (ou `canCreateStateDeputy` verifica `isCampaignUnrestricted`) — precisa validar se o ator tem permissão.
## Dependências
- **Nenhuma dura.** Reusa B27 (padrão de popover), B154 (criação inline), B31 (chips de dobradinha), `StateDeputy` collection (já existe), `loadStateDeputySummaries` (já existe).
- **Suave:** se o B29 (filtro de dobradinha no header) quiser usar a nova coluna como gatilho, a faceta `stateDeputyIDs` nos filter facets será necessária — mas é escopo do B29, não deste item.
## Fora de escopo
- Filtro por dobradinha no header da lista → B29 (já registrado como gatilho).
- Ordenação da lista por dobradinha (sort key `stateDeputies`) → item futuro se houver decisão de produto.
- Editar nome ou partido da dobradinha inline → `/campanha/dobradinhas/<slug>`.
- Criar dobradinha com `notes` inline → `/campanha/dobradinhas/<slug>`.
- Coluna visível para assessor → restrito a `isCampaignUnrestricted`; assessor lê `municipality.stateDeputies` na ficha do município (`MunicipalityStrategyCard`), não na lista.
- Evitar duplicatas por similaridade (ex.: "Fulano" vs "Fulano de Tal") — `StateDeputy.name` é unique, mas similaridade não é detectada.
- Sincronizar a faceta do filtro `?stateDeputy=` sem recarregar — mesmo contrato de B24/B27 (reconcilia na próxima navegação).
## Rabbit holes de produto
- **"Criar dobradinha já com partido, notas e lista de municípios".** Se alguém "só completar" o formulário de criação, o popover vira um cadastro completo de StateDeputy e o appetite explode. **Corte neste item:** só nome + partido (opcional); o resto fica para `/campanha/dobradinhas/<slug>`.
- **"E se o nome já existe?"** `StateDeputy.name` é unique — o endpoint retorna erro e a UI mostra toast. Mas "Fulano" vs "Fulano de Tal" não são detectados como duplicata. **Corte neste item:** sem dedup por similaridade; o coordenador verifica.
- **"Coluna para assessor também".** O assessor vê seus municípios na lista, mas não pode escrever em `stateDeputies` (campo restrito a `isCampaignUnrestricted`). Mostrar a coluna como read-only para assessor dobra o escopo (precisa de `cellTooltip`, variant sem popover, etc.). **Corte neste item:** coluna só para `isCampaignUnrestricted`.
## Questões em aberto (produto)
- **Party inline: como o coordenador informa o partido?** **Opções:** A) campo auxiliar no popover (input "Partido" abaixo da busca, preenchido antes de clicar "Criar") | B) sintaxe `Nome (PARTIDO)` no campo de busca — "Fulano (PT)" cria nome="Fulano", party="PT" | C) sem partido na criação inline, sempre null. **Recomendação:** **B** — mesma sintaxe que a busca já suporta (filtro por partido entre parênteses), natural para a mesa que fala "Fulano do PT", e não adiciona um campo extra no popover. O parser extrai `(PARTIDO)` do fim da string; se não houver parênteses, party fica `null`. _(assumido — validar com produto)_
- **Posição da coluna: entre Assessores e Tendência?** **Opções:** A) após Assessores (grupo "rede" — assessor + dobradinha + tendência) | B) após Votação 2022/Classe (grupo "diagnóstico") | C) após Meta (final, grupo "conta"). **Recomendação:** **A** — assessor e dobradinha são as duas relações de "quem" no município (quem cuida + quem dobra), ficam juntas, e a dobradinha é uma pergunta que surge naturalmente depois de ver o assessor. _(assumido — validar com produto)_
- **Chips com partido ou só nome?** **Opções:** A) só nome na célula, partido no tooltip/busca | B) nome + partido sempre ("Fulano (PT)"). **Recomendação:** **B** — mesmo padrão do B31 (lideranças); a coluna "Dobradinhas" é mais estreita que "Assessores" (menos chips por linha), e o partido é a informação que desambigua dobradinhas de mesmo primeiro nome.
## Referências
- GitHub Issue #352 (B154 — criar assessor inline)
- GitHub Issue #56 (A6 — dobradinhas potenciais)
- `docs/plans/criar-assessor-inline-popover-municipios.md` — plano do B154 (precedente direto)
- `docs/plans/combobox-assessores-lista-municipios.md` — plano do B27 (popover de assessores)
- `docs/plans/dobradinhas-lista-liderancas.md` — plano do B31 (coluna de dobradinhas em lideranças)
- `src/components/campaign/municipality/MunicipalityListAdvisorsControl.tsx` — popover de assessores (precedente de implementação)
- `src/collections/StateDeputy.ts` — collection StateDeputy (name unique, slug, party)
- `src/utilities/stateDeputyData.ts` — `loadStateDeputySummaries`, `StateDeputySummary`
- `src/utilities/municipality/municipalityViewModels.ts` — `MunicipalityListViewModel`, `municipalityListSelect`
- `src/utilities/municipality/municipalityPageData.ts` — `loadMunicipalityListPageBundle`
- `src/app/(campaign)/campanha/(app)/municipios/page.tsx` — página da lista
- `src/app/(campaign)/campanha/(app)/municipios/advisors/route.ts` — endpoint de advisors (precedente)