# Solicitações de serviços digitais (PNTP 15.3) — especificação

| Campo | Valor |
|---|---|
| **Prioridade** | **DEVE** (P25) |
| **Status** | Especificação para implementação (decisão D17) |
| **Fase** | P25 — SIC completo, LGPD e governo digital |
| **Depende de** | P11 (`ProtocolGenerator`/`Deadline`), P15 (`servicos_publicos`), P9 (importador/notificações) |
| **ADRs** | ADR-001, ADR-009, ADR-012, ADR-017, ADR-019, ADR-021, ADR-024, ADR-033, ADR-035, ADR-043 |

## 1. Objetivo

Permitir que o cidadão **solicite um serviço público real** pelo portal, receba um protocolo e
acompanhe o andamento, sem transformar o produto em helpdesk/ticket genérico nem em motor de
workflow. É o requisito PNTP 15.3: pelo menos um serviço digital real, com formulário, protocolo e
acompanhamento.

## 2. Fora de escopo

- Helpdesk/ticket genérico, chat/WhatsApp, SLA comercial, fila de atendimento humano.
- Motor de workflow/BPMN (se um dia houver demanda, é serviço separado — `workflow-bpm-isolado`).
- Integração com protocolo único/SEI ou sistema externo; link externo é navegação.
- Pagamento, assinatura digital, upload público sem controle.
- Portal de serviços de terceiros.

## 3. Modelo de dados

### 3.1 Serviço (dono: P15)

`servicos_publicos` (já previsto em P15) ganha:

| Campo | Tipo | Regra |
|---|---|---|
| `slug` | `text` | único case-insensitive; estável |
| `nome` | `jsonb` | `LocaleCast`; 4 locales |
| `descricao` | `jsonb` | AST (ADR-028) |
| `digital` | `bool` | se `true`, exige solicitação/acompanhamento interno |
| `form_schema` | `jsonb` | schema fechado dos campos (versão) |
| `prazo_dias` | `int` | prazo legal/operacional; `Deadline` |
| `canal` | `text` | `portal|presencial|telefone|email|externo` |
| `responsavel` | `text` | unidade/setor (não PII de servidor) |
| `active` | `bool` | serviço desativado não aceita nova solicitação |

`form_schema`:

```jsonc
{
  "version": 1,
  "fields": [
    {"key":"nome","type":"string","required":true,"max":120},
    {"key":"email","type":"email","required":true},
    {"key":"descricao","type":"text","required":true,"max":4000},
    {"key":"anexo","type":"file","required":false,"accept":["application/pdf"],"max_kb":5120}
  ]
}
```

- Tipos fechados: `string|text|email|phone|date|select|checkbox|file`.
- Sem HTML/CSS/Blade; sem campo livre de script; condicional server-side quando possível.
- A versão do schema é gravada na solicitação; editar o serviço não reescreve o passado.

### 3.2 Solicitação

`solicitacoes_servico`:

| Campo | Tipo | Regra |
|---|---|---|
| `id` | `uuid` | `uuidv7()` |
| `protocolo` | `text` | único; formato `SOL-{ano}-{sequência}`; determinístico |
| `servico_id` | `uuid` | FK `restrictOnDelete` |
| `form_version` | `int` | versão do schema usada |
| `respostas` | `jsonb` | snapshot validado; sem HTML |
| `nome` / `email` / `telefone` | `text` | contato; `encrypted` quando armazenado |
| `consent_at` | `timestamptz` | consentimento explícito |
| `ip_hash` | `text` | HMAC diário; nunca IP cru |
| `status` | `text` | `recebida|em_analise|aguardando_documento|deferida|indeferida|cancelada` |
| `assigned_to` | `uuid` null | operador responsável (CMS) |
| `due_at` | `timestamptz` | calculado por `Deadline` |
| `created_at`/`updated_at` | `timestamptz` | — |

- `UNIQUE (protocolo)`; índice `(status, due_at)`, `(servico_id, created_at)`, `(assigned_to, status)`.
- Anexos em `solicitacao_anexos` (`media_id`, `tipo`, `publico=false`), sempre privados.
- Eventos em `solicitacao_eventos` (`id`, `solicitacao_id`, `tipo`, `actor_id`, `mensagem` AST,
  `created_at`): timeline imutável; correção = novo evento.
