# PLANO_DE_APLICACAO_EM_FASES_FINAL

## Premissas invariáveis

Este plano continua obedecendo às restrições de produção já definidas:

- não mexer no banco do ERP agora;
- não reescrever o ERP;
- não criar dependência obrigatória do ERP com o banco central nesta fase;
- não alterar login, sessão nem permissão interna do ERP;
- implantar em etapas com rollback por isolamento.

---

## Fase 1 — Criar o banco central separado

### Objetivo
Subir o núcleo central em MariaDB 10.6+ sem tocar na operação do ERP.

### Escopo
- provisionar instância dedicada do banco central;
- aplicar `BANCO_CENTRAL_PLATAFORMA_V2_FINAL.sql`;
- habilitar backup, restore e monitoramento;
- validar migrations em homologação;
- preparar workers para jobs/outbox, ainda sem consumidores críticos.

### O que não acontece
- nenhuma alteração no banco do ERP;
- nenhuma alteração no login do ERP;
- nenhuma alteração na sessão do ERP;
- nenhuma alteração na ACL interna do ERP.

### Saída da fase
- schema aplicado;
- backup e restore testados;
- observabilidade básica ativa;
- integridade do schema validada em staging.

---

## Fase 2 — Cadastrar produtos, planos, preços e políticas

### Objetivo
Formar o catálogo oficial da plataforma.

### Escopo
- cadastrar produtos em `produtos`;
- cadastrar módulos em `modulos_produto`;
- cadastrar planos em `planos`;
- montar ofertas em `plano_produto`;
- cadastrar preços em `precos_plano_produto`;
- cadastrar gateways em `gateways_pagamento`;
- definir, por produto:
  - multiplicidade de assinatura ativa;
  - multiplicidade de instância ativa.

### Recomendação inicial
- ERP: assinatura única, instância única
- Chatbot: assinatura única, instância múltipla se o produto vender bots independentes
- PDF Tools: assinatura única, instância única
- Bingo: assinatura única, instância única

### Saída da fase
- catálogo fechado;
- preços sem sobreposição;
- regras por produto definidas;
- gateways com segredo tratado por `secret_ref` ou versão cifrada.

---

## Fase 3 — Ligar o portal principal ao banco central

### Objetivo
Fazer o portal principal usar o banco central como base de identidade e gestão comercial.

### Escopo
- autenticação do portal em `usuarios_plataforma`;
- convites, verificação, reset, sessão e MFA;
- gestão de clientes e memberships;
- contratação e gestão de assinaturas;
- gestão de faturas, pagamentos e cupons;
- emissão de `acessos_produto`;
- logs administrativos em `logs_plataforma`.

### Limite explícito
Isto vale para o **portal principal**, não para o ERP legado.

### Saída da fase
- portal principal funcionando em cima do banco central;
- ciclo completo de onboarding do cliente no portal;
- ERP ainda completamente isolado.

---

## Fase 4 — Integrar produtos por adaptadores, sem risco

### Objetivo
Acoplar os produtos ao núcleo central sem colocar o ERP no caminho crítico.

### Ordem recomendada
1. PDF Tools
2. Chatbot
3. Bingo
4. ERP por último

### Escopo por produto
Para cada produto:

1. criar adapter próprio;
2. consumir `jobs_provisionamento_produto`;
3. publicar/consumir `eventos_outbox_integracao`;
4. criar ou vincular `instancias_produto_cliente`;
5. refletir `acessos_produto`;
6. registrar tentativas, retries, DLQ e logs.

### Estratégia específica para o ERP
A integração inicial do ERP continua sendo apenas:

- espelhamento assíncrono de status comercial;
- provisionamento controlado, se necessário;
- sem consulta síncrona ao banco central no login;
- sem troca de sessão;
- sem troca da ACL interna.

### Saída da fase
- pelo menos um produto não crítico integrado;
- retries e DLQ testados;
- observabilidade operacional validada;
- ERP ainda fora do caminho crítico.

---

## Fase 5 — Avaliar login central / SSO

### Objetivo
Abrir a possibilidade futura de identidade central sem forçar migração agora.

### Caminho recomendado
- introduzir IdP OIDC/SAML separado;
- usar `usuarios_plataforma` como base da conta central;
- começar por produtos novos;
- depois operar modo dual no ERP:
  - login legado
  - login central

### O que não fazer
- não cortar o login legado do ERP de uma vez;
- não colocar o ERP dependente do IdP sem fase dual;
- não misturar migração de identidade com implantação inicial do banco central.

### Saída da fase
- decisão técnica sobre SSO com piloto controlado;
- fallback preservado;
- possibilidade de migração gradual por coorte.

---

## Controles transversais

### 1. Feature flag
Toda integração com produto entra sob flag.

### 2. Rollback
Rollback é desligar:

- adapter;
- worker;
- consumidor de outbox;
- publicação de webhook;
- portal novo, se necessário.

Não há rollback destrutivo no ERP porque o ERP não foi alterado.

### 3. Observabilidade mínima
Monitorar desde a fase 1:

- falha de migration;
- falha de trigger/procedure em homologação;
- jobs em retry;
- DLQ;
- falhas de webhook;
- divergência entre assinatura e acesso;
- erros de autenticação do portal;
- crescimento de `logs_plataforma` e cumprimento de retenção.

### 4. Governança de segredos
- segredo bruto fora de configuração genérica;
- `secret_ref` preferencial;
- versão cifrada apenas quando realmente necessária;
- rotação controlada.

---

## Conclusão

A V2 FINAL pode ser levada para homologação e depois produção **sem abrir risco para o ERP atual**, porque:

- o banco central nasce separado;
- o ERP continua isolado;
- a integração é assíncrona e gradual;
- a mudança de identidade do ERP, se um dia vier, fica para a última fase.