Inicio do Projeto Piloto

docs/spreadsheet-adapter/13-xlsx-library-review.md

@@ -0,0 +1,35 @@
+# Revisão da biblioteca XLSX
+
+## Atual
+
+| Campo | Valor |
+| --- | --- |
+| Biblioteca | ExcelJS |
+| Versão declarada | 4.4.0 |
+| Licença | MIT |
+| Leitura | `workbook.xlsx.load`, valor exibido em `cell.text` |
+| Escrita | Novo workbook, aba `Adaptado`, texto com formato `@` |
+
+## Vantagens
+
+MIT, já integrada, lê e escreve XLSX, não executa macro e não avalia fórmula. O arquivo modelo permanece o blob original; o processamento grava outra chave.
+
+## Limitações
+
+Não preserva estilo, mesclagem, largura de coluna nem as outras abas do modelo no arquivo de saída. Datas e números saem como texto exibido. PDF continua truncado à parte. Arquivo protegido por senha cai em erro de estrutura.
+
+## Riscos
+
+Trocar a biblioteca no piloto reabre a suíte de mapeamento sem ganho para o contrato atual: a saída é um artefato novo e o modelo é imutável.
+
+## Alternativas
+
+SheetJS Community tem restrição de licença que exigiria revisão jurídica. Manter ExcelJS atrás de `readSpreadsheet` e `buildXlsx` permite trocar depois sem mudar o domínio.
+
+## Custo de migração
+
+Alto para o piloto: fixtures, tipos, datas e o contrato de “não executar fórmula” teriam de ser revalidados. Não há blocker que obrigue a troca.
+
+## Recomendação
+
+Manter ExcelJS 4.4.0 no piloto. Não criar uma segunda engine. Fixtures em `tests/unit/xlsx-fixtures.test.ts` cobrem várias abas, fórmula como texto, data, caractere especial e a imutabilidade do modelo.