migration-reference · implemented
Migration 16 — generated_documents
Contrato dos documentos gerados ou registrados no estágio.
Contrato
| Campo | Regra |
|---|---|
id | bigint, chave primária. |
internship_id | FK obrigatória. |
template_version_id | nullable; obrigatório para origem sge e nulo para granting_party. |
origin | sge ou granting_party, conforme GeneratedDocumentOrigin. |
type | Enum — GeneratedDocumentType (GeneratedDocumentType). |
status | Enum — GeneratedDocumentStatus (GeneratedDocumentStatus). |
signature_availability_location | texto curto nullable; obrigatório ao mover documento assinável para awaiting_signature, com o local informado pelo Setor. |
snapshot | JSONB dos dados usados na geração; obrigatório para sge e nulo para granting_party. |
generation_token | UUID idempotente, único para impedir duplicação por retry da mesma ação. |
output_filename / template_sha256 | nome entregue e hash do template usado; não são caminho de arquivo final. |
generated_at | instante da geração bem-sucedida pelo SGE; a autoria é registrada no Activity Log. |
cancelled_at | timestamp nullable, obrigatório quando o documento for cancelado. |
cancellation_reason | texto nullable, obrigatório quando o documento for cancelado. |
| timestamps | auditoria. |
O SGE registra a geração ou a existência, mas não armazena PDF, DOCX de saída ou documentos assinados. Cada geração pelo SGE referencia a versão validada mais recente no momento da geração; não cria uma linha em template_versions. A FK para a versão deve restringir sua exclusão física após uso, e a versão usada não pode ser alterada de forma destrutiva. Versões nunca usadas podem ser excluídas com sua mídia. O SGE armazena apenas templates, versões e snapshots. Para documento de origem sge, a snapshot preserva o catálogo/valores resolvidos, os valores monetários e o texto do §1º de remuneração efetivamente inserido no marcador ${PARAGRAFO_REMUNERACAO}. Nunca inclui prova de emancipação, token, senha ou log. O status de assinatura é do documento; cancelar o documento não cancela automaticamente o estágio.
O arquivo é produzido em diretório privado temporário, transmitido e removido em finally. Geração em lote futura poderá manter temporário com expiração curta, sem convertê-lo em acervo. O contrato operacional completo está em Geração de documentos DOCX e variáveis.
Ao mudar um documento assinável para awaiting_signature, o Setor informa o campo Local de disponibilização para assinatura. Ele é texto livre de até 500 caracteres, por exemplo “SIPAC” ou “portal institucional de assinaturas”; o nome de uma plataforma não é constante, enum nem regra do código. O valor permanece como contexto histórico da disponibilização, inclusive depois de assinado ou cancelado.
Na mesma tela, o Setor pode marcar os interessados que receberão o aviso imediatamente. As opções são calculadas a partir das partes atuais do estágio e do tipo documental — discente, orientador, supervisor e, quando houver e-mail cadastrado, contato da concedente — e não aceitam digitação livre de destinatário. Ao confirmar o envio, pelo menos um interessado deve estar selecionado. O Activity Log registra a transição, o local e a quantidade/categorias escolhidas, sem copiar endereços de e-mail; os snapshots de destinatário e conteúdo pertencem às estruturas de comunicação.
Um aditivo é um generated_documents com type = addendum, versão de template e snapshot próprios.
Regras de combinação
origin = sgeexige template e snapshot da geração.origin = granting_partyregistra somente a existência do documento, exigetemplate_version_id = null, não usa snapshot de geração e não aceita upload ou armazenamento do arquivo externo.OrientationCertificateusageneratede não passa por assinatura.- Os únicos status documentais são
generated,awaiting_signature,signedecancelled;registeredereleasednão existem para documentos. awaiting_signatureexigesignature_availability_locationpara documento que requer assinatura;generated,signedecancelledpodem preservar o valor histórico sem torná-lo uma nova obrigação de preenchimento.- Quando a data de início vencer antes da assinatura, não há ação agendada. O documento continua
awaiting_signaturee o estágio continua aguardando assinaturas até que o Setor decida manualmente registrar a assinatura, cancelar o documento com motivo ou abrir uma correção. Somente após decisão, eventual correção e aprovação o término é recalculado e uma nova versão documental pode ser gerada para assinatura. - Falha de Job não cria status persistente novo sem decisão explícita.
Checklist
- Confirmar catálogo de tipos e transições de status atuais.
- Criar migration com FKs, índice por estágio/status e nulabilidade condicional.
- Criar Model com casts dos três enums e JSONB.
- Validar combinações de origem, tipo, template e status no Model.
- Implementar snapshot imutável no Model e Activity Log de criação/alteração.
- Exigir local de disponibilização genérico ao marcar
awaiting_signature, sem nome de plataforma hardcoded. - Exibir interessados elegíveis como checkboxes e enviar o aviso selecionado após o commit da transição.
- Implementar acompanhamento manual de assinatura externa quando aplicável.
- Testar geração, assinatura, cancelamento, aditivo e documento da concedente.
- Testar que nenhum arquivo final seja armazenado.
- Testar migrate/rollback na ordem completa após as migrations dependentes.