# Plano — Portal De Paula (Protótipo Interno)

## Visão geral

Reformulação do portal interno da De Paula Contadores. O pedido original foi
"estruturar um protótipo visual, mas funcional, para avaliarmos e
estruturarmos melhor o frontend do portal" — reaproveitando a essência do
portal atual (referência: capturas de tela do sistema em produção, tema
escuro roxo/dourado, sidebar com dezenas de seções, busca de aplicações,
cards de atalho, login com logo circular), não recriando do zero.

Decisões de arquitetura tomadas no início e válidas até a rodada 13:

- **Stack: HTML + CSS + JS puro**, sem framework, sem build step, sem
  dependência externa além das fontes do sistema.
- **Sem backend**: todo o estado (sessão, usuários, perfis de acesso,
  favoritos, widgets, compromissos, tema) vivia no `localStorage` do
  navegador.
- **Visual**: modernizar a estrutura existente (sidebar + topbar + busca +
  cards + login), não clonar pixel a pixel as capturas de referência.

Isso valeu como protótipo de validação de fluxo/desenho. Na rodada 13 o
usuário definiu a stack real de backend e pediu a migração completa — ver
essa seção para a arquitetura atual. Este documento foca no histórico de
decisões, no que foi construído em cada rodada e no que ainda está em
aberto; para arquitetura técnica atual (páginas, API, ordem de scripts,
modelo de permissões, como o CSS está dividido entre arquivos), ver
`CLAUDE.md`.

## Cronologia de construção

### 1. Protótipo inicial — login + shell
Tela de login (logo, usuário/senha, "esqueceu senha" apontando para
Integração e Inovação) e o shell principal: sidebar com as 14 seções do
documento original de arquitetura, topbar com hamburger/"Acessar
Ramais"/notificações, busca de aplicações e uma grade de cards de atalho
fixos (Links, OS, Ramais, Relatórios, Calendário, Solicitações). Tema
claro/escuro com toggle salvo em `localStorage`. Um modal de "simular perfil
de acesso" (persona) deixava escolher entre as 7 personas do documento
original para ver o menu mudar — mecanismo **removido depois** (ver item 4).

### 2. Perfis de Acesso
Tela de administração (`perfis-acesso.html`) com lista + edição de perfis:
Código, Nome, árvore de permissões por módulo, aba "Usuários do Escritório".
Criado um perfil especial **"Integração e Inovação"**, com acesso total e
uma capacidade exclusiva — `gerenciaPermissoes` — que também gate-ia o
acesso à própria tela de Perfis de Acesso.

### 3. Usuários
Tela de cadastro de contas (`usuarios.html`), movida para dentro do grupo
"Administração" no menu (junto de Perfis de Acesso), com a mesma restrição:
só quem tem `gerenciaPermissoes` acessa e pode cadastrar/editar/excluir
usuários.

### 4. Login real (fim do simulador de persona)
O usuário pediu para poder testar de verdade o cadastro de acessos —
"podemos testar na realidade como irá funcionar". Isso trocou o mecanismo
inteiro:

- Login parou de aceitar qualquer senha; passou a validar contra contas
  reais em `pid_users_v1`/`v2` (`assets/js/users.js`).
- Duas contas de demonstração criadas: `gabriel`/`gabriel` (perfil
  Integração e Inovação) e `bruno`/`bruno` (sem perfil vinculado, para
  testar o estado "sem acesso").
- O modal de simulação de persona foi **removido**; a visibilidade do menu
  passou a vir do perfil de acesso de verdade vinculado ao usuário logado
  (`access.js` → `pidResolveAccess`).
- Cada um dos 7 perfis do documento original ganhou um registro real em
  Perfis de Acesso (Diretoria, Departamento Pessoal, Gerencial, Legalização,
  Fisco/Contábil, Financeiro, Protocolo), mais Integração e Inovação (8 ao
  todo).

### 5. Múltiplos perfis por usuário
Pedido explícito: "algumas pessoas podem ter acesso ao perfil financeiro e
fisco/contábil". `profileCodigo` (número único) virou `profileCodigos`
(array) em `pid_users`; a resolução de acesso em `access.js` passou a fazer
**união** entre todos os perfis vinculados a um usuário — uma seção aparece
se qualquer um dos perfis do usuário conceder acesso a ela.

### 6. Bugs encontrados e corrigidos
Três bugs reais surgiram e foram corrigidos durante o uso:

- **`users-admin.js` ficou preso na assinatura antiga** de
  `pidResolveAccess()` (`{ profile }` em vez de `{ profiles }`) depois da
  migração do item 5 — a tela de Usuários redirecionava sempre de volta
  pro Principal antes de renderizar, dando a impressão de "não abre".
  Corrigido ajustando a desestruturação.
- **CSS sobrescrevendo o atributo `hidden`**: componentes que definem seu
  próprio `display` (`.no-access`, `.notif-badge`, `.app-card`) ignoravam o
  `hidden` do JS, porque uma regra de autor com `display` explícito vence a
  regra padrão do navegador `[hidden]{display:none}` mesmo com
  especificidade igual. A mensagem de "sem perfil vinculado" continuava
  aparecendo por cima do dashboard normal mesmo com o perfil já vinculado.
  Corrigido com uma regra global em `base.css`:
  `[hidden] { display: none !important; }` — resolveu esse caso e mais dois
  latentes (badge de notificação, filtro de busca nos cards).
- **Submenus recolhidos continuavam clicáveis/focáveis**: o accordion do
  sidebar só usava `max-height:0` + `overflow:hidden` para esconder, o que
  não impede clique nem navegação por Tab. Corrigido adicionando
  `visibility:hidden` + `pointer-events:none` ao estado fechado.

### 7. Permissão granular por aplicação
A árvore de permissões de cada módulo mostrava ações genéricas
(Visualizar/Incluir/Editar/Excluir), sem relação com o conteúdo real do
menu. Trocado por uma lista das aplicações reais de cada seção (ex.: em
Portais, os checkboxes viraram "Portal do Cliente" e "Portal Fiscal") —
e isso passou a **funcionar de verdade**: desmarcar uma aplicação esconde
só aquele item do sidebar (`data-app` + `access.js`), não o módulo inteiro.
Nesta mesma rodada, o campo **Ambiente** (Escritório/Empresa) foi removido
do cadastro de perfil — "trabalharemos como portal interno, sem mais de um
ambiente".

### 8. Favoritos
Pedido: "toda aplicação deve poder ser favoritada, para adicionar na tela
inicial". Implementado sem precisar marcar cada item do menu manualmente —
`favorites.js` deriva um ID estável a partir do próprio texto/estrutura do
sidebar (ver `CLAUDE.md` → "Favoritos") e injeta uma estrela ao lado de
cada aplicação. A tela Principal deixou de ter cards fixos (Links, OS,
Ramais...) e passou a ser inteiramente dirigida pelos favoritos de cada
usuário — o antigo `cards.js` foi removido.

### 9. Calendário De Paula → link externo
"O Calendário De Paula deve ser um redirecionador" para
`https://depaula-tvcorporativa.lovable.app/calendario` (abre em nova aba).
O calendário interno mockado (`calendario.html` + `calendar.js`, com
eventos fixos por setor) foi removido a pedido do usuário depois da troca —
não recriar sem confirmar.

### 10. Calendário Individual + Widgets
Pedido novo, em duas partes:

- **Calendário Individual** (`calendario-individual.html`): agenda pessoal
  de cada colaborador (seção base, disponível a todo perfil). Cada um cria
  compromissos e pode marcá-los como visíveis para todos que compartilham
  pelo menos um perfil de acesso em comum (`sharedWithProfile` +
  `pidEventsVisibleTo` em `events.js`) — colegas só visualizam, não editam
  nem excluem compromisso alheio.
- **Widgets** na tela Principal: área "Widgets" com botão "Adicionar
  Widget" (seletor, no estilo Asana) — pensada para crescer além de um
  único tipo. Hoje só existe o widget de Calendário Individual (próximos 5
  compromissos), mas o registro `PID_WIDGET_TYPES` já está estruturado para
  novos tipos sem refazer a área de adicionar/remover.

### 11. Horário e edição no Calendário Individual
Compromissos ganharam campo de horário (ordenados por horário dentro do
dia) e passaram a ser editáveis depois de criados — clicar num compromisso
próprio abre o mesmo modal preenchido, com um botão "Excluir" adicional,
em vez de excluir direto ao clicar.

### 12. Menu de conta
O chip do canto superior direito mostrava o **perfil/departamento**
("Departamento Pessoal" etc.) — trocado para mostrar o **usuário logado**
(nome + ícone de pessoa). Clicar abre um menu com nome + perfis vinculados,
"Alterar senha" (modal com senha atual/nova/confirmação, validada contra
`pid_users`) e, só para quem tem `gerenciaPermissoes`, um atalho para
Perfis de Acesso (antes era o clique direto no chip que levava pra lá).
Nesta rodada os estilos de campo de modal (`.modal-field`, `.modal-actions`
etc.), que só existiam em `calendario.css`, foram generalizados para
`components.css`, já que agora mais de uma tela precisa deles.

### 13. Migração para backend Django + PostgreSQL

O usuário definiu a stack real do backend: **Python 3.13 + Django 6.0 +
PostgreSQL 14**, e pediu três coisas na mesma rodada:

1. Construir esse backend completo (models, API REST, banco Postgres) —
   não só adaptar o frontend a um contrato assumido.
2. Migrar para o banco **tudo** que hoje existia no `localStorage`, exceto
   a preferência de tema: usuários, perfis de acesso, favoritos, widgets e
   compromissos do Calendário Individual.
3. Autenticação via **sessão/cookie do Django** (decisão explícita, não
   token/JWT) — o que levou à escolha de servir o frontend estático pelo
   próprio Django (mesma origem), evitando complicação de cookie de sessão
   cross-origin.

O que mudou estruturalmente:

- Projeto Django novo, inicialmente em `Portal/backend/` (`config/` + app
  único `portal_api/`) — reorganizado na rodada 14 para o padrão de pastas
  de um projeto Django de verdade. Ver `CLAUDE.md` → "Arquitetura" para o
  detalhamento de cada arquivo e a tabela de endpoints.
- Model de usuário customizado (`Usuario`, estendendo `AbstractUser`) desde
  o início — trocar depois de criado o projeto é doloroso.
- Senha passou a usar hashing nativo do Django (`set_password`/
  `check_password`) — antes era texto puro no protótipo; melhoria de
  segurança real, não só troca de armazenamento.
- Catálogo de módulos/aplicações do menu (antes `PID_MODULES`/
  `PID_MODULE_APPS` hardcoded em `profiles.js`) virou `portal_api/catalogo.py`,
  fonte única da verdade, exposto só leitura via `GET /api/catalogo/`.
- A união de permissões entre múltiplos perfis de um usuário (rodada 5),
  antes calculada no cliente (`access.js` → `pidResolveAccess`/
  `pidApplyAccessVisibility`), passou a ser calculada uma única vez no
  servidor (`permissoes_efetivas()` em `views.py`) e consumida pronta via
  `GET /api/me/`.
- A lógica de "quem vê qual compromisso" do Calendário Individual (rodada
  10 — `pidEventsVisibleTo`) também migrou pro backend
  (`CompromissoAgendaViewSet.get_queryset`).
- Todo o frontend que lia/escrevia `localStorage` foi reescrito para
  `async`/`fetch` contra a API (`assets/js/api.js`, hoje `static/js/api.js`
  — ver rodada 14 — é o módulo novo), mantendo a mesma estrutura de
  arquivos e nomes de função sempre que possível para minimizar o tamanho
  do diff.
- `assets/js/users.js` (armazenamento local de usuários) foi **removido**
  — usuários agora só existem no banco, via `/api/usuarios/`.

**Limitação do ambiente onde essa rodada foi feita**: só havia Python 3.8 e
nenhum servidor PostgreSQL disponíveis, então não foi possível rodar
`makemigrations`/`migrate`/`runserver` nem testar o fluxo ponta a ponta
durante a implementação — o código foi revisado estaticamente com cuidado
(sintaxe, convenções do DRF, coerência entre serializers/views/frontend).
Rodar de verdade — incluindo gerar a migração inicial — fica para o
ambiente com Python 3.13 + Postgres 14.

### 14. Reorganização de pastas no padrão Django

O backend tinha sido criado numa subpasta `Portal/backend/`, com o
frontend (HTML/CSS/JS) solto na raiz de `Portal/` ao lado dela — funcional,
mas não era a estrutura convencional de um projeto Django. Pedido: "reorganize
a estrutura das pastas, conforme o padrão de um projeto Django". Mudanças:

- `manage.py`, `requirements.txt`, `.env`, `config/` e `portal_api/` subiram
  de `Portal/backend/` para a raiz de `Portal/` — `Portal/` passou a **ser**
  o projeto Django, não conter um subprojeto.
- As 5 páginas HTML foram movidas para `Portal/templates/` (antes soltas na
  raiz) — é para lá que `TEMPLATES[0]["DIRS"]` aponta agora.
- `assets/css`, `assets/js` e `img/` viraram `static/css`, `static/js` e
  `static/img` (pasta `assets/` removida) — `STATICFILES_DIRS` (novo em
  `settings.py`) aponta pra lá, e `STATIC_ROOT` foi adicionado para
  `collectstatic` em produção.
- Os 5 templates passaram a usar `{% load static %}` + `{% static 'css/x.css' %}`
  em vez de caminhos hardcoded (`assets/css/x.css`) — forma idiomática do
  Django de referenciar estáticos.
- `config/urls.py` perdeu os `re_path`/`static_serve` manuais para
  `assets/`/`img/` — `django.contrib.staticfiles` já serve `static/`
  automaticamente em `DEBUG` a partir de `STATICFILES_DIRS`, sem
  configuração extra.
- Bug corrigido de passagem: o `.env` já existia (com as credenciais do
  Postgres) mas `settings.py` nunca chamava `load_dotenv()` — ele nunca
  tinha sido lido de verdade. Corrigido ao mexer em `settings.py` por causa
  da mudança de `BASE_DIR`.

Nenhuma mudança de comportamento — só de organização de arquivos; os
endpoints da API, os models e a lógica do frontend continuam os mesmos da
rodada 13.

### 15. Dispensar notificações persiste por usuário

Bug relatado: ao clicar no X de uma notificação individual, o card do
dropdown fechava inteiro (comportamento incorreto) e, além disso, qualquer
notificação dispensada (X individual ou "Limpar tudo") voltava a aparecer
depois de um reload da página.

- **Fechamento indevido do dropdown**: causado pela ordem de eventos —
  `list.innerHTML` era reconstruído (removendo o botão clicado do DOM) antes
  do clique terminar de subir até o listener global em `document` que fecha
  o dropdown em clique fora; como o botão já não estava mais na árvore,
  `dropdown.contains(event.target)` avaliava falso, fechando o card como se
  fosse clique externo. Corrigido com `event.stopPropagation()` no handler
  de dismiss em `notifications.js`.
- **Notificação reaparecendo no reload**: era o comportamento documentado
  até então (`notifications.js` guardava a lista só em memória, "zera a cada
  reload") — o usuário pediu explicitamente para persistir no backend em vez
  de usar `localStorage`. Criado o model `NotificacaoDispensada` (chave
  natural `usuario` + `notif_id`, mesmo padrão de `Favorito`/`WidgetUsuario`)
  e o endpoint `/api/notificacoes-dispensadas/`. `notifications.js` agora
  busca os IDs já dispensados no carregamento e filtra a lista antes de
  renderizar, e persiste via POST a cada X clicado ou "Limpar tudo".
  Importante: só o **estado de dispensada** passou a ser real — o conteúdo
  das notificações de "nova ferramenta" (`PID_NEW_TOOLS_NOTIFICATIONS`)
  continua mockado/hardcoded no frontend, só os itens de compromisso vêm de
  dados reais.

### 16. Links & Ferramentas — tela nova + permissão de edição dedicada

Pedido: estruturar de verdade a tela "Links & Ferramentas" (até então só um
item de menu com `href="#"`, sem página própria), com base num print da
ferramenta antiga (grade de cartões com logo/nome de sistemas externos —
Ottimizza, Sieg, GLPI, Trello, WhatsApp etc., cada um abrindo o link
correspondente). Três exigências específicas:

1. **Edição restrita por permissão de perfil**: só perfis com uma permissão
   dedicada podem reordenar, incluir e remover os cartões — hoje só
   habilitada para "Integração e Inovação" (`gerencia_links_ferramentas=True`
   no seed), mas com o toggle já disponível em Perfis de Acesso pra liberar
   outros perfis depois, sem precisar de código novo.
2. **Adicionar link**: modal com Nome, Link (URL) e "uma foto ou ícone" —
   interpretado como upload de imagem real (não uma URL de ícone nem um
   emoji/picker), já que o print de referência mostra logos de marca de cada
   ferramenta.
3. Nada além disso foi pedido — não existe hoje edição de nome/URL/ícone de
   um link já criado pela UI (só admin do Django), por decisão de manter o
   escopo no que foi pedido (adicionar/remover/reordenar).

O que foi construído:

- **Nova permissão no mesmo padrão de `gerencia_permissoes`**: campo
  `gerencia_links_ferramentas` (BooleanField) em `PerfilAcesso`, união em
  `Usuario.gerencia_links_ferramentas()`, classe `PodeGerenciarLinksFerramentas`
  em `permissions.py`, exposta em `me.gerencia_links_ferramentas`. É uma flag
  **separada** do toggle de visibilidade do módulo "Links & Ferramentas" (que
  já existia no catálogo, controla só se o item aparece no menu) — uma
  controla quem *vê* a tela, a outra quem pode *editar o conteúdo* dela.
  Adicionado um checkbox dedicado na aba Permissões de `perfis-acesso.html`
  (`#pa-gerencia-links-ferramentas`), fora da árvore de módulos/apps — hoje é
  o único toggle "especial" desse tipo com UI própria (`gerencia_permissoes`
  em si só é setável via seed/admin, sem checkbox equivalente ainda; não
  alterado nesta rodada por não ter sido pedido).
- **Model `LinkFerramenta`**: lista **global** (sem FK de usuário, ao
  contrário de Favorito/WidgetUsuario) — todo mundo vê os mesmos cartões.
  Campo `ordem` (inteiro) para a sequência de exibição; `icone` é `ImageField`
  opcional (exigiu adicionar Pillow ao `requirements.txt` e configurar
  `MEDIA_URL`/`MEDIA_ROOT`, que não existiam no projeto até agora — servidos
  em `DEBUG` por `config/urls.py`, sem equivalente em produção ainda
  configurado além do padrão whitenoise/nginx já usado pra `STATIC_ROOT`).
- **Reordenação sem endpoint de lote**: mover um cartão faz duas chamadas
  PATCH trocando o `ordem` de dois itens adjacentes — decisão deliberada de
  não criar um endpoint de bulk-reorder nem usar drag-and-drop (sem
  biblioteca no projeto, drag-and-drop nativo teria custo de acessibilidade/
  touch maior que o ganho); a UI usa duas setas (mover pra cima/baixo) por
  cartão, visíveis só pra quem tem a permissão.
- **Upload multipart**: `pidApiRequest` (`api.js`) só sabia enviar JSON —
  estendido para detectar `body instanceof FormData` e, nesse caso, deixar o
  browser montar o `Content-Type: multipart/form-data` com boundary sozinho
  (sem isso, o upload do ícone quebraria).
- Página nova `links-ferramentas.html`, réplica do shell padrão (mesma
  sidebar/topbar dos outros 5 templates) + `links-ferramentas.js` +
  `links-ferramentas.css`; item do menu "Links & Ferramentas" trocou de
  `href="#"` pra `href="links-ferramentas.html"` nos 5 templates que
  replicam a sidebar.

Mesma limitação de ambiente das rodadas anteriores: sem Python 3.13/Postgres
neste ambiente, não foi possível rodar `makemigrations`/`migrate` (novo
model + dois campos novos em `PerfilAcesso`) nem testar upload de imagem de
ponta a ponta.

### 17. Ambiente ganhou Python 3.13 + Postgres — migração da rodada 16 aplicada

O usuário avisou que "todas as ferramentas necessárias já estão instaladas"
neste ambiente. Confirmado: o `.venv` do projeto já tem Django 6.0.7, DRF
3.17.1, psycopg, python-dotenv e Pillow 12.3.0 (Python 3.13.14), e há um
Postgres local acessível pelas credenciais do `.env` — inclusive já com
migrações antigas aplicadas até `0002_notificacaodispensada` (rodada 15),
de uma sessão anterior fora deste histórico. A limitação documentada nas
rodadas 13–16 (só Python 3.8, sem Django, sem Postgres) não vale mais —
`CLAUDE.md` foi corrigido pra refletir isso.

Com o ambiente disponível, gerada e aplicada a migração pendente da rodada
16 (`0003_linkferramenta_and_more`: model `LinkFerramenta` + campo
`gerencia_links_ferramentas` em `PerfilAcesso`) e reaplicado `seed_portal`
— `gerencia_links_ferramentas=True` confirmado no perfil "Integração e
Inovação". Ainda não testado num navegador de verdade (login +
upload de ícone + reordenar + notificações persistindo entre reloads) —
próximo passo natural se o usuário quiser essa validação.

### 18. Bug visual: espaçamento inconsistente na sidebar

Reportado com print: itens do menu com estrela de favorito (qualquer
`<a class="nav-item">`/`.nav-subitem`, exceto "Principal") pareciam ter
espaçamento diferente dos itens sem estrela (toggles de grupo como
Auditorias/Solicitações, que são `<button>`, não `<a>`, e por isso nunca
ganham estrela via `pidCollectFavoritableApps`). Causa raiz: `.nav-item-row`
(o wrapper que `favorites.js` injeta em volta de um link favoritável pra
acomodar a estrela) não tinha `padding-right` nenhum, então o `.fav-toggle`
ficava encostado na borda direita da sidebar — enquanto o chevron dos
toggles de grupo mantinha os 12px de padding-right do próprio `.nav-item`.
Corrigido com `padding-right: var(--space-3)` em `.nav-item-row`
(`layout.css`), replicado nos dois estados responsivos (sidebar colapsada
no desktop, sidebar recolhida no mobile) pra não descentralizar o ícone
quando a estrela está escondida.

### 19. Permissão de Links & Ferramentas: de checkbox dedicado para visualizar/editar na árvore

A permissão `gerencia_links_ferramentas` (criada na rodada 16 como
`BooleanField` dedicado + checkbox solto no topo do card de edição de
perfil) foi **revertida** a pedido do usuário: "ao invés de ter uma caixa de
seleção acima, deixar uma opção onde marca a liberação para visualizar o
Links & Ferramentas, com subseleções entre visualizar e editar. Pois
teremos outras aplicações com a mesma funcionalidade." Ou seja: o pedido não
era só um ajuste de UI, era um pedido de **modelo de dados reutilizável**
pra qualquer módulo futuro que precise da mesma distinção visualizar/editar.

