agenciapsilmno/HANDOFF.md

# HANDOFF — 2026-05-05 (sprint blueprint tabular Melissa + arquivamento de pacientes)

Documento de continuidade. **Quando voltar, comece lendo esta página.**

> **🟡 PENDENTE — Sub-sessão 2 do A66 (V2 dialog)**: skeleton entregue
> em 2026-05-05 mas user **não gostou do design** ao olhar o preview.
> Aguarda feedback específico (3 zonas tá errado? hierarquia? hero
> grande demais? mobile? referência visual?). Iteração só depois disso.
> Detalhes na seção "Sessões dedicadas pendentes" no fim deste doc.

> **🟢 ENTREGUE HOJE — Blueprint de página tabular Melissa**: documentado
> em `blueprints/melissa-table-page-blueprint.md` (~530 linhas, 18 seções)
> e aplicado em **MelissaCadastrosRecebidos** (refator) +
> **MelissaAgendamentosRecebidos** (NOVO, native page) +
> **MelissaPacientes** (refator parcial). Inclui DataTable com `:loading`
> + `paginator` + frozen action column, view toggle list/grade,
> sidebar com filtros coloridos por status, subheader explicativo,
> Tailwind 600 status colors, e mobile pencil + popover menu.

Sessão de polimento e estruturação — não houve commit. Working tree
acumulada de 4 sprints (28 modificados + 22 novos).

---

## 🚦 STATUS — Working tree

**Modificados:**
```
M HANDOFF.md
M database-novo/agenciapsi-db-dashboard.html
M database-novo/db.config.json
M database-novo/generate-dashboard.cjs
M src/components/notifications/NotificationDrawer.vue
M src/components/notifications/NotificationItem.vue
M src/composables/useFeriados.js
M src/features/agenda/components/AgendaClinicMosaic.vue
M src/features/agenda/components/AgendaEventDialog.vue          ← A66 sub-sessão 1 done
M src/features/agenda/composables/useAgendaSettings.js
M src/features/agenda/pages/AgendaTerapeutaPage.vue
M src/features/documents/DocumentsListPage.vue
M src/features/patients/cadastro/PatientsCadastroPage.vue       ← statusOpts +Arquivado HOJE
M src/features/patients/prontuario/PatientConversationsTab.vue
M src/features/patients/prontuario/PatientProntuario.vue
M src/features/patients/services/patientsRepository.js          ← +restorePatient HOJE
M src/layout/melissa/MelissaAgenda.vue
M src/layout/melissa/MelissaCadastrosRecebidos.vue              ← refator blueprint HOJE
M src/layout/melissa/MelissaEmbed.vue                           ← agendamentos-recebidos removido HOJE
M src/layout/melissa/MelissaEventoPanel.vue
M src/layout/melissa/MelissaLayout.vue                          ← MAR wire-up HOJE
M src/layout/melissa/MelissaPacientes.vue                       ← refator grande HOJE
M src/layout/melissa/composables/useMelissaAgenda.js
M src/layout/melissa/composables/useMelissaEventos.js
M src/layout/melissa/composables/useMelissaPacientes.js
M src/layout/melissa/composables/useMelissaPacientesAside.js
M src/router/routes.misc.js
D database-novo/backups/2026-03-27/                              (3 arquivos antigos)
D database-novo/backups/2026-03-29/                              (3 arquivos antigos)
```

**Novos:**
```
?? blueprints/melissa-table-page-blueprint.md                    ← NOVO HOJE
?? database-novo/migrations/20260504000001_fix_cancel_notifications_excluido.sql
?? src/features/agenda/components/AgendaEventDialog.vue.bak     ← rollback A66
?? src/features/agenda/components/AgendaEventDialogV2.vue       ← A66 sub-sessão 2 (NÃO TESTADO)
?? src/features/agenda/components/InsurancePlanQuickCreateDialog.vue
?? src/features/agenda/components/ServiceQuickCreateDialog.vue
?? src/features/agenda/composables/agendaEventHelpers.js        ← A66 1A
?? src/features/agenda/composables/useAgendaEventActions.js     ← A66 1C-i
?? src/features/agenda/composables/useAgendaEventComposer.js    ← A66 1B
?? src/features/agenda/composables/useAgendaEventLifecycle.js   ← A66 1C-ii-b
?? src/features/agenda/composables/useAgendaEventPickerBilling.js ← A66 1C-ii-a
?? src/features/agenda/composables/__tests__/                    (5 specs)
?? src/features/patients/prontuario/PatientProntuario.vue.bak
?? src/layout/melissa/MelissaAgendaHistoricoCard.vue
?? src/layout/melissa/MelissaAgendamentosRecebidos.vue          ← NOVO HOJE
?? src/layout/melissa/composables/useMelissaAgendaHistorico.js
?? src/layout/melissa/composables/useMelissaDockPins.js
?? src/stores/melissaCacheStore.js
?? src/views/pages/preview/                                      (V2 preview)
```

