# Fluxo Administrativo de Exportacao e Migracao

**Status:** Normativo para implementacao  
**Ultima revisao:** 2026-06-19

> Este documento define como o CMS deve permitir a exportacao administrativa de um projeto e como o pacote gerado deve ser restaurado no servidor final do cliente. O objetivo e padronizar um fluxo operacional seguro, auditavel e repetivel sem acoplar o frontend publico ao processo.

## 1. Objetivo e contexto

- O CMS e a origem privada de conteudo, configuracao e governanca operacional do projeto.
- O repositorio ja possui base para instalacao, configuracao, sessao administrativa, persistencia MySQL e auditoria inicial, mas ainda nao implementa um fluxo de migracao.
- A migracao precisa cobrir tres dominios inseparaveis:
  - arquivos enviados ao CMS;
  - dados persistidos no MySQL;
  - configuracao operacional necessaria para reconstruir o ambiente de destino.

O fluxo definido aqui existe para suportar dois cenarios:

1. entrega inicial do projeto ao servidor final do cliente;
2. backup administrativo para transferencia controlada entre ambientes privados.

Para evitar ambiguidade entre "migrar o CMS" e "entregar o site publico", este documento separa dois artefatos operacionais:

1. `pacote de migracao privada`: restaura CMS, banco, uploads e configuracao sanitizada em um ambiente privado do cliente;
2. `bundle publico de entrega`: publica os ativos do frontend/API publica no hostname final do cliente sem depender de caminhos ou segredos do ambiente de origem.

## 2. Principios do fluxo

- A operacao existe apenas no CMS privado e nunca na API publica.
- Somente `super_admin` pode exportar ou importar pacotes de migracao.
- Toda exportacao e importacao gera evento em trilha de auditoria com actor, alvo, resultado e carimbo UTC.
- O pacote deve ser portavel entre ambientes sem depender de estado local do frontend.
- O dump deve ser logico e reexecutavel; nao depender de snapshot binario do servidor.
- Segredos sensiveis nao devem sair em texto puro no pacote final.
- A restauracao deve falhar cedo quando detectar incompatibilidade de schema, versao ou prefixo.
- O frontend publico deve permanecer substituivel: a entrega final nao pode exigir acesso direto do site publico ao filesystem, sessao ou includes privados do CMS.
- Hostname publico, bucket/CDN, caminhos de deploy e segredos operacionais devem ser acoplados tardiamente no destino.

## 3. Escopo do pacote de exportacao

Cada exportacao deve gerar um arquivo compactado unico, preferencialmente `tar.gz`, com a seguinte estrutura canonica:

```text
migration-package/
  manifest.json
  database/
    schema.sql
    data.sql
  uploads/
  config/
    cms-config.redacted.php
    restore.env.example
  checksums/
    sha256sums.txt
  reports/
    export-report.json
```

### 3.1 Conteudo obrigatorio

- `manifest.json`
  - identificador do pacote;
  - slug/nome do site;
  - versao do formato do pacote;
  - versao esperada do CMS;
  - modo do projeto (`decoupled_site` ou `headless_api`);
  - prefixo das tabelas;
  - timezone;
  - data UTC da exportacao;
  - usuario responsavel pela exportacao;
  - resumo de volumes exportados.
- `database/schema.sql`
  - DDL ordenado para recriar as tabelas do CMS.
- `database/data.sql`
  - inserts/upserts dos dados exportados.
- `uploads/`
  - copia recursiva da arvore de uploads/midias gerenciadas pelo CMS.
- `config/cms-config.redacted.php`
  - copia sanitizada do `config.php`, sem senha, secret ou hostnames privados irrelevantes.
- `config/restore.env.example`
  - placeholders operacionais para o ambiente de destino.
- `checksums/sha256sums.txt`
  - hash de todos os arquivos do pacote.
- `reports/export-report.json`
  - tempos da operacao, contagens, avisos e eventuais itens ignorados.

