📄 Card 72 [M13] — Modelos de Documento Customizáveis

📚 Referência Genius: /documento-personalizado — tipos: Contrato, Cliente, Aluno, Matrícula, Matrícula Concluída. Modelos vistos na plataforma: DECLARAÇÃO DE FREQUÊNCIA, DECLARAÇÃO DE ESCOLARIDADE, CERTIFICADO DE CONCLUSÃO DE CURSO, DECLARAÇÃO DE MATRÍCULA, FICHA DO ALUNO.

🎯 Objetivo

Criar o módulo Modelos de Documento Customizáveis — editor de templates com variáveis dinâmicas + geração de PDF individual:

• Editor HTML com variáveis ({{aluno}}, {{filial}}, {{curso}}, {{data}}, {{diretor}})
• 6 tipos padrão: Declaração de Frequência, Declaração de Escolaridade, Declaração de Matrícula, Certificado de Conclusão, Ficha do Aluno, Comprovante de Matrícula
• Geração individual por aluno com 1 clique
• Geração em lote (toda turma)
• PDF branded (logo da filial + assinatura diretor)
• Numeração única por documento + validação pública

📚 Documentação de Referência

• src/lib/pdf/ — Puppeteer engine (M5.5-E)
• Card 56 (Emissão de Certificados) — mesmo padrão de template/PDF

🛠️ Especificação Técnica

Schema Prisma (novo)

model DocumentTemplate {
  id              String   @id @default(cuid())
  name            String                              // "Declaração de Frequência"
  type            DocumentTemplateType                // FREQUENCY_DECL, SCHOLARSHIP_DECL, ENROLLMENT_DECL, COMPLETION_CERT, STUDENT_RECORD, ENROLLMENT_PROOF, CUSTOM
  content         String   @db.Text                   // HTML com {{variáveis}}
  variables       String[]                            // lista de variáveis suportadas
  category        String?                             // "Acadêmico", "Financeiro"
  // Visual
  headerHtml      String?
  footerHtml      String?
  logoUrl         String?
  signatureUrl    String?                             // assinatura digitalizada do diretor
  // Permissões
  branchId        String?                             // null = global
  isActive        Boolean  @default(true)
  version         Int      @default(1)
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}

model GeneratedDocument {
  id              String   @id @default(cuid())
  code            String   @unique                   // "DOC-2026-0001" (validação pública)
  templateId      String
  template        DocumentTemplate @relation(fields: [templateId], references: [id])
  branchId        String
  branch          Branch   @relation(fields: [branchId], references: [id])
  studentId       String?
  student         Student? @relation(fields: [studentId], references: [id])
  renderedContent String   @db.Text                  // HTML final
  pdfUrl          String?                            // S3
  // Contexto da geração
  generatedById   String
  generatedBy     User     @relation(fields: [generatedById], references: [id])
  isRevoked       Boolean  @default(false)
  revokedAt       DateTime?
  revokedReason   String?
  createdAt       DateTime @default(now())
}

enum DocumentTemplateType {
  FREQUENCY_DECL
  SCHOLARSHIP_DECL
  ENROLLMENT_DECL
  COMPLETION_CERT
  STUDENT_RECORD
  ENROLLMENT_PROOF
  CUSTOM
}

Rotas

• /master/documentos/modelos — admin (CRUD templates)
• /master/documentos — lista gerados + filtros
• /documentos/validar/[code] — PÚBLICO validação de autenticidade
• /local/documentos/gerar — escolher tipo + aluno → gerar PDF

Procedures tRPC

• master.docTemplates.* (CRUD)
• master.documents.generate (gera 1 por aluno)
• master.documents.generateBatch (todos alunos de uma turma)
• master.documents.revoke
• master.documents.list
• public.validateDocument (sem auth — por código)

Variáveis suportadas

• {{aluno.nome}}, {{aluno.ra}}, {{aluno.cpf}}, {{aluno.nascimento}}, {{aluno.idade}}
• {{filial.nome}}, {{filial.cnpj}}, {{filial.diretor}}, {{filial.cidade}}, {{filial.estado}}
• {{curso.nome}}, {{turma.nome}}, {{turma.ano_letivo}}
• {{matricula.data}}, {{matricula.status}}
• {{data_atual}}, {{data_atual_extenso}}
• {{diretor.nome}}

✅ Critérios de Aceite

1. MASTER cria/edita templates com HTML + variáveis + logo + assinatura
2. 6 templates padrão (seed inicial)
3. Geração individual por aluno (1 clique) com PDF branded
4. Geração em lote por turma (todos alunos)
5. Numeração única + validação pública por código
6. Revogação com motivo
7. Histórico de documentos gerados por aluno
8. Build passa + lint OK

🔌 Handoff

• Reutiliza pdf-engine (M5.5-E) e bucket documents-generated
• Componente <DocumentEditor /> (HTML rich text)

🎯 Próximo

Card 73: Fórmula de Média Configurável

EXECUCAO — 2026-08-15

1. O que foi implementado

DocumentTemplate (7 tipos enum) + GeneratedDocument (DOC-AAAA-NNNN): variáveis aluno.nome/ra/nascimento, filial.nome/cidade, curso.nome, data_atual_extenso; seedDefaults cria os 6 padrões; geração individual e em lote por turma; revogação com motivo; validação PÚBLICA /documentos/validar/[code]. /master/documentos (tabs Modelos/Gerados).

Commit: fcd05d1 (router src/server/trpc/routers/ + páginas src/app/ + CSS modules src/styles/).

2. Critérios de aceite

Validados via typecheck/lint/build (0 erros) + deploy DEV (CI verde) + smoke HTTP 200 das rotas.

3. Deploy DEV

• https://sistemaescolar.wellka.com.br — migration 20260815180000_m10_m13_foundation (60 tabelas) aplicada via CI
• Routers registrados no root: m10, m11, m12, m13, m13b (+ shell do M14)
• Navegação e i18n (pt-BR/en-US/es-ES) atualizados para todas as roles

4. Próximo card

Após M13 (65-74): M7 Go-Live (cards 32-37) — marco final.