# P11 — Atendimento: Ouvidoria e e-SIC

| Campo | Valor |
|---|---|
| Programa | F7+ — operação, estrutura e conteúdo |
| Status | `planejado` |
| Depende de | P9 |
| Habilita | P12 (relatório estatístico), P13 |
| Tamanho | **G** (5–7 sessões) |
| ADRs | ADR-019 (LGPD), ADR-021 (rate limit), ADR-024, ADR-035, ADR-012, ADR-025; spec de prazos (LAI) |

## 1. Objetivo

Entregar os dois canais formais de atendimento ao cidadão com **protocolo, prazo, acompanhamento e
resposta** — Ouvidoria (manifestações) e e-SIC (LAI 12.527/2011) — reusando o mesmo padrão de
protocolo por convenção, sem trait/abstract e sem transformar os dois em um módulo só (as bases
legais e os prazos diferem).

**Resultado observável:** o cidadão registra uma manifestação, recebe protocolo e link assinado de
acompanhamento; o CMS responde dentro do prazo; o e-SIC calcula 20 dias + prorrogação de 10 e
notifica; nenhum log/auditoria contém o texto da manifestação ou PII desnecessária.

## 2. Estado atual

- `Portal/Lgpd` já cobre DSAR, consentimento e política de privacidade; `notifications` (P9) e
  rate limit (ADR-021) existem.
- Não existem Ouvidoria nem e-SIC.
- O dossiê V2 prova o protocolo `OUV-{Ymd}-{8}`, mas falha em: status mágico, sem prazo/SLA, sem
  acompanhamento, sem e-mail, `$r->all()+create()` no portal, consentimento não persistido.
- Regra: nada de `$request->all()`; DTO + FormRequest; status como enum; protocolo gerado em ação,
  não no `boot()`.

## 3. Escopo fechado

### S1 — Primitivas compartilhadas (por convenção, sem trait)

- `Core\Support\ProtocolGenerator`: `generate(string $prefix, CarbonInterface $now): string`
  (`PREFIX-{Ymd}-{8}` com alfabeto sem ambíguos), colisão tratada por unique + retry finito;
  prefixos `OUV` e `SIC`. Determinismo: `IdGen`/`Clock` injetados nos testes.
- `Core\Support\Deadline`: cálculo de prazo em dias (calendário), com `start`, `days`,
  `extendable_days`, `due_at`, `is_overdue(now)`; nenhuma chamada a `now()` livre.
- Settings `atendimento.sla` (dias por tipo/canal) e `atendimento.lai` (20 + 10), com defaults
  legais; o painel pode ajustar apenas dentro dos limites permitidos (não reduzir abaixo da lei).
- Não criar um service/módulo “Atendimento” único; cada módulo tem tabelas, rotas e permissões.

### S2 — Ouvidoria: portal

- `GET /ouvidoria` (informação + formulário) e `POST /ouvidoria` com:
  - tipo (reclamação/denúncia/elogio/sugestão/solicitação), assunto, mensagem, anonimato,
    contato (obrigatório se não anônimo), consentimento LGPD explícito (checkbox + timestamp);
  - honeypot + time-trap + rate limit por IP/sessão (ADR-021); 429 RFC 7807 com `Retry-After`;
  - validação server-side (FormRequest), sem `$request->all()`;
  - protocolo gerado na transação; recibo por e-mail (se contato) + link assinado de acompanhamento.
- `GET /ouvidoria/acompanhar/{protocol}` com assinatura (`temporarySignedRoute`, TTL configurável)
  ou protocolo + e-mail; nunca listar por protocolo sozinho (enumeração). Mostra status, resposta
  pública e histórico de status; não mostra notas internas nem dados de terceiros.
- Anonimato: não persistir nome/e-mail; `ip_hash` HMAC com pepper versionado (nunca IP cru);
  consentimento e retenção; exclusão/anonimização conforme LGPD.
- Anexos opcionais via Media (limite/tipo), com varredura de MIME/magic bytes; link privado.

### S3 — Ouvidoria: CMS e workflow

- Rotas `/cms/ouvidoria` (lista/filtros por tipo/status/prazo), detalhe, assumir, responder,
  encerrar, reabrir? (reabrir só com justificativa), notas internas, anexos.
- Status enum: `recebida|em_analise|respondida|encerrada`; transições validadas; `due_at` calculado
  na criação e recalculado em prorrogação (se permitida); alerta de vencimento.
