# Workflow editorial, revisoes e auditoria

## Objetivo

Definir o baseline operacional do CMS minimo funcional para autoria, revisao, aprovacao, publicacao e rastreabilidade de conteudo sem depender de interpretacao ad hoc por tela ou por papel.

## Escopo

- Este documento cobre posts, paginas e, por extensao, qualquer tipo de conteudo editorial versionavel.
- Midia, menus e taxonomias seguem regras proximas de auditoria, mas nao usam necessariamente todos os estados editoriais abaixo.
- O foco e o CMS privado. A API publica e o `front-end/` apenas refletem conteudo ja aprovado e publicado.

## Papeis operacionais

- `author`: cria rascunhos, responde ajustes e pode solicitar revisao do proprio conteudo.
- `editor`: revisa, devolve para ajustes, aprova para publicacao, publica, despublica e agenda publicacao.
- `super_admin`: herda as capacidades de `editor`, administra usuarios/configuracoes e pode executar overrides auditaveis em casos excepcionais.

## Estados editoriais minimos

| Estado | Significado | Quem entra | Quem sai |
| --- | --- | --- | --- |
| `draft` | Conteudo em elaboracao, ainda nao submetido | `author`, `editor`, `super_admin` | `author`, `editor`, `super_admin` |
| `in_review` | Conteudo aguardando revisao editorial | `author`, `editor`, `super_admin` | `editor`, `super_admin` |
| `changes_requested` | Revisao devolveu pendencias ao autor | `editor`, `super_admin` | `author`, `editor`, `super_admin` |
| `approved` | Conteudo validado para publicacao, mas ainda nao publico | `editor`, `super_admin` | `editor`, `super_admin` |
| `scheduled` | Conteudo aprovado com publicacao futura | `editor`, `super_admin` | `editor`, `super_admin` |
| `published` | Conteudo visivel na API publica e no frontend | `editor`, `super_admin` | `editor`, `super_admin` |
| `archived` | Conteudo retirado de circulacao, preservado historicamente | `editor`, `super_admin` | `editor`, `super_admin` |

## Regras de transicao

- `draft -> in_review`: requer titulo, slug, corpo minimo e autor responsavel preenchidos.
- `in_review -> changes_requested`: requer comentario de revisao explicito.
- `in_review -> approved`: somente `editor` ou `super_admin`, com registro da decisao.
- `approved -> published`: publicacao imediata manual.
- `approved -> scheduled`: exige `publish_at` futuro em UTC.
- `scheduled -> published`: transicao automatica por job ou manual por `editor`/`super_admin`.
- `published -> draft`: proibido. Conteudo publicado que precisa retrabalho volta por clonagem de revisao ou nova versao interna.
- `published -> archived`: despublica sem apagar historico.
- `archived -> draft`: permitido apenas quando o conteudo sera retrabalhado como nova iteracao editorial.
- Exclusao definitiva nao faz parte do fluxo normal. Deve ser reservada a `super_admin`, com justificativa e evento de auditoria separado.

## Modelo operacional de revisao

### 1. Autoria

- Todo conteudo nasce em `draft`.
- O autor pode salvar quantas vezes precisar sem gerar versao editorial "aprovada".
- Cada salvamento registra diff versionado e metadata basica de autoria.

### 2. Solicitacao de revisao

- Ao enviar para `in_review`, o CMS deve congelar um snapshot da submissao.
- O pedido de revisao deve registrar:
  - autor solicitante;
  - data/hora UTC;
  - resumo opcional das alteracoes;
  - checklist editorial minima atendida.

### 3. Revisao editorial

- O revisor trabalha sobre o snapshot submetido, nao sobre memoria informal.
- A revisao precisa produzir uma decisao estruturada:
  - `changes_requested` com comentario obrigatorio;
  - `approved` com comentario opcional;
  - `published` ou `scheduled` quando o revisor tambem for o publicador.

### 4. Ajustes

- Quando houver `changes_requested`, o autor continua a edicao a partir da ultima versao de trabalho.
- O historico precisa vincular claramente qual revisao originou o pedido de ajuste e qual submissao o respondeu.

### 5. Publicacao