---

## ✅ FEITO HOJE (2026-05-05)

### 1. Blueprint de página tabular — `melissa-table-page-blueprint.md`

Novo arquivo em `blueprints/`. ~530 linhas, **18 seções**:

1. Princípio (sidebar de filtros + main com toolbar + tabela)
2. Estrutura do template (com **subheader explicativo**)
3. Estado JS (script setup) — busca, statusFilter, paginação, viewMode
4. DataTable view Lista — props canônicas explicadas
5. View Grade — cards em CSS grid, `<div role="button">`
6. Tokens de surface (light/dark) — `--p-content-background` canônico
7. Cores de status — Tailwind 600 (azul/verde/vermelho), aplicadas em 4 lugares
8. Filtro de status + Limpar filtro com Transition fade
9. **Subheader explicativo** — diferencia páginas de layout idêntico
10. Toolbar — busca + view toggle
11. DataTable estilos completos (header transparent, frozen column, paginator)
12. Botão pencil — coluna fixa
13. Empty / loading
14. Mobile (<1024px) — scroll horizontal, NÃO esconde colunas
15. Acessibilidade
16. Checklist de adoção (16 itens)
17. Anti-patterns (11 erros documentados)
18. Referência canônica → `MelissaCadastrosRecebidos.vue`

### 2. MelissaCadastrosRecebidos — refator pra blueprint

Antes era lista de cards verticais; agora é DataTable PrimeVue com:
- **Sidebar** `--m-bg-soft` + border-right + sombra `0 2px 8px` nos cards
- **Stats card** (Total / Novos / Convertidos / Rejeitados) — Novos azul / Conv verde / Rej vermelho
- **Status filter card** com 3 níveis de cor (default 5%, hover 10%, active 16% + ring) + botão
  "Limpar filtro" com Transition fade quando ativo
- **Toolbar main** com search + view toggle (lista/grade)
- **DataTable** `:loading + paginator + scrollable scrollHeight="flex"
  + tableStyle="min-width:640px"` — colunas: Paciente / Contato / Recebido / Ação (frozen 60px right)
- **Coluna frozen** com bg `--p-content-background` (canônico, opaco em ambos modos),
  sombra à esquerda, hover/selected herdam da row
- **Botão pencil** (`mcr-row__action`) primary tinted
- **View Grade** alternativa — cards em CSS grid `auto-fill, minmax(220px, 1fr)`
  com Paginator standalone abaixo
- **Subheader explicativo** com `pi pi-info-circle` em primary

### 3. MelissaAgendamentosRecebidos — NOVO native page

Substitui o embed via `MelissaEmbed`. Espelha 1:1 o blueprint, prefixo `mar`.

- Tabela DB: `agendador_solicitacoes` (não `patient_intake_requests`)
- **4 status com cores próprias**:
  - 🔵 Pendente (`rgb(37, 99, 235)`)
  - 🟢 Autorizado (`rgb(22, 163, 74)`)
  - 🟦 Convertido (`rgb(13, 148, 136)` — teal, distinto)
  - 🔴 Recusado (`rgb(220, 38, 38)`)
- **DataTable**: 6 colunas (Paciente / Solicitado / Tipo / Contato / Recebido / Ação frozen)
- **3 ações condicionais** no dialog de detalhes:
  - **Pendente** → Recusar (com motivo) | Autorizar | Converter em sessão
  - **Autorizado** → Converter em sessão (cria paciente se necessário + abre `AgendaEventDialog`)
  - **Convertido/Recusado** → só fechar
- **AgendaEventDialog wired** com props canônicas (event-row, owner-id, tenant-id,
  agenda-settings, commitment-options, preset-commitment-id,
  restrict-patients-to-owner)
- Subheader explicativo próprio

**Wire-up no `MelissaLayout.vue`:**
- Import de MelissaAgendamentosRecebidos
- `MELISSA_EMBED_KEYS` perdeu `agendamentos-recebidos`
- `MELISSA_NON_CONFIG_SLUGS` ganhou direto
- Render block conditional entre Cadastros e Médicos
- `MelissaEmbed.EMBED_MAP` perdeu a entry agendamentos-recebidos (com comentário)

