{
  "id": "enum-evaluationstatus",
  "title": "Enum — EvaluationStatus",
  "description": "Ciclo persistido das respostas de avaliação enviadas pelo supervisor.",
  "type": "enum-reference",
  "status": "implemented",
  "visibility": "public",
  "tags": [
    "sge/enums",
    "sge/avaliacao"
  ],
  "related": [
    "migration-18-supervisor-evaluations",
    "fase-09-avaliacao-e-conclusao",
    "backlog-e-decisoes",
    "fluxos-principais"
  ],
  "sourceRefs": [
    "https://github.com/sge-suite/sge/blob/master/app/Enums/EvaluationStatus.php",
    "https://github.com/sge-suite/sge/blob/master/tests/Unit/Enums/EvaluationStatusTest.php"
  ],
  "authors": [],
  "updated": null,
  "diagram": "enum-evaluation-status",
  "body": "> [!success] Estado\n> O enum, a migration, o Model e os testes de estados já existem. A liberação funcional e as Policies ainda estão planejadas. A validade para nota depende da carga horária.\n\n## Contrato implementado\n\n| Case        | Valor persistido | Uso                                                                |\n| ----------- | ---------------- | ------------------------------------------------------------------ |\n| `Draft`     | `draft`          | Resposta editável, salva pelo supervisor e ainda não enviada.      |\n| `Submitted` | `submitted`      | Resposta enviada, congelada e aguardando análise.                  |\n| `Returned`  | `returned`       | Envio devolvido com motivo; o mesmo formulário volta a ser editável. |\n| `Approved`  | `approved`       | Envio aceito pelo Setor de Estágio; exige carga horária cumprida.  |\n| `Cancelled` | `cancelled`      | Registro preservado, encerrado sem aprovação e sem exclusão física. |\n\n## Transições\n\n{{diagram:enum-evaluation-status}}\n\n- Somente o supervisor vinculado ao estágio pode preencher e salvar o `Draft` ou o `Returned`.\n- `Draft` aceita preenchimento parcial. Nos demais estados, todos os campos obrigatórios para o ramo condicional escolhido devem estar válidos; ramos não selecionados e pareceres opcionais permanecem nulos.\n- Depois da transição para `Submitted`, a resposta fica bloqueada. `Returned` reabre a mesma linha, permitindo ao supervisor editar todos os campos e reenviá-la.\n- A análise pertence ao vínculo `AffiliationType::InternshipOffice`. O vínculo `Coordinator` continua representando o coordenador de curso e não concede essa ação automaticamente. A avaliação não guarda FK do revisor; o Activity Log já registra o vínculo ativo como *causer*. A autorização e a interface do fluxo de revisão ainda estão pendentes.\n- O Setor de Estágio aprova ou devolve, mas não altera as respostas fornecidas pelo supervisor. O supervisor pode cancelar um envio `Submitted` ou `Returned`; o cancelamento exige motivo.\n- Não há exclusão física. Ações, valores anteriores/novos e transições são preservados no `activity_log`, que não é exibido ao supervisor.\n\n## Avaliação vigente\n\nO envio mais recente não substitui imediatamente uma avaliação já vigente. A avaliação considerada para a nota é a resposta `Approved` mais recente, ordenada por `submitted_at` e `id`. O Setor só pode aprovar quando a confirmação de carga horária estiver atendida.\n\n- Um novo `Submitted` permanece apenas como candidato enquanto aguarda análise.\n- Um `Returned` nunca é usado no cálculo.\n- A avaliação vigente deverá ser referenciada por `internships.current_supervisor_evaluation_id` ou mecanismo equivalente com garantia de unicidade.\n- A aprovação da avaliação, isoladamente, não conclui o estágio; a conclusão ocorre quando a carga horária integral é confirmada. Documentos e notas permanecem como registros próprios do processo.\n\n## Liberação e notificação\n\nA liberação para preenchimento pertence ao estágio, não ao enum da resposta. O sistema deverá registrar `evaluation_released_at`, notificar o supervisor vinculado e só então permitir a criação ou edição do rascunho.\n\n## Checklist de decisão e implementação\n\n- [x] Confirmar que a avaliação terá rascunho, envio e devolução no mesmo registro.\n- [x] Confirmar que o supervisor responde e o Setor de Estágio aprova ou devolve.\n- [x] Confirmar que a avaliação vigente será a aprovada mais recente, com aprovação condicionada à carga horária cumprida.\n- [x] Definir pesos e valores dos conceitos no snapshot do tipo de estágio.\n- [x] Mapear critérios, escala e regras condicionais do formulário fixo de avaliação.\n- [x] Criar o enum e seus testes unitários.\n- [x] Criar migration e campos de liberação/avaliação vigente.\n- [x] Adicionar cast, transições no Model e testes de histórico; autorização e seleção transacional da vigente continuam pendentes.\n- [x] Atualizar [migration de avaliação](doc:migration-18-supervisor-evaluations) e [fase de avaliação](doc:fase-09-avaliacao-e-conclusao).\n\n## Relacionamentos\n\n- [Decisão D-009](doc:backlog-e-decisoes#d-009-ciclo-e-validade-da-avaliacao-do-supervisor)\n- [Fluxo de avaliação](doc:fluxos-principais#6-acompanhamento-academico-e-conclusao)\n- [Painel de desenvolvimento](doc:painel-de-desenvolvimento)",
  "sections": [
    {
      "id": "contrato-implementado",
      "level": 2,
      "title": "Contrato implementado",
      "text": "| Case        | Valor persistido | Uso                                                                | | ----------- | ---------------- | ------------------------------------------------------------------ | | `Draft`     | `draft`          | Resposta editável, salva pelo supervisor e ainda não enviada.      | | `Submitted` | `submitted`      | Resposta enviada, congelada e aguardando análise.                  | | `Returned`  | `returned`       | Envio devolvido com motivo; o mesmo formulário volta a ser editável. | | `Approved`  | `approved`       | Envio aceito pelo Setor de Estágio; exige carga horária cumprida.  | | `Cancelled` | `cancelled`      | Registro preservado, encerrado sem aprovação e sem exclusão física. |",
      "line": 4
    },
    {
      "id": "transicoes",
      "level": 2,
      "title": "Transições",
      "text": "- Somente o supervisor vinculado ao estágio pode preencher e salvar o `Draft` ou o `Returned`. - `Draft` aceita preenchimento parcial. Nos demais estados, todos os campos obrigatórios para o ramo condicional escolhido devem estar válidos; ramos não selecionados e pareceres opcionais permanecem nulos. - Depois da transição para `Submitted`, a resposta fica bloqueada. `Returned` reabre a mesma linha, permitindo ao supervisor editar todos os campos e reenviá-la. - A análise pertence ao vínculo `AffiliationType::InternshipOffice`. O vínculo `Coordinator` continua representando o coordenador de curso e não concede essa ação automaticamente. A avaliação não guarda FK do revisor; o Activity Log já registra o vínculo ativo como *causer*. A autorização e a interface do fluxo de revisão ainda estão pendentes. - O Setor de Estágio aprova ou devolve, mas não altera as respostas fornecidas pelo supervisor. O supervisor pode cancelar um envio `Submitted` ou `Returned`; o cancelamento exige motivo. - Não há exclusão física. Ações, valores anteriores/novos e transições são preservados no `activity_log`, que não é exibido ao supervisor.",
      "line": 14
    },
    {
      "id": "avaliacao-vigente",
      "level": 2,
      "title": "Avaliação vigente",
      "text": "O envio mais recente não substitui imediatamente uma avaliação já vigente. A avaliação considerada para a nota é a resposta `Approved` mais recente, ordenada por `submitted_at` e `id`. O Setor só pode aprovar quando a confirmação de carga horária estiver atendida.  - Um novo `Submitted` permanece apenas como candidato enquanto aguarda análise. - Um `Returned` nunca é usado no cálculo. - A avaliação vigente deverá ser referenciada por `internships.current_supervisor_evaluation_id` ou mecanismo equivalente com garantia de unicidade. - A aprovação da avaliação, isoladamente, não conclui o estágio; a conclusão ocorre quando a carga horária integral é confirmada. Documentos e notas permanecem como registros próprios do processo.",
      "line": 25
    },
    {
      "id": "liberacao-e-notificacao",
      "level": 2,
      "title": "Liberação e notificação",
      "text": "A liberação para preenchimento pertence ao estágio, não ao enum da resposta. O sistema deverá registrar `evaluation_released_at`, notificar o supervisor vinculado e só então permitir a criação ou edição do rascunho.",
      "line": 34
    },
    {
      "id": "checklist-de-decisao-e-implementacao",
      "level": 2,
      "title": "Checklist de decisão e implementação",
      "text": "- [x] Confirmar que a avaliação terá rascunho, envio e devolução no mesmo registro. - [x] Confirmar que o supervisor responde e o Setor de Estágio aprova ou devolve. - [x] Confirmar que a avaliação vigente será a aprovada mais recente, com aprovação condicionada à carga horária cumprida. - [x] Definir pesos e valores dos conceitos no snapshot do tipo de estágio. - [x] Mapear critérios, escala e regras condicionais do formulário fixo de avaliação. - [x] Criar o enum e seus testes unitários. - [x] Criar migration e campos de liberação/avaliação vigente. - [x] Adicionar cast, transições no Model e testes de histórico; autorização e seleção transacional da vigente continuam pendentes. - [x] Atualizar [migration de avaliação](doc:migration-18-supervisor-evaluations) e [fase de avaliação](doc:fase-09-avaliacao-e-conclusao).",
      "line": 38
    },
    {
      "id": "relacionamentos",
      "level": 2,
      "title": "Relacionamentos",
      "text": "- [Decisão D-009](doc:backlog-e-decisoes#d-009-ciclo-e-validade-da-avaliacao-do-supervisor) - [Fluxo de avaliação](doc:fluxos-principais#6-acompanhamento-academico-e-conclusao) - [Painel de desenvolvimento](doc:painel-de-desenvolvimento)",
      "line": 50
    }
  ],
  "sourcePath": "content/enum-evaluationstatus.md",
  "visuals": [
    {
      "id": "enum-evaluation-status",
      "kind": "state",
      "title": "Ciclo da avaliação do supervisor",
      "description": "Estados persistidos da avaliação, da edição progressiva à aprovação ou cancelamento.",
      "summary": "A avaliação começa em Draft, é enviada como Submitted, pode voltar a Returned para correção e, depois da análise do Setor, termina como Approved ou Cancelled.",
      "renderMode": "mermaid",
      "api": "api/diagrams/enum-evaluation-status.json",
      "human": "diagrams/enum-evaluation-status.html"
    }
  ],
  "apiVersion": 1
}