Backlog e decisões

Próximas definições

• Confirmar perfis oficiais e responsabilidades.
• ✓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.

Decisões registradas

D-001 — Documentação versionada em Markdown com Mermaid

• 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.

D-002 — Papéis separados de vínculos

• 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.

D-004 — Dados pessoais fora de internships

• 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.

D-005 — Configurações pessoais por tipo de vínculo

• 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.

D-006 — Canvas espacial para diagramas Mermaid

• 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.

D-007 — Canvas do fluxograma com cards padronizados

• 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.

D-008 — Trilhas separadas para notificações e e-mails

• 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.

D-009 — Ciclo e validade da avaliação do supervisor

• 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, Migration de avaliações e fluxo de avaliação.

D-010 — Templates DOCX versionados e saída sem arquivo final

• 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, Migration 14 — template_versions e Migration 16 — generated_documents.

D-011 — Solicitações pendentes são registros próprios

• 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.

D-012 — Identificação e escopo de partes concedentes

• 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 e Glossário.

D-013 — Controle de acesso por vínculos e remoção das tabelas de permissão

• 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 e Matriz de autorização.

D-014 — Pesos e conceitos pertencem ao tipo de estágio

• 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, Migration 15 — internships e Migration 18 — supervisor_evaluations.

D-015 — Solicitação única e correções orientadas

• 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, Migration 20 — internship_request_corrections, Migration base 04 — activity_log e Fluxos principais.

D-016 — Parágrafo de remuneração gerado no documento

• 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, Migration 13 — document_templates, Migration 16 — generated_documents e Helper — NumberToWordsHelper.

D-017 — Cancelamento solicitado pelo discente

• 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, Fluxos principais e Migration base 04 — activity_log.

D-018 — Emancipação exige comprovação e validação institucional

• 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 e Migration 19 — internship_requests.

D-019 — Previsão de término reproduzível

• 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, Migration 22 — holidays e Migration 23 — internship_work_schedules.

D-020 — Motor DOCX local e catálogo canônico

• 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.

D-021 — Reconciliação temporal por schedules idempotentes

• 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, Ciclos de status e E-mails, notificações e entregas.

D-022 — Avisos de assinatura e término por canal adequado

• 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, Schedules e E-mails, notificações e entregas.

D-023 — Jornada fixa, pausas e alteração somente por aditivo

• 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, Migration 22A — internship_calendar_overrides, Service — InternshipEndDateCalculator e Fluxos principais.