# Plano de Transição para 2026

Objetivo
- Ativar o modelo fiscal de 2026 de forma suave, mantendo o sistema atual totalmente funcional e preservando histórico.

Fases
- Preparação (agora):
  - Campos flexíveis em documentos (`tax_model_version`, `tax_data`) e produtos (`tax_attributes`).
  - Serviço `TaxConfig` e endpoints `/api/fiscal/config` com RBAC.
  - Módulo paralelo `Fiscal2026` com preview isolado.
- Homologação:
  - Validação cruzada com `scripts/fiscal_version_validation.php` em cenários reais.
  - Ajustes de `Calculator2026` e validadores por tipo de documento.
- Transição controlada:
  - Habilitação por tenant via `model_version='2026'` em `fiscal_configs` com `effective_from`.
  - Dual reporting opcional (`options.transition.enable_dual_reporting=true`).
- Ativação:
  - Versão 2026 tomada como padrão de cálculo conforme data de vigência.
  - Manutenção de histórico no formato anterior (`tax_model_version='2024'` em documentos existentes).

Migração Suave
- Compatibilidade com dados existentes: `tax_data` e `tax_attributes` são JSON opcionais, não quebram rotas atuais.
- Versionamento:
  - `VersionRouter::previewNfce(items, forceVersion)` permite alternar motores sem alterar endpoints existentes.
  - `crossValidatePreview` mantém auditoria de comparativos.

Cadastro de Produtos
- Reflexos previstos:
  - Inclusão de `products.tax_attributes` para armazenar atributos IBS/CBS (categoria, regime, benefícios).
  - NCM/CFOP continuam para histórico e consultas; novos atributos não substituem os atuais imediatamente.
- Recomendações:
  - Criar processo de enriquecimento paulatino (`seed_products` + planilha) para `tax_attributes`.

Testes e Observabilidade
- Testes unitários adicionados: `TaxConfigTest.php`, `VersionRouterTest.php`.
- Testes de integração sugeridos: cálculo, emissão mock, RBAC de config e certificados.
- Logs: auditoria permanece e pode registrar alternância de versão.

Desempenho
- Nenhuma alteração em hot-paths de produção; novas funcionalidades são opcionais e isoladas.
- JSON em colunas é indexado conforme necessário; agregações leves no relatório.

Checklist de Ativação
- Migrar tenant: `php scripts/migrate_tenant.php <tenant>`.
- Definir configuração: `PUT /api/fiscal/config { model_version:"2026", options:{ transition:{ enable_dual_reporting:true }}}`.
- Validar em homolog: comparar `legacy` vs `next` com amostras reais.
- Planejar janela de virada com rollback simples via `model_version`.