# Lembretes operacionais

## Objetivo
Este documento descreve a base de lembretes operacionais criada para transformar proximos passos internos em notificacoes agendadas, com reaproveitamento em diferentes modulos.

## Escopo inicial
O primeiro uso foi entregue em `paciente-editar`, dentro da aba de contatos e relacionamento.

Nesse fluxo o lembrete:
- pertence a um contexto, usando `context_type` e `context_id`
- aponta um destinatario interno com `target_user_id`
- pode referenciar o paciente relacionado com `related_user_id`
- define data e hora em `remind_at`
- usa os canais configurados no proprio lembrete
- dispara notificacao in-app e opcionalmente push ou e-mail

## Estrutura tecnica

### Back-end
- `src/Modules/Reminders/Repositories/ReminderRepository.php`
  Responsavel por persistencia, listagem por contexto, consulta de pendentes e mudanca de status.
- `src/Modules/Reminders/Services/ReminderService.php`
  Responsavel por validacao, criacao, enriquecimento do payload, disparo via notificacoes e links de destino.
- `src/Modules/Reminders/Http/RemindersController.php`
  Exposicao da API administrativa em `/adm/api/Reminders/*`.
- `src/Cron/Tasks/RemindersDueCronTask.php`
  Runner usado pelo cron horario.

### Banco
- migration: `sql/2026-04-14-create-app-reminders.sql`
- tabela: `wpjy_app_reminders`

Campos principais:
- `context_type`
- `context_id`
- `target_user_id`
- `related_user_id`
- `title`
- `description`
- `remind_at`
- `channels_json`
- `status`
- `notification_id`
- `notified_at`

### Front-end
- `pages/admin/partials/paciente/tab-contatos.php`
- `pages/admin/partials/paciente/modals-reminders.php`
- `pages/admin/assets/js/paciente-editar/reminders.js`
- `scripts/reminders-popup.js`

## Relacao com notificacoes
O modulo de lembretes nao substitui a central de notificacoes. Ele agenda um evento e, quando chegar a hora, delega a entrega para a infraestrutura ja existente.

Vantagens:
- nao duplica inbox
- reaproveita preferencias por canal
- reaproveita push web
- reaproveita logs de entrega
- mantem um unico centro de notificacoes para o usuario

## Fluxo de disparo
1. o operador cria um lembrete para um contexto
2. o registro fica aberto em `wpjy_app_reminders`
3. o cron horario consulta lembretes vencidos e ainda nao notificados
4. cada lembrete gera uma notificacao do tipo `event_reminder`
5. o lembrete recebe `notification_id` e `notified_at`
6. no admin, o popup `Swal` pode abrir o lembrete vencido assim que ele aparecer no inbox

## Extensao futura
A estrutura foi pensada para crescer sem refazer a modelagem. Exemplos naturais:
- `context_type = task`
- `context_type = lead`
- `context_type = ticket`
- `context_type = booking`

## Segunda etapa entregue
Com a expansao para uso transversal no admin, o modulo agora tambem possui:
- captura rapida na topbar via `includes/template/matdash/offcanvas-reminders.php`
- central administrativa em `pages/admin/lembretes.php`
- listagem filtravel e indicadores em `/adm/api/Reminders/panel` e `/adm/api/Reminders/stats`
- visao global para super admin e outros perfis admin-like

Documento complementar:
- `docs/lembretes-central-admin.md`

Recomendacao:
- manter o lembrete sempre como acao futura
- manter historicos e notas como registro passado
- usar o contexto para montar links de retorno e filtros por modulo