technical-reference · planned
Service — InternshipEndDateCalculator
Contrato técnico do cálculo automático da previsão de término.
Serviço puro, sem Eloquent e sem relógio global. Recebe um DTO com data inicial, carga exigida, jornada inicial de internships.weekly_hours, eventuais vigências criadas por aditivos formalizados, pausas, feriados e margem. Retorna ProjectedEndDateResult com data de conclusão da carga, data final projetada e horas creditadas. Somente a data final projetada é persistida em internships.projected_end_date; o estágio não guarda fórmula, versão de algoritmo nem JSONB das entradas.
Invariantes
- datas são
CarbonImmutableno timezone institucional; - as sete chaves da jornada existem e seus valores são inteiros;
- vigências e pausas não se sobrepõem dentro do mesmo conjunto;
- cada data usa no máximo uma jornada vigente;
- o último dia credita
min(jornada_do_dia, horas_restantes); - margem é contada em dias corridos; após a margem, a data avança até um dia programado não bloqueado;
- máximo defensivo de dez anos de iteração, configurável apenas em teste.
O calendário de feriados nacional, estadual e municipal versionado, aplicável à cidade e à UF do endereço histórico do local de trabalho, é carregado antes da chamada; o serviço não consulta API. A fonte externa, quando usada, serve somente à importação administrativa do calendário, nunca durante o cálculo. O serviço usa os feriados, pausas e exceções aplicáveis ao intervalo; o resultado persistido no estágio é a data projetada. Mudanças autorizadas da previsão são registradas no Activity Log.
Recalculo
Criação do estágio, nova pausa, alteração/cancelamento de pausa, ativação de jornada vinculada a aditivo com assinaturas conferidas e correção da data inicial disparam RecalculateProjectedEndDate. A Action usa lock pessimista, recalcula dentro da transação e registra as datas anterior e nova no Activity Log. Não há alteração temporária ou direta de jornada fora desse fluxo de aditivo.