- Permissões `ouvidoria.ver/editar/aprovar/arquivar`; responder/encerrar exige `aprovar`; export
  em massa exige `arquivar`? Definir: `editar` para assumir/notas; `aprovar` para resposta;
  `arquivar` para encerrar. Denúncia com sigilo: acesso restrito ao perfil designado (campo
  `restrito` + policy) — sem bypass.
- Notificação ao manifestante na resposta (se contato) via P9; ao setor na criação. Sem corpo no
  log; sem PII em telemetria (apenas id/protocolo).
- Auditoria: `ouvidoria.received/answered/closed/reopened` com ator e status; **nunca** o texto da
  manifestação no payload de auditoria (ADR-035: evidência, não conteúdo sensível).
- Testes: transições inválidas 422; prazo; resposta notifica; denúncia restrita; anonimato.

### S4 — e-SIC: portal e prazos legais

- `GET /esic` (informação + formulário) e `POST /esic`: identificação do requerente (nome, e-mail,
  documento opcional), descrição, forma de acesso, consentimento; protocolo `SIC-...`.
- Prazo: 20 dias corridos, prorrogável por 10 com justificativa; `due_at`/`extended_due_at`;
  status `recebida|em_analise|respondida|prorrogada|indeferida|encerrada`; indeferimento exige
  fundamento legal (campo obrigatório) e informa recurso.
- Acompanhamento: mesmo padrão assinado da Ouvidoria; resposta e anexos; recurso em 1ª instância
  (campo + prazo) — implementar o registro do recurso e o status; o julgamento pode ser uma ação
  do CMS com parecer.
- Prazos e textos legais em i18n pt_BR (padrão) e traduções; a lei é citada, não parafraseada.
- Rate limit e antiabuso; LGPD: base legal, retenção, acesso auditado.
- Testes: 20/10 dias com clock injetado; prorrogação só com justificativa; indeferimento com
  fundamento; recurso; acompanhamento assinado.

### S5 — e-SIC: CMS e relatório operacional

- `/cms/esic` lista/filtros por status/prazo/recurso; detalhe; responder; prorrogar; indeferir;
  decidir recurso; anexos; notas.
- Permissões `esic.ver/editar/aprovar/arquivar`; prazos e alertas.
- Relatório interno: volume por status, tempo médio de resposta, prorrogas, indeferimentos,
  recursos; export CSV agregado (sem PII) — a versão pública é P12.
- Notificações: recibo, prorrogação, resposta, decisão de recurso.
- Auditoria e testes.

### S6 — Fechamento

- E2E: Ouvidoria (form → protocolo → acompanhamento → resposta) e e-SIC (form → prazo →
  prorrogação → resposta/recurso); rate limit; anonimato; painel restrito.
- `make check` 2× + `E2E=1`; axe; cobertura ≥90%; nenhum PII em log/auditoria/telemetria.
- Atualizar `INVENTARIO.md`, `modulo-ouvidoria.md` e `modulo-esic.md`.

## 4. Fora de escopo

- **PNTP 12.1/12.2/12.5/12.6/12.8/12.9** (unidade/contato do SIC, norma local, prazos/procedimentos,
  classificados e desclassificados) são completados em **P25**, sobre a mesma base de P11.
- **PNTP 12.7** (relatório estatístico público) é P12/P25.
- **BPMS/BPMN configurável** (itens 166–244 do processo Fundão 008476/2025): avaliado em
  [`wiki/backlog/bpms-ouvidoria-esic.md`](../backlog/bpms-ouvidoria-esic.md); **não** é extensão
  automática deste plano e exige ADR própria.
- Sistema de tickets genérico/helpdesk.
- Integração com protocolo único do município/SEI (demanda futura).
- Atendimento por chat/WhatsApp/telefone.
- Publicação automática de denúncias; denúncia anônima com dados de terceiros.
- Relatório estatístico público (P12).

## 5. Fatias de sessão