- Publicacao so ocorre a partir de `approved` ou `scheduled`.
- A primeira publicacao deve registrar `published_at`, `published_by` e a revisao exata publicada.
- Republicacoes ou atualizacoes de conteudo ja publicado devem criar nova revisao interna antes de substituir o payload publico.

## Versionamento e registro de alteracoes

- O CMS deve separar:
  - estado atual de trabalho;
  - revisoes submetidas/aprovadas;
  - revisao efetivamente publicada.
- Cada revisao precisa ter identificador estavel, numero sequencial por conteudo e ponteiro para a revisao anterior.
- Campos minimos por revisao:
  - `content_id`;
  - `revision_id`;
  - `revision_number`;
  - `status_snapshot`;
  - `title`, `slug`, `excerpt`, `body`, metadados estruturados;
  - `created_at` UTC;
  - `created_by`;
  - `review_decision` quando aplicavel;
  - `reviewed_at` e `reviewed_by` quando aplicavel;
  - `published_at` e `published_by` quando aplicavel.
- O changelog visivel no CMS deve mostrar diff semantico suficiente para titulo, slug, resumo, corpo e SEO.

## Auditoria obrigatoria

### Eventos minimos

- criacao de conteudo;
- salvamento de rascunho;
- submissao para revisao;
- pedido de ajustes;
- aprovacao;
- agendamento;
- publicacao;
- despublicacao/arquivamento;
- restauracao de arquivado;
- exclusao logica ou definitiva;
- override administrativo de permissao ou estado.

### Payload minimo do evento

- `event_id`;
- `event_type`;
- `content_id`;
- `revision_id` quando houver;
- `actor_user_id`;
- `actor_role_snapshot`;
- `target_status_before`;
- `target_status_after`;
- `occurred_at` em UTC;
- `reason` ou comentario operacional quando aplicavel;
- `request_id` ou correlation id;
- `ip`;
- `user_agent`.

### Regras

- Eventos de auditoria sao append-only no nivel logico.
- Correcao de metadado errado gera novo evento; nao se edita o evento anterior.
- O painel de auditoria deve permitir filtro por conteudo, actor, tipo de evento e intervalo de tempo.
- `editor` pode consultar auditoria editorial; somente `super_admin` pode acessar eventos administrativos sensiveis de usuarios/configuracoes.

## Governanca editorial

### Ownership

- Cada conteudo precisa ter um autor primario.
- Um revisor nao pode aprovar silenciosamente uma alteracao sem deixar trilha.
- A regra minima e separacao de funcoes por permissao, nao necessariamente por pessoa: o sistema permite que `editor` publique, mas a trilha precisa mostrar quando a mesma pessoa escreveu e aprovou.

### Checklist minima de publicacao

- titulo presente;
- slug valido e unico;
- corpo nao vazio;
- status editorial coerente;
- metadados basicos de SEO preenchidos ou assumidos por fallback explicito;
- categoria/taxonomia principal definida quando o tipo exigir.

### Conteudo publicado

- O frontend e a API so podem expor revisoes em `published` cujo `published_at` seja passado.
- Conteudo em `scheduled` nao pode vazar para endpoints publicos.
- Conteudo `archived` deixa de aparecer publicamente, mas permanece no historico interno.

## Implicacoes de implementacao minima

- Tabela de conteudo precisa separar documento canonico de revisoes.
- O modelo de permissao precisa checar papel e ownership por acao editorial, nao apenas por rota.
- O CMS precisa de comentarios de revisao estruturados no fluxo, nao apenas campo livre solto.
- Um job de publicacao agendada deve buscar revisoes `scheduled` vencidas e promover para `published` com evento de auditoria.
- A API publica precisa sempre resolver a ultima revisao `published` vigente por conteudo.

## Fora de escopo desta definicao

- Workflow multi-etapa com aprovadores paralelos.
- Assinatura eletronicamente forte ou trilha de compliance regulatorio.
- Branching editorial complexo com merge entre revisoes concorrentes.

## Ordem recomendada de implementacao

1. Modelar entidades de conteudo, revisao e evento de auditoria.
2. Implementar RBAC + ownership para `author`, `editor` e `super_admin`.
3. Implementar transicoes de estado com validacao de pre-condicoes.
4. Adicionar comentarios de revisao e timeline visivel no CMS.
5. Expor apenas revisoes `published` na API publica.