Novo desenho (documentado em detalhe em `CLAUDE.md` → "Padrão
visualizar/editar"): em vez de um campo dedicado por módulo, "visualizar" e
"editar" passaram a ser **dois `apps` normais** de `links-ferramentas` em
`catalogo.MODULE_APPS` — reaproveitando 100% a árvore de permissões
genérica que já existia (`profiles.js`), sem nenhum código de UI novo. Isso
também tornou o backend mais estrito: antes, `GET /api/links-ferramentas/`
era liberado a qualquer autenticado; agora exige `apps.visualizar`, e a
escrita exige `apps.editar` — ambos checados por uma única classe genérica
`PermissaoApp(module_key, app_key)` (`permissions.py`) reaproveitável por
qualquer módulo futuro com a mesma necessidade, sem precisar de subclasse
nova.

Removido nesta rodada: campo `gerencia_links_ferramentas` em `PerfilAcesso`
(migração `0004_remove_perfilacesso_gerencia_links_ferramentas`), método
`Usuario.gerencia_links_ferramentas()`, classe `PodeGerenciarLinksFerramentas`,
o campo em `PerfilAcessoSerializer`/`PerfilResumoSerializer`/`me_view`, e o
checkbox `#pa-gerencia-links-ferramentas` em `perfis-acesso.html`/`profiles.js`.

Pegadinha resolvida no `seed_portal.py`: como `links-ferramentas` está em
`BASE_KEYS` (habilitado pra todo perfil), `catalogo.permissions_from_keys()`
habilitaria **todos** os apps do módulo de uma vez — incluindo "editar" pra
todo mundo. Corrigido forçando `apps.editar = False` explicitamente pra
qualquer perfil que não seja "Integração e Inovação" (código 8), depois de
montar o dict de permissões. Confirmado via shell: os 7 perfis "normais"
saíram com `visualizar=True, editar=False`; só o código 8 saiu com ambos
`True`.

Migração `0004` gerada e aplicada no ambiente local (Python 3.13/Postgres
disponíveis desde a rodada 17); `manage.py check` limpo.

### 20. Logo com texto branco + sidebar maior

Dois bugs visuais de marca reportados com print: (1) a logo da tela de
login (`logo.png`) tem o texto "DePaula Contadores" em preto, ilegível
contra o fundo escuro do card de login (`--bg-surface`); (2) a logo da
sidebar (`logo-mono.png`, versão toda em branco/cinza claro) estava
pequena demais (`.sidebar__logo` era 56×56 fixo, espremendo uma arte que é
bem mais larga que alta) — pedido explícito pra usar ali uma versão com o
**D colorido e a letra branca**, num tamanho maior.

Essa variante (D colorido + texto branco) não existia como arquivo — só
existiam `logo.png` (D colorido, texto preto) e `logo-mono.png` (tudo
branco, D incluído). Gerada uma nova, `logo-branco.png`, com um script
Python usando Pillow (ambiente já tinha Pillow desde a rodada 16): varre
`logo.png` pixel a pixel e recolore pra branco só os opacos
quase-neutros/escuros (`max(r,g,b) < 70` e `spread(r,g,b) < 12`) — o
degradê dourado/marrom do D nunca bate nesse filtro porque mesmo na sombra
mais escura mantém um matiz quente (testado: pixel mais escuro do D
amostrado foi `(80,65,42)`, spread 38; texto era `(0,0,0)` puro, spread 0).
572.209 pixels alterados. Resultado confirmado visualmente (Read da imagem
gerada) antes de usar.

Trocado `logo.png` → `logo-branco.png` no login (`index.html`) e
`logo-mono.png` → `logo-branco.png` nos 5 shells (mesmo arquivo nos dois
lugares — ambos os fundos são escuros, então a mesma variante serve para
os dois). `.sidebar__logo` foi de `56×56` fixo pra `width:200px;
height:auto` (a arte é ~1.41:1, largura bem maior que altura — forçar
quadrado a esmagava); adicionado encolhimento pra `44px` nos dois estados
de sidebar colapsada (`.is-collapsed` no desktop, breakpoint mobile) pra
não vazar da faixa de 76px.

`logo.png` e `logo-mono.png` continuam no repo (não usados em nenhum
template agora) — o primeiro como fonte pra regerar `logo-branco.png` se a
arte oficial mudar, o segundo como variante alternativa disponível.

### 21. Ramais — tela nova

Pedido: reconstruir de verdade a tela "Ramais" (até então só um item de menu com `href="#"` e um botão "Acessar Ramais" sem destino em todos os shells), com base em prints da ferramenta antiga: diretório de ramais alimentado pelo cadastro real de usuário (Nome/Departamento/Ramal), modal de "Adicionar um Novo Ramal" (com opção de vincular um usuário existente ou criar uma linha avulsa "Não Tem Usuário"), botão "Novo Chamado", botão "Criar Ausência" e cartões especiais para colaborador ausente/aniversariante. Três decisões confirmadas com o usuário antes de implementar:

- **Novo Chamado** abre embutido na própria tela (modal com `<iframe>` apontando pro token da ferramenta de chamados), não em nova aba — diferente do padrão de todo outro link externo do portal.
- **Editar um ramal vinculado a usuário**: só o número do Ramal é gravável nesta tela — grava direto em `Usuario.ramal`; Nome/Departamento continuam só leitura do cadastro.
- **Ausência**: "(AUSENTE)" é calculado automaticamente comparando a hora atual com o período criado, mais uma ação de "Encerrar Ausência" pra quem volta antes do previsto.
- **Férias**: fora de escopo — o próprio usuário disse que depende de uma integração futura com outro banco; nenhuma UI de férias foi construída.

O que foi construído (detalhe técnico completo em `CLAUDE.md` → seção "Ramais"):

- Dois models novos: `Ramal` (linha da tela, opcionalmente vinculada a `Usuario` — vinculada, os dados vêm sempre do cadastro; avulsa, `nome`/`departamento`/`numero` moram na própria linha) e `RamalAusencia` (`esta_ativa()` calcula "ausente agora" comparando datas/horas, sem armazenar um flag; `encerrada_manualmente` permite encerrar antes do previsto sem mexer no período original).
- Mesmo padrão visualizar/editar da rodada 19 (Links & Ferramentas): `ramais` ganhou os dois apps na árvore de permissões, com o mesmo cuidado no `seed_portal.py` de forçar `editar=False` pra todo perfil que não seja Integração e Inovação (já que `ramais` está em `BASE_KEYS`, `permissions_from_keys()` habilitaria os dois de uma vez sem esse override).
- Endpoint dedicado `GET /api/ramais/usuarios/` pra alimentar o `<select>` "Lista de Usuários" dos modais, em vez de reaproveitar `/api/usuarios/` — aquele é restrito a `gerencia_permissoes`, e a permissão de Ramais foi mantida deliberadamente desacoplada disso (mesmo espírito da própria refatoração visualizar/editar da rodada 19).
- Página nova `ramais.html` + `ramais.js` + `ramais.css`, réplica do shell padrão, reaproveitando a tabela genérica `.pa-table*` de `perfis-acesso.css` (mesmo padrão que `usuarios.html` já usa sem CSS de tabela próprio). Nos outros 5 templates, o item de menu "Ramais" (antes `href="#"`) e o botão "Acessar Ramais" do topbar (antes um `<button>` sem handler nenhum) passaram a apontar de verdade pra `ramais.html`.
- Migração `0012_ramal_ramalausencia` gerada e aplicada no ambiente local; `seed_portal` reaplicado (confirmado via shell: 7 perfis com `ramais.apps.editar=False`, só "Integração e Inovação" com `True`).

Ainda não testado num navegador de verdade — próximo passo natural se o usuário quiser essa validação (ver "Roadmap" abaixo).

### 22. Ramais: colaboradores aparecem automaticamente, sem precisar "adicionar"

Depois de testar a rodada 21 no navegador (print anexado: só Gabriel aparecia na lista, porque ele tinha se "adicionado" manualmente pelo modal), o usuário pediu duas coisas:

1. "Pode trazer automaticamente o cadastro do usuário para esta tela de ramais, ficando apenas pendente o cadastro de ramal, se necessário" — ou seja, o modelo original (rodada 21), que exigia criar uma linha `Ramal` vinculada a um `Usuario` pra alguém aparecer no diretório, criava um passo manual desnecessário: todo colaborador com conta no Portal já deveria aparecer sozinho, com o ramal pendente até ser preenchido.
2. "Melhore a visualização da opção de adicionar ramal, o ícone de seleção está feio e destoa da página" — o `<select>` nativo do browser (sem nenhum CSS) destoava do tema escuro do resto do portal.

O que mudou:

- **`Ramal` perdeu o campo `usuario`** (migração `0013_remove_ramal_usuario_alter_ramal_nome`) — agora é só linha avulsa (sem conta de sistema por trás, ex.: telefone de sala), com `nome` obrigatório e `departamento`/`numero` opcionais (podem ficar pendentes, igual a um colaborador de verdade).
- **`RamalViewSet.list()` foi reescrito** pra mesclar duas fontes numa lista só, sem passar pelo `RamalSerializer`: todo `Usuario` ativo (linha montada direto do cadastro — `nome`, `departamentos`, `ramal`) + as linhas avulsas de `Ramal`. Cada item ganha um `id` sintético (`"usuario-<id>"`/`"avulso-<id>"`) e um `tipo`, que o frontend usa pra decidir a ação certa.
- **Editar o ramal de um colaborador de verdade** deixou de ser "criar uma linha vinculada" — agora é a nova action `PATCH /api/ramais/usuarios/{usuario_id}/` (`atualizar_ramal_usuario`), que grava direto em `Usuario.ramal`. "Adicionar Ramal" ficou só para linhas avulsas — o `<select>` "Lista de Usuários" que existia nesse modal foi **removido** (não faz mais sentido, já que o colaborador já aparece sozinho); só o modal de Criar Ausência ainda tem esse `<select>` (via `GET /api/ramais/usuarios/`, agora simplificado pra só `id`/`nome`).
- **Excluir** só existe pra linhas avulsas agora (não dá pra "excluir" um colaborador do diretório sem excluir a conta dele, o que é escopo da tela de Usuários) — o ícone de lixeira some das linhas de usuário de verdade.
- **Usuário inativo não aparece mais** no diretório (`list()` filtra `is_active=True`) — efeito colateral da reescrita que corrige uma limitação que a rodada 21 tinha deixado em aberto.
- **Select/textarea estilizados**: `components.css` ganhou `.modal-field select`/`.modal-field textarea` genéricos (seta customizada via `background-image`, sem o `appearance` nativo do browser) — não existia nenhum estilo pra esses dois elementos antes (só `input`), então qualquer modal futuro com `<select>`/`<textarea>` já sai consistente com o tema escuro sem precisar de CSS próprio.

Pegadinha resolvida durante a migração: como o campo `usuario` foi removido por completo (não só esvaziado), a única linha `Ramal` vinculada que já existia (a que o usuário tinha criado testando a rodada 21, ligada à própria conta dele) ficou órfã — virou uma linha avulsa com todos os campos em branco, porque a informação de qual usuário ela representava dependia só da FK removida. Identificada e apagada manualmente depois da migração (não tinha dado nenhum pra preservar, já que os três campos ficavam vazios pra linhas vinculadas no desenho antigo); o ramal do usuário de teste `bruno` também tinha sido alterado por um smoke test rodado antes desta correção e foi restaurado ao valor original. Sem consequência pra dado real, já que a tela nunca tinha sido usada em produção — mas fica registrado porque é o tipo de coisa que merece atenção se acontecer de novo com dado que importe.

## Limitações conhecidas / decisões assumidas

- Calendário De Paula (empresa) não tem mais versão interna — depende
  inteiramente do link externo `depaula-tvcorporativa.lovable.app`.
- Widgets: só um tipo implementado (Calendário Individual) até agora.
- Sem teste automatizado (nem no frontend, nem no backend Django) — todo o
  fluxo foi validado manualmente no navegador. As rodadas 13 e 14 não
  puderam ser testadas ponta a ponta no ambiente da época; a partir da
  rodada 17 o ambiente já roda `migrate`/`runserver` de verdade (ver acima),
  mas o teste manual no navegador de Links & Ferramentas (rodada 16) e da
  persistência de notificações (rodada 15) ainda não foi feito.
- Tema (claro/escuro e cor) continua só no `localStorage` — é preferência
  de navegador, decisão deliberada de manter fora da migração para o
  banco.
- Links & Ferramentas: não dá pra editar nome/URL/ícone de um link já
  criado pela UI, só adicionar/remover/reordenar (o que foi pedido na
  rodada 16) — editar um existente hoje é só via Django admin.
- Ramais: sem UI de férias (integração futura com outro banco, combinado
  com o usuário na rodada 21); excluir um colaborador do diretório não é
  possível por ali (só linhas avulsas podem ser excluídas) — é escopo da
  tela de Usuários, por decisão da rodada 22.
- Simulação de Custo de Contratação (rodada 37): v1 cobre só Empregado
  CLT — as outras 4 modalidades do pedido original ficam para quando
  houver uma planilha/regra de referência validada pelo contador.
- Indicador de Desempenho (rodada 38): v1 cobre só o Fiscontábil — outros
  departamentos ficam para rodada futura; sem visão própria do
  colaborador no Portal (recibo é documento interno do RH).

### 23. Ramais: ajustes visuais + visualizar/editar/excluir ausência

Três pedidos pequenos, feitos em sequência depois de testar a rodada 22 no navegador:

1. **Overflow no modal de Adicionar Ramal**: `.modal-field-row` usava `grid-template-columns: 1fr 1fr` sem `minmax(0, ...)`, e os inputs de `.modal-field` não tinham `width: 100%` explícito — o conteúdo (tamanho intrínseco do `<input>`) empurrava a grade além da borda do modal. Corrigido em `components.css` (`grid-template-columns: minmax(0, 1fr) minmax(0, 1fr)` + `width: 100%` em `input`/`select`/`textarea` de `.modal-field`) — bug genérico, vale pra qualquer modal do portal com campos lado a lado, não só Ramais.
2. **Modal "Novo Chamado" cortando conteúdo**: a ferramenta externa embutida no iframe (rodada 21) é mais alta que um modal padrão; o iframe tinha altura fixa (`min(70vh, 640px)`) menor que o conteúdo, cortando o formulário no meio de um campo em vez de rolar de forma previsível. Corrigido em `ramais.css`: `.ram-chamado-card` passou a ocupar quase a tela inteira (`min(960px, 95vw)` × `min(92vh, ...)`, o teto em px ajustado depois pelo próprio usuário direto no CSS) e o iframe virou `flex:1` dentro do `.modal-card` (que já é flex-column), preenchendo todo o espaço vertical restante.
3. **Visualizar/editar/excluir ausência**: o usuário passou um print de como devia ficar — clicar no badge "(AUSENTE)" de uma linha abre um modal "Visualizar Ausência" com os campos do período (desabilitados) e dois botões, "Editar Ausência" e "Deletar Ausência". Implementado reaproveitando o `RamalAusenciaViewSet` que já existia (nenhuma mudança de backend — `GET`/`PATCH`/`DELETE` em `/api/ramais-ausencias/{id}/` já funcionavam, só faltava a UI): o badge virou um `<button data-ram-ver-ausencia>` que busca o registro via `GET` e abre o modal; "Editar" habilita os mesmos campos in-place (sem modal novo) e troca os botões por "Cancelar"/"Salvar Ausência"; "Deletar" remove o registro de verdade. Isso **substituiu** o botão "Encerrar Ausência" da rodada 21 (que só marcava `encerrada_manualmente=True`, preservando o registro) — o campo continua no model, mas sem UI própria; editar/excluir cobre o caso de uso real de forma mais direta, do jeito que foi demonstrado.

Nenhuma migração nova (mudança 3 não tocou o backend). `manage.py check` limpo depois das mudanças 1 e 2 (não alteraram Python, só confirmado por precaução).

### 24. Ramais: contraste dos indicadores de ausente/aniversariante

Prints em claro e escuro mostrando as linhas de Bruno (ausente) e Willian (aniversariante) — pedido pra melhorar a legibilidade. Perguntado antes de mexer, porque "observações" no pedido original não batia com nenhum print (nenhum mostrava o campo Observações do modal de Ausência); o usuário confirmou que o problema era **o tingimento de fundo da linha inteira** (`.ram-row--ausente td`/`.ram-row--aniversario td`, rodada 21) somado à cor do próprio selo — duas camadas de cor translúcida da mesma matiz empilhadas, contraste ruim nos dois temas.

Primeira tentativa: removido o tingimento da linha inteira, deixando só o selo comunicar o status (mesmo padrão do selo "Pendente"). O usuário pediu de volta o tingimento — "quero que deixe o tingimento, porém que fique num tom mais forte, para facilitar sua visualização". Desenho final: `.ram-row--ausente`/`.ram-row--aniversario` td voltaram (com opacidade maior que a versão original da rodada 21) **e** `.ram-badge--ausente` virou um selo (pill) de verdade, igual ao de aniversariante — as duas coisas juntas, cada uma com cor de texto/fundo ajustada por tema via `:root[data-theme="light"]` (mesmo padrão de override que `tokens.css` já usa) em vez de reaproveitar `--danger`/`--gold` crus, que não tinham contraste suficiente pensados pra texto pequeno sobre um selo ou fundo de linha.

### 25. Favicon

Pedido: "no ícone da aba do navegador, deve constar esta logo minimalista do escritório" — o usuário passou um print de referência: só o D (o mesmo pen/quill em degradê dourado/marrom de `logo.png`), sem o texto "De Paula Contadores", sobre fundo transparente.

Esse recorte isolado do D não existia como arquivo — as três variantes de `static/img/` sempre têm o texto junto. Gerado `favicon.png` a partir de `logo.png` reaproveitando o mesmo filtro criado na rodada 20 pra `logo-branco.png` (pixel opaco quase-neutro/escuro = texto, nunca o D, que mantém matiz quente até na sombra mais escura do degradê) — mas em vez de recolorir esses pixels pra branco, apagados (`alpha=0`) pra isolar só o D; resultado recortado pelo bounding box do que sobrou e centralizado num canvas quadrado transparente (o D é mais alto que largo), redimensionado pra 192×192. Resultado comparado visualmente (`Read` da imagem gerada) contra o print do usuário antes de usar — bateu.

Ligado via `<link rel="icon" type="image/png" href="{% static 'img/favicon.png' %}">` no `<head>` das 7 páginas (`index.html` + os 5 shells + `ramais.html`). Nenhuma mudança de Python; `manage.py check` limpo por precaução.

### 26. Bug: busca de aplicações deixava grupos do menu abertos depois de limpar

Reportado com print: depois de pesquisar em "Pesquise por Aplicação..." (`search.js`) e apagar a busca, os grupos do menu (Portais, Geradoc etc.) que a busca tinha aberto pra mostrar o resultado continuavam abertos, em vez de voltar ao estado de antes de buscar.

Causa: `search.js` só tinha o caminho de **abrir** um `nav-group` (`classList.add("is-open")`) quando ele dava match durante a digitação — nunca fechava de volta quando o termo era apagado. Corrigido guardando, no início de cada sessão de busca (primeira tecla digitada), quais grupos já estavam abertos manualmente (`gruposAbertosAntesDaBusca`, um `Set`); ao limpar o campo, cada grupo volta exatamente pro estado daquele snapshot, em vez de simplesmente remover `is-open` de todo mundo (o que fecharia até um grupo que o usuário tinha aberto manualmente antes de buscar). Só front-end (`static/js/search.js`), nenhuma mudança de backend.

### 27. Botão "Criar Ausência" fora do padrão + texto do menu no tema claro

Dois ajustes pequenos:

- **Botão "Criar Ausência"** (`ramais.html`) usava `btn-outline`, destoando dos outros dois botões da mesma barra de ações ("Adicionar Ramal", "Novo Chamado"), ambos `btn-solid`. Trocado pra `btn-solid`, sem nada mais mudar no comportamento.
- **Texto do menu no tema claro**: a sidebar é intencionalmente congelada (fundo sempre escuro nos dois temas, ver `CLAUDE.md` → "CSS — organização entre arquivos"), mas as variáveis de texto (`--sidebar-text-primary`/`--sidebar-text-secondary`/`--sidebar-text-muted`) nunca tinham sido sobrescritas pro tema claro — pedido explícito pra virarem branco puro nesse tema, pra melhorar a legibilidade contra o fundo que continua escuro. Adicionada uma exceção deliberada em `tokens.css` (`:root[data-theme="light"]`) só pra essas três variáveis; fundo/borda da sidebar continuam frozen como antes. `CLAUDE.md` atualizado pra documentar a exceção, já que a regra geral (não usar overrides de tema na sidebar) continua valendo pro resto.

### 28. Fonte "Bree Serif" no título da tela inicial

Pedido: trocar a fonte do texto "Portal De Paula" no topbar da tela inicial (`portal.html`) pra Bree Serif, serif, negrito — só ali, não em `--font-sans` (usada em todo o resto do portal) nem no `.topbar__title` dos outros shells (que mostram outros títulos, como "Ramais"/"Administração").

Primeira fonte externa do projeto — até aqui só fontes do sistema (`--font-sans`). Carregada via Google Fonts (`<link rel="preconnect">` + `<link ... family=Bree+Serif>`) no `<head>` de `portal.html`. Estilo aplicado num id novo, `#portal-title` (no mesmo `<h1 class="topbar__title">` de sempre, só ganhou o id), colocado em `widgets.css` por ser o único CSS próprio da página — mesmo não sendo um widget. Ajustado por iterações diretas do usuário logo em seguida: negrito removido, tamanho aumentado (1.3rem), negrito devolvido, negrito removido de novo — estado final é Bree Serif 400/1.3rem. Na mesma leva de ajustes, o usuário pediu a mesma fonte também no título "Portal De Paula" da tela de login (`.login-card__title`, `login.css`) — `index.html` ganhou o mesmo `<link>` do Google Fonts.

### 29. Animações — pedido explícito pra ignorar `prefers-reduced-motion`

Pedido: "inclua animações nas páginas, para deixá-las fluidas", com duas condições explícitas — rápidas ("otimizando o tempo") e que **ignorem** a preferência de acessibilidade do sistema operacional/navegador do usuário (`prefers-reduced-motion`). Isso é uma inversão deliberada da prática padrão de acessibilidade (que normalmente desativaria animação quando essa preferência está ativa) — decisão do dono do produto pro próprio portal interno, registrada aqui pra não ser "corrigida" de volta sem confirmar de novo.

Implementado com três `@keyframes` genéricos em `base.css` (`pidFadeIn`, `pidFadeSlideUp`, `pidScaleIn` — único CSS carregado por toda página, inclusive `index.html`), aplicados via `animation` (não `transition`, que não anima a troca `display:none` ↔ visível causada por `hidden`) em: `.modal-overlay`/`.modal-card` (todo modal do app), `.account-dropdown`/`.notif-dropdown`, `.page-content` (toda navegação entre páginas) e `.login-card`. Botões (`.btn-solid`/`.btn-outline`/`.btn-ghost`/`.btn-danger-outline`/`.icon-btn`) ganharam `transform: scale()` no `:active` como feedback de clique, e `.pa-table td` (reaproveitada por Perfis de Acesso/Usuários/Ramais) ganhou `transition: background` no hover da linha, que antes trocava sem transição nenhuma. Durações todas curtas (120–200ms, a maioria usando os tokens `--transition-fast`/`--transition-base` que já existiam). Nenhum `@media (prefers-reduced-motion: reduce)` foi adicionado — ausência deliberada, não descuido (ver `CLAUDE.md` → "Animações").

### 30. "Acessar Ramais" vira modal de consulta rápida, em vez de navegar

Pedido, com print de referência do portal antigo: o botão "Acessar Ramais" do topbar (presente em `portal.html`, `links-ferramentas.html` e `calendario-individual.html` — só essas 3 páginas têm o atalho) não deveria mais levar pra `ramais.html`; deveria abrir um modal com a lista de ramais cadastrados, com busca por nome/departamento/ramal. O print de referência mostrava um estilo DataTables (branco/azul, "Show N entries", colunas ordenáveis, paginação numerada) — decisão de modernizar a funcionalidade pro visual escuro/roxo do resto do portal, não clonar pixel a pixel (mesmo critério já usado desde a rodada 1).

O que foi construído:

- `#ramais-btn` voltou a ser um `<button>` (não `<a href="ramais.html">`, que era o estado desde a rodada 21) nas 3 páginas.
- Modal novo (`#ramais-lookup-modal`, duplicado nas 3 páginas — mesmo padrão de outros modais compartilhados como o de senha) + `static/js/ramais-lookup.js` + `static/css/ramais-lookup.css`: busca numa caixa só (filtra as três colunas ao mesmo tempo, mais simples que a busca em duas caixas da tela `ramais.html`), ordenação por coluna (clique no cabeçalho alterna asc/desc) e paginação (10/25/50/100 por página) — tudo client-side, sem endpoint novo, reaproveitando `GET /api/ramais/` (a mesma listagem mesclada usuário+avulso da tela completa), buscado uma vez por abertura de página.
- Gate por permissão: o botão some (`hidden`) se o perfil do usuário não tiver `apps.visualizar` em `ramais` — mesmo padrão do resto do app.
- Botão "Ir para Controle de Ramais" no rodapé do modal é o link de verdade pra `ramais.html` (tela com edição); o modal em si é só consulta.
- Pegadinha resolvida: a tabela do modal não podia reaproveitar `.pa-table` de `perfis-acesso.css` porque `portal.html`/`links-ferramentas.html`/`calendario-individual.html` não carregam esse CSS (só `ramais.html`/`usuarios.html`/`perfis-acesso.html` carregam) — `ramais-lookup.css` ficou com estilo de tabela autocontido (`.ram-lookup-table*`) em vez de depender de um CSS que a página não tem.

Nenhuma mudança de backend — `GET /api/ramais/` já existia e já retornava exatamente os dados necessários. `manage.py check` limpo (confirmado por precaução, já que a mudança foi só front-end).

### 31. Ramais vira uma seção com 5 subtelas (abas)

Dois prints do sistema antigo mostraram que "Ramais" no fundo é uma seção com 5 subtelas navegáveis por abas: Ramais, Responsável no Tareffa, Telefones Externos, Férias, Funções de Telefonia. Pedido: adicionar essa navegação em `ramais.html`, construir Telefones Externos e Funções de Telefonia de verdade, e criar Responsável no Tareffa/Férias como abas vazias ("sem informações, pois serão trabalhadas posteriormente"). Isso **supera** a decisão da rodada 21 de que Férias estava fora de escopo — agora a aba existe (vazia); a limitação de fundo (integração futura com outro banco) continua valendo, só a navegação foi antecipada.

Perguntado antes de implementar se "Funções de Telefonia" (tabela de comandos tipo `*01 + Código de Agente` → LogOn) deveria ser conteúdo fixo no HTML ou uma lista administrável no banco — o usuário escolheu **lista administrável (CRUD completo)**, mesmo padrão de Telefones Externos.

O que foi construído:

- **Dois models novos**, ambos sem FK pra `Usuario` (dados avulsos, mesmo espírito de `Ramal` avulso): `TelefoneExterno` (nome/ramal/telefone/observações, só `nome` obrigatório) e `FuncaoTelefonia` (comando/função/resumo, só `comando` obrigatório). `FuncaoTelefonia.Meta.ordering = ["comando"]` reproduz sozinho a ordem do print (`*0, *01, *02, *03, *1, *2, *20, *21, *22, *23, *5, *503, *8`) porque essa é exatamente a ordem lexicográfica da string — dispensou um campo `ordem` manual e endpoint de reorder.
- **Permissão reaproveitada**: as duas subtelas usam o mesmo par `ramais.apps.visualizar`/`ramais.apps.editar` que já existia (`PermissaoApp("ramais", app_key)`) — são subtelas da mesma seção do menu, não aplicações novas; nenhuma mudança em `catalogo.py`.
- **Seed só para Funções de Telefonia**: `seed_portal.py` ganhou `FUNCOES_TELEFONIA_SEED` (as 13 linhas do print, via `update_or_create` por `comando`, idempotente) — decisão de que são comandos padrão de central telefônica (documentação genérica), diferente de Telefones Externos, que começa **vazio** de propósito (são contatos reais de fornecedores/terceiros, o usuário cadastra pela própria tela).
- **Abas**: reaproveitado o CSS genérico `.pa-tabs`/`.pa-tab`/`.pa-tab-panel` que já existia em `perfis-acesso.css` (mesmo padrão das abas Permissões/Usuários de `perfis-acesso.html`), com uma implementação independente em `ramais.js` (`data-ram-tab`/`data-ram-tab-panel`/`activeRamTab`) pra não colidir com `profiles.js`. O conteúdo que já existia (filtros/tabela/botões de Ramais) migrou pro painel `data-ram-tab-panel="ramais"`, sem mudar de comportamento.
- Endpoints novos: `/api/telefones-externos/` e `/api/funcoes-telefonia/`, CRUD padrão via `ModelViewSet`.

Migração `0014_funcaotelefonia_telefoneexterno` gerada e aplicada no ambiente local; `seed_portal` reexecutado (confirmado via shell: 13 linhas de Funções de Telefonia, na ordem certa). `manage.py check` limpo. Ainda não testado num navegador de verdade — cadastrar/editar/excluir um Telefone Externo e uma Função de Telefonia, alternar entre as 5 abas, e conferir que um perfil só-visualizar não vê nenhum botão de escrita fica para a próxima validação.

### 32. Ramais: permissão granular por subtela (visualizar por aba + editar nas 3 administráveis)

No mesmo dia da rodada 31, o usuário pediu um ajuste no modelo de permissão recém-criado: em vez de um único par `visualizar`/`editar` cobrindo as 5 abas de Ramais, cada aba deveria ter sua própria permissão de visualização, e só as 3 com conteúdo administrável (Ramais, Telefones Externos, Funções de Telefonia) deveriam ter também uma permissão de edição própria — Responsável no Tareffa/Férias, sendo placeholders vazios, só precisam de visualizar. Pedido explícito de "estado inicial": só "Integração e Inovação" com acesso de editar nas 3, os demais 7 perfis com visualizar liberado em todas as 5.

Implementado reestruturando `catalogo.MODULE_APPS["ramais"]` de uma lista flat de 2 apps pra **5 subgrupos** (mesmo formato `{"key", "label", "tools": [...]}` já usado em Auditorias) — cada subgrupo é uma aba, com 1 tool (`Visualizar`) ou 2 (`Visualizar`/`Editar`). Isso reaproveitou 100% a árvore de permissões genérica de `profiles.js` (`renderTree`/`renderEntry`/`renderLeaf` já sabem renderizar subgrupos com `tools`, usado desde a rodada de Auditorias) — nenhum código de UI novo em Perfis de Acesso.

O que mudou:

- **Backend**: os 4 `ModelViewSet` relacionados (`RamalViewSet`, `RamalAusenciaViewSet`, `TelefoneExternoViewSet`, `FuncaoTelefoniaViewSet`) passaram a checar a chave específica da própria subtela (`"telefones-externos-visualizar"`/`"editar"`, etc.) em vez do genérico `"visualizar"`/`"editar"` — `RamalAusenciaViewSet` usa as mesmas chaves de `ramais-visualizar`/`ramais-editar` do diretório, por ser parte dessa mesma aba.
- **`seed_portal.py`**: o override que força `editar=False` pros 7 perfis "normais" cresceu de 1 chave (`ramais.apps.editar`) pra 3 (`ramais-editar`, `telefones-externos-editar`, `funcoes-telefonia-editar`) — mesmo princípio de sempre, só mais chaves.
- **`ramais.js`**: reescrito o bloco de permissão — de um único `canView`/`canManage` pra 5 pares (um por aba), um objeto `ramTabViewPerms` que esconde (`hidden`) o botão de cada aba sem `visualizar`, e a aba ativa por padrão passou a ser a primeira visível (não sempre "Ramais", que pode estar oculta pra um perfil específico no futuro, embora hoje todos os 7 perfis "normais" vejam as 5).
- **`ramais-lookup.js`** (modal de consulta rápida no topbar): trocado de `apps.visualizar` genérico pra `apps["ramais-visualizar"]` especificamente, já que esse modal só mostra o diretório de Ramais.

Como isso mudou as **chaves** armazenadas em `PerfilAcesso.permissoes["ramais"]["apps"]` (não só valores), foi necessário reexecutar `seed_portal` pra sincronizar os 8 perfis com o novo formato — sem isso, todo perfil ficaria sem nenhum acesso a Ramais (as chaves antigas `visualizar`/`editar` não existem mais no catálogo). Confirmado via shell depois do reseed: os 7 perfis "normais" saíram com as 5 chaves `*-visualizar=True` e as 3 `*-editar=False`; só "Integração e Inovação" saiu com as 3 `*-editar=True` também. `gabriel`/`bruno` não foram tocados (proteção da rodada anterior, [[feedback_seed_nao_reseta_gabriel_bruno]] segue valendo). `manage.py check` limpo.

**Nota pra quem for customizar um perfil manualmente na tela de Perfis de Acesso**: qualquer ajuste fino que já tivesse sido feito nas chaves antigas (`ramais.visualizar`/`ramais.editar`) precisa ser refeito nas novas chaves — é uma troca de namespace, não uma migração automática de valor (JSONField não tem esse mecanismo).

### 33. Liderança (gerente/coordenador)

Pedido: gerentes/coordenadores precisam enxergar a agenda de compromissos privados de quem lideram, sem precisar que cada liderado marque o compromisso como "todos"/"departamento". Implementado com `Usuario.lideranca` (booleano) + `Usuario.liderados` (M2M auto-referenciado, `symmetrical=False` — "A lidera B" não implica o contrário). Dois pontos gravam a mesma relação: a tela de Usuários (seção "Liderança" no formulário, só quem tem `gerencia_permissoes`) e um modal novo "Gerenciar Usuário" (substituiu o antigo botão direto "Alterar senha" no dropdown da conta), que permite ao próprio gerente se autogerenciar via `PATCH /api/me/liderados/` sem precisar de acesso à tela administrativa. `CompromissoAgendaViewSet.get_queryset` passou a incluir compromissos `"somente_eu"` de quem está em `usuario.liderados`, mas sem dar direito de editar (`sou_dono` continua `False` pra esses). O checklist de liderados (com busca por nome/departamento e "marcar todos os resultados da busca") virou um componente genérico (`components.css`) reaproveitado nos dois lugares. Migração `0015_usuario_liderados_usuario_lideranca`. Detalhe completo em `CLAUDE.md` → "Liderança (gerente/coordenador) e o modal 'Gerenciar Usuário'".

### 34. Acessos Gerais — segunda aplicação de Links & Ferramentas

Pedido, com uma tela do Asana como referência: um cadastro de acessos/logins compartilhados da equipe (ex.: login geral de um site), organizado em seções e linhas, com popup de detalhes por linha. Virou a segunda aplicação real da seção "Links & Ferramentas" — o item do menu, que antes era um link direto, passou a ser um `nav-group` expansível com dois sub-itens ("Links & Ferramentas" e "Acessos Gerais"), cada um favoritável separadamente.

O que foi construído: dois models novos (`AcessoGeralSecao`, `AcessoGeral`, sem relação com `LinkFerramenta`), mesmo padrão visualizar/editar já usado em Links & Ferramentas (chaves próprias `acessos-gerais-visualizar`/`acessos-gerais-editar`); ordenação escopada por seção (não global); restrição opcional de seção por perfil (`perfis_restritos` M2M pra `PerfilAcesso` — filtro de **dado**, independente da árvore de permissões); e um editor de "Observações" com texto rico + imagens embutidas (`contenteditable`, colar/arrastar imagem vira `data:` URI, sem upload separado). Sanitização no backend via `nh3` (não `bleach`, sem manutenção desde 2023) — allowlist estrita de tags/atributos, permitindo só `<img>` com esquema `data:` além de tags de texto básicas, contra XSS via HTML malicioso injetado no payload. Migrações `0016_acessogeralsecao_acessogeral` e `0017_acessogeralsecao_perfis_restritos_and_more`. Detalhe completo em `CLAUDE.md` → "Acessos Gerais".

### 35. Eventos Corporativos no Calendário Individual

Pedido: distinguir compromissos pessoais/departamentais de **eventos corporativos** formais (reuniões, treinamentos) — com categoria, local, modalidade (presencial/remoto/híbrido) e descrição — e restringir quem pode criar compromissos visíveis para o departamento ou para todos, que até então qualquer usuário podia fazer livremente.

O que foi construído: `CategoriaEvento` (nome único + cor hex, cadastro editável direto no modal de criar/editar compromisso, botão "+" ao lado do `<select>` de categoria); `CompromissoAgenda` ganhou `categoria` (FK), `eh_evento` (booleano — força `visibilidade="todos"` na validação), `local`, `modalidade` e `descricao`. Nova permissão `calendario-individual-criar-evento` (`catalogo.py`, único `tool` dentro de um subgrupo — não um par visualizar/editar, já que o módulo em si é liberado a todo perfil) passou a ser exigida por `CompromissoAgendaSerializer.validate()` para qualquer compromisso com `visibilidade` em `departamento`/`todos` — liberada só pra "Integração e Inovação" no `seed_portal.py` por ora, mesmo cuidado de sempre (`calendario-individual` está em `BASE_KEYS`). No calendário, eventos ganharam uma 5ª categoria de filtro/cor (`"evento"`, token `--coral`), distinta das 4 já existentes (`somente_eu`/`departamento`/`todos`/`equipe`). Migrações `0018_remove_compromissoagenda_compartilhado_com_perfil_and_more`, `0019_categoriaevento_compromissoagenda_descricao_and_more` e `0020_compromissoagenda_eh_evento`. Detalhe completo em `CLAUDE.md` → "Eventos Corporativos" (dentro de "Calendário Individual e Widgets").

### 36. Importação de Plano de Saúde (Utilitários)

Primeira aplicação de "Utilitários" (os placeholders "Conversor de Arquivos"/"Calculadora Fiscal" foram removidos do menu nesta mesma rodada). Importa o relatório de faturamento de uma operadora de plano de saúde/odontológico (Amil, Unimed) e gera o arquivo de lançamento no leiaute do Questor, mais um relatório de auditoria do que não pôde ser lançado automaticamente. A lógica de negócio veio de um pipeline já testado (`projects/importacao-planos-saude.skill` + protótipo em `projects/project/`), portado quase 1:1 pra dentro do Django em `portal_api/planos_saude/` (pacote Python puro, sem ORM).

Decisões principais: permissão de **toggle único** (quem tem acesso faz o fluxo inteiro — criar, revisar, gerar); histórico completo (cada importação fica salva, diferente de um fluxo descartável); regra de custeio (empresa/empregado/específica, com limite de valor e/ou percentual) configurável por tipo de lançamento e tipo de beneficiário na tela, em vez da regra fixa do pipeline original; resolução manual de auditoria por nome (confirmação humana item por item quando o casamento automático falha, nunca fuzzy matching); pré-validação de cada arquivo anexado antes do envio final, reaproveitando o mesmo parser Python que o `create()` usaria. Migrações `0021_importacaoplanosaude_importacaoplanosaudeauditoria_and_more` e `0022_importacaoplanosaudeauditoria_resolucao_manual`. Detalhe completo em `CLAUDE.md` → "Importação de Plano de Saúde (Utilitários)".

### 37. Simulação de Custo de Contratação (Geradoc)

Pedido (2026-08-11): substituir a planilha manual de custo de contratação (`projects/planilha de custo/*.xlsx`) por um formulário no Portal que gera um PDF pronto pra enviar ao cliente — primeira aplicação de "Geradoc" a sair do estado de placeholder.

Decisões confirmadas com o usuário: v1 cobre só Empregado CLT (as outras 4 modalidades do pedido original — Simples Nacional, Regime Normal, Pró-labore, Empregado Doméstico — ficam para quando houver planilha de referência equivalente); cálculo pontual, sem persistência (devolve o PDF direto, nada salva no banco); corrigido um gap real da planilha original (dedução por dependente não somava à base do IRRF quando usava desconto real de INSS); e as tabelas de INSS/IRRF, que nasceram hardcoded, viraram um cadastro editável (`ParametroFiscalCustoContratacao`, singleton) na mesma rodada em que a redução de IRRF da Lei 15.270/2025 (vigente desde jan/2026) foi implementada, já que ambas mudam por lei/todo ano. PDF gerado via `reportlab` (adicionado ao `requirements.txt`), com cabeçalho nas cores reais da marca (dourado/marrom amostrados de `logo.png`), não o roxo do tema do Portal. Migração `0023_parametrofiscalcustocontratacao`. Detalhe completo em `CLAUDE.md` → "Simulação de Custo de Contratação (Geradoc)".

### 38. Indicador de Desempenho (Geradoc)

Pedido (2026-08-12): substituir a apuração manual do indicador de desempenho do Fiscontábil — feita numa planilha (`projects/Indicadores/FISCO CONTABIL *.ods`) com fórmulas quebradas por edições manuais acumuladas — por uma ferramenta completa dentro de Geradoc, com histórico de apurações mensais e recibo em PDF por colaborador. A maior feature construída até aqui em número de models/endpoints (6 models, 6 `ModelViewSet`, pacote de negócio próprio `portal_api/indicadores/` com 6 arquivos).

Escopo confirmado com o usuário: v1 cobre só o Fiscontábil (papéis Balancete/Liberação Fiscal/Conciliação); o "tipo" do colaborador é derivado por empresa via a planilha "Serviços Tareffa", não é cadastro; só 3 critérios (entrega de balancetes/liberações fiscais/conciliações no prazo) são calculados automaticamente, todo o resto é marcação manual do RH; critérios e percentuais por tipo são cadastros genéricos editáveis pela tela, não hardcoded (percentuais nunca editados in-place, só um histórico com `vigente_desde`); ajuste manual em dois níveis (por critério, e pelo percentual agregado Individual/Grupo/Departamento, este último aplicado de uma vez a todo o grupo/departamento — "cada gerente representa um grupo"); recibo é documento interno do RH, sem visão do próprio colaborador nesta v1. Validado com dados reais de 43 colaboradores, o que revelou e corrigiu dois bugs de robustez: `openpyxl` em modo `read_only` precisa de `.close()` explícito no Windows (senão bloqueia excluir o upload depois) e campos percentuais precisaram de `max_digits=7` (não 6) pra não estourar em cálculos que batem exatamente 100%. Primeiro histórico populado via `seed_indicador_desempenho` (idempotente), com os valores exatos da planilha antiga. Migrações `0024` a `0028`. Detalhe completo em `CLAUDE.md` → "Indicador de Desempenho (Geradoc)".

Ajuste pequeno feito logo depois de testar a tela de revisão no navegador: a coluna "Meta (%)" da tabela "Metas de Grupo e Departamento" era um campo de texto livre (permitindo qualquer percentual) — o usuário apontou que, pra Grupo/Departamento, só existem duas possibilidades reais ("será pago ou não"), então o campo virou um `<select>` Sim/Não (100%/0%), reaproveitando o mesmo raciocínio já aplicado aos critérios individuais de Grupo/Departamento (que também só têm Sim/Não, sem "não se aplica"/"não faz"). O percentual Individual de cada colaborador (composição ponderada dos 3 níveis) continua livre, por poder ser legitimamente fracionário.

Segundo ajuste, também depois de testar no navegador: o resumo do card de cada colaborador só mostrava "Individual: X%", sem explicar como esse número foi composto. Pedido: mostrar a composição completa (ex.: "Individual: 57,14% (peso 60%) Grupo: 100% (peso 10%) Departamento: 100% (peso 30%) Total Indicador: 74,29%"), com cada um dos 3 níveis em verde/vermelho conforme foi atingido (100%) ou não; o Total em si fica neutro (sem cor), pra não repetir a mesma informação 4 vezes. O percentual bruto de Individual (antes da composição) e o peso de cada nível eram calculados em `calculo.recalcula_colaborador` mas descartados depois de usados — extraída a lógica de filtro de respostas por nível pra uma função reaproveitável (`respostas_aplicaveis`) e adicionada `composicao_individual()`, exposta como campo computado (`composicao_individual`) em `IndicadorApuracaoColaboradorSerializer`, sem nenhuma migração (não persiste nada novo, só reconstrói pra exibição). Aproveitado pra adicionar `prefetch_related` na action `retrieve` de `IndicadorApuracaoViewSet` (`colaboradores__empresas`, `colaboradores__respostas__criterio`), já que o campo novo faria mais uma consulta por colaborador na tela de revisão sem isso. Layout do cabeçalho do card também foi reorganizado a pedido do usuário: a composição saiu de baixo do nome/gerente pra ficar ao lado, centralizada, numa coluna própria do grid; e o lápis de ajuste manual do Total passou a ficar sempre ao lado do valor (isolado numa linha própria que nunca quebra), não mais embaixo quando o rótulo "Total Indicador" (mais longo que o antigo "Individual") não coubesse na coluna.

Terceiro ajuste: a tabela de Metas de Grupo/Departamento tinha um `<select>` Sim/Não duplicado por critério — um ao lado do texto que descreve o critério (bulk, via `aplicar-em-lote`) e outro na coluna "Meta (%)" à direita (que já ajusta `pct_grupo`/`pct_departamento` direto). O usuário pediu pra remover o primeiro, mantendo só o da direita — `renderMetaCriteriosHtml` voltou a ser só texto informativo (nome + peso do critério), e o listener de `change` associado a `.ind-meta-criterio-select` foi removido. Responder um critério específico continua possível por colaborador, dentro do card de revisão (`renderRespostasGrupoHtml`) — só o atalho de responder em lote pela tabela de metas deixou de existir.

Quarto ajuste: o modal "Ajuste Indicador em Lote" (ajusta `pct_individual` de vários colaboradores selecionados de uma vez) tinha um campo de texto livre "Percentual Individual (0 a 100)". Mesmo raciocínio das rodadas anteriores — o RH só usa esse ajuste em lote pra dois casos reais ("considerar atingido, mesmo quem não bateu a meta" ou "desfazer o ajuste manual") — trocado por dois botões, "Sim" (aplica `pct_individual=100` a todos os selecionados) e "Reverter" (chama a action `recalcular` de cada colaborador selecionado, voltando ao cálculo automático). Nenhuma mudança de backend — os dois endpoints por-colaborador já existiam (PATCH e `recalcular`), só o disparo em paralelo (`Promise.all`) mudou de "um valor pra todos" pra "uma ação pra todos". Ajustado de novo logo em seguida: "Reverter" e "Sim" (renomeado pra "Ajustar") viraram os dois `btn-solid`, mesma cor — só "Cancelar" ficou `btn-outline` — já que as duas ações são igualmente "reais", não uma primária/secundária.

Quinto ajuste: o checkbox "Só com honorário não encontrado" (filtrava a lista de colaboradores pra só quem tinha alguma empresa sem honorário) virou um botão dedicado, "Visualizar Empresas sem Honorário" (com contador), que abre um modal próprio. Pedido explícito do usuário: a mesma empresa pode aparecer sob mais de um colaborador (um responsável pelo balancete, outro pela liberação fiscal, outro pela conciliação financeira) — preencher o honorário uma vez deve valer pra todos eles de uma vez, já que o honorário é da empresa, não da pessoa. Isso não era possível antes: o campo de preencher honorário existente (`PATCH /api/indicadores-apuracoes-empresas/{id}/`) só ajustava uma linha por id.

O que foi construído: o modal agrupa as `IndicadorApuracaoEmpresa` com `honorario_nao_encontrado=True` da apuração por `codigo_empresa` (mostrando os colaboradores/tipos responsáveis por cada uma), com um campo de honorário por grupo. Novo endpoint `POST /api/indicadores-apuracoes/{id}/ajustar-honorario-empresa/` (`IndicadorApuracaoViewSet.ajustar_honorario_empresa`, serializer `IndicadorApuracaoAjusteHonorarioEmpresaSerializer`) atualiza **todas** as linhas com aquele código na apuração de uma vez, recalculando cada colaborador afetado — mesmo padrão de `ajustar_grupo`/`ajustar_departamento` (aplicar uma mudança a um escopo de uma vez, não registro a registro). O endpoint por-linha antigo continua existindo, usado pela tabela "Empresas" de dentro do card do colaborador (caso raro de querer corrigir só uma linha). Nenhuma migração — só um endpoint novo, sem campo novo no model.

Bug corrigido logo depois de testar: numa apuração com muitas empresas sem honorário, o modal crescia além da altura da tela (mesma causa raiz já documentada em `CLAUDE.md` pra `.calendar-day` — um filho de `flex-column` só rola em vez de esticar o pai quando o próprio pai também tem uma altura limitada e o filho tem `min-height:0`). Corrigido dando `max-height:85vh` a `.ind-esh-modal-card` e `overflow-y:auto`/`min-height:0` à lista (`.ind-esh-list`) — título, aviso e os botões de ação ficam sempre visíveis, só a lista de empresas rola internamente quando não cabe.

Sexto ajuste, três pedidos numa rodada só: (1) ao preencher o honorário (linha única ou em lote pelo modal novo), deixar uma nota "honorário ajustado manualmente" na tabela "Empresas" de dentro do card do colaborador — campo novo `IndicadorApuracaoEmpresa.honorario_ajustado_manualmente` (migração `0029`, junto com a mudança do item 2), marcado pelos dois caminhos de ajuste (linha única e em lote) e exposto no serializer; sem UI de reverter, já que não existe "automático" pra essa linha voltar (o código nunca casou com a planilha). (2) Listar as empresas por código, não por nome, na mesma tabela — trocado `IndicadorApuracaoEmpresa.Meta.ordering` de `["nome_empresa", "id"]` pra `["codigo_empresa", "id"]` (mesma migração `0029`). Bug reportado logo depois de testar: "80" e "503" apareciam no fim da lista, depois de "2134" — `codigo_empresa` é `CharField`, então ordenar só por ele é alfabético (`'8'`/`'5'` são "maiores" que `'1'`/`'2'` como caractere, mesmo o número sendo menor), não numérico. Corrigido (migração `0030`) ordenando primeiro por `Length("codigo_empresa")` e só depois pelo valor — pra códigos sem zero à esquerda, string mais curta é sempre número menor, então isso reproduz a ordem numérica certa sem precisar converter pra inteiro (que quebraria com erro de banco se algum código não fosse só dígitos). (3) Botão "Visualizar Empresas sem Honorário" ganhou cor de atenção (`--danger`, mesma linguagem visual do input/selo de honorário não encontrado) — não reaproveitado `.btn-danger-outline` (que tem `margin-right:auto`, pensado pra separar um botão "Excluir" dentro de `.modal-actions`, efeito colateral indesejado no toolbar) — classe própria `.ind-empresas-sem-honorario-btn` só com as cores.

Sétimo ajuste, testando o modal "Empresas sem Honorário" com dados reais: três pedidos. (1) Ordenar também por código nessa lista (estava só por nome) — reaproveitado o mesmo critério "tamanho da string primeiro" da correção anterior, agora também em JS (`empresasAgrupadasPorCodigo`), já que essa lista é montada em memória a partir do que já foi carregado, não vem de uma query com `Meta.ordering`. (2) Código antes do nome no cabeçalho de cada item — trocada a ordem dos dois `<span>` (`.ind-esh-codigo` primeiro), mesma ordem da tabela "Empresas" do colaborador (coluna "Código" antes de "Empresa"). (3) Um segundo botão/modal, "Verificar Empresas Ajustadas Manualmente", pra rever e **corrigir** um honorário já ajustado — antes só dava pra preencher uma vez (o modal "sem honorário" some da lista assim que `honorario_nao_encontrado` vira falso, sem nenhum caminho de volta pra editar de novo). Backend: o filtro de `ajustar_honorario_empresa` mudou de `honorario_nao_encontrado=True` pra `Q(honorario_nao_encontrado=True) | Q(honorario_ajustado_manualmente=True)` — o mesmo endpoint agora cobre preenchimento inicial e correção, sem endpoint novo. Frontend: as funções de agrupar/renderizar/salvar dos dois modais foram generalizadas (parametrizadas por um filtro e pelos ids de cada um) em vez de duplicadas; o modal de correção pré-preenche o campo com o valor atual (o de preenchimento inicial continua em branco).

Ajustado de novo na sequência, testando o segundo botão/modal recém-criado: o usuário pediu pra **não** ter um botão separado — "facilitando a usabilidade da ferramenta". Revertido pra um popup só: o botão/modal "Verificar Empresas Ajustadas Manualmente" foi removido, e sua lista virou uma segunda seção dentro do próprio popup "Empresas sem Honorário" (`.ind-esh-section-title` como divisor), embaixo da lista original. As duas listas passaram a viver num wrapper único que rola (`.ind-esh-scroll`), com o título e o botão "Fechar" sempre visíveis fora dele — antes cada modal tinha sua própria rolagem. `renderEmpresasHonorario()` (nova função) renderiza as duas listas de uma vez, tanto ao abrir o popup quanto depois de qualquer "Salvar" — necessário porque corrigir uma empresa "sem honorário" faz ela migrar pra seção "ajustada manualmente" na hora, então as duas sempre precisam refletir o estado atual juntas. Nenhuma mudança de backend nesta correção.

Ajustado uma terceira vez, testando a versão com as duas seções sempre visíveis: pedido pra a seção "ajustadas manualmente" ficar escondida por padrão, atrás de um botão no final do modal — "lá seja possível a correção" quando o usuário quiser ver. Adicionado `#ind-empresas-ajustadas-toggle-btn` (largura cheia, com contador, alterna "Visualizar"/"Ocultar Empresas Ajustadas Manualmente (N)") logo depois da lista principal, escondendo `#ind-empresas-ajustadas-section` por padrão (`hidden`, resetada a cada abertura do popup) e só renderizando/mostrando a lista quando o botão é clicado. `renderEmpresasHonorario()` ajustada pra só re-renderizar a seção "ajustadas" se ela já estiver aberta — evita trabalho à toa quando ela está escondida, mas mantém sincronizada se o usuário já estiver com ela visível ao salvar algo na lista principal. Nenhuma mudança de backend.

### 39. Indicador de Desempenho: checklist de validação por colaborador

Pedido: um checkbox no início de cada card de colaborador (tela de revisão), pra o RH marcar quem já validou — ao marcar, a borda do card fica verde, pra dar visibilidade de quem ainda está pendente numa apuração com muitos colaboradores.

O que foi construído: campo novo `IndicadorApuracaoColaborador.validado` (migração `0031`) — booleano simples, sem relação com nenhum cálculo (nem participa de `calculo.recalcula_colaborador`). Novo endpoint `POST /api/indicadores-apuracoes-colaboradores/{id}/marcar-validado/` só grava esse campo. Diferente de todos os outros ajustes desta tela (que recarregam a apuração inteira e re-renderizam tudo depois de qualquer mudança), marcar/desmarcar o checklist atualiza só o card clicado no DOM, sem recarregar nem re-renderizar a lista inteira — decisão deliberada, já que essa ação tende a ser repetida muitas vezes seguidas numa conferência longa, e um refresh completo fecharia outros cards já expandidos e resetaria a posição de rolagem a cada clique. Erro de rede reverte o checkbox e o estado local, mesmo padrão de outros toggles imediatos do app.

Detalhe de acessibilidade descoberto ao implementar: o gate de clique que expande/recolhe o card no cabeçalho precisou excluir o `<label>` inteiro do checkbox, não só o `<input>` — clicar na área do label fora do glifo do checkbox dispara dois eventos de clique encadeados (um no label, outro sintético no input), e só excluir o input pelo seletor deixava o primeiro clique (target=label) passar batido, expandindo/recolhendo o card ao mesmo tempo que marcava/desmarcava o validado.

### 40. Indicador de Desempenho: corrigir o responsável por uma empresa/papel

Pedido, com exemplo concreto: a empresa 168 (MULTIVERSA CONSULTORIA LTDA) tinha "Valéria Bonete — Fiscal" como responsável, mas devia ser "Alan Lima Cassulli — Fiscal". Ou seja, reatribuir qual colaborador responde por um papel (tipo) de uma empresa — diferente de tudo que já existia na tela (honorário, percentuais), que nunca mexia em **quem** é o responsável, só em valores.

O que foi construído: novo botão "Corrigir Responsável" (popup próprio, busca por nome/código entre **todas** as empresas da apuração — não só as com honorário pendente) — selecionar uma empresa mostra a mesma lista de responsáveis já usada no popup "Empresas sem Honorário" ("Nome — Tipo"), mas agora com um `<select>` por linha pra escolher outro colaborador da apuração. Novo endpoint `POST /api/indicadores-apuracoes-empresas/{id}/trocar-responsavel/` (`IndicadorApuracaoEmpresaViewSet.trocar_responsavel`) só troca a FK `colaborador` da linha (`codigo_empresa`/`tipo`/honorário continuam intactos) e recalcula os **dois** colaboradores envolvidos — o que perdeu a empresa e o que ganhou, já que o conjunto de empresas de cada um mudou. Validações no backend: o novo colaborador precisa existir na mesma apuração, não pode ser o mesmo de já é, e não pode já ser responsável por essa mesma empresa/tipo (evitaria duas linhas duplicadas). O `<select>` de cada linha já exclui o colaborador atual das opções e nasce num placeholder desabilitado, pra nunca reatribuir sem escolha explícita do usuário. Nenhuma migração — só um endpoint novo, reaproveitando o model existente.

Ajuste pequeno na sequência, no botão "Visualizar Empresas sem Honorário" (popup "Empresas sem Honorário", rodada anterior): ele continuava vermelho e com o mesmo texto mesmo quando não havia mais nenhuma empresa pendente. Pedido: nesse caso, o botão devia virar "Visualizar Empresas com Honorário Ajustado" e perder a cor de atenção, já que não há mais nada de errado pra resolver. `atualizarBotaoEmpresasSemHonorario()` (JS) passou a alternar a classe `.ind-empresas-sem-honorario-btn` (antes fixa no HTML, agora só aplicada via JS quando `semHonorario > 0`) e o texto do botão conforme o total de empresas pendentes.

### 41. Indicador de Desempenho: filtro por setor organizacional, com meta de Departamento própria por setor

Pedido, olhando a tabela "Metas de Grupo e Departamento" real (competência 2026-07, 43 colaboradores): trocar o filtro por gerente por botões de departamento/setor no topo da revisão — selecionar um setor (ex.: "Fisco/Contábil") devia restringir a tabela de Metas a só a linha de Departamento daquele setor + os gerentes dele, e a lista de colaboradores abaixo a só quem tem esses gerentes. O pedido também trazia uma regra de negócio concreta: "Contabilidade" e "Fiscal / Tributário" formam um setor só ("Fisco/Contábil"); os demais setores são independentes; os próprios líderes do Fisco/Contábil (João Candido Rodrigues, Lhais Vergilio Delavy, Paloma Ramão, Elizangela dos Santos) deviam aparecer num setor à parte, "Gerentes"; e Luciane Gonzaga no setor "Rocket".

Antes de implementar, esclarecido com o usuário (a mudança tinha implicações que iam além de "só um filtro visual", ver perguntas feitas): (1) cada setor passaria a ter sua própria meta de Departamento (`pct_departamento`), não mais um valor único pra toda a apuração — escolhido em vez de manter uma meta global só filtrada na tela; (2) a associação pessoa→setor devia ser um cadastro editável, não fixo no código — mas o usuário revelou, na sequência, que o setor de cada colaborador **já existe** como coluna ("departamento") na planilha Serviços Tareffa, então não precisava de um cadastro manual pra maioria dos casos.

Investigado o arquivo real (`projects/Indicadores/Serviços Tareffa.xlsx`) pra confirmar: a coluna "departamento" tem valores "Contabilidade"/"Fiscal / Tributário"/"Rocket"/"Condomínio"/"Pessoa Física IRPF"/"Auditoria Fisco/Contábil" por linha de serviço. Rodando a extração real dos 43 colaboradores da apuração existente, confirmou-se que os 4 líderes citados pelo usuário têm o setor bruto da planilha igual ao setor operacional de quem lideram (ex.: João Candido Rodrigues aparece como "Contabilidade", não "Gerentes") — ou seja, a fusão automática Contabilidade/Fiscal→Fisco/Contábil não bastava pra colocá-los em "Gerentes"; só Luciane Gonzaga já vinha certa ("Rocket") sem precisar de nada extra.

**O que foi construído** (ver CLAUDE.md → "Setor organizacional" pro detalhe técnico completo):
- Campo novo `IndicadorApuracaoColaborador.setor` (migração `0032`) — valor bruto da coluna "departamento" da planilha, lido em `leiaute.le_servicos_tareffa` (campo novo `LinhaTareffa.setor`) e propagado por `pipeline.processa_apuracao` até o colaborador (primeira ocorrência por responsável, mesmo padrão já usado pra `gerente`).
- Model novo `IndicadorSetorApelido` (nome do colaborador → setor) — cadastro persistente e editável (aba "Apelidos de Setor" em Configurações, `/api/indicadores-setores-apelidos/`, CRUD completo) pros casos em que o setor bruto da planilha não reflete o setor "de verdade" da pessoa (os 4 líderes). Cadastrados no ambiente local: os 4 nomes → "Gerentes".
- `portal_api/indicadores/setores.py` (novo módulo, sem ORM direto além de ler `IndicadorSetorApelido`): `resolve_setor(nome, setor_bruto, apelidos)` aplica o apelido se existir, senão funde "Contabilidade"/"Fiscal / Tributário" em "Fisco/Contábil" (`FUSAO_SETORES`) e usa o valor bruto como está pros demais (Rocket, Condomínio, Pessoa Física IRPF, ...) — nenhum código novo é necessário quando um setor novo aparecer na planilha.
- `pct_departamento` deixou de ser ajustado/recalculado pra **toda** a apuração de uma vez — `IndicadorApuracaoViewSet.ajustar_departamento`/`recalcular_departamento` agora recebem `setor` no corpo e aplicam só aos colaboradores daquele setor (`setores.colaboradores_do_setor`), mesma mecânica que `ajustar_grupo`/`recalcular_grupo` já usavam por gerente.
- Frontend (`indicador-desempenho.js`): removido o `<select id="ind-filtro-gerente">`; adicionados botões de setor (`#ind-filtro-setor`, `.ind-setor-chip`) no topo da seção de Metas — clicar num setor filtra tanto a tabela de Metas (uma linha "Departamento (todo o &lt;setor&gt;)" + as linhas de Grupo só dos gerentes daquele setor) quanto a lista de colaboradores abaixo. Campo `setor_bucket` (`SerializerMethodField`, já resolvido no servidor) exposto por colaborador.
- **Apurações criadas antes desta mudança** ficam com `setor` em branco — feito um backfill pontual, via `manage.py shell`, lendo de novo a planilha Tareffa já anexada à única apuração existente no ambiente (competência 2026-07); não existe management command dedicado pra isso ainda, caso surja uma apuração antiga sem o arquivo disponível.

Validado contra os dados reais da apuração existente antes de considerar pronto: sem apelido, o agrupamento automático já dava Fisco/Contábil=35 (incluindo os 4 líderes) + Condomínio=4 + Pessoa Física IRPF=1 + Rocket=2 + Auditoria Fisco/Contábil=1; com os 4 apelidos cadastrados, o resultado bateu exatamente com o pedido: Fisco/Contábil=32 (gerentes "João Candido Rodrigues"/"Lhais Vergilio Delavy"), Gerentes=4, Rocket=2, Condomínio=4, Pessoa Física IRPF=1.

### 42. Indicador de Desempenho: três ajustes rápidos de usabilidade na tela de revisão

Testando a rodada 41 no navegador, três pedidos pequenos em sequência:

1. **Info no "Honorário Ajustado"**: pedido, com print, de um botão de informação ao lado do cabeçalho da coluna "Honorário Ajustado" (tabela "Empresas" de dentro do card do colaborador) — ao clicar, abre um popup pequeno explicando que o valor é o honorário proporcionalizado ao percentual do Indicador atingido, já mostrando o percentual real daquele colaborador (não um texto genérico). Não existia nenhum componente de popover/tooltip no projeto — construído do zero (`.ind-info-wrap`/`.ind-info-btn`/`.ind-info-popover` em `indicador-desempenho.css`), inspirado no mesmo mecanismo de `.notif-dropdown` (`notifications.js`): botão "i" (`data-ind-info-toggle`) alterna um `<span>` posicionado em `absolute` logo abaixo, e um listener em `document` fecha ao clicar fora. Como o botão fica dentro de um `<th>` (que tem `text-transform: uppercase`/fonte pequena via `.pa-table th`), o popover precisou resetar essas propriedades pra virar texto normal de novo. Todo o texto (incluindo o percentual) é montado em `renderHonorarioAjustadoInfoHtml(colaborador)`, chamada por colaborador ao montar a tabela — sem mudança de backend, `pct_individual` já vinha no payload.
2. **Filtro por setor no "Ajuste Indicador em Lote"**: o modal já tinha busca por nome; pedido pra também poder filtrar por departamento/setor. Adicionado um `<select id="ind-lote-global-setor">` (opções = setores distintos da apuração, via `pidIndAgruparPorSetor`) que combina (E lógico) com a busca por nome — os dois filtros juntos decidem quem aparece no checklist e quem "Marcar todos os resultados da busca" marca. Nenhuma mudança de backend (filtragem 100% em memória sobre `colaborador.setor_bucket`, já exposto desde a rodada 41).
3. **Modal de seleção pra "Gerar Recibos"**: antes, o botão gerava na hora pra **todos** os colaboradores da apuração, sem escolha. Pedido: abrir um modal parecido com o de "Ajuste Indicador em Lote" — mesma busca por nome + filtro por setor + checklist com "marcar todos os resultados da busca" — permitindo gerar recibo de um colaborador só, de alguns específicos, de um setor inteiro, ou de todo mundo. Implementado reaproveitando exatamente o mesmo padrão de UI do item 2 (funções/variáveis próprias, prefixo `gerarRecibos*`, sem duplicar `loteGlobal*`), com uma diferença deliberada: o checklist já nasce com **todo mundo marcado** ao abrir (reproduz o comportamento antigo — gerar pra todos — sem exigir que o RH marque um por um; ele só desmarca quem não quer incluir desta vez).

   Mudança de backend: `IndicadorApuracaoViewSet.gerar` passou a aceitar `colaborador_ids` (lista, opcional) no corpo — sem isso, gera pra todos (comportamento antigo); com isso, gera só pra quem foi pedido, validando que todos os ids pertencem à apuração (400 caso contrário). Decisão tomada sem perguntar, por ser a leitura mais correta do dado: a apuração só é marcada `concluida` quando a seleção pedida cobre **todos** os colaboradores (sem filtro, ou uma seleção que bate com o total) — gerar um recibo avulso pra conferência não deveria fechar a apuração inteira como se o mês tivesse sido todo revisado. Validado via `django.test.Client` logado como `gabriel`: geração parcial (1 colaborador) manteve `status="revisao"`; geração de todos marcou `concluida`; um id de outra apuração devolveu 400. O estado real da apuração no ambiente local (já estava `concluida` de um uso anterior) foi restaurado ao original depois do teste.

### 43. Indicador de Desempenho: três ajustes no PDF do recibo

Pedido com print real do PDF gerado (colaborador com o Individual ajustado manualmente pra 100%, e colaborador Natan da Costa com a tabela de Empresas ilegível):

1. **Banner "PERCENTUAL DO INDICADOR INDIVIDUAL" mostrava o valor pago, não o medido**: quando o RH/Diretoria ajusta o percentual Individual manualmente (`pct_individual_ajustado_manualmente=True`), `colaborador.pct_individual` passa a guardar só o valor sobrescrito — o percentual real medido (a composição dos 3 níveis) não ficava salvo em lugar nenhum depois do ajuste. Pedido: o banner deve sempre mostrar o valor **efetivo/medido** (ex.: 74,29%), independente do ajuste; embaixo, a linha que dizia "Percentual individual ajustado manualmente pelo RH" devia virar "Percentual Individual Ajustado Pela Direção" **com o percentual ajustado ao lado** (ex.: 100%) — os dois números lado a lado, pra ficar claro o que foi atingido e o que foi considerado.

   Implementado sem duplicar a fórmula: `calculo.composicao_individual()` (já calculava os 3 níveis brutos pra exibição no card de revisão) ganhou uma chave nova, `total_calculado` — a mesma composição ponderada (`_combina_niveis`) que `recalcula_colaborador` teria gravado em `pct_individual` se não houvesse ajuste manual, calculada ali mesmo a partir dos níveis que a função já monta. `recibo.py._banner_percentual` passou a mostrar `composicao["total_calculado"]` no banner principal (sempre o medido) e, só quando `pct_individual_ajustado_manualmente`, uma linha extra com o rótulo novo + `colaborador.pct_individual` (o valor pago).

2. **"Total Resultado" → "Total do Indicador"**: troca simples de rótulo na última linha da tabela "Empresas" (`_tabela_empresas`).

3. **Overflow generalizado na tabela "Empresas"** (causa raiz do "texto da coluna Tipo tapando o Hon. Ajustado" e dos valores da linha de total "ultrapassando as linhas"): toda célula da tabela, exceto "Empresa", era uma **string solta**, não um `Paragraph` — string solta não quebra linha dentro da largura da coluna; combinado com `ALIGN` à direita (aplicado a todas as colunas de valor, inclusive "Tipo" sem querer) ou ao negrito da linha de total (mais largo que a mesma string em peso normal), um valor mais largo que a coluna vazava visualmente por cima da célula vizinha em vez de quebrar linha — daí "Contador (com conciliador)" (right-aligned, mais largo que a coluna de Tipo) vazar pra esquerda cobrindo Hon. Ajustado, e os totais em negrito vazarem na última linha mesmo cabendo em peso normal. Corrigido convertendo toda célula em `Paragraph` com um estilo de alinhamento próprio (`celula_centro`/`celula_direita`/`celula_negrito`/`celula_direita_negrito`, novos em `_estilos()`) — agora qualquer valor mais largo que a coluna quebra em duas linhas em vez de vazar. Coluna "Tipo" também ganhou um dicionário de labels curtos só pro PDF (`TIPO_LABEL_CURTO`: "Contador SC"/"Contador CC" em vez de "Contador (sem/com conciliador)", abreviação que já era usada informalmente na documentação do projeto) — o label completo não cabia nem quebrando linha numa coluna estreita. Larguras de coluna também redistribuídas (Tipo de 1,5 pra 2,2cm, usando os ~1,3cm de folga que a tabela tinha sobre a largura útil da página A4).

   Validado gerando de verdade os PDFs de "Alan Lima Cassulli" (sem ajuste manual — banner mostra só o medido, sem linha extra) e "Natan da Costa" (com ajuste manual pra 100% — banner mostra 81,74% medido + linha "Percentual Individual Ajustado Pela Direção: 100,00%") a partir da apuração real do ambiente, lendo o PDF gerado de volta pra conferir visualmente — tabela "Empresas" sem nenhum vazamento em nenhum dos dois casos, "Contador CC"/"Contador SC" legíveis na coluna Tipo, "Total do Indicador" com os 4 valores certos sem sobrepor.

### 44. Indicador de Desempenho: recibo em PDF — "R$" separando do valor + capitalização do rótulo

Testando a rodada 43 com valores maiores (ex.: R$ 27.710,19), dois ajustes finos:

1. **"R$" quebrando pra uma linha acima do valor**: ao converter as células da tabela "Empresas" pra `Paragraph` (rodada 43), o espaço comum entre "R$" e o número virou um ponto de quebra de linha válido — quando o valor não cabia numa linha só, o reportlab quebrava bem ali, deixando "R$" sozinho acima do número em vez de vazar (o bug da rodada anterior), mas ainda longe do ideal. Pedido: "R$" deve estar sempre do lado esquerdo do valor, nunca acima. Trocado o espaço comum por `&nbsp;` (não separável) em `_moeda()` — sozinho isso só moveu o ponto de quebra pra dentro do próprio número (ex.: "R$ 27.710,1" / "9"), então a correção completa também exigiu abrir mais espaço de verdade pras colunas: `LEFTPADDING`/`RIGHTPADDING` da tabela reduzidos de 6pt (padrão do reportlab) pra 3pt, e as larguras das colunas Honorário/Hon. Ajustado/Indiv./Grupo/Depto./Total redistribuídas (tirando um pouco de Código e Empresa, que tinham folga de sobra) pra caber o maior valor real visto na apuração (R$ 28.023,16) numa linha só, com padding.
2. **Capitalização do rótulo**: "Percentual Individual Ajustado Pela Direção" (Title Case) virou "Percentual individual ajustado pela direção" (só a primeira letra maiúscula).

Validado regerando os mesmos dois recibos da rodada 43 (Alan Lima Cassulli, Natan da Costa) — inclusive o valor mais alto da apuração inteira (R$ 28.023,16, CELLSHOP DUTY FREE no recibo de Natan da Costa) coube numa linha só, "R$" sempre grudado à esquerda do número, em toda a tabela e na linha de total.

### 45. Indicador de Desempenho: Departamento como entidade própria — critérios e percentuais por departamento

Pedido: "vamos passar a apurar as metas e regras por departamento" — critérios e percentuais deixam de ser globais (uma regra só pra toda a apuração) e passam a ser por departamento (ex.: a regra do Fisco/Contábil pode ser diferente da do Condomínio). Duas exigências explícitas: (1) precisa de um cadastro de verdade de departamentos, com relação a gerentes — um departamento pode ter mais de um gerente (ex.: Fisco/Contábil tem João Candido Rodrigues **e** Lhais Vergilio Delavy); por enquanto essa relação é mantida manualmente pela própria aplicação (alimentar da planilha fica pra decidir depois); (2) por enquanto replicar a mesma regra em todo departamento, mas a estrutura já precisa suportar customização.

**Decisão tomada com o usuário antes de implementar** (rodada consultada via pergunta direta, dado o tamanho da mudança): o novo cadastro de Departamento **substitui por completo** o mecanismo de "setor" da rodada 41 (coluna bruta da planilha + fusão automática + `IndicadorSetorApelido`) — fica só um conceito de departamento no sistema, usado tanto pras Metas quanto agora pra critérios/percentuais. O caso que o apelido resolvia (os 4 líderes de Fisco/Contábil) passa a ser coberto mapeando a gerente deles, "Elizangela de Paula Kuhn", pro departamento "Gerentes".

**O que foi construído** (ver CLAUDE.md → "Departamento organizacional" pro detalhe técnico completo):
- Dois models novos: `IndicadorDepartamento` (nome/ativo) e `IndicadorDepartamentoGerente` (gerente→departamento, `nome_gerente` único — um gerente só pertence a um departamento, mas um departamento aceita vários gerentes).
- `IndicadorCriterio`/`IndicadorPercentualTipo` ganharam FK obrigatória `departamento` — cada departamento passa a ter seu próprio histórico de critérios/percentuais, de verdade (não é mais um bucket calculado, é uma tabela filtrada por FK).
- `IndicadorApuracaoColaborador.setor` (texto) virou `departamento` (FK nullable) — resolvido uma vez na criação da apuração, a partir do `gerente` do colaborador via `IndicadorDepartamentoGerente` (não mais da coluna bruta da planilha). Sem mapeamento pro gerente, o colaborador fica com `departamento=None` e vira um aviso no processamento.
- `pipeline.processa_apuracao()` também passou a agrupar os **critérios automáticos** por departamento (`criterios_automaticos_por_departamento`) — cada colaborador só calcula os critérios do **seu** departamento, não mais todos os critérios ativos da apuração.
- Migração em 3 passos (schema com FK nullable → `RunPython` criando "Fisco/Contábil" e apontando todo critério/percentual já existente pra ele, já que era literalmente o que a regra única representava → schema tornando a FK obrigatória) — mesmo padrão de qualquer FK NOT NULL adicionada numa tabela já populada.
- `seed_indicador_desempenho.py` ajustado pra criar/reaproveitar o departamento "Fisco/Contábil" antes de popular critérios/percentuais (senão quebraria ao rodar de novo, já que os models agora exigem departamento) — testado rodando de novo: atualizou os 7 critérios e reconheceu os 5 percentuais já existentes, sem duplicar nada.
- Tela de Configurações: aba "Apelidos de Setor" virou aba "Departamentos" (cadastro de departamentos + botão "Gerenciar Gerentes" por linha, popup com lista de gerentes daquele departamento + campo pra adicionar um novo). Abas "Critérios" e "Percentuais por Tipo" ganharam um filtro por departamento no topo + coluna "Departamento" na tabela + campo obrigatório de departamento no modal de adicionar. Filtro de Metas/"Ajuste Indicador em Lote"/"Gerar Recibos" (todos já existentes desde a rodada 41) tiveram a chave de agrupamento trocada de string (`setor_bucket`) pra id (`departamento`), mesma mecânica visual.

Validado via `django.test.Client` (login `gabriel`): criados 4 departamentos de teste + 6 relações gerente→departamento reproduzindo a estrutura real conhecida (Fisco/Contábil: João Candido Rodrigues + Lhais Vergilio Delavy; Rocket: Luciane Gonzaga; Condomínio: Cristiano Silverio; Pessoa Física IRPF: Daniel Gustavo Manenti; Gerentes: Elizangela de Paula Kuhn) e gerada uma apuração de teste de verdade com os 2 arquivos reais — distribuição resultante: Fisco/Contábil 32, Gerentes 5, Rocket 1, Condomínio 4, Pessoa Física IRPF 1 (só os colaboradores de Fisco/Contábil ganharam respostas de critério, já que só esse departamento tem critérios cadastrados — esperado). Tudo (apuração de teste, departamentos de teste, relações de teste) removido depois do teste, mantendo só o "Fisco/Contábil" real criado pela migração.

**Limitação real encontrada nesse teste, documentada em CLAUDE.md**: resolver o departamento pelo `gerente` (não mais pelo colaborador individual) quebra o caso de uma gerente que supervisiona pessoas de departamentos diferentes — "Elizangela de Paula Kuhn" supervisiona os líderes de Fisco/Contábil **e** Luciane Gonzaga (que deveria cair em "Rocket", não em "Gerentes" junto com os outros). Como não existe mais uma exceção por colaborador individual (o antigo `IndicadorSetorApelido` cobria isso), Luciane Gonzaga passou a cair em "Gerentes" nesse teste — diferente do que a rodada 41 tinha estabelecido pra ela (Rocket). Sinalizado ao usuário como limitação conhecida do novo desenho; não corrigido nesta rodada por não ter sido pedido, e porque reintroduzir uma exceção por colaborador contrariaria a decisão de "só um mecanismo" tomada no início desta rodada — só mexer nisso se o usuário confirmar que quer.

### 46. Indicador de Desempenho: sugestões de gerente no popup "Gerenciar Gerentes"

Pedido, testando a rodada 45: o campo "Adicionar gerente" era só texto livre — o usuário pediu pra já vir preenchido com os nomes de gerente encontrados na última apuração, pra só precisar relacionar (clicar) em vez de redigitar cada nome (risco real de typo, já que o nome precisa bater exatamente com a coluna "gerente" da planilha pra apuração futura casar com o departamento certo).

Implementado 100% no frontend, sem endpoint novo: `carregarGerentesSugeridos()` busca a apuração mais recente (`GET /api/indicadores-apuracoes/`, a lista já vem ordenada por `-competencia`/`-criado_em` via `IndicadorApuracao.Meta.ordering` — não precisou de parâmetro novo), pega o detalhe dela (`GET /api/indicadores-apuracoes/{id}/`) e extrai os nomes distintos de `colaborador.gerente`, excluindo os que já estão em `departamentoGerentesConfig` (já mapeados pra algum departamento). O popup "Gerenciar Gerentes" ganhou uma seção "Sugestões" entre a lista atual e o campo de texto — cada sugestão é um botão (`.checklist-item` reaproveitado como `<button>`, mesmo padrão já usado em "Corrigir Responsável"/`.ind-corrigir-resultado`) que, ao ser clicado, já chama `POST /api/indicadores-departamentos-gerentes/` pra aquele departamento. Lista recarregada (`carregarGerentesSugeridos()` de novo) depois de qualquer adição/remoção de gerente, em qualquer departamento, pra manter as sugestões sempre refletindo quem ainda falta mapear. O campo de texto livre continua disponível, pra gerentes que não apareceram na última apuração (colaborador novo, ainda sem apuração processada).

Validado com a apuração real do ambiente: as sugestões bateram exatamente com os 6 gerentes conhecidos (João Candido Rodrigues, Lhais Vergilio Delavy, Cristiano Silverio, Daniel Gustavo Manenti, Luciane Gonzaga, Elizangela de Paula Kuhn), já que nenhum deles está mapeado ainda no ambiente.

### 47. Bug: `SuspiciousFileOperation` ao anexar arquivo com nome muito longo na Importação de Plano de Saúde

Testando em produção real, upload de um arquivo da operadora com nome de arquivo original bem longo (ex.: "LEIAUTE_IMPORTACAO_DESPESAS_MEDICAS_EMP_92_PRESCINOTTI_CIA_LTDA...OPER_5060_UNIMED_DO_ESTADO_DO_PARANA_-_FEDERACAO_ESTADUAL_DA.CSV") deu 400 com `django.core.exceptions.SuspiciousFileOperation: Storage can not find an available filename ... Please make sure that the corresponding file field allows sufficient "max_length"`.

Causa: `ImportacaoPlanoSaude.planilha_padrao`/`arquivo_operadora` (`FileField`) não tinham `max_length` explícito — o padrão do Django é 100, insuficiente pra `upload_to="planos_saude/planilha_padrao/"` (ou `.../operadora/`) somado a um nome de arquivo original longo (nome de arquivo real do cliente, fora do controle do Portal) + o sufixo que a storage acrescenta pra evitar colisão.

Corrigido definindo `max_length=255` nos dois campos (`portal_api/models.py`, migração `0036_alter_importacaoplanosaude_arquivo_operadora_and_more`, aplicada no ambiente local). Mesmo cuidado vale pra qualquer `FileField`/`ImageField` novo que aceite nome de arquivo originado fora do Portal (upload do usuário) — o padrão de 100 caracteres do Django é apertado demais pra nomes de arquivo reais de operadoras/clientes.

### 48. Banco de regras de custeio salvas na Importação de Plano de Saúde

Pedido do usuário, testando a importação da empresa 92 (Unimed): em vez de exportar/importar um arquivo `.json` com a regra de custeio preenchida (mecanismo puramente client-side, sem persistência — nada guardado no banco, sem nome, sem observação), ele queria um banco de regras de verdade: salvar a configuração usada como "092 - Unimed", escolhê-la numa lista em importações futuras, poder editá-la depois e anexar uma observação livre (ex.: "Empresa não desconta plano do empregado XX").

O que mudou:

- **Model novo** `RegraCusteioPlanoSaude` (migração `0037_regracusteioplanosaude`) — `nome`/`operadora`/`tipos_lancamento`/`custeio_por_tipo` (mesmo formato dos campos homônimos de `ImportacaoPlanoSaude`) + `observacoes` (texto livre) + `criado_por`/`criado_em`/`atualizado_em`. Lista compartilhada, sem "dono", mesma permissão de toggle único da ferramenta (`PermissaoApp("utilitarios", "importacao-plano-saude")`).
- **`RegraCusteioPlanoSaudeViewSet`** (CRUD completo, GET/POST/PATCH/DELETE) registrado em `/api/regras-custeio-plano-saude/`, seguindo o mesmo padrão de `IndicadorPercentualTipoViewSet` (`perform_create` grava `criado_por`).
- **Validação de custeio extraída pra uma função compartilhada** (`_monta_regra_custeio()`, `serializers.py`) — antes só existia dentro de `ImportacaoPlanoSaudeCreateSerializer._valida_regra_especifica()`; extraída pra módulo-level e reaproveitada por `RegraCusteioPlanoSaudeSerializer.validate()`, pra não duplicar a regra de negócio (parsing BR, faixa 0–100 do percentual, "ao menos limite ou percentual") em dois serializers que podiam divergir com o tempo. `ImportacaoPlanoSaudeCreateSerializer` foi refatorado pra chamar essa mesma função — comportamento idêntico, validado com teste manual comparando a saída antes/depois do refactor.
- **Round-trip float↔texto BR**: uma regra salva volta do `GET` com `limite_valor`/`percentual` já como `float` (formato final persistido), mas a validação de entrada só entende texto BR (`"150,00"`). `_valor_custeio_para_texto_br()` normaliza um float de volta pra BR (via `formata_valor_br`, já existente em `leiaute_sistema.py`) antes de repassar pro parser — sem isso, reenviar uma regra sem editar o custeio (ex.: só corrigindo o nome) corromperia o valor (`"150.0"` seria lido como 15000 por `parse_valor_br`, que remove pontos como separador de milhar). Validado via shell: criar uma regra, pegar `validated_data` de volta e revalidar como se fosse um update sem mudanças reproduz exatamente o mesmo resultado.
- **Frontend** (`importacao-plano-saude.js`/`.html`/`.css`): a seção "Regra de custeio" do formulário de Nova Importação trocou os botões "Exportar regra"/"Importar regra" por um `<select>` de regras salvas + "Aplicar" (preenche o formulário inteiro, incluindo a operadora se ainda existir na lista — `aplicarRegraNoFormulario()`), "Salvar regra atual..." (abre `#ips-regra-save-modal` pra nomear/descrever, nascendo em modo "atualizar" quando a regra aplicada ainda existe, com uma checkbox pra virar "criar nova" em vez de sobrescrever) e "Ver regras salvas" (`#ips-regras-modal`, lista com Aplicar/Excluir por linha). "Editar" uma regra não é uma tela separada — é aplicar, ajustar o que quiser nos campos normais do formulário, e salvar de novo (decisão deliberada pra não duplicar a grade de custeio dentro de um segundo modal). A validação de "custeio completo pros tipos marcados" (`mensagemErroCusteio()`) foi extraída do handler do botão "Processar" pra ser reaproveitada por "Salvar regra atual..." também.
- Testado via Django test client (shell): criar/listar/atualizar/excluir uma regra pelo endpoint real, e confirmado que `criado_por` grava certo.
- **Ajuste de posição, no mesmo dia**: a pedido do usuário, a seção "Regra de custeio salva" moveu do final do formulário (depois de "Tipo de importação") pro **início**, antes até de "Operadora" — já que aplicar uma regra também preenche a operadora, faz mais sentido esse ser o primeiro passo do fluxo. A borda de separação (`.ips-regra-field`) virou `border-bottom` (era `border-top`), já que agora separa do campo abaixo (Operadora), não de cima.

### 49. Quarta operadora: Dental Uni Odonto

Usuário forneceu um PDF real ("1084 - RELATORIO DENTAL UNI 072026.pdf", relatório "BENEFICIÁRIOS") + a planilha padrão (leiaute Questor) já casada como referência, descrevendo o formato: coluna "Beneficiário" traz titular e dependentes juntos (dependentes com indentação um pouco maior), sem CPF pra ninguém, coluna "Valor Unit" é o valor a custear/descontar de cada um.

- **Novo parser** `operadoras/dental_uni/odonto_mensalidade.py` (`DentalUniOdontoMensalidade`), registrado em `pipeline.OPERADORAS` como `dental_uni_odonto_mensalidade`/"Dental Uni Odonto". `chave_casamento = "nome"` (sem CPF no arquivo, igual Unimed/Itamed) — só mensalidade (sem coluna de coparticipação nesse relatório).
- **Titular vs dependente por indentação, não por rótulo**: ao contrário da Itamed (que tem "Titula"/"Dependente" escrito no início da linha), este relatório não rotula nada — só indenta o texto do dependente um pouco mais que o do titular. O parser resolve isso comparando a indentação de cada linha com a indentação da primeira linha de beneficiário do arquivo (sempre um titular, por construção do relatório): igual ou menor → Titular; maior → Dependente.
- **Nome quebrado em duas linhas**: um titular do próprio exemplo ("SUZILAINE ZENATTI MEYER BEZERRA") tem o nome longo o bastante pra quebrar em duas linhas físicas no texto extraído do PDF, com o "[Nº Cartão]" só aparecendo na linha seguinte. O parser acumula linhas "órfãs" que parecem nome (só letras maiúsculas/espaços — nomes no relatório vêm 100% em caixa alta, o que distingue confiavelmente uma continuação de nome de qualquer outro texto do PDF, que nunca vem inteiramente maiúsculo) até encontrar a linha com o cartão, e usa a indentação da PRIMEIRA linha do bloco (não a da linha do cartão) pra decidir titular/dependente.
- **Extração do valor por padrão, não por posição de coluna**: como o número de datas antes do "Valor Unit" pode variar (ex.: uma linha com Data Exclusão preenchida teria uma data a mais), o parser não conta colunas — pega sempre o PRIMEIRO número no formato monetário (vírgula decimal) depois do "[Nº Cartão]", já que datas (`dd/mm/aaaa`) nunca coincidem com esse padrão. A coluna "Total Fam" (só preenchida na linha do titular, soma da família) é ignorada de propósito, mesmo espírito da "Valor Total" da Amil.
- **Validado com o exemplo real** (via script no shell do Django, não pelo formulário — ver caveat abaixo): os 11 lançamentos do PDF (4 famílias) foram extraídos corretamente, incluindo o nome quebrado em duas linhas, e o casamento com a planilha padrão fornecida bateu certo para 10 dos 11 — o 11º ("HELOISA NUNEZ RAMBO" no PDF vs "HELOISA NUNES RAMBO" na planilha, uma divergência real entre os dois arquivos de exemplo) caiu corretamente em auditoria (`NOME_DIVERGENTE`), exatamente o comportamento esperado (nunca resolvido por aproximação automática).
- **Caveat importante**: o parser foi escrito a partir do texto extraído do PDF mostrado na conversa, sem rodar o `pdfplumber` de verdade contra o arquivo binário (não ficou salvo em nenhum lugar acessível pelo ambiente de desenvolvimento). A indentação exata que o `pdfplumber` com `layout=True` vai produzir pro PDF real pode diferir da observada — o parser usa indentação *relativa* (comparada com a primeira linha do próprio arquivo, não um número fixo) exatamente para tolerar isso, mas só validar de verdade com o botão "Selecionar arquivo" (2. Arquivo da operadora) da tela de Nova Importação, que já chama esse parser isoladamente via `/importacoes-plano-saude/validar-arquivo/` sem precisar de uma importação completa — mesmo caminho que a Unimed também vai precisar percorrer antes de ter um PDF real (hoje `_extrai_pdf` da Unimed é só um `NotImplementedError` explícito por esse motivo).

### 50. Dois bugs corrigidos testando a Dental Uni com o PDF real

Dois problemas apareceram ao testar de fato (o "caveat" da rodada 49 se confirmou útil):

1. **Regressão em `ImportacaoPlanoSaudeDetailSerializer` (afetava TODAS as operadoras, não só a Dental Uni)**: `POST /api/importacoes-plano-saude/` dava 500 (`AttributeError: 'ImportacaoPlanoSaudeDetailSerializer' object has no attribute 'get_resumo_por_tipo'`) — o frontend mostrava só "Erro ao processar a solicitação." (mensagem genérica que `pidErrorMessageFrom()` usa quando a resposta não é JSON, ver `api.js`). Causa: ao inserir `RegraCusteioPlanoSaudeSerializer` logo depois de `ImportacaoPlanoSaudeDetailSerializer` na rodada 48, o método `get_resumo_por_tipo()` (que já existia, definido **depois** do `class Meta` da primeira classe) ficou fisicamente entre as duas — como Python não usa chaves pra delimitar classe, ele passou a pertencer à classe nova (`RegraCusteioPlanoSaudeSerializer`) por indentação, não à original. Corrigido movendo o método de volta pro lugar certo. Validado recriando uma importação completa via shell e conferindo que a serialização da resposta não quebra mais, além de reconfirmar que o CRUD de regras de custeio continua funcionando.
2. **Ordem de junção do nome quebrado em duas linhas estava invertida**: testando com o PDF real, "SUZILAINE ZENATTI MEYER" (titular) ficou sem "BEZERRA" (foi pra auditoria como pessoa não cadastrada, exigindo vínculo manual) e o dependente seguinte virou "BEZERRA JOAO LUCAS MEYER BEZERRA" (nem dava pra vincular, porque não existe ninguém com esse nome na planilha nem parecido o suficiente). A hipótese original (baseada só na inspeção visual do PDF, sem rodar o `pdfplumber` de verdade) era que o "[Nº Cartão]" e os valores apareciam *depois* de todas as linhas do nome; o comportamento real do `pdfplumber` é o oposto — o cartão/valores ficam grudados na *primeira* linha do nome, e o excedente (quando o nome quebra) sobra sozinho numa linha própria *depois*, antes do próximo beneficiário. Corrigido invertendo a lógica: cada linha com "[Nº Cartão]" agora é processada na hora (não espera nada depois dela); uma linha órfã em CAIXA ALTA sem colchete é anexada ao nome do **último** lançamento já adicionado (nunca ao próximo). Revalidado com um teste reproduzindo a estrutura real (cartão na linha do "SUZILAINE ZENATTI MEYER", "BEZERRA" sozinho na linha seguinte, "JOAO LUCAS MEYER BEZERRA" depois) — os 11 beneficiários das 4 famílias voltaram a bater certo, incluindo o titular com nome quebrado reconstituído corretamente e o dependente seguinte sem o prefixo indevido.

Lição prática: sem o PDF real rodando de fato no `pdfplumber`, a extração de texto mostrada por inspeção visual pode enganar sobre a ORDEM em que o excedente de uma célula quebrada aparece — vale sempre desconfiar de qualquer heurística de "juntar linhas" escrita sem testar contra o parser de verdade.

### 51. Bug (não específico da Dental Uni): planilha padrão em Windows-1252 quebrava a leitura

Testando com uma segunda empresa (planilha padrão com "SOPHIA FERNANDES GONÇALVES", um nome com "Ç"), o campo "1. Planilha padrão (Questor)" recusava o arquivo com "Este arquivo não parece ser a planilha padrão exportada do Questor...", mesmo o CSV tendo exatamente o cabeçalho esperado.

Causa: `le_planilha_padrao()` (`leiaute_sistema.py`) sempre abria o arquivo como `encoding="utf-8-sig"`, fixo. A planilha exportada do Questor, quando tem algum nome com acento, às vezes sai em **Windows-1252/ANSI**, não UTF-8 — decodificar um byte como `0xC7` ("Ç" em cp1252) como UTF-8 estoura `UnicodeDecodeError`. E como `_valida_planilha_padrao()`/`create()` capturam qualquer exceção genericamente (pra dar uma mensagem amigável quando o arquivo realmente está errado), o erro real (encoding) ficava escondido atrás da mensagem "não parece ser a planilha padrão" — nada a ver com o leiaute de colunas em si, que estava certo.

Corrigido com um fallback de encoding, mesmo espírito do `encoding="latin-1"` que o parser CSV da Unimed já usa: `_decodifica_planilha()` (nova função em `leiaute_sistema.py`) lê os bytes crus e tenta `utf-8-sig` primeiro (não muda nada pro caso comum sem acento, onde os bytes são idênticos nos dois formatos); só cai pra `cp1252` se a decodificação UTF-8 falhar. `le_planilha_padrao()` passou a ler de um `io.StringIO` sobre esse texto já decodificado, em vez de abrir o arquivo diretamente com um encoding fixo. Validado com teste cobrindo os 3 casos (UTF-8 sem BOM, UTF-8 com BOM, cp1252) e reproduzindo o arquivo real do usuário (17 beneficiários, valida certo agora).

Vale a mesma observação de robustez pro `arquivo_operadora` de qualquer operadora nova baseada em CSV (a Unimed já se protegeu disso; Dental Uni é PDF, não é afetada) — se aparecer o mesmo tipo de erro genérico de "formato não reconhecido" pra um CSV com acento, suspeitar de encoding antes de desconfiar do leiaute de colunas.

### 52. Quinta operadora: Unimed Oeste do Paraná

Usuário forneceu um PDF real ("Demonstrativo Junho.2026.pdf", "Resumo de Faturamento" emitido pela ACIME — associação comercial que fatura em nome da Unimed Oeste do Paraná) + a planilha padrão correspondente, descrevendo o formato: empregados e dependentes aparecem na coluna "Serviço/Produto", o TIPO (mensalidade/coparticipação) também é decidido por essa mesma coluna ("Convenio Unimed" = mensalidade, o resto = coparticipação), e o valor usado é "Val. Total".

- **Novo parser** `operadoras/unimed_oeste_pr/saude.py` (`UnimedOestePrSaude`), registrado em `pipeline.OPERADORAS` como `unimed_oeste_pr_saude`/"Unimed Oeste do Paraná" — **deliberadamente separado** do `unimed_saude` já existente, apesar do nome parecido: aquele espera um CSV com colunas próprias ("Id. Benef."/"Tipo Benef.", export direto da Unimed), este é um PDF de fatura da ACIME com um formato completamente diferente (nem CPF nem coluna de tipo dedicada). `chave_casamento = "nome"` (sem CPF no arquivo).
- **Cada pessoa pode ter mais de um "Nro." (contrato)** — ex.: "ALINE PATRICIA RAMOS" aparece em dois blocos "(T) ALINE PATRICIA RAMOS - Nro.: ..." com números de contrato diferentes (um pro plano base/Convênio, outro pro Aditivo de resgate aéreo). Por isso o parser agrupa por NOME (não por "Nro.", que varia por contrato da mesma pessoa), diferente de todas as operadoras anteriores que usavam um número de carteirinha/cartão estável por pessoa.
- **Tipo de lançamento decidido pelo texto da própria descrição, linha a linha** (não por bloco/contrato inteiro): dentro do MESMO bloco "Nro.", a linha "Convenio Unimed..." conta como mensalidade e a linha "Taxa Administrativa Unimed..." — que fica junto, no mesmo contrato — conta como coparticipação, por instrução explícita do usuário ("Convenio Unimed é o valor de mensalidade e os demais são coparticipação"). **Sinalizado ao usuário como algo a confirmar** — não é o desenho mais intuitivo (taxa administrativa normalmente anda junto do valor de mensalidade), mas foi implementado ao pé da letra da instrução recebida.
- **Duas variações de quebra de linha no PDF** precisaram de tratamento: (a) quando a coluna "Prestador" está vazia (ex. "ADITIVO UNIMED AIR TERRESTRE..."), a descrição e os 3 números (Qtd/Val.Unit/Val.Total) saem em linhas físicas separadas — o parser junta uma linha-só-texto com a linha-só-números que vem logo depois; (b) quando a coluna "Prestador" tem texto longo (ex. "ASSOCIACAO MISSIONARIA DE BENEFICENCIA DAS IRMAS SERVAS DO E"), esse texto transborda pra linha(s) DEPOIS dos números já lançados — como não sobra número nenhum nessas linhas de transbordo, elas são descartadas sem gerar lançamento extra (não precisamos do conteúdo de "Prestador" pra nada).
- **Validado com o PDF de exemplo completo**: reproduzindo as 4 pessoas (1 família de uma pessoa só + 1 família com titular e 2 dependentes), a soma de todos os lançamentos bateu exatamente com o "Total Faturados: 4.628,37" impresso no próprio PDF — confirma que nenhuma linha foi perdida nem contada em dobro, inclusive nos dois casos de quebra de linha acima. Casamento com a planilha padrão também testado (mensalidade e coparticipação separadas): as 4 pessoas casaram automaticamente, 0 itens de auditoria.
- Mesmo caveat das duas últimas rodadas: escrito a partir do texto extraído mostrado na conversa, sem rodar o `pdfplumber` de verdade contra o PDF binário — validar com o botão "Selecionar arquivo" antes de confiar em produção.

### 53. Regra de custeio salva: `<select>` virou combobox pesquisável

Com o banco de regras salvas crescendo (8 regras já cadastradas pelo usuário entre as 5 operadoras), o `<select>` nativo do campo "Regra de custeio salva" deixou de ser prático — sem busca, precisava rolar a lista inteira toda vez.

Trocado por um combobox pesquisável (`#ips-regra-combo`): um `<input type="text">` (`#ips-regra-search`) que funciona tanto como campo de busca quanto como "display" do valor selecionado, com uma lista flutuante (`#ips-regra-combo-list`, `position:absolute` abaixo do input) que filtra pelas regras cujo nome contém o texto digitado (case-insensitive) — abre no foco (mostrando todas) e a cada tecla digitada; fecha ao clicar fora (listener de `click` no `document`, checando `!ipsRegraCombo.contains(event.target)`) ou ao escolher um item. Mesmo espírito de busca+lista já usado em "Vincular pessoa", só que aqui o campo de busca dobra como o "valor exibido" no lugar de uma `<option>` selecionada.

Estado novo em JS: `regraSelecionadaId` (o que está de fato escolhido no combobox — diferente de `regraAplicadaId`, que reflete o que está refletido nos CAMPOS do formulário). Digitar de novo no campo depois de já ter selecionado algo invalida `regraSelecionadaId` até o usuário clicar numa regra da lista — sem isso, "Aplicar" poderia aplicar uma regra antiga enquanto o texto exibido já era outra busca, incoerência que o `<select>` antigo não tinha (mudar o texto de um `<select>` só é possível escolhendo uma opção de verdade).

`renderRegraSelect()` (populava as `<option>`) foi substituída por `renderRegraComboList(filtro)`; `refreshRegras()` deixou de re-renderizar um `<select>` inteiro e passou só a limpar a seleção se a regra escolhida tiver sido excluída em outro lugar enquanto isso (ex.: via o modal "Ver regras salvas").

### 54. Sexta cor de tema: Vermelho

Adicionada mais uma opção de tema de cor (`--accent`) ao seletor de swatches do modal "Gerenciar Usuário": "Vermelho" (`key: "vermelho"`, `#ef4444` no tema escuro / `#b91c1c` no tema claro), ao lado das 5 já existentes (roxo/azul/verde/âmbar/rosa). Só duas mudanças, já que a UI do seletor é gerada dinamicamente a partir de `PID_COLOR_THEMES` (`theme.js`, consumida por `account.js`): nova entrada no array `PID_COLOR_THEMES` e o par de blocos `:root[data-color-theme="vermelho"]`/`:root[data-theme="light"][data-color-theme="vermelho"]` em `tokens.css`, mesmo padrão das outras cores.

Como `--danger` (usado em feriados/selos de ausente etc.) já era um tom de vermelho (`#e5484d`) escolhido antes de "vermelho" existir como cor de tema selecionável, agora há uma sobreposição visual esperada quando o usuário escolhe o tema "Vermelho": elementos que usam `--accent` (ex.: pill "somente_eu" do Calendário Individual) ficam bem parecidos com elementos de erro/alerta que usam `--danger`. Diferente de `--gold`/`--teal`/`--slate`/`--coral` (rodada 35, escolhidos deliberadamente fora das cores de tema pra nunca colidir com `--accent`), `--danger` não foi criado pensando nisso — é uma coincidência aceita ao adicionar "Vermelho" à lista, não um bug. Se isso incomodar na prática, ajustar `--danger` para um tom fora da família "vermelho" é a correção futura, não mudar a cor do tema.

### 55. Regra de custeio salva: "Salvar regra atual..." movido pro final do formulário + botão "Limpar seleção"

Ajuste de usabilidade pedido pelo usuário na seção "Regra de custeio salva" do formulário de Nova Importação: "Salvar regra atual..." saiu de junto de Aplicar/Ver regras salvas (topo do formulário) e passou pro **final** (depois de "Tipo de importação", antes do botão "Processar") — salvar só faz sentido depois de parametrizar o custeio, é o último passo do fluxo, não um botão que deveria ficar ao lado de Aplicar. Aplicar/Limpar seleção/Ver regras salvas continuam no topo, já que aplicar uma regra continua sendo o primeiro passo natural (preenche operadora + custeio de uma vez).

Novo botão "Limpar seleção" (`#ips-regra-limpar-btn`, ao lado de Aplicar) resolve o caso de aplicar a regra errada por engano: desfaz tanto o rastreamento (`regraSelecionadaId`/`regraAplicadaId`, texto do combobox, observações) quanto o próprio custeio que a regra preencheu (tipos de lançamento, radios de custeio, limite/percentual de cada combinação tipo×pessoa) — as duas partes de `resetForm()` que faziam isso foram extraídas em `limparCusteioForm()`/`limparRegraSelecionada()` pra serem reaproveitadas aqui. De propósito não mexe em Operadora nem nos arquivos já anexados — só desfaz o que uma regra aplicada de fato preenche em massa.

### 56. Importação de Plano de Saúde: aba "Alterações" com histórico e reversão

Pedido do usuário: na tela de revisão (Mensalidade/Coparticipação/Auditoria), incluir uma quarta aba "Alterações" que registra cada edição de valor, exclusão de linha e inclusão manual de linha feita na revisão, permitindo verificar e reverter cada uma.

Novo model `ImportacaoPlanoSaudeAlteracao` (migração `0038`) — um registro por operação, nunca apagado (`revertida`/`revertida_em` marcam quando o usuário desfez). `ImportacaoPlanoSaudeLinhaViewSet` passou a gravar um registro a cada `perform_create`/`perform_update`/`perform_destroy`, com um snapshot completo da linha (`dados_linha`, JSONField) — necessário porque uma linha excluída deixa de existir, então o snapshot é o único jeito de mostrar/recriar essa linha depois. Novo endpoint `POST /api/importacoes-plano-saude-alteracoes/{id}/reverter/` desfaz uma alteração específica: edição volta o campo, inclusão remove a linha, exclusão recria a linha a partir do snapshot — idempotente, e a própria reversão não gera um novo registro (evita loop).

De propósito, o valor lançado por "Vincular pessoa" (resolução manual de auditoria) não entra nessa aba — já tem seu próprio rastro (selo "Resolvido" na aba Auditoria).

### 57. Bug no parser da Itamed: reajuste de mensalidade não estava sendo somado ao valor lançado

Usuário reportou, testando o arquivo real de 08/2026: para "Elizangela de Paula Kuhn", a aplicação lançou R$ 900,65 de mensalidade, quando o correto era R$ 964,87 (a soma que a própria linha-resumo da pessoa mostra em "VI.Pré-Estab."/"VI mensal.").

Causa: na mini-tabela "Item/Valor" de cada pessoa, quando há reajuste no mês, o valor vem **separado** em duas linhas — "Reajuste - Variação de custo" (ex.: 64,22) e "Preço pré-estabelecido" (ex.: 900,65), que juntas somam o valor real da mensalidade (964,87). `operadoras/itamed/saude.py` só tinha regex pra "Preço pré-estabelecido"/"Co-participação" — a linha de reajuste não casava com nada e era simplesmente ignorada, subtraindo o valor do reajuste da mensalidade de **todo mundo, todo mês com reajuste** (não era um caso raro: no arquivo de teste, as 14 pessoas tinham essa linha).

Corrigido adicionando `_REAJUSTE_RE` e lançando "Reajuste - Variação de custo" também como `tipo_lancamento="mensalidade"` — soma automaticamente com "Preço pré-estabelecido" na agregação por indivíduo (`_agrega_por_individuo_e_tipo`, sem mudança nenhuma nela). Validado rodando o parser direto contra `media/planos_saude/operadora/501_Itamed.PDF`: os 3 totais da página de resumo (14 beneficiários, R$ 4.475,41 de mensalidade, R$ 600,63 de coparticipação) bateram exatamente depois da correção.

### 58. Operadora ganha código de cadastro no nome + combobox pesquisável

Pedido do usuário: no `<select>` "Operadora" da tela de Nova Importação, incluir o código de cadastro de cada operadora no Questor antes do nome, e permitir buscar por nome (a lista tende a crescer, mesmo motivo que já tinha levado "Regra de custeio salva" a virar combobox na rodada 53).

`pipeline.OPERADORAS` — `label` de cada operadora passou a vir pré-formatado como `"<código> - <Nome>"`: `1723 - Dental Uni Odonto`, `3755 - Itamed Saúde`, `3758 - Amil Odonto`, `4709 - Unimed Oeste do Paraná`, `5060 - Unimed Saúde` (códigos informados pelo usuário). Como `GET /operadoras/` é a fonte única do rótulo em todo lugar que exibe operadora (combobox do formulário, `operadoraLabel()` na lista de regras salvas, `nome_operadora` de cada importação), a mudança aparece em todos esses lugares sem precisar tocar em nenhum deles.

O `<select id="ips-form-operadora">` virou um combobox pesquisável (`#ips-operadora-combo`), mesmo componente visual de "Regra de custeio salva" — as classes CSS que antes eram `.ips-regra-combo*` foram generalizadas pra `.ips-combo*` (`importacao-plano-saude.css`) pra serem reaproveitadas pelos dois campos, sem duplicar estilo. Diferença de implementação: Operadora não tem um botão "Aplicar" separado — o valor de fato submetido viaja num `<input type="hidden" id="ips-form-operadora">`, e escolher um item da lista já grava o valor na hora (`selecionarOperadora()`), preservando todo o código existente que lia `formOperadora.value` (validação do form, payload de submit, payload de "Salvar regra atual...", pré-validação de arquivo por operadora).

Ajuste pedido na sequência: "Limpar seleção" (da regra de custeio) passou a chamar também `limparOperadoraSelecionada()`, não só `limparRegraSelecionada()`/`limparCusteioForm()` — já que aplicar uma regra pode ter preenchido a Operadora junto, desfazer a seleção da regra precisa desfazer isso também.

### 59. "Regra empresa" — custeio especial de mensalidade por família (primeira: Tecnomyl/Unimed)

Pedido do usuário: incluir uma empresa (Tecnomyl, cliente na Unimed, código 1778) cuja regra de custeio não cabe no desenho normal "por tipo de lançamento × titular/dependente" — a Tecnomyl paga até R$ 661,61 de mensalidade **por família inteira** (titular + todos os dependentes juntos, não por pessoa): família acima do teto tem o excedente descontado do empregado; igual ou abaixo, a empresa cobre 100%. O usuário deixou claro que regras assim serão sempre cadastradas diretamente por programação (nunca pela tela) e não têm relação nenhuma com o banco de "Regras de custeio salvas" (`RegraCusteioPlanoSaude`) já existente.

Terceiro checkbox em "Tipo de importação" (ao lado de Mensalidade/Coparticipação): "Regra empresa" — mutuamente exclusivo com "Mensalidade" (as duas configuram o mesmo tipo de lançamento `"mensalidade"`, só que de formas diferentes). Ao marcar, aparece um botão "Selecionar regra" que abre um modal listando as regras cadastradas em `portal_api/planos_saude/regras_empresa.py` (`REGRAS_EMPRESA`, registro fixo no código — nada de tela de cadastro).

**Decisão de engenharia (não pedida explicitamente, mas necessária)**: como o teto é por família e a planilha padrão do sistema é uma linha por pessoa, o valor custeado pela empresa é distribuído **proporcionalmente** entre a linha do titular e a de cada dependente (não dá pra simplesmente jogar tudo na linha do titular — quebra sempre que a mensalidade do titular sozinho já é menor que o teto). Implementado em `regras_empresa._aplica_teto_familia()`, com a última linha da família absorvendo o resto do arredondamento (mesmo cuidado já usado em `matcher._calcula_valores`). `matcher._casa_por_nome()` ganhou um segundo modo (`regra_empresa_fn`): em vez de aplicar o custeio linha a linha, acumula todas as linhas/valores da família primeiro e só aplica a regra especial no fim do laço daquela família.

Validações de segurança adicionadas (`regras_empresa.valida_regra_empresa`, exceção própria `RegraEmpresaIncompativelError` capturada à parte em `views.py` pra mostrar a mensagem certa em vez do erro genérico de arquivo): só funciona com operadora de casamento por nome (a agregação por família depende do agrupamento que já existe em `_casa_por_nome`; Amil, por CPF, não suporta ainda) e só se a planilha padrão anexada tiver alguma linha com o `codigo_empresa` esperado pela regra (trava contra aplicar a regra da Tecnomyl numa planilha de outra empresa por engano).

Modelo ganhou `ImportacaoPlanoSaude.regra_empresa` (migração `0039`). Validado rodando o pipeline direto (fora do Django test runner, via `manage.py shell`-style script) com os dois exemplos exatos passados pelo cliente (família de R$800 → R$661,61/R$138,39) e com duas famílias reais extraídas do arquivo de teste anexado (abaixo do teto → 100% empresa) — bateu exatamente nos dois casos.

### 60. "Regra empresa" (Tecnomyl/Unimed): correção da prioridade de distribuição do teto — dependentes primeiro

Testando com dados reais (família Caroline Fernandes + dependente Luciano Ramos Xavier, R$873,69 de mensalidade no total), o usuário reportou que a distribuição **proporcional** implementada na rodada 59 estava errada: pediu explicitamente pra priorizar abater o valor dos dependentes primeiro, e só depois disso — se sobrar teto — aplicar no titular; se ainda faltar descontar depois de esgotar o teto nos dependentes, aí sim cai desconto no titular (ou no próprio dependente, se os dependentes sozinhos já estourarem o teto).

`regras_empresa._aplica_teto_familia()` reescrita: em vez de repartir `min(total_familia, teto)` proporcionalmente entre todas as linhas, agora percorre primeiro os dependentes (na ordem em que aparecem), cada um recebendo `valor_empresa = min(seu valor, teto_restante)`, e só no fim processa o titular com o que sobrou do teto (`teto_restante`). Validado reproduzindo exatamente o caso real reportado: dependente (R$559,57) sai 100% custeado pela empresa (sobra R$102,04 de teto), titular (R$314,12) fica com `valor_empresa=R$102,04`/`valor=R$212,08` — bateu com os números que o usuário mostrou como "como deve ficar".

### 61. "Regra empresa": "Vincular pessoa" (resolução de auditoria) ignorava a regra empresa

Usuário reportou, testando dados reais: numa importação com "Regra empresa" ativa, ao vincular manualmente um item de auditoria (nome divergente) a uma linha, o sistema lançava o valor inteiro como desconto do empregado (`valor_empresa=0`) em vez de aplicar o teto de R$661,61 da Tecnomyl.

Causa: `ImportacaoPlanoSaudeAuditoriaViewSet.resolver` sempre usava o custeio normal por pessoa (`matcher.valores_formatados_para_pessoa`, lendo `custeio_por_tipo[tipo_lancamento]`) — mas quando a importação usa regra empresa, esse campo fica vazio (`{}`) de propósito (ver rodada 59), então caía no padrão `{"modo": "empregado"}` (100% desconto), sem nenhuma noção de família/teto.

Corrigido: quando o item é de mensalidade e a importação tem `regra_empresa` configurada, `resolver()` grava o valor bruto na linha (placeholder) e chama a nova `_recalcula_familia_regra_empresa(importacao, linha)` (`views.py`) — reúne **todas** as linhas de mensalidade da mesma família (mesmo `nome_func`), recupera o valor bruto de cada uma como `valor_empresa + valor` (soma que preserva o total não importa qual split foi aplicado antes) e reaplica a regra empresa na família inteira de uma vez (`bulk_update`). Precisa reaplicar em todas as linhas, não só a recém-vinculada, porque o valor novo muda o total da família e o teto precisa ser redistribuído do zero (dependentes primeiro, titular absorve o residual — mesma prioridade da rodada 60).

`regras_empresa._aplica_teto_familia` deixou de depender do método `LinhaSistema.eh_linha_titular()` (virou `_eh_linha_titular()` duck-typed, checando `nome_dependente`/`cpf_dependente` direto) — precisa rodar tanto contra `LinhaSistema` (pipeline) quanto contra `ImportacaoPlanoSaudeLinha` (model Django, usado só no recálculo pós-vincular).

Validado com um teste de integração real (dentro de uma transação revertida de propósito, nada commitado): simulou vincular primeiro o dependente (R$172,51, abaixo do teto sozinho) e depois o titular (R$162,69) da mesma família reportada pelo usuário (Rafael Cornelius/Viviani Busko Souza) — os dois ficaram 100% custeados pela empresa em cada etapa, batendo com o esperado (família de R$335,20 no total, bem abaixo do teto de R$661,61).

### 62. "Regra empresa" ganha campo de observações, exibido só-leitura na tela de Revisão

Pedido do usuário: quando a importação usa uma regra empresa com observação cadastrada, mostrar essa observação na tela de Revisão — sem permitir edição, só pra conferência — entre o cabeçalho ("Revisão" + informações da execução) e as abas Mensalidade/Coparticipação/Auditoria/Alterações.

`REGRAS_EMPRESA` (`regras_empresa.py`) ganhou o campo opcional `observacoes` (texto livre) — a regra `unimed_1778_tecnomyl` já nasceu com uma explicando o teto de R$661,61 e a prioridade dependentes→titular (rodada 60). Exposto via `ImportacaoPlanoSaudeDetailSerializer.regra_empresa_observacoes` (resolvido a cada carregamento a partir do registro no código, não persistido — se o texto do registro mudar depois, importações antigas refletem o texto novo também). Frontend: novo bloco `#ips-review-regra-empresa-obs` em `importacao-plano-saude.html`, populado por `abrirRevisao()` e escondido quando a importação não usa regra empresa ou a regra não tem observação cadastrada.

### 63. "Regras de custeio salvas" também ganham observação exibida na Revisão

Usuário testou uma importação (código 1601, "1601 - Unimed Oeste PR", regra de custeio salva com observação "Custeado integralmente pelo empregado e sócio...") e notou que a observação não aparecia na tela de Revisão — só a de "Regra empresa" (rodada 62) tinha esse tratamento.

`ImportacaoPlanoSaude` ganhou `regra_custeio_salva` (FK opcional, `SET_NULL`, pra `RegraCusteioPlanoSaude`, migração `0040`) — só registro informativo de qual regra salva (se alguma) foi aplicada no formulário antes do "Processar", preenchido no submit com `regraAplicadaId` (JS) quando "Regra empresa" não está marcada. As duas nunca vêm preenchidas juntas: marcar "Regra empresa" já limpa o rastreamento da regra de custeio salva (`limparRegraSelecionada()`), e aplicar uma regra de custeio salva já desliga "Regra empresa" (`limparRegraEmpresa()` dentro de `aplicarCusteio()`) — esse segundo ponto já existia da rodada 59, só faltava o primeiro (adicionado agora).

O mesmo bloco `#ips-review-regra-empresa-obs` (rodada 62) foi reaproveitado: se não há observação de regra empresa mas há `regra_custeio_salva_observacoes` (novo campo em `ImportacaoPlanoSaudeDetailSerializer`, lendo `RegraCusteioPlanoSaude.observacoes` de verdade via FK), o bloco mostra essa observação com o rótulo "Observações da regra de custeio salva — `<nome>`".

### 64. Nova operadora: Bradesco Saúde (1386) — primeiro PDF sem texto selecionável, extração via OCR (`docling`)

Usuário trouxe um modelo novo de fatura (Bradesco Saúde, empresa 221 - Rossoni Piotto) e perguntou se dava pra ler/converter pra parametrizar a importação, já que o PDF é "formato de imagem, sem texto selecionável". Confirmado empiricamente rodando `pdfplumber` contra o arquivo real baixado (`Downloads/221 -BRADESCO SAUDE.pdf`): `page.chars`/`page.extract_text()` vêm vazios nas 3 páginas — o documento é uma composição de dezenas de imagens raster por página (cada faixa da tabela é um bitmap próprio), sem nenhuma camada de texto. É o primeiro caso desse tipo entre as operadoras do módulo; todas as outras (Amil/Itamed/Unimed/Dental Uni/Unimed Oeste PR) têm texto selecionável e usam `pdfplumber`.

Depois de comparar duas ferramentas de conversão (MarkItDown vs. Docling — MarkItDown não tem OCR/reconstrução de tabela embutidos, feito pra documento já estruturado; Docling tem OCR local + modelo dedicado de estrutura de tabela, TableFormer), a escolha foi Docling — adicionado ao `requirements.txt` (pesado: traz `torch`/`transformers`/`opencv-python`/`pandas` como dependência transitiva, ~90 pacotes novos no freeze).

**Bug real encontrado testando contra o arquivo de verdade** (por isso vale sempre testar contra o arquivo real antes de confiar, não só contra o texto que o próprio Docling "acha" que extraiu): nas colunas estreitas "Mês/Ano"/"Valor" (sob o cabeçalho mesclado "Lançamento"), o TableFormer às vezes junta as duas numa célula só, e às vezes o valor de uma pessoa "vaza" pra célula da linha anterior (visto de fato: o valor da GABRIELA saiu dentro da célula "Valor" da MILENA, deixando a própria célula da GABRIELA vazia). Subir a resolução de renderização (`images_scale=4`) não mudou nada — não é falta de resolução, é erro de fronteira de célula do modelo mesmo. Contorno implementado em `operadoras/bradesco/saude.py` (`_extrai_valores_area`): em vez de confiar em qual célula/linha especificamente carrega o valor, concatena-se todo o texto da área "Mês/Ano+Valor" de cada linha (de cima para baixo) e extrai-se TODOS os valores monetários encontrados, preservando a ordem de leitura — depois redistribui 1 valor por linha de beneficiário, na mesma ordem (a ordem de leitura continua certa mesmo quando a fronteira de célula erra). Se a contagem final não bater 1:1 com o número de linhas, levanta erro em vez de arriscar lançar o valor errado em alguém.

Titular x dependente é decidido pela coluna "Certif." (formato `<família>/<sufixo>`, sufixo `"00"` = titular, qualquer outro = dependente daquela família — confirmado pelo usuário), não por uma coluna "Tipo" dedicada como as outras operadoras. Casamento com a planilha padrão é por nome (`chave_casamento = "nome"`, igual Itamed/Unimed/Dental Uni/Unimed Oeste PR — este arquivo também não traz CPF). Coparticipação ("Part. Seg.") ainda não foi validada com nenhum arquivo real com valor diferente de zero — o usuário disse "acreditamos que ficariam" ali; o parser já está pronto pra gerar lançamento de coparticipação quando isso acontecer (mesmo padrão "ausência de valor = zero, não gera Individuo" da Itamed), mas isso é uma suposição a confirmar, não um fato validado.

Validado rodando o parser (`BradescoSaude.extrai`) e o pipeline completo (`processa_importacao`) direto contra o arquivo real de 08/2026 + a planilha padrão de exemplo fornecida pelo usuário (empresa 221): os 4 valores de mensalidade saíram exatamente certos (incluindo o caso MILENA/GABRIELA acima) e o casamento por nome bateu certo para os 4 beneficiários presentes na planilha (mais um, LUIZ CARLOS PIOTTO, corretamente ficou sem lançamento por não aparecer na fatura daquele mês).

Registrado em `pipeline.OPERADORAS` como `"bradesco_saude": {"label": "1386 - Bradesco Saúde", ...}`.

### 65. Filtro Ativos/Inativos/Todos na lista de Usuários

Usuário pediu um botão pra filtrar a lista de `usuarios.html` entre Ativos/Inativos, abrindo por padrão só com os Ativos, mas com opção de tirar o filtro pra ver os inativos também.

Implementado como 3 chips ("Ativos"/"Inativos"/"Todos", `#ua-status-filtros`, ao lado do título "Usuários") — mesma linguagem visual de `.ind-departamento-chip` (Indicador de Desempenho). Filtro 100% client-side sobre o array `users` já carregado (`statusFiltro`, padrão `"ativos"`), aplicado em `renderList()` antes da busca por texto. Sem endpoint novo.

### 66. Colunas de código cadastral (Folha/Questor/Tareffa/Contabit/Ramal) + ordenação na lista de Usuários

Usuário pediu pra ver os campos cadastrais opcionais (`codigo_folha`/`codigo_questor`/`codigo_tareffa`/`codigo_contabit`/`ramal`, hoje só visíveis dentro do formulário de edição) como colunas na lista, e poder ordenar por elas — mesmo sendo campos opcionais, o objetivo é achar quem está sem algum deles cadastrado antes de outras aplicações passarem a depender dessas informações.

`UsuarioListSerializer` já expunha os 5 campos (nenhuma mudança de backend necessária). Adicionadas 5 colunas em `#ua-table` (`usuarios.html`) entre Nome e Perfil de Acesso; célula vazia mostra `—` em itálico apagado (`.ua-campo-vazio`) em vez de ficar em branco, pra ficar visualmente óbvio ao ordenar. Cabeçalhos com `data-sort` (login, nome, os 4 códigos, ramal, status) ficam clicáveis e alternam asc/desc — mesmo padrão (`comparaValoresUsuario`, ícone `↕` que vira `--accent` no ativo) já usado em `#ips-list-table` (Importação de Plano de Saúde) e no modal de Ramais.

### 67. Aba "Usuários do Escritório" (Perfis de Acesso) reestruturada em duas tabelas com seleção múltipla

Usuário anexou um print de outro sistema (duas grades lado a lado, cada uma com checkbox, busca por coluna, ordenação e um botão de ação em lote — "VINCULAR"/"DESVINCULAR") e pediu pra reestruturar a aba "Usuários do Escritório" (dentro da edição de um perfil, `perfis-acesso.html`) nesse mesmo estilo: ver todos os usuários ativos de um lado e vincular, ver os já vinculados do outro lado e desvincular.

Substituído o antigo `<select>` + botão "Vincular" + lista simples com X (`.pa-users-add`/`.pa-user-list`, removidos) por `.pa-users-dual` — duas tabelas (`#pa-users-available-*` à esquerda, só usuários ativos ainda não vinculados; `#pa-users-linked-*` à direita, todos os já vinculados, inclusive inativos, com selo `.status-pill--inativo`), cada uma com checkbox por linha + "selecionar todos" (sobre as linhas filtradas visíveis), busca por nome/e-mail, ordenação por nome (clique no cabeçalho, ícone `↕`) e um botão de atualizar. "Vincular"/"Desvincular" operam em lote sobre a seleção (`bulkAlterarVinculo()`, `Promise.all` de `PATCH /api/usuarios/{id}/` por usuário selecionado) — sem endpoint novo, só reaproveitando `GET/PATCH /api/usuarios/` que já existiam. Abrir a aba de um perfil diferente sempre reseta seleção/ordenação/busca dos dois painéis.

### 68. Botão "Vincular" (só visual) nos campos Código da Folha/Questor/Tareffa

Usuário anexou um print mostrando 3 campos específicos (Código da Folha, Código do Questor, Código do Tareffa — não Contabit nem Ramal) e explicou que, no futuro, esses códigos serão buscados/vinculados automaticamente a partir de ferramentas externas (ex.: `codigo_tareffa` via a view que já existe no banco pra ler o Tareffa) em vez de digitados manualmente. Pediu explicitamente pra **não** construir essa vinculação agora — só deixar a estrutura visual pronta, com um botão "Vincular".

Passou por 3 versões visuais no mesmo dia até o formato final: (1) botão "Vincular" solto ao lado do input (`.btn-outline`, com texto); (2) só o ícone de elo no canto do próprio input (`position:absolute`, sem texto — pedido do usuário: "deixe o botão mais simples, só o símbolo no canto"); (3) formato final — input + botão "Vincular" (ícone + texto) encostados numa única caixa (`.ua-field-link`, borda/raio únicos, `border-left` separando os dois), depois do usuário mostrar um print de referência (campo de busca com botão "Buscar" atado à direita) e pedir esse mesmo estilo. Sempre `disabled` com `title` explicando que a vinculação ainda não foi implementada. Sem handler de JS nenhum — puramente estrutural, pra reaproveitar quando a integração de verdade for construída.

### 69. Bug: `IntegrityError` ao criar um novo perfil de acesso (`codigo` duplicado)

Usuário reportou erro `500` ao criar um perfil pela tela: `django.db.utils.IntegrityError: duplicate key value violates unique constraint "portal_api_perfilacesso_pkey" — DETAIL: Key (codigo)=(6) already exists`.

Causa: `seed_portal.py` semeia os 8 perfis com `codigo` **explícito** (`update_or_create(codigo=dado["codigo"], ...)`, necessário porque vários lugares do código referenciam código fixo, ex. `codigo == 8`). No Postgres, `INSERT` com PK explícita não avança a sequence do `AutoField` — a sequence de `PerfilAcesso.codigo` ficou parada em 1 desde a criação do banco, então o primeiro `POST /api/perfis/` (sem PK explícita) pediu `nextval()` e recebeu um código baixo já usado pelo seed (6 = "Financeiro").

Corrigido com `_reset_sequence()` (nova função em `seed_portal.py`, `SELECT setval(pg_get_serial_sequence(...), MAX(codigo))` via SQL puro) chamada logo após semear `PERFIS_SEED` — toda execução do comando realinha a sequence de novo, então o bug não volta a acontecer mesmo que o seed seja reexecutado no futuro. Aplicado no banco em produção rodando `python manage.py seed_portal` (confirmado via `SELECT last_value FROM portal_api_perfilacesso_codigo_seq` = 8, igual ao maior código existente).

### 70. "Usuários sob liderança" reestruturado em duas tabelas (não vinculados/vinculados)

Usuário anexou dois prints — um da própria seção "Liderança" (checklist único, com busca e "marcar todos") e outro de um sistema externo com duas grades lado a lado (checkbox, "Código"/"Nome", ordenação, paginação, VINCULAR/DESVINCULAR) — e pediu pra reestruturar "Usuários sob liderança" nesse mesmo estilo de duas tabelas: não vinculados de um lado, vinculados do outro (corrigido depois pra confirmar: não vinculados à **esquerda**, vinculados à **direita** — mesma convenção já usada no widget "Usuários do Escritório" de Perfis de Acesso, rodada 67).

Essa seção aparece em dois lugares (formulário de edição de usuário em `usuarios.html` **e** o modal "Gerenciar Usuário", presente em todo shell, pra autogestão do próprio gerente/coordenador) — perguntado ao usuário se a mudança deveria valer só pra tela de Usuários ou pros dois lugares; resposta: os dois.

Como o widget "Usuários do Escritório" (rodada 67) já tinha esse exato padrão visual mas vivia só em `perfis-acesso.css`/inline em `profiles.js` (só usado nessa página), foi extraída uma versão genérica reaproveitável: `static/js/dual-select.js` (`pidCriarSeletorDuplo()`, fábrica que recebe as referências de DOM de cada painel + uma função pro valor da coluna secundária, devolve `{setDados, getVinculadosIds}` — vinculação só em memória, sem chamada de API própria) + `.dual-select`/`.dual-select__*` em `components.css` (não em `perfis-acesso.css`, já que o modal "Gerenciar Usuário" existe em todo shell e a maioria não carrega esse CSS). `dual-select.js` foi adicionado ao prefixo de scripts compartilhado das 10 páginas-shell, logo depois de `api.js`.

Trocados: `usuarios.html` (seção "Liderança") e as 10 cópias do modal "Gerenciar Usuário" (uma por shell) — `.checklist-box`+busca+"marcar todos" virou o par de tabelas com coluna "Nome" (ordenável) + "Departamento" (busca própria). `#manage-account-modal-card` ganhou id novo pra `account.js` poder aplicar `.modal-card--wide` só quando `me.lideranca` é `true` (o modal padrão de 420px não cabe duas tabelas lado a lado). `users-admin.js`/`account.js` tiveram a lógica de checklist único substituída por chamadas a `pidCriarSeletorDuplo` — o restante do fluxo (salvar `liderados` junto do form em `usuarios.html`, `PATCH /api/me/liderados/` imediato no modal) não mudou.

**Ajuste de proporção no mesmo dia**: usuário reportou dois problemas visuais depois de testar — (1) "Perfis de Acesso" e "Departamento" (`usuarios.html`) não ficaram do mesmo tamanho; (2) o par de tabelas de "Usuários sob liderança" ficou comprimido num canto, sem usar a largura da seção. Causa de (1): `.pa-field-row.ua-permissions-row` usava `grid-template-columns: 1.6fr 1fr` (resquício de quando só existia um checklist de cada lado, sem se importar com simetria) — trocado para `1fr 1fr`. Causa de (2): `.ua-liderados-field` tinha `max-width: 480px`, herdado de quando o campo continha só um `.checklist-box` estreito — removido, já que agora o campo precisa da largura inteira da seção pras duas tabelas do `.dual-select`.

### 72. Inativar usuário desvincula perfis de acesso e liderança automaticamente

Regra de negócio pedida pelo usuário: ao marcar um usuário como Inativo, ele deve ser desvinculado automaticamente de todos os perfis de acesso que tinha, e removido da lista de liderados de qualquer gerente que o tivesse — pra não deixar um vínculo "pendurado" em alguém que já não pode mais acessar o Portal.

Implementado em `_revogar_acesso_se_inativo()` (`serializers.py`), chamada ao final de `UsuarioSerializer.create()`/`update()` (depois dos `.set()` de `perfis`/`departamentos`/`liderados`, nunca antes — o formulário de edição sempre reenvia o checklist de perfis inteiro junto com qualquer alteração no checkbox "Usuário ativo", então limpar antes dos `.set()` seria desfeito na mesma requisição). Cobre os dois pontos reais de entrada (botão de alternar na lista e checkbox no formulário), ambos via `PATCH /api/usuarios/{id}/`.

Uma primeira versão tentou resolver isso em `Usuario.save()` (model), mas foi abandonada: tanto o `ModelSerializer.update()` do DRF quanto o admin do Django chamam `.set()`/`save_m2m()` nos M2M **depois** de `instance.save()`, então uma limpeza dentro de `save()` seria sempre desfeita pelo `.set(perfis)` que vem a seguir no mesmo request. Por isso a limpeza mora no serializer, como o último passo, não no model.

**Complemento no mesmo dia**: usuário reportou visualmente que usuários inativos ainda apareciam nos dois widgets de vinculação (dual-select de "Usuários sob liderança" e de "Usuários do Escritório" em Perfis de Acesso) — pediu que usuário inativo nunca seja exibido em nenhum dos dois painéis (nem disponível, nem já vinculado). Corrigido: `listaParaPainelUsuarios()` (`profiles.js`) agora filtra `usuariosCacheAtual` por `is_active` antes de separar entre disponível/vinculado (removido também o selo "Inativo" que antes marcava um usuário inativo ainda vinculado, já que esse caso não deve mais aparecer); `fillLideradosChecklist()` (`users-admin.js`) ganhou o mesmo filtro. No modal "Gerenciar Usuário" (`account.js`) já não era um problema — `GET /api/usuarios-resumo/` só devolve usuários ativos.

### 73. Nova identidade visual "P.I.D." — favicon, login e sidebar

Usuário forneceu uma nova marca (`C:\Users\Depaula\Documents\Projetos\LOGOS\pid-marca`, ver `pid-marca-leiame.md`) e pediu a adoção progressiva no Portal, mantendo o logo cursivo "D De Paula Contadores" só nos documentos/PDFs gerados pela aplicação (contrato, procuração, recibo do Indicador de Desempenho, simulação de custo de contratação) — decisão explícita: esses documentos são emitidos como se o próprio escritório os tivesse gerado, carregam a identidade dele perante o cliente, não a do Portal como ferramenta interna.

- **Favicon**: trocado de `favicon.png` (variante antiga do "D") pra `pid-icone-escuro.svg` (ícone quadrado da marca nova, variante fundo escuro) nas 11 páginas.
- **Login (`index.html`)**: o card ficou **congelado escuro nos dois temas** (tokens dedicados `--login-card-bg`/`--login-field-bg`/`--login-border`/`--login-text-*` em `tokens.css`, nunca redefinidos em `:root[data-theme="light"]` — mesmo padrão da sidebar) — pedido explícito depois de uma primeira tentativa (só a caixa de login/senha escura) não ter sido o que o usuário queria; só o fundo da página ao redor do card continua claro/escuro por tema. A logo alterna entre `pid-icone.svg`/`pid-icone-escuro.svg` conforme `data-theme` (`pidSyncLoginLogo()` em `theme.js`), e o texto "Portal De Paula" virou "Portal Interno da De Paula". Um slogan da marca ("Grandes aplicações de todos os tamanhos.", fonte "Pinyon Script"/dourado `#c6a24a`) foi adicionado — testado primeiro no topbar de `portal.html`, removido de lá a pedido do usuário, e reintroduzido no login (rodapé, depois movido pra logo abaixo do título), tamanho ajustado até ficar legível sem competir com o título.
- **Sidebar** (10 shells): `sidebar__brand` passou a ter duas logos sempre no DOM, sobrepostas com `position:absolute` dentro de um container de altura fixa, alternando por `opacity`+`scale()` (crossfade, não troca de `src`) conforme a sidebar está expandida (`pid-logo-horizontal-escuro.svg`, assinatura com texto) ou colapsada (`pid-icone-escuro.svg`, só o símbolo) — sempre as variantes "-escuro", já que a sidebar é sempre escura nos dois temas. Tamanho da logo expandida aumentado em duas rodadas (176px/70% → 220px/92% → 250px/96% da largura útil) até o subtítulo "PORTAL INTERNO DA DE PAULA" ficar legível.

Ver `CLAUDE.md` ("Logos em `static/img/`") pro estado final detalhado de cada arquivo.

### 74. Animação de intro pós-login (porta de `pid-intro-escuro.html`)

Usuário forneceu um segundo arquivo da mesma pasta de marca, `pid-intro-escuro.html` — um bundle de "Design Canvas" (Anthropic) com uma animação de apresentação da marca P.I.D. (composição em 4 cenas: o ícone se desenha, ganha rosto, desliza pra revelar o wordmark "P.I.D." + tagline, e por fim voa/esmaece). Pediu pra reproduzir essa animação como transição entre o login e a tela Principal: ao clicar "Entrar" com sucesso, a animação toca por inteiro e só depois a tela Principal aparece, "pela barra lateral primeiro".

O arquivo fornecido não é HTML/CSS simples — é um bundle auto-contido do editor de canvas com um runtime próprio (React + motor de composição por tempo autorado "OM", fontes e o JSX fonte embutidos como blobs base64/gzip dentro de um `<script type="__bundler/manifest">`). Decodificado (script Python ad-hoc, gzip+base64 por uuid) pra extrair o JSX de verdade (`pid-intro.jsx`) e a biblioteca de easing/interpolação (`animations-v3.jsx`) — essas fórmulas na íntegra permitiram portar a coreografia **fielmente** (mesmas durações de cena, mesmas curvas de easing hand-rolled tipo Popmotion, mesmo timing de blink dos olhos) pra vanilla JS/CSS, sem carregar o runtime React/canvas original (pesado demais e não pensado pra produção).

- **Cenas** (mesma duração do original, 9.7s no total): Build (2.6s, contorno do ícone se desenha, aba dourada cai, tela do "rosto" abre) → Face (2s, olhos aparecem com pop e piscam, sorriso dourado se desenha) → Wordmark (2.8s, ícone desliza pra esquerda enquanto "P.I.D." + régua dourada + "Portal Interno da De Paula" aparecem) → Portal (2.3s, wordmark some, ícone encolhe e "voa" até o canto superior esquerdo real da janela — não as coordenadas de um frame de vídeo 1920×1080 do arquivo original, recalibradas pra mirar onde a logo colapsada da sidebar (`.sidebar__logo--icon`, 40px) realmente fica — e a cena inteira esmaece).
- **Arquivos novos**: `static/css/login-intro.css` (só `index.html`) e `static/js/login-intro.js` (motor de animação — easing/`animate`/`clamp`/render por `requestAnimationFrame`, tudo portado das fórmulas extraídas). Cores/formas idênticas às já usadas em `pid-icone-escuro.svg`/`pid-logo-horizontal-escuro.svg` (hardcoded, não são tokens de tema — é a paleta fixa da marca). Fontes "Space Grotesk" (wordmark) e "DM Mono" (tagline) adicionadas ao `<link>` de fontes de `index.html`, junto de "Bree Serif"/"Pinyon Script" já usadas ali.
- **Fluxo**: `auth.js`, no sucesso do POST de login, chama `pidPlayLoginIntro(onDone)` em vez de navegar direto — só ao final da animação (`onDone`) marca `sessionStorage.pid_reveal_portal="1"` e navega pra `portal.html`.
- **"Aparecendo primeiro pela barra lateral"**: novo `static/js/portal-reveal.js` (só `portal.html`, IIFE de topo tipo `theme.js`) — se a sessionStorage tiver a marca, aplica `html.pid-entering` antes da primeira pintura (evita flash) e remove a classe ~350ms depois do `DOMContentLoaded`. `layout.css` esconde `.main-content` (topbar+conteúdo) enquanto essa classe está presente, sem afetar `.sidebar` — como a sidebar não é tocada, ela fica visível o tempo todo e "aparece primeiro", com o resto do app surgindo num fade logo depois. Acesso direto a `portal.html` (sem passar pelo login) não aciona nada disso, já que a sessionStorage nunca é setada nesse caminho.

**Ainda não testado num navegador de verdade** — a próxima rodada deve conferir o resultado visual completo (timing, posição do "fly" final em diferentes tamanhos de tela, e o crossfade da sidebar) antes de considerar fechado.

**Três ajustes no mesmo dia, depois do primeiro teste real** (funcional, mas com pontos a melhorar): (1) a cor de fundo do overlay (`#241c33`, roxo-tinto do arquivo original) destoava do fundo real do Portal — trocada pra `#121017`, o mesmo valor de `--bg-canvas` no tema escuro, pra a sequência login→animação→portal ler como uma coisa só; (2) o overlay aparecia de repente por cima do card de login ainda visível ("de um modo bruto") — agora o card se dissolve (`.login-card.is-leaving`) enquanto o overlay sobe (`.login-intro.is-visible`), um cross-fade de 350ms, e só depois disso o ícone começa a se desenhar; (3) a cena final (Portal) tinha uma pausa parada depois do ícone já ter chegado ao canto até o fade acontecer — comprimida de 2,3s pra 0,95s (wordmark some quase na hora, ícone voa em 0,6s, tudo esmaece logo em seguida, sem intervalo morto) — duração total da animação caiu de 9,7s pra 8,35s.

**Quarto ajuste, mesmo dia**: a revelação da tela Principal (rodada 74) só escondia `.main-content`, deixando a sidebar sempre visível desde o início (sem nenhuma entrada própria) — usuário pediu mais fluidez, com a sidebar de fato aparecendo antes do resto. `portal-reveal.js` passou a aplicar duas classes em sequência: `pid-entering-sidebar` (esconde só a sidebar, com um leve `opacity`+`translateX(-16px)`) sai primeiro, 120ms depois do `DOMContentLoaded`; só 200ms depois disso é que `pid-entering` (esconde `.main-content`) sai, revelando o resto do app.

**Quinto e sexto ajustes, rodada seguinte**: (5) usuário pediu pra acelerar a construção do ícone — `Build` e `Face` (2,6s/2s no original) foram pra **1s cada**, `Wordmark` ("a parte onde aparece o nome do portal") ficou **igual** (2,8s, pedido explícito de não mexer), e `Portal` ("a parte na qual ele some") foi arredondada pra **~1s** também — total da animação caiu de 8,35s pra 5,7s; os deslocamentos internos de cada cena precisaram ser reproporcionados pra caber nas durações novas (não é só trocar `CUES`, os offsets tipo `Build+1.15` etc. também mudaram), e o terceiro blink do olho (na cena Portal) foi removido por não caber mais visivelmente numa cena tão curta. (6) A entrada da sidebar em `portal.html` (ajuste anterior, `opacity`+`translateX(-16px)`) foi considerada "ainda não satisfatória" — pequena demais pra ler como "a barra lateral surgindo da esquerda pra direita". Trocada por um slide de verdade: `translateX(-100%)` (a largura inteira da sidebar, não 16px) com uma transição própria de 420ms e curva de chegada suave (`cubic-bezier(0.16, 1, 0.3, 1)`, não `var(--transition-base)`); o tempo de espera antes de revelar o resto do app também subiu de 200ms pra 420ms, pra não sobrepor as duas entradas.

**Sétimo ajuste, rodada seguinte**: o fade de entrada (card se dissolvendo + overlay subindo, antes do ícone começar a se desenhar) estava "muito rápido" — a duração (350ms, tanto em `login.css`/`login-intro.css` quanto em `PID_INTRO_FADE_MS` de `login-intro.js`) subiu pra **500ms**, um ajuste pequeno de propósito ("bem pouco, só pra ficar mais fluído").

### 75. Logo da sidebar vira link pra "Principal", com os olhos do ícone piscando ao clicar

Usuário pediu duas coisas sobre a marca da sidebar (`sidebar__brand`, presente nos 10 shells): (1) transformá-la num botão/link que navegue pra `portal.html` (tela Principal) e (2) uma animação de piscar nos olhos do ícone (o "disquete") ao clicar.

`.sidebar__brand` deixou de ser `<div>` e virou `<a href="portal.html" id="sidebar-brand-link">` — mudança de tag que não quebra nada, já que todo CSS do crossfade (rodada 20/72) é por classe. O ponto difícil: as duas logos ali (`pid-logo-horizontal-escuro.svg` expandida, `pid-icone-escuro.svg` colapsada) eram `<img src="...svg">`, e uma `<img>` é uma imagem opaca — não dá pra CSS/JS da página alcançar elementos internos dela (os olhos) pra animar. Solução: **inlinear** o markup das duas logos como `<svg>` de verdade, direto no HTML dos 10 shells (os arquivos `.svg` continuam existindo em `static/img/`, só não são mais referenciados por essa parte da sidebar — favicon continua usando o arquivo normalmente).

Dentro do SVG inline, os dois olhos (círculo creme + glint escuro) ficam cada um num `<g class="sidebar-icon-eye__lid">` (renomeada pra `.pid-icon-eye` na rodada seguinte, ver abaixo) sem nenhum `transform` de atributo XML — detalhe técnico importante: um `transform` CSS aplicado a um elemento que já tem `transform` de atributo **substitui** o atributo inteiro (perderia a posição do olho). `static/js/sidebar-brand.js` (novo, incluído nos 10 shells) escuta o clique: ignora cliques modificados (ctrl/cmd/shift/meio, deixa abrir em nova aba normal), senão previne a navegação, adiciona `.is-blinking` nos olhos (dispara `@keyframes pidSidebarBlink` em `layout.css`, `scaleY(1)→0.05→1`, 200ms) e só navega de fato 260ms depois — tempo da piscada terminar de tocar antes da página trocar, mesmo espírito já usado na animação de intro do login (rodada 74).

### 76. Mesma piscada no ícone do login + logo do login deixa de alternar por tema

Usuário pediu duas coisas: (1) o mesmo efeito de piscar do olho (rodada 75) também no ícone do card de login, ao clicar; (2) usar a **mesma logo nos dois temas** no login (parar de alternar `pid-icone.svg`/`pid-icone-escuro.svg` conforme `data-theme`).

(2) foi resolvida primeiro, e simplificou (1): já que o card do login é congelado escuro nos dois temas desde uma rodada anterior, a alternância de logo por tema nunca fez muito sentido — removida (`pidSyncLoginLogo()` tirada de `theme.js`, os atributos `data-logo-dark`/`data-logo-light` tirados de `index.html`); a logo do login agora sempre usa as cores de `pid-icone-escuro.svg`, sem checagem de tema nenhuma. Isso deixou `pid-icone.svg` (a variante clara) sem nenhum consumidor no Portal.

Pra (1), mesmo problema técnico da rodada 75 (não dá pra animar dentro de um `<img>`) — o ícone do login virou `<button type="button" id="login-logo-btn">` com o SVG inline dentro (igual à sidebar), e `static/js/login-logo-blink.js` (novo, só `index.html`) dispara a piscada ao clicar — sem `preventDefault`/delay/navegação, já que estamos na própria tela de login, é só um toque decorativo.

**Refatoração de nomes, pra reaproveitar entre os dois lugares**: como agora dois contextos diferentes (sidebar e login) piscam o mesmo ícone, `.sidebar-icon-eye__lid`/`pidSidebarBlink` (que moravam em `layout.css`, não carregado por `index.html`) foram renomeados pra `.pid-icon-eye`/`pidIconBlink` e movidos pra `base.css` (único CSS comum às duas telas) — `layout.css` e os 10 shells foram atualizados pra usar o nome novo.

### 77. Fundo da tela de login no tema claro batendo com o fundo real do Portal

Usuário reportou que, no tema claro, o fundo da tela de login (`.login-page`, a área ao redor do card) ficava com um tom acinzentado/amarronzado bem diferente do fundo de verdade da tela Principal nesse tema (um lavanda bem claro, quase branco). Causa: `.login-page` sempre aplicou um scrim escuro + um brilho radial por cima do `--bg-canvas`, pensados pra dar profundidade num fundo escuro — no tema claro, esse mesmo scrim escuro por cima de um `--bg-canvas` já claro produzia esse cinza sujo, nada parecido com o `--bg-canvas` puro que `portal.html` usa (via `body` em `base.css`).

Corrigido com um override `:root[data-theme="light"] .login-page { background: var(--bg-canvas); }` — no tema claro, zera o scrim/glow e usa só a cor sólida, igual ao resto do Portal; no tema escuro (padrão) nada mudou, o scrim+glow continuam dando a profundidade de antes.

### 78. Mesmo ajuste na animação de intro: fundo claro no tema claro, texto do wordmark escuro

Sequência natural da rodada 77 (fundo de `.login-page`): o usuário pediu o mesmo pro fundo da **animação de intro** (`#login-intro`) — no tema claro, também devia usar o `--bg-canvas` claro, não o `#121017` escuro fixo. Só que aqui tinha uma pegadinha que `.login-page` não tinha: o wordmark da animação ("P.I.D." + tagline) usa texto **claro**, pensado pra contrastar contra um fundo escuro — mudar só o fundo pro claro deixaria esse texto ilegível.

`login-intro.css` ganhou os overrides de tema claro: `.login-intro` vira `background: var(--bg-canvas)`, e `.login-intro__letter`/`.login-intro__tagline` viram cores escuras (`#241c33`/`rgba(36, 28, 51, 0.62)`) só nesse tema. O ícone (corpo roxo + tela escura do disquete) não precisou de nenhum ajuste — já tem contraste de sobra nos dois fundos. Tema escuro (padrão) ficou intocado.

### 79. Fundo de `.login-page` no tema claro refinado: brilho roxo mais claro + base levemente mais escura

Depois de ver o fundo liso (`var(--bg-canvas)`, rodada 77), usuário pediu um refinamento: "um tom de roxo um pouco mais claro e o fundo branco levemente escurecido", só no tema claro. Trocado por `radial-gradient(circle at 20% 20%, rgba(var(--accent-rgb), 0.12), transparent 45%)` sobre `#ece7f2` (levemente mais escuro que o `--bg-canvas` puro, `#f3f1f7`) — o brilho radial já existia no tema escuro com opacidade `0.25`, aqui ficou bem mais sutil (`0.12`) pra não ficar turvo sobre um fundo claro. A cor exata é fixa só nesta regra (não altera o token `--bg-canvas`), então o resto do Portal no tema claro continua com o tom original.

### 80. Buscar a planilha padrão do Questor via SQL (Importação de Plano de Saúde)

Até aqui, "Nova Importação" exigia exportar manualmente do Questor a "planilha padrão" (CSV) e anexá-la, além do relatório da operadora. Usuário validou uma consulta SQL contra o Questor (mesmo pacote `database/` só-leitura já usado em `empresas_questor.py`) que devolve exatamente essa informação a partir de `codigo_empresa` (já cadastrado em `RegraCusteioPlanoSaude`) + operadora + competência (mês/ano) — eliminando o passo manual na maioria dos casos.

- **Upload manual continua existindo**, como alternativa (Questor fora do ar, ou empresa ainda não migrada) — decisão explícita do usuário. "Nova Importação" ganhou um toggle "Buscar automaticamente do Questor" (padrão) / "Anexar manualmente", com um campo "Competência" (`<input type="month">`) só no primeiro modo.
- **Código da operadora**: até então só existia embutido no `label` de `pipeline.OPERADORAS` (ex. "5060 - Unimed Saúde"), extraído por *string split* onde precisava só do nome. Separado em campos próprios (`codigo_operadora`/`nome`), com `label_operadora()` calculando o label onde ainda é exibido — elimina o split e dá um valor confiável pra filtrar a consulta por operadora.
- **Nova consulta** (`sqls.questor.QuestorSQL.consulta_planilha_plano_saude`) e novo módulo `portal_api/planos_saude/questor_planilha.py` (`busca_linhas_questor`/`linhas_para_csv_bytes`) — a busca é resolvida **antes** de criar o registro `ImportacaoPlanoSaude` (uma falha de conexão nunca deixa nada órfão pra limpar, diferente do caminho de upload). `pipeline.processa_importacao` deixou de ler o arquivo sozinho (`caminho_planilha_padrao: str`) e passou a receber a lista de `LinhaSistema` já resolvida (`linhas_sistema_template`), de qualquer uma das duas origens — decisão de qual usar ficou em `views.py`.
- Mesmo vindo do Questor, um CSV é gerado (mesmo formato do upload) e salvo no campo `planilha_padrao` — preserva o histórico completo já documentado pra toda importação. Novo campo `ImportacaoPlanoSaude.competencia` (`DateField`, null) registra a competência usada, só quando a origem foi o Questor (migração `0045`).
- A "trava de conferência do código de empresa" (existente desde a rodada do Cadastro de Regras) é pulada quando a origem é Questor — redundante, já que a própria consulta já filtrou por aquele `codigo_empresa`.

**Ajuste no mesmo dia, depois do primeiro teste real**: o campo "Competência" nasceu como `<input type="month">` — usuário rejeitou o seletor nativo do browser como "horrível" e pediu o mesmo padrão já usado no Indicador de Desempenho: texto livre com máscara MM/AAAA (`mascaraCompetencia()`/`competenciaParaIso()`, cópia local das mesmas funções de `indicador-desempenho.js`), o usuário digita "082026" e o campo forma "08/2026" sozinho. Backend acompanhou: `competencia` no serializer é um `DateField` normal (mesmo padrão de `IndicadorApuracaoCreateSerializer`), recebendo o ISO `"AAAA-MM-01"` já convertido pelo JS, nunca a string mascarada crua.

**Segundo ajuste, mesmo teste real**: a coluna `DATAINICIAL` do CSV gerado via Questor saía no formato ISO (`2023-12-01`, `linha["datainicial"].isoformat()` — a renderização padrão do Postgres pra uma coluna `date`), mas o leiaute real de importação do sistema espera `DD/MM/AAAA` (`01/12/2023`) nessa coluna — mesmo formato que uma planilha padrão exportada manualmente do Questor já usa. Corrigido em `questor_planilha.busca_linhas_questor()` pra `linha["datainicial"].strftime("%d/%m/%Y")`. `data_inicial` é sempre um passthrough string em todo o pipeline (nenhum outro ponto faz parsing de data nele, só grava/lê a string), então a mudança não exigiu tocar em mais nenhum arquivo. Nenhum registro histórico ficou com o formato errado — a única importação de teste que chegou a usar a busca via Questor (antes deste ajuste) já tinha sido excluída pelo próprio usuário.

**Terceiro ajuste, mesmo dia — regra de edição da tabela de revisão revista**: até aqui, todo campo de `ImportacaoPlanoSaudeLinha` era editável em qualquer linha na tela de Revisão (decisão de uma rodada anterior). Vendo dados reais de uma importação via Questor (22 linhas, várias famílias), o usuário pediu pra restringir: só `Valor Empresa`/`Valor` editáveis numa linha que já veio do processamento (upload ou Questor) — os demais campos (cadastro da pessoa: nome, CPF, código, data...) só ficam editáveis numa linha incluída manualmente via "Adicionar linha", e só nela. Implementado 100% no frontend (`importacao-plano-saude.js`, `linhasIncluidasManualmente()`), sem campo novo: reaproveita o sinal que já existia em `ImportacaoPlanoSaudeAlteracao` (toda linha criada via "Adicionar linha" já gerava um registro `tipo="inclusao"` ali, só pra alimentar a aba "Alterações" — agora também decide, no cliente, quais linhas ganham os campos extras liberados). O backend continua aceitando PATCH em qualquer campo (nenhuma trava nova no serializer/model) — é uma restrição de UI, não de permissão.

**Quarto ajuste, mesmo dia — trava de edição depois de "Gerar Arquivo"**: o ajuste anterior já restringia *quais campos*, mas o usuário notou que uma importação já `concluida` (arquivo já gerado/entregue) continuava 100% editável — pediu pra travar de vez, com um botão "Editar" explícito pra reabrir quando for realmente necessário corrigir algo depois da conclusão. Diferente do ajuste anterior, este saiu **também no backend**: `_garante_importacao_em_revisao(importacao)` (nova função em `views.py`) é chamada em todo ponto que escreve dentro de uma importação já criada — `ImportacaoPlanoSaudeLinhaViewSet.perform_create/update/destroy`, `ImportacaoPlanoSaudeAuditoriaViewSet.resolver`, `ImportacaoPlanoSaudeAlteracaoViewSet.reverter` — e recusa (400) se `status == "concluida"`. Novo endpoint `POST /api/importacoes-plano-saude/{id}/reabrir/` (`ImportacaoPlanoSaudeViewSet.reabrir`) volta `status="revisao"` e zera `concluida_em` — único jeito de destravar. `gerar()` em si nunca é bloqueado (sempre pode regerar/rebaixar o arquivo já concluído). No frontend, a tela de Revisão some com todo controle de edição (inputs viram texto, "×"/"Adicionar linha"/"Vincular pessoa"/"Reverter" somem) quando `status === "concluida"`, e mostra um botão "Editar" (ao lado de "Gerar Arquivo") que chama o `reabrir()` e volta tudo ao normal. Testado ponta a ponta via `APIRequestFactory`/`force_authenticate` (sem afetar dados reais, dentro de uma transação revertida): reabrir muda o status, edita normalmente em revisão, e volta a bloquear ao marcar concluída de novo.

**Quinto ajuste, mesmo dia**: "Gerar Arquivo" passou a voltar direto pro histórico depois do download disparar (`showView("list")` + `refreshList()`) — como a importação já fica `concluida`/travada nesse momento (ajuste anterior), não fazia sentido continuar na tela de Revisão sem nada pra fazer ali.

**Sexto ajuste, mesmo dia — filtro no histórico**: com o histórico crescendo (23 importações já), o usuário pediu pra filtrar a lista, não só ordenar — ex.: ver todas as execuções da empresa 221, ou combinar empresa 221 + operadora 3755. Primeira versão foi um campo de texto por coluna (Cód. Empresa/Operadora/Criado por) + um `<select>` pra Status. 100% client-side, sem endpoint novo.

**Sétimo ajuste, mesmo dia — filtro revisado pra "estilo Excel"**: usuário pediu pra trocar os campos de texto por um filtro de planilha de verdade — clicar num ícone de funil na coluna e marcar/desmarcar os valores que aparecem numa lista, como no AutoFilter do Excel. Reescrito (`criarFiltroColuna()`) como um popup por coluna com busca + checklist dos valores distintos daquela coluna (reaproveita `.checklist-box` de Perfis de Acesso, sem CSS/componente novo pra isso) e botões "Aplicar"/"Limpar" — os filtros das 4 colunas continuam combinando entre si (AND). Precisou de um ajuste de CSS colateral: `.pa-table-wrap` corta com `overflow:hidden` pra arredondar os cantos da tabela, o que cortaria o popup também — resolvido com uma classe extra só nesta tabela (`.ips-list-table-wrap`) sobrescrevendo pra `overflow:visible`.

### 81. "Mais informações" por aplicação (botão "?") — e correção do `seed_portal.py` resetando nomes de perfil

Pedido explícito do usuário: um botão "?" ao lado do nome de qualquer aplicação, mostrando "Mais informações" no hover e abrindo, ao clicar, um modal com um texto de ajuda (objetivo/processo/cuidados/resultado esperado). Visualizar é livre a qualquer autenticado; editar é restrito a quem tem o perfil **"Inovação"** vinculado.

- Novo model `AjudaAplicacao` (chave natural `app_key`, `texto`, `atualizado_em`/`atualizado_por`) + endpoint `GET`/`PATCH /api/ajuda-aplicacoes/<app_key>/`. A checagem de quem pode editar é por **nome fixo** do perfil (`Usuario.eh_perfil_inovacao()`/`models.PERFIL_INOVACAO_NOME`), mesmo padrão já usado pro selo "Restrito" de Relatórios Gerenciais (nome === "Diretoria") — decisão explícita do usuário pra não precisar aparecer na árvore de Perfis de Acesso. `GET /api/me/` ganhou `eh_perfil_inovacao`.
- Ligado por ora só em Importação de Plano de Saúde (`static/js/ajuda-aplicacao.js`, `pidCriarBotaoAjuda()`), com um texto inicial já estruturado e salvo no banco — mecanismo genérico o bastante pra outra aplicação só precisar do botão+tooltip no HTML.
- **Ganhou imagens embutidas** (pedido explícito, mesmo mecanismo de "Observações" de Acessos Gerais): editor `<div contenteditable>` com colar/arrastar imagem, sanitizado no servidor via `nh3` antes de salvar. As constantes de allowlist do nh3 foram generalizadas (`ACESSO_GERAL_OBSERVACOES_ALLOWED_*` → `RICHTEXT_ALLOWED_*`, `serializers.py`) pra serem compartilhadas pelos dois campos.
- **Bug real corrigido, achado ao investigar a preocupação do usuário com nomenclatura**: o usuário tinha renomeado o perfil "Integração e Inovação" (código 8) pra "Inovação" e criado um perfil novo "Integração" (código 9) — mas `seed_portal.py` fazia `update_or_create(codigo=..., defaults={"nome": ...})`, que reescrevia `nome` de volta pro valor original a cada execução do seed. Corrigido pra `get_or_create(codigo=..., defaults={"nome": ...})` (nome só gravado na criação); `ativo`/`gerencia_permissoes`/`permissoes` continuam realinhados a cada execução, de propósito. Todas as 8 telas/textos do frontend que ainda diziam "Integração e Inovação" foram atualizadas pra "Inovação".

### 82. Modal de confirmação/aviso genérico — fim do `window.confirm`/`window.alert` nativo

Usuário viu o popup nativo do Chrome ("192.168.x.x:8000 diz...") na confirmação de "Sair sem salvar" do modal de "Mais informações" (rodada 81) e pediu, de forma geral: nenhum popup deve usar o diálogo nativo do browser — sempre um modal dentro do próprio Portal, no padrão visual dele.

- `static/js/confirm-modal.js` (novo, incluído logo depois de `api.js` em **todo** shell, inclusive `index.html`): `pidConfirm(mensagem, opcoes)` (Promise<boolean>) e `pidAlert(mensagem, opcoes)` (Promise<void>) compartilham o mesmo modal (`#pid-confirm-modal`), que empilha por cima de qualquer modal já aberto (`.modal-overlay--top`, z-index maior) sem fechá-lo. `opcoes.perigoso` troca o botão de ação pra `.btn-danger-outline`.
- **Migração completa** (pedido explícito — "migre as demais"): todo `window.confirm()`/`window.alert()` do app (31 ocorrências em 8 arquivos — `acessos-gerais.js`, `calendar-individual.js`, `links-ferramentas.js`, `importacao-plano-saude.js`, `ramais.js`, `profiles.js`, `indicador-desempenho.js`, `users-admin.js`) foi trocado por `pidConfirm`/`pidAlert`. Um modal bespoke que já existia em `importacao-plano-saude.js` só pra esse mesmo motivo (`#ips-regracad-confirm-fechar-modal`, no "Cadastro de Regras") foi removido e consolidado no componente genérico. **Não migrado**: um `window.prompt()` em `users-admin.js` (renomear departamento) — tipo de popup diferente (pede texto), sem componente equivalente ainda.

### 83. Múltiplos arquivos de operadora + Unimed Saúde em PDF (Importação de Plano de Saúde)

Cliente real (Fallkner Ribeiro Borges) em que a Unimed manda **dois PDFs separados** (mensalidade + coparticipação analítico) em vez do CSV único já suportado — diferente de toda operadora até então, que sempre mandava um único arquivo. Duas mudanças, decididas em `EnterPlanMode`/`ExitPlanMode` antes de implementar dado o tamanho:

- **"Arquivo da operadora" passou a aceitar 1+ arquivos** — mudança de arquitetura que afeta todas as operadoras, não só a Unimed. `ImportacaoPlanoSaude.arquivo_operadora` (FileField único) foi substituído por `ImportacaoPlanoSaudeArquivoOperadora` (FK + `arquivo` + `ordem`), migração em 3 passos (`0048` cria o model novo + torna o campo legado `blank=True`; `0049` faz o backfill via `RunPython`, reapontando pro mesmo caminho já salvo sem copiar bytes; `0050` remove o campo legado) — mesmo padrão já usado em `IndicadorDepartamento`/`RegraCusteioPlanoSaude.codigo_empresa`. `pipeline.processa_importacao` passou a receber uma lista de caminhos, chamando `OperadoraParser.extrai()` uma vez por arquivo. Frontend: `<input type="file" multiple>` + lista dinâmica com validação e remoção individuais.
- **Bug real encontrado testando de ponta a ponta** (2 arquivos idênticos da mesma operadora/tipo, via `APIRequestFactory` real): simplesmente concatenar os indivíduos de cada arquivo não bastava — se dois arquivos contribuem pra mesma pessoa e mesmo `tipo_lancamento`, `_aplica_regra_custeio` (matcher.py) **grava** o valor por linha, não acumula, então o segundo arquivo sobrescrevia o valor do primeiro. Corrigido com `_agrega_individuos_entre_arquivos()` (`pipeline.py`), somando por (`numero_beneficiario`, `tipo_lancamento`) antes do casamento — mesmo padrão que cada parser já fazia **dentro** de um arquivo, agora replicado entre arquivos.
- **Parser da Unimed Saúde (`operadoras/unimed/saude.py`) ganhou o segundo formato**: `extrai()` detecta automaticamente, pelo conteúdo da primeira página, se o PDF é o relatório de mensalidade ("BENEFICIARIOS COM FATURAMENTO NO MES") ou o analítico de coparticipação ("SERVIÇOS PRESTADOS"/"ANALITICO") — nunca pede pro usuário escolher. Os dois usam `pdfplumber` com `layout=True` (mesma técnica já validada em `ItamedSaude`). Confirmado com o usuário: a coparticipação por beneficiário é a soma do "Vl Total" de cada serviço (a coluna "Tt Copar", valor fixo repetido em todo o documento, não é usada).
- **3 bugs reais encontrados e corrigidos testando com PDFs gerados via `reportlab`** (reproduzindo linha a linha o texto dos exemplos, através do fluxo completo de `create()`, não mocks): (1) os valores nos PDFs vêm em formato americano (ponto decimal, vírgula de milhar), diferente do formato BR do resto do pipeline — `_valor_pdf_para_float` separada; (2) o grau "FILHO(A)" nunca casava porque a regex usava `\b` logo depois de `)`, que não é caractere de palavra (`\b` nunca bate entre dois não-palavra) — trocado por `(?=\s|$)`; (3) `numero_titular` de um dependente estava sendo setado como o código da família, mas o resto do pipeline (`nomes_titular_por_numero`/`_casa_por_nome` em matcher.py) espera o `numero_beneficiario` do próprio titular ali — sem isso, a família nunca era resolvida e tudo caía em auditoria "sem titular identificado".
- **Ressalva que permanecia**: o arquivo real da Unimed nunca tinha sido processado (só o texto/imagem colados na conversa) — confirmada como necessária no mesmo dia: o usuário testou pela tela e a coparticipação deu "Nenhum beneficiário foi encontrado neste arquivo."

**Ajuste no mesmo dia, depois do teste real — usuário forneceu o caminho dos dois arquivos no disco**: em vez de tentar adivinhar a estrutura de novo a partir de texto colado (já teria sido a terceira vez), pedi e recebi o caminho local dos PDFs e rodei o `pdfplumber` de verdade contra eles (`.venv/Scripts/python.exe` + scripts descartáveis). Duas descobertas reais, só possíveis com o arquivo de verdade — **o texto de um PDF colado numa conversa não é o que `pdfplumber.extract_text()` de fato produz**, então as duas primeiras tentativas (rodada 83 acima) estavam desenhadas sobre uma estrutura que nunca existiu:

- **Mensalidade**: `extract_text()` simples (sem `layout=True`) já devolve linhas bem formadas — a regex da rodada anterior funcionou de primeira contra o arquivo real, bateu exatamente com "Total por Contratante: 6.061,74".
- **Coparticipação analítica**: `benef`+`nome`+`grau` vêm **colados sem espaço nenhum** (ex.: "0975.0167003824292ANDREIA STORMTITULAR") — corrigido ajustando a regex pra não exigir espaço entre eles. Mas surgiu um problema mais sério: o **nome do beneficiário sai truncado em ~13 caracteres** por largura de coluna ("ANDREIA STORMOSKI LARA" → "ANDREIA STORM"), o que faria casamento por nome falhar sistematicamente pra qualquer nome mais longo que a coluna — não é um bug de regex, é informação perdida de verdade no relatório. Como esse mesmo relatório traz CPF completo e confiável, a solução foi trocar a estratégia de casamento: `OperadoraParser` ganhou `chave_casamento_para_tipo(tipo_lancamento)` (default: mesmo valor de sempre, backward-compatible pra todo outro parser) e `UnimedSaude` a sobrescreve pra devolver `"cpf"` só quando `tipo_lancamento="coparticipacao"` **e** a origem foi o PDF (rastreado numa flag de instância setada em `extrai()` — mensalidade, sem CPF em nenhum formato, continua em `"nome"`). Também corrigido: linhas "Pct:MED"/"Pct:HOS"/"Pct:MAT" (detalhamento de um item já somado no valor principal) estavam sendo contadas como itens de serviço de verdade (colidindo com a mesma regex de tipo de serviço), duplicando o valor — agora ignoradas explicitamente.
- **Validado de ponta a ponta com os dois arquivos reais** através do fluxo completo de `create()`: bateu exatamente com "Total da Familia"/"Total da Sequencia" impressos no próprio relatório (1.372,08 de coparticipação, 6.061,74 de mensalidade) e, usando a planilha padrão real da empresa 1123, cada família presente na planilha casou centavo a centavo — a única família ausente da planilha de teste foi corretamente pra auditoria "não cadastrado", não ignorada.

### 84. Vínculos de nome salvos (DE/PARA) — reaplicação automática de "Vincular pessoa"

Usuário perguntou se a resolução manual de nome divergente ("Vincular pessoa") precisava ser refeita em toda execução futura, ou se podia ficar guardada "como se fosse um DE/PARA". Confirmado: sim — guardar, reaplicar automaticamente em importações futuras da mesma operadora+empresa, e mostrar cada aplicação automática na aba Alterações com um botão pra apagar o vínculo. Continua não sendo aproximação — só existe depois de uma confirmação humana explícita (ver "Vínculos de nome salvos (DE/PARA)" no CLAUDE.md pro detalhamento completo).

- Novo model `VinculoNomeOperadora` (migração `0051`, junto com `ImportacaoPlanoSaudeAlteracao.TIPO_VINCULO_AUTOMATICO` + FK `vinculo_nome`) — `codigo_empresa` fica cru no model (normalizado só em `views.py`, pra evitar um import circular entre `models.py` e `empresas_questor.py`, que já importa de `models.py`).
- `matcher._casa_por_nome` ganhou `vinculos_por_nome`/`tipo_lancamento`: quando titular ou dependente não bate por nome exato, consulta o DE/PARA antes de cair em auditoria; cada aplicação automática vira um `VinculoAplicado` (dataclass pura, sem ORM), devolvido por `pipeline.processa_importacao` em `ResultadoProcessamento.vinculos_aplicados`.
- `ImportacaoPlanoSaudeAuditoriaViewSet.resolver()` passou a gravar (`update_or_create`) o `VinculoNomeOperadora` depois de aplicar a resolução manual. `ImportacaoPlanoSaudeViewSet.create()` busca os vínculos relevantes (`_carrega_vinculos_por_nome`) antes de processar, e depois do `bulk_create` das linhas correlaciona cada `VinculoAplicado` (por índice dentro do tipo de lançamento) com a linha já persistida, criando um `ImportacaoPlanoSaudeAlteracao` por vínculo aplicado.
- Botão "Apagar vínculo" (aba Alterações, mesmo endpoint `reverter()`) zera o valor lançado na linha (redistribuindo a regra empresa da família, se houver) e apaga o `VinculoNomeOperadora` — a divergência volta a cair em auditoria nas próximas importações.
- Testado via `APIRequestFactory` dentro de uma transação revertida (nada persistido nos dados reais): matcher.py aplicando/não aplicando o DE/PARA corretamente, `resolver()` criando o vínculo, `_carrega_vinculos_por_nome` encontrando-o, e `reverter()` zerando a linha + apagando o vínculo.

### 85. Nova operadora: Unimed Vitória (4750)

Usuário forneceu os dois PDFs reais do cliente Weitnauer Brasil (empresa 792 na planilha padrão): "Demonstrativo Analítico de Pré Pagamento" (mensalidade) e "Extrato de Co-Participação" (coparticipação), sempre em arquivos separados — nenhum dos dois traz CPF, casamento por nome.

- `operadoras/unimed_vitoria/saude.py` (`UnimedVitoriaSaude`), registrada em `pipeline.OPERADORAS["unimed_vitoria_saude"]`. Detecção automática do tipo pelo conteúdo (marcador "DEMONSTRATIVO" vs. "CO-PARTICIPA" na página 1), mesmo espírito da Unimed do Paraná.
- Particularidade de extração: no PDF de mensalidade, a coluna de nome quebra em 2 linhas físicas quando o nome é longo, num `top` diferente (mas próximo) da linha de dados — nem `extract_text()` nem `extract_text(layout=True)` resolvem isso sem ambiguidade. Solução: reconstruir as linhas a partir de `extract_words(extra_attrs=["fontname","size"])` agrupadas por posição vertical (tolerância calibrada contra o arquivo real) e usar sempre o cabeçalho em negrito (nome completo, sem quebra, distinguido por ser 100% maiúsculo e não começar com dígito) como fonte do nome — nunca a linha de dados quebrada. No PDF de coparticipação, as colunas não têm espaço literal nenhum entre si (só posição) — `extract_words()` tokeniza certo, concatenar `page.chars` direto colaria "1CONSULTA" sem espaço.
- Validado rodando o parser e o `pipeline.processa_importacao` completo contra os dois arquivos reais + a planilha padrão real (empresa 792): mensalidade bateu R$ 340,74 e coparticipação R$ 55,57 (os mesmos valores impressos no próprio relatório), casamento por nome correto contra a planilha, zero itens de auditoria.
- **Limitação conhecida, não validada**: os dois arquivos de exemplo só têm titular, sem nenhum dependente, e nenhum dos dois relatórios traz um marcador textual "Titular"/"Dependente" explícito. A classificação usada (sequência "00" da carteirinha = titular, qualquer outra = dependente; família = tudo antes da sequência) é a convenção nacional já conhecida de outras Unimeds, mas nunca confirmada contra um arquivo real desta operadora com dependente — testar com um caso real antes de confiar nela de olhos fechados (ver CLAUDE.md, seção "Unimed Vitória (4750)").

### 86. Nova operadora: SulAmérica Odonto (4726)

Usuário forneceu o PDF real do cliente Weitnauer Brasil (empresa 792 na planilha padrão, competência 08/2026) — relatório "Conferência de Faturamento PJ (Completo)" do sistema "IS Odonto", plano "ODONTO MAIS PME", só mensalidade (sem coparticipação). Diferente das duas Unimeds já portadas: este relatório traz **CPF de todo mundo** e um campo textual explícito de "Grau parentesco" — casamento por CPF, sem nenhuma suposição sobre numeração de carteirinha.

- `operadoras/sulamerica/odonto_mensalidade.py` (`SulAmericaOdontoMensalidade`), registrada em `pipeline.OPERADORAS["sulamerica_odonto_mensalidade"]`.
- Usuário avisou que a coluna "Valor" tem um totalizador por família impresso no relatório, mas o lançamento deve ser feito por beneficiário — o parser sempre lê o valor da linha individual (última coluna monetária de cada linha de beneficiário), nunca a linha de subtotal da família (que nem tem código nenhum pra casar com nada, então já ficaria de fora naturalmente).
- Mesma técnica de reconstrução de linha por posição (`extract_words()` agrupadas por `top`) já usada na Unimed Vitória, porque o nome de um beneficiário longo quebra pro relatório — só que aqui o corte é mais agressivo (o próprio relatório trunca a última letra da palavra, ex. "SILV" em vez de "SILVA"), sem prejuízo nenhum já que o casamento é por CPF, não por nome.
- Validado rodando o parser e o `pipeline.processa_importacao` completo contra o arquivo real + a planilha padrão real: 15 beneficiários extraídos, R$ 437,40 no total (bate com "Total R$ 437,40" impresso no relatório); 13 casaram certo por CPF contra a planilha padrão de teste, os outros 2 (ausentes dessa planilha) foram corretamente para auditoria "CPF não encontrado" em vez de ignorados/silenciosos.

## Roadmap / próximos passos

Nenhuma pendência explícita em aberto no momento, exceto a limitação conhecida
da rodada 45 (Luciane Gonzaga caindo em "Gerentes" em vez de "Rocket" quando o
usuário mapear os gerentes de verdade — ver rodada 45) — cada rodada acima foi
fechada a pedido do usuário. Ao retomar o projeto, perguntar o que vem a
seguir em vez de assumir. As migrações já foram rodadas até a `0035`
(rodada 45); o passo natural que falta é validar de ponta a ponta num
navegador de verdade um conjunto grande de funcionalidades que só foram
revisadas estaticamente ou testadas parcialmente: Links & Ferramentas
(rodada 16), a tela de Ramais completa (rodadas 21–23, 31–32), Acessos
Gerais (rodada 34) incluindo a restrição de seção por perfil e as
observações ricas com imagem, Eventos Corporativos no Calendário
Individual (rodada 35) com um perfil sem a permissão de criar evento,
Importação de Plano de Saúde (rodada 36) ponta a ponta com um arquivo
real de cada operadora, Simulação de Custo de Contratação (rodada 37)
conferindo o PDF gerado e a Lei 15.270/2025, e Indicador de Desempenho
(rodada 38) com uma apuração completa nova (fora do teste já feito com
os 43 colaboradores, que já validou o pipeline em si).