### 3.2 Conteudo que nao pode sair no pacote

- hash de sessao em memoria;
- segredos da aplicacao em texto puro;
- credenciais reais de banco do ambiente de origem;
- caches descartaveis;
- logs tecnicos completos;
- arquivos temporarios.

## 3.3 Bundle publico de entrega final

Entrega final ao cliente nao e apenas restaurar o pacote privado. O ambiente final tambem precisa receber um artefato publico separado, montado para o hostname definitivo do cliente.

Estrutura minima esperada:

```text
public-delivery/
  manifest.json
  frontend/
    current/
  public-assets/
  config/
    runtime.public.json
  reports/
    delivery-report.json
```

Conteudo esperado:

- `frontend/current/`
  - build estatico versionado do `front-end/` pronto para publicacao no docroot, container web ou bucket/CDN.
- `public-assets/`
  - ativos publicos fingerprintados gerados no build;
  - includes imagens, CSS, JS, fontes e outros arquivos servidos anonimamente;
  - nao duplica `uploads/` privados do CMS, exceto quando o pipeline explicitamente materializar derivados publicos.
- `config/runtime.public.json`
  - configuracao publica do runtime final, como `apiBaseUrl`, `siteUrl`, politicas de cache e flags publicas nao sensiveis.
- `reports/delivery-report.json`
  - commit/build de origem, data UTC, hash do bundle, destino esperado e checklist de validacao.

Regras:

- O bundle publico nao transporta segredo, cookie, sessao nem credencial do ambiente de origem.
- URLs absolutas devem ser resolvidas para o dominio final apenas no momento da publicacao ou do build final do destino.
- O frontend deve consumir a API publica por contrato; qualquer referencia direta ao `cms/` invalida a entrega.
- `uploads/` do CMS continuam governados pelo pacote privado. Se o projeto expor media publica derivada, o processo deve gerar explicitamente tais derivados no bundle publico.

## 4. Escopo de dados exportados

O exportador deve trabalhar por allowlist de bounded context. No baseline atual, o schema minimo criado pelo instalador cobre:

- `users`
- `roles`
- `permissions`
- `user_roles`
- `role_permissions`
- `contents`
- `content_revisions`
- `settings`
- `audit_log`

Quando os modulos operacionais do CMS forem adicionados, a allowlist deve crescer para incluir:

- taxonomias e relacoes;
- midia e metadados;
- menus;
- configuracoes SEO;
- ownership granular por site/tenant;
- trilha de auditoria com politica de retenção configuravel.

`audit_log` pode ser exportado em dois modos:

1. `full`, para migracoes internas entre ambientes controlados;
2. `sanitized`, removendo ou truncando IP e `user_agent` quando o objetivo for entrega ao cliente final.

O modo recomendado por padrao para entrega ao cliente e `sanitized`.

## 5. Fluxo administrativo no CMS

## 5.1 Entrada de navegacao

- Nova area privada: `Configuracoes -> Exportacao e migracao`.
- A pagina deve ficar indisponivel para `editor` e `author`.
- Antes de qualquer acao destrutiva, exigir reautenticacao recente do `super_admin`.

## 5.2 Exportacao

Passos do wizard administrativo:

1. Selecionar o objetivo da operacao:
   - `Entrega ao cliente`
   - `Migracao entre ambientes`
   - `Backup administrativo`
2. Escolher o escopo:
   - banco + uploads + configuracao sanitizada;
   - banco sem auditoria;
   - banco + uploads + auditoria completa.
3. Exibir checklist de pre-flight:
   - storage gravavel;
   - espaco temporario suficiente;
   - acesso de leitura aos uploads;
   - conectividade ao MySQL;
   - ausencia de exportacao concorrente em andamento.
4. Exibir resumo do pacote estimado:
   - total de tabelas;
   - total de arquivos;
   - volume previsto;
   - avisos.
