{
  "id": "services",
  "title": "Services",
  "description": "Índice dos serviços de domínio planejados para cálculos, documentos, snapshots e transições.",
  "type": "technical-hub",
  "status": "planned",
  "visibility": "public",
  "tags": [
    "sge/desenvolvimento",
    "sge/services",
    "sge/arquitetura"
  ],
  "related": [
    "service-internshipenddatecalculator",
    "service-internshipgradecalculator",
    "geracao-de-documentos-docx-e-variaveis"
  ],
  "sourceRefs": [],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "Services concentram regras que combinam dados, mas não representam por si só um caso de uso com autorização e efeitos colaterais. Actions orquestram transações, Policies autorizam e Jobs executam trabalho assíncrono.\n\n## Inventário planejado\n\n| Serviço | Contrato |\n| --- | --- |\n| [`InternshipEndDateCalculator`](doc:service-internshipenddatecalculator) | previsão reproduzível de término. |\n| [`InternshipGradeCalculator`](doc:service-internshipgradecalculator) | nota do supervisor e soma consolidada. |\n| `InternshipSnapshotBuilder` | cria snapshots tipados no aceite sem buscar dados atuais depois. |\n| `InternshipStateTransitionService` | guardas puras de transição do estágio. |\n| `InternshipExecutionStatusResolver` | determina o estado de execução para uma data e uma pausa ativa, sem efeitos colaterais. |\n| `EvaluationStateTransitionService` | guardas de edição, envio, retorno, aprovação e cancelamento. |\n| `RegistrationRequestApprovalService` | associa/cria supervisor ou concedente em transação. |\n| `EmancipationReviewService` | aprova/devolve prova sem expor arquivo no log. |\n| `TemplateVariableCatalog` / `TemplateValidator` | catálogo e validação de DOCX. |\n| `DocumentSnapshotBuilder` / `DocumentVariableResolver` | contexto histórico e valores do documento. |\n| `RemunerationParagraphFormatter` / `DocxDocumentGenerator` | texto jurídico e geração temporária. |\n\nO conjunto documental é detalhado em [Geração de documentos DOCX e variáveis](doc:geracao-de-documentos-docx-e-variaveis). Nenhum desses serviços deve retornar resposta HTTP, ler sessão global ou decidir permissão do usuário.\n\n## Actions correspondentes\n\n- `AcceptInternshipRequest` — valida cadastros/aceite, cria estágio com snapshots e jornada inicial em uma transação;\n- `RecalculateProjectedEndDate` — bloqueia o estágio, calcula, persiste resultado/base e registra auditoria;\n- `ApproveSupervisorEvaluation` — valida carga, escolhe avaliação vigente e recalcula notas;\n- `UpdateAdvisorGrades` — autoriza o orientador e recalcula a nota consolidada;\n- `GenerateInternshipDocument` — gera e registra documento de forma idempotente;\n- `ReviewInternshipCancellationRequest` — decide, aplica efeitos e inicia a rescisão documental.\n- `SynchronizeInternshipExecutionStatus` — bloqueia o estágio, aplica a transição temporal válida, audita e notifica sem duplicar eventos;\n- `NotifyProjectedInternshipEnd` — cria o único lembrete de sete dias para o discente e o resumo interno diário do Setor, de forma idempotente;\n- `NotifySignatureAvailability` — valida os interessados selecionados, cria os avisos internos/externos adequados e despacha e-mail após o commit.\n\n## Regra de teste\n\nServices puros recebem DTOs/objetos de valor e têm testes unitários sem banco quando possível. Actions têm testes de feature cobrindo transação, concorrência, autorização, Activity Log, notificações e rollback.",
  "sections": [
    {
      "id": "inventario-planejado",
      "level": 2,
      "title": "Inventário planejado",
      "text": "| Serviço | Contrato | | --- | --- | | [`InternshipEndDateCalculator`](doc:service-internshipenddatecalculator) | previsão reproduzível de término. | | [`InternshipGradeCalculator`](doc:service-internshipgradecalculator) | nota do supervisor e soma consolidada. | | `InternshipSnapshotBuilder` | cria snapshots tipados no aceite sem buscar dados atuais depois. | | `InternshipStateTransitionService` | guardas puras de transição do estágio. | | `InternshipExecutionStatusResolver` | determina o estado de execução para uma data e uma pausa ativa, sem efeitos colaterais. | | `EvaluationStateTransitionService` | guardas de edição, envio, retorno, aprovação e cancelamento. | | `RegistrationRequestApprovalService` | associa/cria supervisor ou concedente em transação. | | `EmancipationReviewService` | aprova/devolve prova sem expor arquivo no log. | | `TemplateVariableCatalog` / `TemplateValidator` | catálogo e validação de DOCX. | | `DocumentSnapshotBuilder` / `DocumentVariableResolver` | contexto histórico e valores do documento. | | `RemunerationParagraphFormatter` / `DocxDocumentGenerator` | texto jurídico e geração temporária. |  O conjunto documental é detalhado em [Geração de documentos DOCX e variáveis](doc:geracao-de-documentos-docx-e-variaveis). Nenhum desses serviços deve retornar resposta HTTP, ler sessão global ou decidir permissão do usuário.",
      "line": 3
    },
    {
      "id": "actions-correspondentes",
      "level": 2,
      "title": "Actions correspondentes",
      "text": "- `AcceptInternshipRequest` — valida cadastros/aceite, cria estágio com snapshots e jornada inicial em uma transação; - `RecalculateProjectedEndDate` — bloqueia o estágio, calcula, persiste resultado/base e registra auditoria; - `ApproveSupervisorEvaluation` — valida carga, escolhe avaliação vigente e recalcula notas; - `UpdateAdvisorGrades` — autoriza o orientador e recalcula a nota consolidada; - `GenerateInternshipDocument` — gera e registra documento de forma idempotente; - `ReviewInternshipCancellationRequest` — decide, aplica efeitos e inicia a rescisão documental. - `SynchronizeInternshipExecutionStatus` — bloqueia o estágio, aplica a transição temporal válida, audita e notifica sem duplicar eventos; - `NotifyProjectedInternshipEnd` — cria o único lembrete de sete dias para o discente e o resumo interno diário do Setor, de forma idempotente; - `NotifySignatureAvailability` — valida os interessados selecionados, cria os avisos internos/externos adequados e despacha e-mail após o commit.",
      "line": 21
    },
    {
      "id": "regra-de-teste",
      "level": 2,
      "title": "Regra de teste",
      "text": "Services puros recebem DTOs/objetos de valor e têm testes unitários sem banco quando possível. Actions têm testes de feature cobrindo transação, concorrência, autorização, Activity Log, notificações e rollback.",
      "line": 33
    }
  ],
  "sourcePath": "content/services.md",
  "visuals": [],
  "apiVersion": 1
}