**Importante**: o `MelissaEmbed.vue` foi modificado pra fazer `hideChrome` flag
+ close flutuante numa tentativa anterior — **revertido** ao original
porque ficou ruim. Layout Rail (`/therapist/agendamentos-recebidos`,
`/admin/agendamentos-recebidos`) continua usando `AgendamentosRecebidosPage.vue`
inalterada.

### 4. MelissaPacientes — refator parcial pra blueprint

A página é 3-pane (filters / list / detail) — não converti pra
DataTable (perderia o detail panel). Aplicado o que faz sentido:

**Sidebar:**
- Sombra `0 2px 8px` nos cards `.mp-w` (sidebar + quick view direita)
- Status pills com cores próprias por status:
  - Todos = neutral (sem cor)
  - 🟢 Ativos verde
  - 🟡 Inativos amber `rgb(217, 119, 6)` (warn, pausa temporária)
  - 🔴 Arquivados vermelho
- Botão "+" do header de Grupos/Tags **substituído** por:
  - Botão `pi pi-cog` no header (sem borda, hover primary) — emite
    `goto-grupos`/`goto-tags` que navegam pras Melissa Pages nativas
  - Botão tracejado "+ Grupo / + Tag" (texto sem "+", só com ícone
    `pi pi-plus`) abaixo de cada lista — abre popover de criação
- Botão `[×]` (clear filter) agora vermelho `rgb(220, 38, 38)`

**Card de paciente (list view):**
- **Email em coluna própria** (220px, truncate) — separada do main
- **Telefone em coluna própria** (140px) — paralela ao email
- Em mobile (<768px) email/phone escondem (info no detail panel)
- Subheader explicativo

**Mobile:**
- Coluna ação fixa (`position: sticky; right: 0; bg --m-bg-medium`)
- 5 botões inline → 1 botão `pi pi-pencil` único que abre `<Popover>`
- **Popover de ações** global no fim da `<section>` com 5 items:
  Prontuário / Sessões / WhatsApp / Editar / Arquivar (com divider)
- Bug fix: **`min-height: 0` na `.mp-list`** — sem isso a `mp-list__body`
  não scrollava em mobile (`flex: 1; overflow-y: auto` precisa de
  parent constrained)

**Toolbar:**
- View toggle list/grade (persistido em `mp.viewMode.v1` localStorage)
- Botão "Novo paciente" usa `PatientCreatePopover` (mesmo do agenda) —
  já estava wired, só explicitei `$event` no click handler

**Grid view (NOVO):**
- CSS grid `auto-fill, minmax(240px, 1fr)`
- Cards com avatar+pencil topo, nome+novo, status, email+phone empilhados,
  tags, "Última: X" com border-top
- Mantém `selecionarPaciente` (mostra detail panel mesmo no grid)
- `<div role="button" tabindex="0">` com handlers de teclado

### 5. Subheader explicativo (padrão novo do blueprint § 9)

Aplicado em 3 páginas, cada uma com texto próprio que diferencia
páginas de layout idêntico:

- **MelissaCadastrosRecebidos**: "Cadastros completos enviados por
  pacientes via formulário externo (link público). Revise os dados,
  **converta em paciente ativo** com 1 clique ou **rejeite** com motivo
  opcional."
- **MelissaAgendamentosRecebidos**: "Solicitações de horário vindas do
  agendador online à espera de ação. **Autorize** pra reservar o slot,
  **recuse** com motivo, ou **converta direto em sessão** — a gente cria
  o paciente automaticamente se ainda não existir."
- **MelissaPacientes**: "Lista completa dos pacientes cadastrados.
  Filtre por **status, grupo ou tag** à esquerda, busque por nome ou
  contato, e clique numa linha pra abrir o **prontuário** com histórico,
  sessões e documentos."

CSS padrão: `bg --m-bg-soft` + ícone `pi pi-info-circle` em primary +
texto muted 0.78rem com `<strong>` em `--m-text`. Border-bottom matching
o page__head.

### 6. Arquivamento de pacientes — restore implementado

**Repository** (`patientsRepository.js`):
- Novo `restorePatient(id, { tenantId })` — espelha `softDeletePatient`
  mas seta `status = 'Ativo'`

**PatientsCadastroPage** (`statusOpts:749`):
- Adicionado `{ label:'Arquivado', value:'Arquivado' }` à lista de
  opções do dropdown — fecha o gap de inconsistência ao editar paciente
  arquivado

**MelissaPacientes**:
- Helper `isArquivado(p)` (case-insensitive)
- Função `restaurarPaciente(p)` com confirm dialog → `restorePatient` →
  toast "Restaurado" → `refetchTudo`