- `protocolo` não é segredo; o acompanhamento exige **protocolo + e-mail** ou link assinado com TTL.
  Rate limit por IP/protocolo para evitar enumeração.

## 4. Fluxo e regras

1. Portal `/servicos/{slug}/solicitar` (serviço `digital=true` e ativo) valida `form_schema`,
   consentimento e anexos; cria a solicitação e o protocolo; exibe recibo.
2. `POST`/`GET` de acompanhamento: `/servicos/acompanhar/{protocolo}` com e-mail ou link assinado;
   mostra status, timeline pública e pendências; nunca mostra anexo por URL adivinhável.
3. CMS `Solicitações`: inbox por status/serviço/prazo; assumir, solicitar documento, deferir,
   indeferir, cancelar; cada ação é um evento auditado.
4. Transições explícitas:
   `recebida → em_analise → aguardando_documento → deferida|indeferida`,
   `recebida|em_analise|aguardando_documento → cancelada`.
   Transição inválida = 422; não há workflow configurável.
5. Prazo: `Deadline` (P11) calcula `due_at`; atraso é visível; não altera o prazo legal.
6. Notificação: e-mail de recibo/mudança de status via `Notifications` (P9), sem corpo em log.
7. LGPD: consentimento, finalidade, retenção; contato cifrado; acesso auditado; expurgo via
   `RetentionRegistry`; sem PII em telemetria. `ip_hash` só para antiabuso.
8. Acessibilidade: formulário com labels/erros, funciona sem JS; timeline semântica; link assinado
   com aviso de expiração; 4 locales.

## 5. Contratos e superfícies

- **Módulo:** `Servicos/Solicitacoes` (token `solicitacoes`, grupo `Servicos`), permissions
  `[VIEW, EDIT, APPROVE]`; o serviço em si é `Servicos/CartaServicos` (P15).
- **Portas:** `ProtocolGenerator`/`Deadline` (P11) por injeção; `SitemapSource`/`SearchSource`
  quando o serviço for público.
- **Rotas:** `servicos.solicitar`, `servicos.acompanhar`, `solicitacoes.cms.*`.
- **Eventos:** `solicitacoes.created`, `solicitacoes.assigned`, `solicitacoes.document_requested`,
  `solicitacoes.approved`, `solicitacoes.rejected`, `solicitacoes.cancelled`.
- **Auditoria:** criação, acesso a dado sensível, mudança de status, download de anexo.
- **Sem API pública** de solicitações no MVP; acompanhamento é rota pública controlada.

## 6. Fatias de sessão

| Sessão | Entrega | Prova |
|---|---|---|
| **P25.S3a** | schema/DB + `ProtocolGenerator`/`Deadline` + criação | protocolo único; transição inválida 422; sem PII em log |
| **P25.S3b** | portal de solicitação + acompanhamento | form sem JS; link assinado expira; rate limit |
| **P25.S3c** | CMS inbox + ações + anexos privados | assumir/responder; anexo 403; auditoria |
| **P25.S3d** | notificações + retenção + E2E | e-mail fake; expurgo; 4 locales; axe |

## 7. Critérios de aceite

- [ ] Pelo menos um serviço real (`digital=true`) com formulário e acompanhamento.
- [ ] Protocolo determinístico/único; nenhuma enumeração; acesso exige protocolo+e-mail ou link.
- [ ] Transições explícitas; nenhuma ação por `GET`; CSRF e permissão.
- [ ] Anexo privado; nenhuma URL S3 exposta; download auditado.
- [ ] Contato cifrado; consentimento; retenção/expurgo; sem PII em log/telemetria.
- [ ] Formulário e timeline acessíveis; 4 locales; `make check` 2× + `E2E=1`.

## 8. Rejeições

- Motor de formulário/workflow genérico, helpdesk, ticket, chat.
- HTML/Blade no `form_schema`.
- Auto-provisionamento de usuário ou login do cidadão.
- Anexo público ou link sem expiração.