migration-reference · in-progress
Migration 14 — template_versions
Contrato das versões dos templates DOCX e preservação após uso.
Contrato
| Campo | Regra |
|---|---|
id | bigint, chave primária. |
document_template_id | FK obrigatória. |
version | inteiro positivo e único dentro do template. |
file_sha256 / file_size | identidade e tamanho do DOCX recebido; o hash não se repete dentro do mesmo template lógico. |
required_variables / optional_variables | JSONB com o schema declarado da versão. |
detected_variables | JSONB do resultado da inspeção do DOCX. |
validation_report | JSONB de erros, avisos, renderização e versão do validador. |
uploaded_by_affiliation_id | vínculo autorizado que enviou o arquivo. |
validated_at / validated_by_affiliation_id | confirmação técnica/visual antes de disponibilizar a versão para geração. |
| timestamps | auditoria. |
O DOCX original é armazenado pelo Spatie Media Library na coleção privada template_file, com uma mídia por versão. A tabela template_versions registra revisões do arquivo recebido e seu contrato de variáveis; não recebe uma linha por documento gerado. O catálogo de variáveis aceitas é fixo no código, enquanto cada DOCX utiliza apenas as variáveis necessárias. O hash impede criar uma segunda versão do mesmo template com o mesmo arquivo.
A geração seleciona a versão validada mais recente pelo maior número de versão e registra seu ID em generated_documents.template_version_id. Uma versão enviada, mas ainda não validada, não substitui a última versão validada. Se o Setor corrigir um DOCX que já gerou documentos, envia outro arquivo como nova versão; a anterior e seus documentos permanecem íntegros. Uma versão sem documentos gerados pode ser excluída fisicamente, incluindo sua mídia. Quando generated_documents for criada, a FK com exclusão restrita e as regras de atualização impedirão exclusão ou alteração destrutiva da versão utilizada. Não há ativação ou desativação manual de versões.
O validador aceita apenas ${NOME_DA_VARIAVEL} do catálogo canônico, rejeita o dialeto {{...}}, relacionamentos externos, macros, variável desconhecida ou marcador obrigatório ausente. A validação antes do uso exige geração fictícia e revisão visual de todas as páginas, conforme Geração de documentos DOCX e variáveis.
Checklist
- Definir mídia privada única, metadados, schema de variáveis e relatório de validação.
- Criar migration com unicidade por template/versão e template/hash.
- Criar Model, relação com template, casts e coleção privada única no Media Library.
- Validar DOCX e catálogo de variáveis
${variavel}antes do uso. - Selecionar a versão validada mais recente do template lógico.
- Impedir alteração destrutiva e exclusão após uso em
generated_documents; permitir exclusão física enquanto não houver uso. - Testar seleção da versão validada, duplicidade de arquivo e nova versão.
- Testar inspeção OOXML, variável desconhecida e proteção de versão utilizada.
- Testar migrate/rollback da 14 e rollback da 13 na ordem das FKs.