- **Toggle visual condicional**:
  - Paciente **ativo**: 🗑 trash vermelho ("Arquivar")
  - Paciente **arquivado**: ↶ undo primary ("Restaurar")
- Aplicado em ambos contextos:
  - Desktop (5 botões inline) — `mp-card__action--restore` com hover primary
  - Mobile popover menu — `mp-actions-menu__item.is-restore`

---

## 🧪 ROTEIRO DE TESTE (rápido — ~15 min)

### Setup
```powershell
Remove-Item -Recurse -Force node_modules\.vite -ErrorAction SilentlyContinue
npm run dev
```

### Fase 1 — MelissaCadastrosRecebidos (5 min)
- `/melissa/cadastros-recebidos` → DataTable com header transparent +
  bold, paginator centralizado, coluna Ação frozen direita com bg
  branco no light
- Toolbar: search + view toggle (lista/grade)
- Sidebar: stats com Novos azul, Convertidos verde, Rejeitados vermelho
  (quando >0); Status filter com 3 cores + Limpar filtro fade
- Subheader azul info-circle explicativo
- Mobile: drawer abre, scroll horizontal funciona, pencil único na
  Ação frozen, todas colunas visíveis (não escondem)

### Fase 2 — MelissaAgendamentosRecebidos (5 min)
- `/melissa/agendamentos-recebidos` → mesma estrutura, 4 status com cor
  (Pendente azul / Autorizado verde / Convertido teal / Recusado vermelho)
- Click numa pendente → dialog mostra 3 ações (Recusar / Autorizar /
  Converter em sessão); converter cria paciente automático + abre
  AgendaEventDialog
- Subheader próprio diferenciando da Cadastros Recebidos

### Fase 3 — MelissaPacientes (5 min)
- `/melissa/pacientes`:
  - Sidebar com sombras nos cards (Estatísticas, Status, Grupos, Tags)
  - Cards Grupos/Tags: cog `⚙` no header (sem borda, navega pra
    `/melissa/grupos` e `/melissa/tags`); botão tracejado "+ Grupo" /
    "+ Tag" abaixo da lista; X de limpar filtro vermelho
  - Status pills coloridas (Ativos verde / Inativos amber / Arquivados
    vermelho)
- Card de paciente: email coluna própria, phone coluna própria
- Toolbar: view toggle lista/grade (persiste); "Novo paciente" abre
  PatientCreatePopover com 3 opções (rápido / completo / link)
- **Mobile (<1024px)**: scroll vertical funciona (era bug, corrigido com
  `min-height: 0` na `.mp-list`); ações reduzem a 1 pencil sticky-right
  com Popover de 5 items
- **Restore de arquivado**:
  - Filtra por "Arquivados" (cor vermelha)
  - Hover num card → desktop mostra ↶ "Restaurar" (primary) no lugar
    do 🗑 trash
  - Mobile: pencil → popover mostra "Restaurar" primary
  - Click → confirm "Restaurar X?" → status volta a Ativo → some do
    filtro Arquivados, aparece em Ativos

---

## ⏭️ PRÓXIMOS PASSOS (sugestão)

### 1. Decidir A66 V2 — design

User testou o esqueleto V2 em `/preview/agenda-dialog-v2` (rota em
`routes.misc.js`) e **não gostou do design**. Aguarda feedback
específico antes de iterar:
- Estrutura: 3 zonas (PACIENTE/QUANDO/O QUÊ) tá errado? Prefere 2 zonas?
  1 coluna scroll? Tabs?
- Hierarquia: hero PACIENTE muito grande/pequeno?
- Densidade: airy demais ou apertado demais?
- Chips de duração/scope/status: muito visuais?
- Mobile: já testou viewport pequeno?
- Referência visual: Win11? Cleaner? Mais como V1? Algum app?

Quando tiver feedback, iterar em `AgendaEventDialogV2.vue`. Sub-sessão
3 (migração nos 9 consumers) só depois do V2 estabilizar.

### 2. Aplicar blueprint nas demais páginas tabulares Melissa

Ainda faltam (todas seguem `melissa-table-page-blueprint.md`):
- `MelissaCompromissos.vue`
- `MelissaMedicos.vue`
- `MelissaConversas.vue`
- `MelissaRecorrencias.vue`
- `MelissaTags.vue`
- `MelissaGrupos.vue`

Padrão: prefixo próprio (`mco`, `mmd`, etc.), sidebar com filtros
coloridos, DataTable com frozen action column, view toggle, subheader,
mobile pencil+popover.

### 3. Decidir commits

Acumulado de 4 sprints sem commitar (28 mod + 22 novos). Sugestão de
chunks lógicos (em ordem temporal):