5. Confirmar a operacao com frase de seguranca.
6. Executar a exportacao de forma assíncrona com job rastreavel.
7. Disponibilizar:
   - download do pacote;
   - checksum;
   - relatorio da exportacao;
   - instrucoes de restauracao.

## 5.3 Importacao

Passos do wizard administrativo:

1. Upload do pacote ou apontamento para arquivo ja presente no servidor privado.
2. Validacao do manifesto e checksums.
3. Dry-run obrigatorio mostrando:
   - versao do pacote;
   - versao do CMS local;
   - tabelas afetadas;
   - conflitos de prefixo;
   - risco de sobrescrita de uploads;
   - diferencas de configuracao.
4. Escolha do modo:
   - `restaurar em ambiente vazio`
   - `sobrescrever ambiente existente`
5. Confirmacao forte com reautenticacao recente.
6. Execucao da restauracao com lock administrativo.
7. Exibicao de pos-validacoes e pendencias finais.

## 6. Execucao tecnica esperada

## 6.1 Exportacao

Sequencia de implementacao:

1. Abrir um registro de job de exportacao com status `running`.
2. Resolver a allowlist de tabelas conforme o escopo escolhido.
3. Gerar `schema.sql`.
4. Gerar `data.sql` em ordem consistente por dependencias.
5. Copiar uploads para diretório temporario isolado.
6. Gerar configuracao sanitizada e manifesto.
7. Calcular checksums.
8. Compactar tudo em um unico pacote.
9. Marcar o job como `completed` ou `failed`.
10. Registrar evento de auditoria.

Requisitos tecnicos:

- usar diretório temporario exclusivo por job;
- evitar streaming direto para a resposta HTTP;
- expirar automaticamente artefatos antigos;
- impedir duas exportacoes simultaneas do mesmo ambiente.

## 6.2 Importacao

Sequencia de implementacao:

1. Abrir job de importacao com status `running`.
2. Extrair o pacote em diretório temporario isolado.
3. Validar manifesto, checksums e compatibilidade minima.
4. Entrar em modo de manutencao administrativa.
5. Fazer backup preventivo rapido do estado atual antes de sobrescrever.
6. Restaurar schema e dados.
7. Sincronizar uploads.
8. Aplicar configuracao sanitizada com prompts para segredos obrigatorios.
9. Rodar verificacoes pos-restauração.
10. Sair do modo de manutencao e registrar auditoria.

## 7. Regras de restauracao e compatibilidade

- O importador nao deve assumir que o host, usuario e senha MySQL do destino sao iguais aos da origem.
- `config.php` do destino deve ser recomposto no servidor final com segredos locais.
- O importador deve bloquear restauracao quando:
  - a versao minima do CMS for maior que a instalada;
  - o pacote declarar modulo ausente no destino;
  - checksums falharem;
  - o dry-run detectar colisoes sem confirmacao explicita.
- O importador deve permitir remapeamento de:
  - host/porta do banco;
  - nome do banco;
  - prefixo de tabelas, quando tecnicamente suportado;
  - URLs canonicas e hostname publico.

## 7.1 Acoplamento tardio no servidor final

Para `decoupled_site`, a entrega final deve acontecer em duas etapas independentes:

1. restaurar o ambiente privado do CMS/API com o pacote de migracao;
2. publicar o bundle publico apontando para o endpoint `/api/v1` do destino final.

Isso implica as seguintes regras normativas:

- nenhum arquivo exportado deve carregar hostnames privados do ambiente de homologacao como dependencia obrigatoria;
- o `front-end/` deve aceitar `siteUrl`, `apiBaseUrl` e origem de assets por configuracao externa do destino;
- o pipeline final do cliente pode recompilar o frontend com variaveis do destino ou apenas promover um build pregerado, desde que o manifesto declare para qual hostname o bundle foi preparado;
- invalidacao de cache/CDN deve acontecer por release atomico versionado, nunca sobrescrevendo assets sem fingerprint quando houver risco de mistura entre releases.

## 7.2 Sequencia operacional da entrega final

Fluxo recomendado para entrega inicial ao cliente:

1. Provisionar infraestrutura final do cliente:
   - banco, storage de uploads, docroot ou bucket/CDN e variaveis de ambiente.
2. Restaurar o `pacote de migracao privada` no ambiente privado:
   - validar manifesto, aplicar schema/dados, sincronizar `uploads/` e recompor segredos locais.
3. Configurar o contrato publico do destino:
   - definir `siteUrl`, `apiBaseUrl`, URLs canonicas, politicas de cache e host final dos assets.
4. Gerar ou promover o `bundle publico de entrega`:
   - buildar o frontend com configuracao do destino ou validar que o bundle pregerado ja aponta para o host final.
5. Publicar os ativos publicos:
   - copiar para docroot, imagem/container ou bucket/CDN;
   - aplicar release atomico por pasta versionada, symlink `current` ou mecanismo equivalente.
6. Executar verificacoes minimas de aceite:
   - homepage responde `200`;
   - assets fingerprintados respondem `200`/cache correto;
   - `/api/v1` responde no destino final;
   - media publica critica referencia arquivos existentes;
   - `robots`, `sitemap` e canonical refletem o dominio final.
7. Encerrar a entrega com relatorio:
   - origem do build, hash do bundle, destino publicado e pendencias operacionais remanescentes.

## 8. Seguranca, auditoria e operacao

- Exigir CSRF em todas as etapas stateful do wizard.
- Exigir reautenticacao recente para iniciar exportacao e para confirmar importacao.
- Escrever eventos de auditoria para:
  - `migration.export.started`
  - `migration.export.completed`
  - `migration.export.failed`
  - `migration.import.started`
  - `migration.import.completed`
  - `migration.import.failed`
- Ocultar o arquivo final apos TTL configuravel ou download unico opcional.
- Permitir revogacao manual do artefato pelo `super_admin`.
- Informar checksum SHA-256 antes do download.
- Publicacao do bundle publico deve gerar evento operacional rastreavel, mesmo quando a copia para o servidor final ocorrer fora do painel.

## 9. UX operacional minima

- A tela nao deve prometer "backup completo" sem indicar o escopo real exportado.
- O usuario precisa ver tamanho estimado, duracao aproximada e consequencias de sobrescrita.
- Dry-run deve ser legivel para operador nao tecnico, mas com link para detalhes tecnicos.
- O relatorio final precisa listar:
  - tabelas exportadas;
  - total de linhas por tabela;
  - total de arquivos copiados;
  - itens ignorados;
  - avisos de compatibilidade;
  - proxima acao recomendada.

Na entrega final ao cliente, o relatorio tambem precisa indicar:

- hostname final preparado;
- hash/versao do bundle publico;
- estrategia de publicacao usada (`symlink`, `bucket versionado`, `container image`, etc.);
- quais ativos continuaram privados no CMS e quais foram promovidos como publicos.

## 10. Fora de escopo desta primeira entrega

- replicacao continua entre ambientes;
- rollback incremental por objeto de negocio;
- migracao parcial por entidade editorial;
- sincronizacao bidirecional;
- pacote criptografado com gestao de chaves dedicada.

## 11. Decisoes de implementacao derivadas

Para implementar o fluxo acima, o CMS passa a precisar de quatro entregas tecnicas separadas:

1. modulo administrativo de jobs de exportacao/importacao com auditoria;
2. gerador de pacote (`manifest`, dump logico, uploads, checksums, relatorio);
3. importador com dry-run, validacao e restauracao segura;
4. documentacao operacional de restauracao no servidor do cliente.

Estas entregas devem nascer como issues filhas independentes para que o fluxo definido aqui saia do plano normativo e chegue a uma implementacao verificavel.

## 12. Referencia operacional

Enquanto o importador administrativo ainda nao existir como fluxo automatizado no CMS, a restauracao no servidor do cliente deve seguir o runbook operacional em [client-server-restoration-runbook.md](./client-server-restoration-runbook.md).