# BPMS/BPMN para Ouvidoria e e-SIC (requisito contratual)

> **Capacidade genérica:** este item é a demanda **contratual** de um cliente. A possibilidade
> genérica, isolada, fora da sequência e só sob demanda está em
> [`workflow-bpm-isolado.md`](./workflow-bpm-isolado.md).

| Campo | Valor |
|---|---|
| **Prioridade** | **Prioritário (contratual)** |
| **Status** | Em análise |
| **Origem** | Requisitos do cliente — Processo Fundão 008476/2025, itens **166–244** (`local://paste-1.md`) |
| **ADR provável** | ADR própria — “motor de workflow/BPMS: escopo, conformidade e fronteira” |
| **Relaciona** | P11, P25, P2/P3; ADR-001, ADR-002, ADR-009, ADR-010, ADR-019, ADR-020, ADR-025, ADR-028, ADR-033, ADR-035, ADR-038/039/040, ADR-043 |

## Veredito

**É possível — mas não como uma extensão simples do módulo P11.** O conjunto 166–244 descreve um
**BPMS** (process modeling + execution + forms + document types/templates + task inbox + API
orchestration + citizen portal), não apenas “Ouvidoria/e-SIC com fluxo configurável”.

**Faz sentido** apenas com escopo negociado:

1. **BPMS separado** (motor maduro, ex.: Camunda 7/Flowable) integrado por API, com o CMS como
   front-end; ou
2. **motor próprio de subconjunto** (recomendado se o cliente aceitar “baseado em BPMN”, não
   “conformante”): estados/transições versionados, tarefas humanas, gateways XOR/AND, prazos,
   notificações, formulários declarativos, atribuição a setor/perfil, inbox e linha do tempo.

O texto do contrato precisa ser cumprido literalmente ou renegociado: “aderente à notação BPMN 2.0
**e** utilizar um motor BPMS” são **duas** obrigações distintas. Um motor próprio de subconjunto
não pode ser vendido como “BPMN 2.0 Execution Conformance”.

## O que os itens realmente pedem

| Bloco | Itens | Natureza |
|---|---|---|
| Modelagem BPMN + versionamento + ativação | 166–175 | Repositório de definições, modeler, validação, deploy |
| Formulários e tarefas humanas | 176–177, 191–201 | Form builder + renderer + versionamento |
| Execução BPMN | 179–190 | Motor de tokens, gateways, eventos, tasks, DMN |
| Atribuição e grupos | 182–183 | Identidade/grupos/filas, não o RBAC atual |
| Documentos e templates | 184, 203–214 | DMS: tipos, templates, permissões, geração |
| Inbox de tarefas | 215–221 | Lista, filtros, paginação, assign/abandon em lote |
| Portal do cidadão | 223–244 | Abertura, acompanhamento, timeline, diagrama, e-mail, contas |

## Análise BPMN

- **Notação ≠ execução.** A cláusula 13 da BPMN 2.0.2 define tokens, ciclos de vida, gateways e
  eventos; implementar isso é um **motor**. A cláusula 2 define tipos de conformidade; os itens
  179–190 pedem, na prática, **Process Execution Conformance** (e DMN à parte).
- **BPMN não resolve dados sozinha.** Ela oferece ganchos (`ItemDefinition`, `DataObject`,
  `DataAssociation`, expressões externas), mas **não define** estrutura de dados nem linguagem de
  expressão. “Onde o dado surge, como é tratado e para onde vai” exige **form schema + camada de
  dados + expressão/condições + integrações**; BPMN é só o desenho do fluxo.
- **Versionamento, deploy, inbox, grupos, formulários, DMN e templates** são features de **BPMS**,
  não da notação. É preciso um produto de workflow para atendê-las.
- **Scripts** (179, 185, 193) e **API arbitrária** (186) não são “configuração”: são execução de
  código e chamadas externas. Exigem sandbox, allowlist, secrets, timeout, idempotência,
  auditoria e limites — ou são um risco inaceitável de RCE/SSRF.