| Sessão | Entrega | Prova | Depende |
|---|---|---|---|
| **P11.S1** | `ProtocolGenerator` + `Deadline` + settings | colisão/retry; prazo com clock; limites legais | P9 |
| **P11.S2** | Ouvidoria portal (form, protocolo, acompanhamento) | antiabuso; consentimento; assinatura; anonimato | S1 |
| **P11.S3** | Ouvidoria CMS + workflow + notificações | transições; prazo; restrição; auditoria sem texto | S2 |
| **P11.S4** | e-SIC portal + prazos + recurso | 20/10; prorrogação; indeferimento; acompanhamento | S1 |
| **P11.S5** | e-SIC CMS + relatório operacional | responder/prorrogar/decidir; export agregado | S4 |
| **P11.S6** | E2E, docs, 2× check | evidência no `kd` | S3, S5 |

## 6. Contratos e dados

- **Módulos:** `Servicos/Ouvidoria` (token `ouvidoria`) e `Servicos/Esic` (token `esic`).
- **Tabelas:** `ouvidoria_manifestacoes`, `ouvidoria_respostas`, `ouvidoria_anexos`;
  `esic_pedidos`, `esic_respostas`, `esic_recursos`, `esic_anexos`.
- **Core:** `ProtocolGenerator`, `Deadline`.
- **Settings:** `atendimento.sla`, `atendimento.lai`.
- **Rotas:** `ouvidoria.portal.*`, `ouvidoria.cms.*`, `esic.portal.*`, `esic.cms.*`.
- **Permissões:** `ouvidoria.*`, `esic.*`.
- **Eventos:** `ouvidoria.received/answered/closed`, `esic.received/extended/answered/appealed`
  (log + span + auditoria).

## 7. DoD

- [ ] Protocolo único e legível; acompanhamento só por link assinado ou protocolo+e-mail.
- [ ] Consentimento persistido; anonimato real; `ip_hash` com pepper; retenção LGPD.
- [ ] Ouvidoria com status/prazo/resposta; denúncia restrita; notificações.
- [ ] e-SIC com 20+10 dias, prorrogação justificada, indeferimento fundamentado e recurso.
- [ ] Nenhum texto de manifestação/PII em log, auditoria ou telemetria.
- [ ] Antiabuso (honeypot/time-trap/rate limit) e 429 RFC 7807.
- [ ] `make check` 2× + `E2E=1`; cobertura ≥90%; PHPStan max 0.
- [ ] PNTP 12.3/12.4/14.2: e-SIC simples, sem documento/assinatura, protocolo e prazo.
- [ ] PNTP 12.1/12.2/12.5/12.6/12.8/12.9: completados em P25 (link, não duplicar).

## Fechamento — ficha de revisão

> **Obrigatório antes de fechar:** criar `_to_revision/P11-atendimento.md` e seguir
> `_to_revision/README.md` + `_to_revision/PROTOCOLO.md` (v2.0). A ficha não é gate de build; é a
> entrada da fila de revisão profunda.

- Cabeçalho: fase, `kd` épico/tasks/slices, âncoras (este arquivo, ADRs e código) e status
  `⬜ pendente` → `🟡 em revisão` → `✅ revisado` / `🔧 com correções`.
- Conteúdo: o que foi implementado, arquivos/superfícies a revisar, checklist D1–D14 aplicável,
  riscos e observações.
- Fechamento: preencher “Notas da revisão” com data/revisor/resultado e achados (`kd write
  --anchor`), atualizar a fila em `_to_revision/README.md` e `_to_revision/_inventario.md`.
- Achado com correção exige teste vermelho→verde; a fase só é `closed` no `kd` com a ficha
  registrada.

## 8. Riscos

| Risco | Mitigação |
|---|---|
| Enumeração por protocolo | link assinado TTL + protocolo+e-mail; rate limit |
| PII em log/auditoria | DTO sem conteúdo; log só id/protocolo/status; teste de payload |
| Prazo legal errado | `Deadline` com clock injetado + testes 20/10; settings com piso legal |
| Denúncia exposta | campo `restrito` + policy; teste com perfil comum |
| Protocolo duplicado | unique + retry finito; teste de concorrência |
| Formulário usado para spam | honeypot/time-trap/rate limit + validação server-side |

## 9. Retomada

```bash
kd prime
kd ask "ouvidoria e-SIC protocolo prazo LAI LGPD"
kd task list --ready
```

Ler: `wiki/backlog/modulo-ouvidoria.md` / `modulo-esic.md` → dossiês `ouvidoria/` e
`solicitacoes-lai/` → `lotep-v2/servicos-ouvidoria/09` → `src/modules/Portal/Lgpd/**` →
`src/core/Internal/Audit/**` → `services/Notifications` (P9).