# 10 — Estados de `contratos_casos` (módulo Contratos)

Fase 0 do módulo Contratos. Tal como descrito em `docs/CONTRATOS-PLANO.md` secção
"Estados de `contratos_casos`", reproduzido aqui como documento próprio (paralelo a
`docs/02-MAQUINA-ESTADOS.md` de Fichas) para a Fase 3 (webapp) implementar sem voltar a
abrir o plano inteiro.

## Diagrama

```
sem_gerar ──► gerado_com_perguntas ──(responder às perguntas)──► sem_gerar (recalcula)
    │
    ├──► gerado_completo ──► publicado
    │
    └──► gerado_com_falta ──(preencher [FALTA] no Word, fora da app)──► publicado
```

## Estados

| Estado | Significado | Transições de saída |
|---|---|---|
| `sem_gerar` | Caso criado (processo na fila), motor ainda não correu ou dados mudaram desde a última geração | → `gerado_com_perguntas` / `gerado_completo` / `gerado_com_falta` (correr o motor) |
| `gerado_com_perguntas` | O motor devolveu `perguntas` não vazias — nenhum `.docx` foi escrito (equivalente ao exit 2 da skill) | → `sem_gerar` (responder às perguntas e recalcular) |
| `gerado_completo` | `.docx` gerado, 0 `[FALTA: ...]` | → `publicado` |
| `gerado_com_falta` | `.docx` gerado, 1+ `[FALTA: ...]` (campo com pergunta ainda em aberto que não bloqueou a geração, ex. `nhoras=0` não é pergunta mas outros campos sem valor viram `[FALTA]`) | → `publicado` (o utilizador publica na mesma e completa no Word, tal como a skill) |
| `publicado` | **Terminal.** Ficheiro(s) copiados para `Assistente/Contratos Feitos/<zona>/`; nunca sobrescrito | — |

## Regras

- Sem estados `aprovado`/`rejeitado` (ao contrário de Fichas): não há aprovação de
  leitura de documentos aqui, há geração determinística e publicação — a decisão de
  publicar é do próprio ato de publicar (mesma regra já validada pelo utilizador na
  skill em 03/09/2026, "publica sem pedir OK quando não há perguntas pendentes").
- Regenerar depois de `publicado` (modelo mudou, dados do Sabichão mudaram) cria nova
  `contratos_versoes` mas **não** volta a `sem_gerar` nem republica — fica um aviso
  "já publicado em `<caminho>`, gerar de novo cria conflito a resolver à mão" (mesma
  regra de "nunca sobrescrever" herdada da skill). Do ponto de vista da máquina de
  estados, `publicado` é terminal; uma regeneração pós-publicação é uma ação de
  auditoria (`contratos_eventos`), não uma transição de estado do caso.
- Um processo tem **zero ou um** caso "em curso" de cada vez — ao contrário de Fichas
  (registo livre por MAI/NIF), aqui `id_processo` já existe no Sabichão e é a chave
  natural; abrir a fila cria o caso a `sem_gerar` se ainda não existir um para aquele
  `id_processo`.
- Cada transição fica registada em `contratos_eventos` (quem gerou, quem respondeu a
  uma pergunta, quem publicou), tal como Fichas.