{
  "id": "backlog-e-decisoes",
  "title": "Backlog e decisões",
  "description": "Decisões aprovadas e assuntos ainda pendentes no planejamento do SGE.",
  "type": "decisions",
  "status": "in-progress",
  "visibility": "public",
  "tags": [
    "sge/decisoes",
    "sge/backlog"
  ],
  "related": [
    "e-mails-notificacoes-e-entregas",
    "enum-evaluationstatus",
    "enum-brazilianstate",
    "enum-holidayscope",
    "migration-01a-cities",
    "migration-01-addresses",
    "migration-18-supervisor-evaluations",
    "fluxos-principais",
    "migration-13-document-templates",
    "migration-14-template-versions",
    "migration-16-generated-documents",
    "migration-12-granting-parties",
    "glossario",
    "modelo-de-dados-acesso",
    "matriz-de-autorizacao",
    "migration-11-internship-types",
    "migration-15-internships",
    "migration-19-internship-requests",
    "migration-20-internship-request-corrections",
    "migration-base-04-activity-log",
    "helper-numbertowordshelper",
    "migration-21-internship-cancellation-requests",
    "migration-22-holidays",
    "migration-22-internship-calendar-overrides",
    "migration-23-internship-work-schedules",
    "geracao-de-documentos-docx-e-variaveis",
    "schedules",
    "ciclos-de-status"
  ],
  "sourceRefs": [],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Próximas definições\n\n- [ ] Confirmar perfis oficiais e responsabilidades.\n- [x] Fechar o catálogo de placeholders e os critérios de validação dos templates.\n- [ ] Definir política de retenção de documentos e auditoria.\n- [ ] Criar testes de aceitação para os fluxos principais.\n- [ ] Mapear os campos, critérios, escalas e regras condicionais dos formulários nativos de abertura e avaliação.\n\n## Decisões registradas\n\n### D-001 — Documentação versionada em Markdown com Mermaid\n\n- **Status:** definido.\n- **Decisão:** manter a documentação publicada em arquivos `.md`, com diagramas Mermaid versionados no repositório.\n- **Motivo:** facilita navegação, versionamento, revisão e atualização durante o desenvolvimento.\n\n### D-002 — Papéis separados de vínculos\n\n- **Status:** definido.\n- **Decisão:** não tratar função institucional apenas como um campo fixo no usuário. Usar `affiliations` para permitir múltiplos contextos por pessoa, campus e função.\n- **Motivo:** um usuário pode exercer funções diferentes em campi ou em momentos diferentes.\n\n### D-004 — Dados pessoais fora de `internships`\n\n- **Status:** definido.\n- **Decisão:** CPF permanece em `users` como identificador único da conta. RG, data de nascimento, telefone, endereço atual e campos profissionais opcionais do supervisor ficam em `user_personal_data`, relacionado um-para-um com `users` e preenchido nos fluxos pertinentes; os estágios manterão FKs e snapshots `jsonb` para preservar o histórico, enquanto os endereços históricos serão cópias imutáveis na própria tabela `addresses`.\n- **Motivo:** evita repetição de dados pessoais e mantém os documentos e estágios imunes a alterações posteriores no cadastro.\n\n### D-005 — Configurações pessoais por tipo de vínculo\n\n- **Status:** definido.\n- **Decisão:** qualquer usuário pode alterar a própria senha e o e-mail de login; o nome não é editável. A troca de e-mail exige senha atual, duas entradas coincidentes do novo endereço, vínculo ativo e aviso para os e-mails antigo e novo. Essa parte já está implementada na aba Segurança; a edição de RG, data de nascimento, endereço, telefone e dados profissionais continua pendente e deve respeitar o contexto do vínculo.\n- **Motivo:** separa dados da conta de dados necessários ao estágio e restringe a edição aos usuários que realmente precisam desses campos.\n\n### D-006 — Canvas espacial para diagramas Mermaid\n\n- **Status:** definido.\n- **Decisão:** manter os diagramas Mermaid em notas Markdown independentes e organizá-los em um canvas específico por meio de cards de arquivo.\n- **Motivo:** preserva a renderização e a exportação dos diagramas, ao mesmo tempo que permite organizar fontes e artefatos no repositório.\n\n### D-007 — Canvas do fluxograma com cards padronizados\n\n- **Status:** definido.\n- **Decisão:** o canvas do fluxograma usará cards de texto coloridos, grupos e conexões com cores por semântica. O JSON Canvas não possui formas nativas específicas para processo, decisão, documento ou banco de dados.\n- **Motivo:** evita depender de recursos que não fazem parte do formato e mantém os diagramas compatíveis com o pipeline de publicação.\n\n### D-008 — Trilhas separadas para notificações e e-mails\n\n- **Status:** definido.\n- **Decisão:** `notifications` registrará o aviso interno; `email_messages` preservará a mensagem preparada e `email_delivery_attempts` cada envio ou reenvio. Não haverá confirmação adicional de endereço de e-mail. Cada tentativa segue diretamente de `queued` para `sent` ou `failed`.\n- **Motivo:** preserva conteúdo e histórico de entrega das notificações operacionais, sem armazenar tokens de recuperação e sem confundir leitura interna com aceite pelo SMTP.\n- **Referência:** [E-mails, notificações e entregas](doc:e-mails-notificacoes-e-entregas).\n\n### D-009 — Ciclo e validade da avaliação do supervisor\n\n- **Status:** definido.\n- **Decisão:** após a liberação e notificação, o supervisor poderá salvar a avaliação como `Draft`, com campos ainda nulos. Em `Submitted`, `Returned`, `Approved` e `Cancelled`, todos os campos obrigatórios do caminho condicional escolhido estarão preenchidos. O Setor de Estágio poderá aprovar ou devolver, mas não editar respostas. `Returned` reabre o mesmo registro para edição integral e novo envio; cada alteração e transição fica no `activity_log`. O supervisor poderá cancelar um `Submitted` ou `Returned`, sem exclusão física e com motivo. A aprovação exige a confirmação de carga horária cumprida; se ela não estiver cumprida, o Setor devolve a resposta. A avaliação vigente será o `Approved` mais recente por data de envio.\n- **Motivo:** preserva um único formulário por estágio e supervisor, permite correção integral sem criar versões artificiais e mantém a auditoria de valores e estados fora da interface do supervisor.\n- **Autorização:** a análise pertence ao vínculo `AffiliationType::InternshipOffice`; `AffiliationType::Coordinator` continua representando o coordenador de curso.\n- **Referências:** [Enum — EvaluationStatus](doc:enum-evaluationstatus), [Migration de avaliações](doc:migration-18-supervisor-evaluations) e [fluxo de avaliação](doc:fluxos-principais#6-acompanhamento-academico-e-conclusao).\n\n### D-010 — Templates DOCX versionados e saída sem arquivo final\n\n- **Status:** definido.\n- **Decisão:** templates DOCX serão cadastrados separadamente dos tipos de documento. O catálogo de variáveis é fixo no código e cada DOCX usa as variáveis necessárias. Cada arquivo diferente enviado e validado cria uma versão; cada geração usa a versão validada mais recente e referencia exatamente a versão e a snapshot de dados usadas. Após uso, uma correção cria outra versão e a anterior permanece. Uma versão nunca usada pode ser excluída fisicamente com sua mídia. O SGE não armazena o arquivo DOCX/PDF final ou o documento assinado.\n- **Motivo:** permite rastrear e, quando necessário, reproduzir a geração histórica sem misturar template, tipo documental e arquivo final.\n- **Referências:** [Migration 13 — document_templates](doc:migration-13-document-templates), [Migration 14 — template_versions](doc:migration-14-template-versions) e [Migration 16 — generated_documents](doc:migration-16-generated-documents).\n\n### D-011 — Solicitações pendentes são registros próprios\n\n- **Status:** definido.\n- **Decisão:** dados de supervisor ou parte concedente ainda não cadastrados serão salvos em estruturas próprias de solicitação, com origem, análise, decisão, motivo e associação ao cadastro resultante. Notificações apenas avisam o Setor de Estágio e apontam para a solicitação.\n- **Motivo:** uma notificação não preserva adequadamente os dados, o histórico de análise e a decisão do cadastro.\n\n### D-012 — Identificação e escopo de partes concedentes\n\n- **Status:** definido e refletido no schema e nas validações dos Models.\n- **Decisão:** `granting_parties` usa `document_type` (`CPF` ou `CNPJ`) e `document_number` normalizado, mas cada cadastro pertence a um campus por FK. Os cadastros são locais ao campus, inclusive para dados de conselho, credenciamento, contatos e endereço. O mesmo CPF ou CNPJ pode aparecer em mais de um cadastro e não terá unicidade global nem por campus. O CPF de uma concedente não é chave para associar ou mesclar uma conta em `users`. As solicitações de concedente também devem preservar o campus de origem, e sua aprovação deve resultar em uma concedente daquele campus.\n- **Motivo:** algumas empresas exigem o CNPJ da matriz nas filiais e escolas estaduais podem compartilhar o CNPJ; pessoas físicas e seus dados de credenciamento também precisam permanecer no escopo institucional local.\n- **Referências:** [Migration 12 — granting_parties](doc:migration-12-granting-parties) e [Glossário](doc:glossario).\n\n### D-013 — Controle de acesso por vínculos e remoção das tabelas de permissão\n\n- **Status:** definido.\n- **Decisão:** remover as tabelas de permissões anteriormente previstas. A autorização será feita exclusivamente pelos recursos nativos do Laravel: Gates e Policies verificam vínculo ativo, `AffiliationType`, campus/curso, posse do registro e estado do fluxo. A matriz é estática no código e nos testes.\n- **Motivo:** as regras são institucionais, determinísticas e tipadas. O vínculo já representa função e escopo, sem segunda fonte de verdade ou tabelas dinâmicas.\n- **Referências:** [Modelo de dados — Acesso](doc:modelo-de-dados-acesso) e [Matriz de autorização](doc:matriz-de-autorizacao).\n\n### D-014 — Pesos e conceitos pertencem ao tipo de estágio\n\n- **Status:** definido.\n- **Decisão:** cada tipo de estágio definirá a carga horária, os pesos da avaliação do supervisor, do relatório e da apresentação, e os valores numéricos dos conceitos da avaliação. Os três pesos devem totalizar 10. Na criação do estágio, essas regras serão copiadas para o snapshot do tipo; alterações posteriores no cadastro do tipo não recalcularão estágios já iniciados.\n- **Motivo:** os critérios de conclusão variam por modalidade e precisam permanecer auditáveis no contexto em que o estágio foi realizado.\n- **Referências:** [Migration 11 — internship_types](doc:migration-11-internship-types), [Migration 15 — internships](doc:migration-15-internships) e [Migration 18 — supervisor_evaluations](doc:migration-18-supervisor-evaluations).\n\n### D-015 — Solicitação única e correções orientadas\n\n- **Status:** definido.\n- **Decisão:** o formulário nativo de abertura edita uma única solicitação de estágio vinculada ao `affiliation_id` do discente. Após o aceite, a solicitação é associada a um único estágio. Devoluções não criam outra solicitação nem versões completas de resposta: elas abrem um registro de correção com mensagem e seções afetadas. O discente altera somente as seções indicadas e reenvia a mesma solicitação. Todo reenvio volta obrigatoriamente para análise e aprovação formal do Setor de Estágio antes de gerar ou reemitir documentos. O `activity_log` preserva os valores alterados e o contexto da ação.\n- **Motivo:** preserva um processo simples para o discente e deixa as correções visíveis e priorizadas para o Setor de Estágio, sem usar o log de auditoria como fonte do estado atual.\n- **Referências:** [Migration 19 — internship_requests](doc:migration-19-internship-requests), [Migration 20 — internship_request_corrections](doc:migration-20-internship-request-corrections), [Migration base 04 — activity_log](doc:migration-base-04-activity-log) e [Fluxos principais](doc:fluxos-principais#2-solicitacao).\n\n### D-016 — Parágrafo de remuneração gerado no documento\n\n- **Status:** definido.\n- **Decisão:** o template padrão usa o marcador descritivo `${PARAGRAFO_REMUNERACAO}`. `RemunerationParagraphFormatter` insere o §1º completo: remunerado, com bolsa e auxílio-transporte em moeda e por extenso; ou não remunerado. A condição é definida diretamente por `is_remunerated`; não haverá tabela de regras nem editor de texto neste momento. O número de processo de credenciamento é uma substituição de dado simples quando o template o solicitar. Quando houver diferenças relevantes de credenciamento, serão mantidos templates separados e o Setor de Estágio escolherá manualmente o modelo aplicável em cada geração.\n- **Motivo:** o §1º é conhecido e estável; manter a regra em um único serviço evita multiplicar templates por combinações de remuneração. Já as diferenças estruturais de credenciamento justificam modelos próprios, sem automatismo de seleção.\n- **Referências:** [Migration 12 — granting_parties](doc:migration-12-granting-parties), [Migration 13 — document_templates](doc:migration-13-document-templates), [Migration 16 — generated_documents](doc:migration-16-generated-documents) e [Helper — NumberToWordsHelper](doc:helper-numbertowordshelper).\n\n### D-017 — Cancelamento solicitado pelo discente\n\n- **Status:** definido.\n- **Decisão:** antes de existir um estágio formalizado, o discente pode desistir cancelando a própria solicitação. Depois do aceite, pode solicitar cancelamento antes do início ou durante o estágio, sempre com motivo e histórico. O Setor de Estágio aprova ou recusa. A aprovação cancela documentos ainda não assinados, preserva documentos assinados, gera rescisão quando aplicável, cancela avaliações pendentes e mantém notas/avaliações aprovadas apenas como histórico, sem concluir o estágio.\n- **Motivo:** a desistência é diferente de uma recusa do Setor e o cancelamento de estágio formalizado exige tratamento rastreável.\n- **Referências:** [Migration 21 — internship_cancellation_requests](doc:migration-21-internship-cancellation-requests), [Fluxos principais](doc:fluxos-principais#4-estagio-em-andamento) e [Migration base 04 — activity_log](doc:migration-base-04-activity-log).\n\n### D-018 — Emancipação exige comprovação e validação institucional\n\n- **Status:** definido.\n- **Decisão:** o formulário terá rádio obrigatório com três opções: maior de idade, menor de idade e menor emancipado. Maior é conferido contra a data de nascimento; menor exige responsável legal. Menor emancipado envia o comprovante pelo próprio SGE, em upload privado vinculado à solicitação, e dispensa o responsável neste envio. Cada upload gera registro próprio, com vínculo do discente, instante, mídia privada e status de análise; novo envio não apaga o anterior. O envio cria pendência de verificação, não aprovação automática: o Setor confere manualmente e valida ou devolve com motivo. Se devolver por prova inválida, o discente envia nova prova ou muda para menor de idade e informa o responsável. A validação registra data, vínculo responsável e referência à mídia protegida. O arquivo não entra no `activity_log`, em mensagens de e-mail ou em documentos gerados e só é visível ao discente e ao Setor conforme necessidade.\n- **Motivo:** o rádio deixa a interface clara para o discente e preserva a análise humana da prova, sem forçar os dados de responsável antes de o Setor apontar uma pendência.\n- **Referências:** [Migration 02 — user_personal_data](doc:migration-02-user-personal-data) e [Migration 19 — internship_requests](doc:migration-19-internship-requests).\n\n### D-019 — Previsão de término reproduzível\n\n- **Status:** definido.\n- **Decisão:** a data prevista de término é calculada pela jornada válida, pela margem de sete dias corridos configurada e congelada no tipo de estágio, pelo calendário nacional, estadual e municipal versionado — conforme a cidade/UF do endereço histórico do local de trabalho —, pelas pausas e pelas exceções específicas do estágio. Eventual nova vigência exige aditivo formalizado. O cálculo limita o último dia às horas restantes e persiste uma base reproduzível; não aceita horas restantes livres como fonte primária.\n- **Motivo:** mantém o cálculo rastreável e evita resultados inconsistentes após alterações de calendário, jornada ou pausa.\n- **Referências:** [Service — InternshipEndDateCalculator](doc:service-internshipenddatecalculator), [Migration 22 — holidays](doc:migration-22-holidays) e [Migration 23 — internship_work_schedules](doc:migration-23-internship-work-schedules).\n\n### D-020 — Motor DOCX local e catálogo canônico\n\n- **Status:** definido.\n- **Decisão:** gerar DOCX localmente com PHPWord, usando somente `${NOME_DA_VARIAVEL}` de um catálogo canônico. Uploads são inspecionados, renderizados e versionados; o resultado é temporário e não vira acervo. Cada template passa por revisão antes de ser ativado.\n- **Motivo:** permite validar os dados usados e preserva rastreabilidade sem armazenar documentos finais.\n- **Referências:** [Geração de documentos DOCX e variáveis](doc:geracao-de-documentos-docx-e-variaveis).\n\n### D-021 — Reconciliação temporal por schedules idempotentes\n\n- **Status:** definido.\n- **Decisão:** dois commands diários, no fuso institucional, reconciliarão a execução do estágio e enviarão o único lembrete de término previsto a sete dias. O primeiro inicia estágios liberados na data planejada, pausa estágios com pausa ativa e retoma os pausados cujo período terminou. O segundo avisa o discente e gera o resumo interno agrupado do Setor de Estágio. Assinaturas, cancelamento documental, pendência, correção e reemissão são tratados manualmente pelo Setor. Não haverá conclusão automática, cancelamento automático de documento, abertura automática de correção, recálculo diário da previsão nem varredura genérica de e-mails.\n- **Motivo:** a passagem do tempo não pode depender de alguém acessar o sistema, mas decisões de conclusão, correção e reenvio ainda exigem regras e análise humanas. Restringir o escopo aos fatos temporais evita efeitos duplicados e processamento desnecessário.\n- **Referências:** [Schedules](doc:schedules), [Ciclos de status](doc:ciclos-de-status) e [E-mails, notificações e entregas](doc:e-mails-notificacoes-e-entregas).\n\n### D-022 — Avisos de assinatura e término por canal adequado\n\n- **Status:** definido.\n- **Decisão:** ao colocar um documento assinável em `awaiting_signature`, o Setor informa em campo textual genérico onde ele está disponível e escolhe, por checkboxes, os interessados elegíveis que devem ser avisados. Pessoas com conta recebem notificação interna e e-mail; o contato externo selecionado da concedente recebe somente e-mail. Não há destinatário digitado livremente nem nome de plataforma hardcoded. O discente recebe notificação interna e e-mail pelos fatos temporais do próprio estágio e por um único lembrete sete dias antes da previsão vigente de término. O Setor recebe somente um resumo interno diário, por campus e destinatário, que agrupa eventos e pendências.\n- **Motivo:** a assinatura exige que o Setor comunique o local efetivo, que pode mudar de plataforma, sem transformar uma ferramenta externa em dependência do domínio. A separação de canais mantém o discente informado e evita que o Setor receba e-mails ou avisos fragmentados em excesso.\n- **Referências:** [Migration 16 — generated_documents](doc:migration-16-generated-documents), [Schedules](doc:schedules) e [E-mails, notificações e entregas](doc:e-mails-notificacoes-e-entregas).\n\n### D-023 — Jornada fixa, pausas e alteração somente por aditivo\n\n- **Status:** definido.\n- **Decisão:** a solicitação define uma jornada semanal por carga horária em cada dia, sem registrar horários de entrada ou saída. Essa jornada permanece fixa durante a execução. Pausas são registradas normalmente no formulário: suspendem o cômputo e alteram a previsão de término, mas nunca distribuem ou modificam horas. Quando uma pausa não prevista precisar ter seus efeitos formalizados no instrumento do estágio, o Setor de Estágio gera um aditivo, conforme a análise do caso. Qualquer alteração de carga horária exige um documento de aditivo; somente depois de suas assinaturas serem conferidas pelo Setor o sistema encerra a vigência anterior, cria a nova e recalcula a previsão. Não há alteração temporária de carga horária como funcionalidade independente.\n- **Motivo:** mantém o cálculo simples e rastreável, separa interrupção de execução de mudança contratual e impede que um ajuste informal reescreva a base de documentos ou de cálculos anteriores.\n- **Referências:** [Migration 23 — internship_work_schedules](doc:migration-23-internship-work-schedules), [Migration 22A — internship_calendar_overrides](doc:migration-22-internship-calendar-overrides), [Service — InternshipEndDateCalculator](doc:service-internshipenddatecalculator) e [Fluxos principais](doc:fluxos-principais#4-estagio-em-andamento).",
  "sections": [
    {
      "id": "proximas-definicoes",
      "level": 2,
      "title": "Próximas definições",
      "text": "- [ ] Confirmar perfis oficiais e responsabilidades. - [x] Fechar o catálogo de placeholders e os critérios de validação dos templates. - [ ] Definir política de retenção de documentos e auditoria. - [ ] Criar testes de aceitação para os fluxos principais. - [ ] Mapear os campos, critérios, escalas e regras condicionais dos formulários nativos de abertura e avaliação.",
      "line": 1
    },
    {
      "id": "decisoes-registradas",
      "level": 2,
      "title": "Decisões registradas",
      "text": "",
      "line": 9
    },
    {
      "id": "d-001-documentacao-versionada-em-markdown-com-mermaid",
      "level": 3,
      "title": "D-001 — Documentação versionada em Markdown com Mermaid",
      "text": "- **Status:** definido. - **Decisão:** manter a documentação publicada em arquivos `.md`, com diagramas Mermaid versionados no repositório. - **Motivo:** facilita navegação, versionamento, revisão e atualização durante o desenvolvimento.",
      "line": 11
    },
    {
      "id": "d-002-papeis-separados-de-vinculos",
      "level": 3,
      "title": "D-002 — Papéis separados de vínculos",
      "text": "- **Status:** definido. - **Decisão:** não tratar função institucional apenas como um campo fixo no usuário. Usar `affiliations` para permitir múltiplos contextos por pessoa, campus e função. - **Motivo:** um usuário pode exercer funções diferentes em campi ou em momentos diferentes.",
      "line": 17
    },
    {
      "id": "d-004-dados-pessoais-fora-de-internships",
      "level": 3,
      "title": "D-004 — Dados pessoais fora de internships",
      "text": "- **Status:** definido. - **Decisão:** CPF permanece em `users` como identificador único da conta. RG, data de nascimento, telefone, endereço atual e campos profissionais opcionais do supervisor ficam em `user_personal_data`, relacionado um-para-um com `users` e preenchido nos fluxos pertinentes; os estágios manterão FKs e snapshots `jsonb` para preservar o histórico, enquanto os endereços históricos serão cópias imutáveis na própria tabela `addresses`. - **Motivo:** evita repetição de dados pessoais e mantém os documentos e estágios imunes a alterações posteriores no cadastro.",
      "line": 23
    },
    {
      "id": "d-005-configuracoes-pessoais-por-tipo-de-vinculo",
      "level": 3,
      "title": "D-005 — Configurações pessoais por tipo de vínculo",
      "text": "- **Status:** definido. - **Decisão:** qualquer usuário pode alterar a própria senha e o e-mail de login; o nome não é editável. A troca de e-mail exige senha atual, duas entradas coincidentes do novo endereço, vínculo ativo e aviso para os e-mails antigo e novo. Essa parte já está implementada na aba Segurança; a edição de RG, data de nascimento, endereço, telefone e dados profissionais continua pendente e deve respeitar o contexto do vínculo. - **Motivo:** separa dados da conta de dados necessários ao estágio e restringe a edição aos usuários que realmente precisam desses campos.",
      "line": 29
    },
    {
      "id": "d-006-canvas-espacial-para-diagramas-mermaid",
      "level": 3,
      "title": "D-006 — Canvas espacial para diagramas Mermaid",
      "text": "- **Status:** definido. - **Decisão:** manter os diagramas Mermaid em notas Markdown independentes e organizá-los em um canvas específico por meio de cards de arquivo. - **Motivo:** preserva a renderização e a exportação dos diagramas, ao mesmo tempo que permite organizar fontes e artefatos no repositório.",
      "line": 35
    },
    {
      "id": "d-007-canvas-do-fluxograma-com-cards-padronizados",
      "level": 3,
      "title": "D-007 — Canvas do fluxograma com cards padronizados",
      "text": "- **Status:** definido. - **Decisão:** o canvas do fluxograma usará cards de texto coloridos, grupos e conexões com cores por semântica. O JSON Canvas não possui formas nativas específicas para processo, decisão, documento ou banco de dados. - **Motivo:** evita depender de recursos que não fazem parte do formato e mantém os diagramas compatíveis com o pipeline de publicação.",
      "line": 41
    },
    {
      "id": "d-008-trilhas-separadas-para-notificacoes-e-e-mails",
      "level": 3,
      "title": "D-008 — Trilhas separadas para notificações e e-mails",
      "text": "- **Status:** definido. - **Decisão:** `notifications` registrará o aviso interno; `email_messages` preservará a mensagem preparada e `email_delivery_attempts` cada envio ou reenvio. Não haverá confirmação adicional de endereço de e-mail. Cada tentativa segue diretamente de `queued` para `sent` ou `failed`. - **Motivo:** preserva conteúdo e histórico de entrega das notificações operacionais, sem armazenar tokens de recuperação e sem confundir leitura interna com aceite pelo SMTP. - **Referência:** [E-mails, notificações e entregas](doc:e-mails-notificacoes-e-entregas).",
      "line": 47
    },
    {
      "id": "d-009-ciclo-e-validade-da-avaliacao-do-supervisor",
      "level": 3,
      "title": "D-009 — Ciclo e validade da avaliação do supervisor",
      "text": "- **Status:** definido. - **Decisão:** após a liberação e notificação, o supervisor poderá salvar a avaliação como `Draft`, com campos ainda nulos. Em `Submitted`, `Returned`, `Approved` e `Cancelled`, todos os campos obrigatórios do caminho condicional escolhido estarão preenchidos. O Setor de Estágio poderá aprovar ou devolver, mas não editar respostas. `Returned` reabre o mesmo registro para edição integral e novo envio; cada alteração e transição fica no `activity_log`. O supervisor poderá cancelar um `Submitted` ou `Returned`, sem exclusão física e com motivo. A aprovação exige a confirmação de carga horária cumprida; se ela não estiver cumprida, o Setor devolve a resposta. A avaliação vigente será o `Approved` mais recente por data de envio. - **Motivo:** preserva um único formulário por estágio e supervisor, permite correção integral sem criar versões artificiais e mantém a auditoria de valores e estados fora da interface do supervisor. - **Autorização:** a análise pertence ao vínculo `AffiliationType::InternshipOffice`; `AffiliationType::Coordinator` continua representando o coordenador de curso. - **Referências:** [Enum — EvaluationStatus](doc:enum-evaluationstatus), [Migration de avaliações](doc:migration-18-supervisor-evaluations) e [fluxo de avaliação](doc:fluxos-principais#6-acompanhamento-academico-e-conclusao).",
      "line": 54
    },
    {
      "id": "d-010-templates-docx-versionados-e-saida-sem-arquivo-final",
      "level": 3,
      "title": "D-010 — Templates DOCX versionados e saída sem arquivo final",
      "text": "- **Status:** definido. - **Decisão:** templates DOCX serão cadastrados separadamente dos tipos de documento. O catálogo de variáveis é fixo no código e cada DOCX usa as variáveis necessárias. Cada arquivo diferente enviado e validado cria uma versão; cada geração usa a versão validada mais recente e referencia exatamente a versão e a snapshot de dados usadas. Após uso, uma correção cria outra versão e a anterior permanece. Uma versão nunca usada pode ser excluída fisicamente com sua mídia. O SGE não armazena o arquivo DOCX/PDF final ou o documento assinado. - **Motivo:** permite rastrear e, quando necessário, reproduzir a geração histórica sem misturar template, tipo documental e arquivo final. - **Referências:** [Migration 13 — document_templates](doc:migration-13-document-templates), [Migration 14 — template_versions](doc:migration-14-template-versions) e [Migration 16 — generated_documents](doc:migration-16-generated-documents).",
      "line": 62
    },
    {
      "id": "d-011-solicitacoes-pendentes-sao-registros-proprios",
      "level": 3,
      "title": "D-011 — Solicitações pendentes são registros próprios",
      "text": "- **Status:** definido. - **Decisão:** dados de supervisor ou parte concedente ainda não cadastrados serão salvos em estruturas próprias de solicitação, com origem, análise, decisão, motivo e associação ao cadastro resultante. Notificações apenas avisam o Setor de Estágio e apontam para a solicitação. - **Motivo:** uma notificação não preserva adequadamente os dados, o histórico de análise e a decisão do cadastro.",
      "line": 69
    },
    {
      "id": "d-012-identificacao-e-escopo-de-partes-concedentes",
      "level": 3,
      "title": "D-012 — Identificação e escopo de partes concedentes",
      "text": "- **Status:** definido e refletido no schema e nas validações dos Models. - **Decisão:** `granting_parties` usa `document_type` (`CPF` ou `CNPJ`) e `document_number` normalizado, mas cada cadastro pertence a um campus por FK. Os cadastros são locais ao campus, inclusive para dados de conselho, credenciamento, contatos e endereço. O mesmo CPF ou CNPJ pode aparecer em mais de um cadastro e não terá unicidade global nem por campus. O CPF de uma concedente não é chave para associar ou mesclar uma conta em `users`. As solicitações de concedente também devem preservar o campus de origem, e sua aprovação deve resultar em uma concedente daquele campus. - **Motivo:** algumas empresas exigem o CNPJ da matriz nas filiais e escolas estaduais podem compartilhar o CNPJ; pessoas físicas e seus dados de credenciamento também precisam permanecer no escopo institucional local. - **Referências:** [Migration 12 — granting_parties](doc:migration-12-granting-parties) e [Glossário](doc:glossario).",
      "line": 75
    },
    {
      "id": "d-013-controle-de-acesso-por-vinculos-e-remocao-das-tabelas-de-permissao",
      "level": 3,
      "title": "D-013 — Controle de acesso por vínculos e remoção das tabelas de permissão",
      "text": "- **Status:** definido. - **Decisão:** remover as tabelas de permissões anteriormente previstas. A autorização será feita exclusivamente pelos recursos nativos do Laravel: Gates e Policies verificam vínculo ativo, `AffiliationType`, campus/curso, posse do registro e estado do fluxo. A matriz é estática no código e nos testes. - **Motivo:** as regras são institucionais, determinísticas e tipadas. O vínculo já representa função e escopo, sem segunda fonte de verdade ou tabelas dinâmicas. - **Referências:** [Modelo de dados — Acesso](doc:modelo-de-dados-acesso) e [Matriz de autorização](doc:matriz-de-autorizacao).",
      "line": 82
    },
    {
      "id": "d-014-pesos-e-conceitos-pertencem-ao-tipo-de-estagio",
      "level": 3,
      "title": "D-014 — Pesos e conceitos pertencem ao tipo de estágio",
      "text": "- **Status:** definido. - **Decisão:** cada tipo de estágio definirá a carga horária, os pesos da avaliação do supervisor, do relatório e da apresentação, e os valores numéricos dos conceitos da avaliação. Os três pesos devem totalizar 10. Na criação do estágio, essas regras serão copiadas para o snapshot do tipo; alterações posteriores no cadastro do tipo não recalcularão estágios já iniciados. - **Motivo:** os critérios de conclusão variam por modalidade e precisam permanecer auditáveis no contexto em que o estágio foi realizado. - **Referências:** [Migration 11 — internship_types](doc:migration-11-internship-types), [Migration 15 — internships](doc:migration-15-internships) e [Migration 18 — supervisor_evaluations](doc:migration-18-supervisor-evaluations).",
      "line": 89
    },
    {
      "id": "d-015-solicitacao-unica-e-correcoes-orientadas",
      "level": 3,
      "title": "D-015 — Solicitação única e correções orientadas",
      "text": "- **Status:** definido. - **Decisão:** o formulário nativo de abertura edita uma única solicitação de estágio vinculada ao `affiliation_id` do discente. Após o aceite, a solicitação é associada a um único estágio. Devoluções não criam outra solicitação nem versões completas de resposta: elas abrem um registro de correção com mensagem e seções afetadas. O discente altera somente as seções indicadas e reenvia a mesma solicitação. Todo reenvio volta obrigatoriamente para análise e aprovação formal do Setor de Estágio antes de gerar ou reemitir documentos. O `activity_log` preserva os valores alterados e o contexto da ação. - **Motivo:** preserva um processo simples para o discente e deixa as correções visíveis e priorizadas para o Setor de Estágio, sem usar o log de auditoria como fonte do estado atual. - **Referências:** [Migration 19 — internship_requests](doc:migration-19-internship-requests), [Migration 20 — internship_request_corrections](doc:migration-20-internship-request-corrections), [Migration base 04 — activity_log](doc:migration-base-04-activity-log) e [Fluxos principais](doc:fluxos-principais#2-solicitacao).",
      "line": 96
    },
    {
      "id": "d-016-paragrafo-de-remuneracao-gerado-no-documento",
      "level": 3,
      "title": "D-016 — Parágrafo de remuneração gerado no documento",
      "text": "- **Status:** definido. - **Decisão:** o template padrão usa o marcador descritivo `${PARAGRAFO_REMUNERACAO}`. `RemunerationParagraphFormatter` insere o §1º completo: remunerado, com bolsa e auxílio-transporte em moeda e por extenso; ou não remunerado. A condição é definida diretamente por `is_remunerated`; não haverá tabela de regras nem editor de texto neste momento. O número de processo de credenciamento é uma substituição de dado simples quando o template o solicitar. Quando houver diferenças relevantes de credenciamento, serão mantidos templates separados e o Setor de Estágio escolherá manualmente o modelo aplicável em cada geração. - **Motivo:** o §1º é conhecido e estável; manter a regra em um único serviço evita multiplicar templates por combinações de remuneração. Já as diferenças estruturais de credenciamento justificam modelos próprios, sem automatismo de seleção. - **Referências:** [Migration 12 — granting_parties](doc:migration-12-granting-parties), [Migration 13 — document_templates](doc:migration-13-document-templates), [Migration 16 — generated_documents](doc:migration-16-generated-documents) e [Helper — NumberToWordsHelper](doc:helper-numbertowordshelper).",
      "line": 103
    },
    {
      "id": "d-017-cancelamento-solicitado-pelo-discente",
      "level": 3,
      "title": "D-017 — Cancelamento solicitado pelo discente",
      "text": "- **Status:** definido. - **Decisão:** antes de existir um estágio formalizado, o discente pode desistir cancelando a própria solicitação. Depois do aceite, pode solicitar cancelamento antes do início ou durante o estágio, sempre com motivo e histórico. O Setor de Estágio aprova ou recusa. A aprovação cancela documentos ainda não assinados, preserva documentos assinados, gera rescisão quando aplicável, cancela avaliações pendentes e mantém notas/avaliações aprovadas apenas como histórico, sem concluir o estágio. - **Motivo:** a desistência é diferente de uma recusa do Setor e o cancelamento de estágio formalizado exige tratamento rastreável. - **Referências:** [Migration 21 — internship_cancellation_requests](doc:migration-21-internship-cancellation-requests), [Fluxos principais](doc:fluxos-principais#4-estagio-em-andamento) e [Migration base 04 — activity_log](doc:migration-base-04-activity-log).",
      "line": 110
    },
    {
      "id": "d-018-emancipacao-exige-comprovacao-e-validacao-institucional",
      "level": 3,
      "title": "D-018 — Emancipação exige comprovação e validação institucional",
      "text": "- **Status:** definido. - **Decisão:** o formulário terá rádio obrigatório com três opções: maior de idade, menor de idade e menor emancipado. Maior é conferido contra a data de nascimento; menor exige responsável legal. Menor emancipado envia o comprovante pelo próprio SGE, em upload privado vinculado à solicitação, e dispensa o responsável neste envio. Cada upload gera registro próprio, com vínculo do discente, instante, mídia privada e status de análise; novo envio não apaga o anterior. O envio cria pendência de verificação, não aprovação automática: o Setor confere manualmente e valida ou devolve com motivo. Se devolver por prova inválida, o discente envia nova prova ou muda para menor de idade e informa o responsável. A validação registra data, vínculo responsável e referência à mídia protegida. O arquivo não entra no `activity_log`, em mensagens de e-mail ou em documentos gerados e só é visível ao discente e ao Setor conforme necessidade. - **Motivo:** o rádio deixa a interface clara para o discente e preserva a análise humana da prova, sem forçar os dados de responsável antes de o Setor apontar uma pendência. - **Referências:** [Migration 02 — user_personal_data](doc:migration-02-user-personal-data) e [Migration 19 — internship_requests](doc:migration-19-internship-requests).",
      "line": 117
    },
    {
      "id": "d-019-previsao-de-termino-reproduzivel",
      "level": 3,
      "title": "D-019 — Previsão de término reproduzível",
      "text": "- **Status:** definido. - **Decisão:** a data prevista de término é calculada pela jornada válida, pela margem de sete dias corridos configurada e congelada no tipo de estágio, pelo calendário nacional, estadual e municipal versionado — conforme a cidade/UF do endereço histórico do local de trabalho —, pelas pausas e pelas exceções específicas do estágio. Eventual nova vigência exige aditivo formalizado. O cálculo limita o último dia às horas restantes e persiste uma base reproduzível; não aceita horas restantes livres como fonte primária. - **Motivo:** mantém o cálculo rastreável e evita resultados inconsistentes após alterações de calendário, jornada ou pausa. - **Referências:** [Service — InternshipEndDateCalculator](doc:service-internshipenddatecalculator), [Migration 22 — holidays](doc:migration-22-holidays) e [Migration 23 — internship_work_schedules](doc:migration-23-internship-work-schedules).",
      "line": 124
    },
    {
      "id": "d-020-motor-docx-local-e-catalogo-canonico",
      "level": 3,
      "title": "D-020 — Motor DOCX local e catálogo canônico",
      "text": "- **Status:** definido. - **Decisão:** gerar DOCX localmente com PHPWord, usando somente `${NOME_DA_VARIAVEL}` de um catálogo canônico. Uploads são inspecionados, renderizados e versionados; o resultado é temporário e não vira acervo. Cada template passa por revisão antes de ser ativado. - **Motivo:** permite validar os dados usados e preserva rastreabilidade sem armazenar documentos finais. - **Referências:** [Geração de documentos DOCX e variáveis](doc:geracao-de-documentos-docx-e-variaveis).",
      "line": 131
    },
    {
      "id": "d-021-reconciliacao-temporal-por-schedules-idempotentes",
      "level": 3,
      "title": "D-021 — Reconciliação temporal por schedules idempotentes",
      "text": "- **Status:** definido. - **Decisão:** dois commands diários, no fuso institucional, reconciliarão a execução do estágio e enviarão o único lembrete de término previsto a sete dias. O primeiro inicia estágios liberados na data planejada, pausa estágios com pausa ativa e retoma os pausados cujo período terminou. O segundo avisa o discente e gera o resumo interno agrupado do Setor de Estágio. Assinaturas, cancelamento documental, pendência, correção e reemissão são tratados manualmente pelo Setor. Não haverá conclusão automática, cancelamento automático de documento, abertura automática de correção, recálculo diário da previsão nem varredura genérica de e-mails. - **Motivo:** a passagem do tempo não pode depender de alguém acessar o sistema, mas decisões de conclusão, correção e reenvio ainda exigem regras e análise humanas. Restringir o escopo aos fatos temporais evita efeitos duplicados e processamento desnecessário. - **Referências:** [Schedules](doc:schedules), [Ciclos de status](doc:ciclos-de-status) e [E-mails, notificações e entregas](doc:e-mails-notificacoes-e-entregas).",
      "line": 138
    },
    {
      "id": "d-022-avisos-de-assinatura-e-termino-por-canal-adequado",
      "level": 3,
      "title": "D-022 — Avisos de assinatura e término por canal adequado",
      "text": "- **Status:** definido. - **Decisão:** ao colocar um documento assinável em `awaiting_signature`, o Setor informa em campo textual genérico onde ele está disponível e escolhe, por checkboxes, os interessados elegíveis que devem ser avisados. Pessoas com conta recebem notificação interna e e-mail; o contato externo selecionado da concedente recebe somente e-mail. Não há destinatário digitado livremente nem nome de plataforma hardcoded. O discente recebe notificação interna e e-mail pelos fatos temporais do próprio estágio e por um único lembrete sete dias antes da previsão vigente de término. O Setor recebe somente um resumo interno diário, por campus e destinatário, que agrupa eventos e pendências. - **Motivo:** a assinatura exige que o Setor comunique o local efetivo, que pode mudar de plataforma, sem transformar uma ferramenta externa em dependência do domínio. A separação de canais mantém o discente informado e evita que o Setor receba e-mails ou avisos fragmentados em excesso. - **Referências:** [Migration 16 — generated_documents](doc:migration-16-generated-documents), [Schedules](doc:schedules) e [E-mails, notificações e entregas](doc:e-mails-notificacoes-e-entregas).",
      "line": 145
    },
    {
      "id": "d-023-jornada-fixa-pausas-e-alteracao-somente-por-aditivo",
      "level": 3,
      "title": "D-023 — Jornada fixa, pausas e alteração somente por aditivo",
      "text": "- **Status:** definido. - **Decisão:** a solicitação define uma jornada semanal por carga horária em cada dia, sem registrar horários de entrada ou saída. Essa jornada permanece fixa durante a execução. Pausas são registradas normalmente no formulário: suspendem o cômputo e alteram a previsão de término, mas nunca distribuem ou modificam horas. Quando uma pausa não prevista precisar ter seus efeitos formalizados no instrumento do estágio, o Setor de Estágio gera um aditivo, conforme a análise do caso. Qualquer alteração de carga horária exige um documento de aditivo; somente depois de suas assinaturas serem conferidas pelo Setor o sistema encerra a vigência anterior, cria a nova e recalcula a previsão. Não há alteração temporária de carga horária como funcionalidade independente. - **Motivo:** mantém o cálculo simples e rastreável, separa interrupção de execução de mudança contratual e impede que um ajuste informal reescreva a base de documentos ou de cálculos anteriores. - **Referências:** [Migration 23 — internship_work_schedules](doc:migration-23-internship-work-schedules), [Migration 22A — internship_calendar_overrides](doc:migration-22-internship-calendar-overrides), [Service — InternshipEndDateCalculator](doc:service-internshipenddatecalculator) e [Fluxos principais](doc:fluxos-principais#4-estagio-em-andamento).",
      "line": 152
    }
  ],
  "sourcePath": "content/backlog-e-decisoes.md",
  "visuals": [],
  "apiVersion": 1
}