1. **Sprint A** — Sprint 04-29/30 (hub Configurações + 7 Melissa Pages
   + dialog blueprint dark)
2. **Sprint B** — Sprint 05-03 (timeline FullCalendar parity, cards
   resumo, dock pins, topbar, NotificationDrawer redesign,
   melissaCacheStore, useMelissaDockPins)
3. **Sprint C** — Sprint 05-04 (MelissaAgendaHistoricoCard, useFeriados
   cache opt-in, PatientProntuario aba Visão Geral, migration
   `20260504000001_fix_cancel_notifications_excluido.sql`)
4. **Sprint D** — A66 sub-sessão 1 (5 composables + 5 specs + 265
   testes) + sub-sessão 2 esqueleto (V2 + preview) — **MARCAR como WIP**
5. **Sprint E HOJE** — Blueprint tabular Melissa + MelissaCadastrosRecebidos
   + MelissaAgendamentosRecebidos + MelissaPacientes refator + restore
   de pacientes arquivados

### 4. Restore em outros layouts

A `PatientsListPage.vue` (layout Rail) também tem KPI "Arquivados"
mas SEM botão Restaurar. Quando tocar nela, replicar o pattern:
botão condicional ↶ "Restaurar" baseado em `p.status === 'Arquivado'`,
chama `restorePatient` do mesmo repository.

---

## 🛠️ Sessões dedicadas pendentes

### A66 — Refactor `AgendaEventDialog` V2 (3 sub-sessões)

**Estado**:
- ✅ Sub-sessão 1 (composables) — 5 composables + 265 testes, 495/495
  suite passando, AgendaEventDialog 3522→2632 linhas (-25%)
- 🟡 Sub-sessão 2 (template V2) — esqueleto entregue 2026-05-05,
  **user não gostou do design**, aguarda feedback específico
- ⏳ Sub-sessão 3 (migração nos 9 consumers) — depende do V2 estabilizar

**Por que sessão dedicada**: arquivo tinha 3522 linhas, é consumido em
9 páginas críticas (AgendaTerapeutaPage, AgendaClinicaPage,
MelissaLayout, MelissaEventoPanel, useMelissaAgenda,
AgendamentosRecebidosPage, TherapistDashboard, AgendaDevDocs).
Refatoração inteira não cabe em uma única conversa sem alto risco
de regressão.

**Estado dos arquivos**:
- Backup: `src/features/agenda/components/AgendaEventDialog.vue.bak`
  (155KB, byte-idêntico ao original)
- 5 composables novos em `src/features/agenda/composables/`:
  `agendaEventHelpers.js` (262L) +
  `useAgendaEventComposer.js` (485L) +
  `useAgendaEventActions.js` (387L) +
  `useAgendaEventPickerBilling.js` (378L) +
  `useAgendaEventLifecycle.js` (474L)
- 5 specs em `__tests__/` (75+76+28+43+43 = 265 testes)
- `AgendaEventDialogV2.vue` (~1100L, 3 zonas) — não testado visualmente
- Preview em `/preview/agenda-dialog-v2` com 5 cenários

**Próxima ação**: user dá feedback design → eu itero V2.

---

## 📚 Tracking persistente

- **A66** — sub-sessão 2 (V2 design) aguardando feedback do user
- **Blueprint tabular Melissa** — referência canônica:
  `MelissaCadastrosRecebidos.vue`. Próximas adoções planejadas:
  Compromissos, Médicos, Conversas, Recorrências, Tags, Grupos
- **Restore pacientes** — implementado no Melissa; replicar no Rail
  (`PatientsListPage.vue`) quando tocar
- **Migration aplicada local**: `20260504000001_fix_cancel_notifications_excluido.sql`
  (cancela 'excluido' do enum trigger). Já aplicada no DB local.

---

## 📦 Setup pra retomar

```powershell
# Limpa cache do Vite (recomendado depois de muita mudança em styles)
Remove-Item -Recurse -Force node_modules\.vite -ErrorAction SilentlyContinue

# Sobe dev
npm run dev

# Build sanity check (opcional, mas roda em ~25s)
npm run build
```

**Suite de testes** (495 testes do A66 incluídos):
```powershell
npm run test
```

**Login**: user com `layout_variant=melissa` no profile pra testar
direto em `/melissa/...`. Pra testar Rail (regressão), troca em
`/account/profile` → terceiro card "Layout".

---

**Boa noite. Amanhã começa pelo feedback do A66 V2 ou aplicação do
blueprint nas demais Melissa Pages tabulares — o que você preferir.**