## Conflitos com as ADRs (não são detalhes)

| ADR | Conflito |
|---|---|
| **001** — simplicidade, nativo primeiro, determinismo | Um motor BPMN completo, scripts e eventos externos são o oposto de “nativo primeiro”; timers/APIs/scripts tornam o teste não determinístico sem isolamento |
| **002** — mínimas dependências, permissivas, zero CDN | Modeler + engine + DMN + form builder; possível com MIT/Apache, mas novas pilhas e runtime (Java) precisam de ADR |
| **009** — sem Livewire/UI reativa; reactive exige ADR | Modeler BPMN, drag-and-drop de formulário e inbox “em tempo real” são reativos por natureza |
| **010** — JS mínimo, progressive enhancement | Modeler/form builder são JS pesado; o fluxo público ainda precisa funcionar sem JS |
| **019** — LGPD | Contas de cidadão, anexos, timeline, scripts e logs ampliam PII/superfície de tratamento |
| **020** — CSP estrita/Trusted Types | Scripts JS/Groovy/Python e HTML de documento/template colidem com CSP e execução segura; API configurável abre SSRF |
| **025** — acessibilidade é gate | Canvas BPMN e drag-and-drop são difíceis em teclado/leitor de tela; axe/eMAG no CMS e portal |
| **028** — TipTap é o único editor rico | Editor de documentos/modelos deve ser AST TipTap; nada de HTML/CSS livre no banco |
| **033** — um perfil por usuário, 4 ações, sem grupos | Itens 182–183 pedem **múltiplos usuários/grupos** por tarefa; hoje não existe modelo de grupos/filas |
| **035** — auditoria imutável | Cada transição, atribuição, script, API e documento gerado precisa de evento auditável, sem PII |
| **038/039/040** — cobertura 90%, mutation, PHPStan max | A superfície de um motor + modeler + forms + DMS é enorme; o gate fica caro e o risco de código não testado cresce |
| **043** — áreas restritas invisíveis | Diagrama público do item 235 não pode expor lanes internas, scripts, endpoints ou prazos internos; precisa de visão sanitizada |

## Lacunas atuais no V7

- **Sem grupos/filas de trabalho**: ADR-033 tem um perfil por usuário e quatro ações; não há
  “setor”, “equipe” ou “grupo” atribuível a tarefa.
- **Sem DMS**: Media cuida de imagens; não há tipos de documento, templates, versões, permissões
  por tipo e geração automática.
- **Sem form builder**: P11/P25 têm formulários fixos; não há schema declarativo versionado com
  condicionais e validação visual.
- **Sem motor de workflow**: P6/P11/P15 usam enums/Actions; não há definição versionada, tokens,
  gateways, timers, compensação ou task inbox.
- **Sem conta de cidadão**: P11 usa protocolo + link assinado/e-mail; item 239 pede cadastro/login.
- **Sem “tempo real”**: item 236 exige atualização em tempo real; o padrão atual é request/response
  e cache.

## Opções

### A. BPMS separado (atende o texto literal)

Motor maduro em container próprio (Camunda 7/Flowable), integrado por REST; CMS/portal como
front-end; BPMN/DMN/tasklist/forms do produto. **Prós:** semântica BPMN testada, DMN, versionamento.
**Contras:** segunda stack (Java), operação, licença/versão, acessibilidade e CSP do UI do BPMS,
sincronização de dados/auditoria, SSO, backup/DR, custo de integração. Exige ADR e novo serviço no
Compose; não é “mais um módulo”.

### B. Motor próprio de subconjunto (recomendado se o cliente negociar)

Definição versionada em JSON (não BPMN XML como runtime), com:

- `start` → `user_task`/`manual_task` → `exclusive`/`parallel` → `end`;
- atribuição a **setor/fila** e perfil; múltiplos responsáveis por fila;
- formulário declarativo por etapa (schema JSON + renderer Blade), sem drag-and-drop no MVP;
- prazo/SLA, escalonamento, notificações e-mail; sem WhatsApp no MVP;
- documentos por tipo fixo + template AST TipTap; sem DMS livre;
- inbox com filtros/paginação/assign em lote; linha do tempo pública sanitizada;
- auditoria de cada transição; sem scripts/DMN/call activity/compensação/event-based no MVP;
- export BPMN 2.0 apenas para documentação/intercâmbio (não é o runtime).

**Prós:** cabe em PHP/Laravel, ADR-001/009/033/035, testável e determinístico. **Contras:** não é
“BPMN 2.0 completo”; exige negociação explícita e ainda é um projeto grande (formulários, inbox,
versionamento, documentos).

### C. Só documentação BPMN

Não atende os itens 176–244; serve apenas para a ficha do processo. É o item
[`bpmn-documentacao-processos.md`](./bpmn-documentacao-processos.md).

## Decisão recomendada

1. **Não** aceitar o bloco 166–244 como extensão de P11 sem ADR e sem mudança de contrato.
2. Se “BPMS” for obrigatório, escolher **A** (motor separado) e orçar como **produto/serviço
   separado**, com matriz de conformidade BPMN e integração via API.
3. Se o cliente aceitar “baseado em BPMN”, escolher **B** com escopo fechado; o editor visual pode
   ser uma **lista/estado + swimlanes** (não canvas livre) e o BPMN XML fica como export.
4. **Nunca** executar JavaScript/Groovy/Python dentro do PHP; se scripts forem contratuais, exigir
   sandbox isolado (sem rede, CPU/memória/tempo limitados) e ADR de segurança.
5. **Nunca** expor o `.bpmn` bruto ao cidadão; publicar só uma visão sanitizada ou a linha do tempo.
6. Tratar conta de cidadão como decisão de identidade: preferir protocolo + link assinado/e-mail;
   se conta for obrigatória, gov.br SSO (backlog) em vez de senha local.

## Perguntas que precisam ser respondidas antes de codar

- Qual **nível de conformidade** BPMN é contratual: modelagem, execução, BPEL, coreografia?
- “Motor BPMS” é obrigatório ou “aderente à notação” basta? Qual produto/versão?
- Scripts são obrigatórios? Quais linguagens? Podem rodar em sandbox externo?
- “Grupos de usuários” são **grupos de autenticação** ou **filas/setores de trabalho**?
- O diagrama público é o BPMN completo ou uma visão sanitizada?
- Conta de cidadão é obrigatória? Pode ser substituída por protocolo + link assinado?
- WhatsApp é obrigatório no MVP ou pode ser fase 2?
- Documentos são **tipos fixos com template** ou um DMS com editor livre?
- Qual o volume de processos/tarefas e o SLA de retenção/auditoria?

## Critérios de promoção

- [ ] Contrato/escopo com a opção A ou B escolhida e a matriz de conformidade assinada.
- [ ] ADR do motor (BPMS separado × subconjunto próprio) + ADR de scripts/API (se houver).
- [ ] Modelo de grupos/filas e extensão da ADR-033.
- [ ] Modelo de formulários versionados e de documentos/templates.
- [ ] Gate de acessibilidade do modeler/form builder e do portal.
- [ ] Plano de fases (P11/P25 ou programa separado) com estimativa e dependências.
- [ ] `make check` 2× + E2E; cobertura/mutation/estático viáveis.

## Notas

- O item 202 (“eliminar formulário se vinculado”) e o 214 (“remover tipo de documento se associado”)
  precisam de definição: exclusão destrutiva de artefato em uso quebra processos e auditoria;
  o normal é **desvincular/bloquear** e versionar.
- O item 236 (“tempo real”) deve ser traduzido para **atualização near-real-time** (polling/ETag/SSE)
  antes de prometer WebSocket.
- O item 179/193 (“scripts em qualquer elemento”) é o maior risco de segurança do bloco; não
  entra sem sandbox e ADR específica.