{ "id": "guia-completo", "title": "Guia completo do SGE", "description": "Referência única do Sistema de Gestão de Estágios, preparada para leitura contínua e exportação em PDF.", "type": "user-guide", "status": "defined", "visibility": "public", "tags": [ "sge/guia", "sge/produto", "sge/pdf" ], "related": [ "home", "visao-geral", "pessoas-e-responsabilidades", "fluxos-principais", "ciclos-de-status", "glossario", "planejamento", "arquitetura-atual" ], "sourceRefs": [ "https://github.com/sge-suite/sge/blob/master/routes/web.php", "https://github.com/sge-suite/sge/blob/master/routes/settings.php", "https://github.com/sge-suite/sge/blob/master/config/fortify.php", "https://github.com/sge-suite/sge/blob/master/composer.json" ], "authors": [], "updated": null, "diagram": "guia-completo-jornada", "body": "> [!abstract] Leitura única\n> Esta é a versão consolidada da documentação do SGE. Ela foi escrita para leitura contínua e impressão em PDF: contém apenas um diagrama compacto, sem Canvas ou mapas grandes. As páginas vinculadas ao final aprofundam cada assunto quando necessário.\n\n> [!info] Estado do produto\n> Este guia combina o comportamento definido para o SGE com o estado atual do código. Uma regra marcada como **definida** é parte do produto planejado, mas pode ainda não estar disponível em uma tela. O estado detalhado aparece em [Planejamento](doc:planejamento).\n\n## 1. O que é o SGE\n\nO Sistema de Gestão de Estágios (SGE) centraliza a solicitação, a formalização, o acompanhamento e a conclusão de estágios. Ele reduz a dependência de formulários dispersos, e-mails e planilhas, deixando claro o que falta, quem precisa agir e qual informação está válida para cada processo.\n\nO sistema trabalha com uma conta por pessoa e, quando aplicável, com um **vínculo** institucional. O vínculo informa a atuação da pessoa — por exemplo, discente, orientador ou integrante do Setor de Estágio — e limita o campus, o curso e as ações disponíveis naquele contexto.\n\n## 2. Como interpretar este guia\n\n| Marca | Significado |\n| --- | --- |\n| **Implementado** | O artefato já existe no código atual; ainda pode faltar integração com o domínio. |\n| **Definido** | A regra foi aprovada para o produto, mas sua implementação completa ainda está pendente. |\n| **Planejado** | O trabalho ainda não começou ou depende de decisão anterior. |\n\nNo estado atual, login, recuperação de senha, dashboard, seleção e troca de vínculo, configurações próprias de senha/e-mail e o comando `admin:create` estão disponíveis. O Administrador do Sistema também tem páginas para gerir campi e contas/vínculos administrativos, consultar alterações de auditoria e ver o histórico de e-mails associados a contas e vínculos administrativos, inclusive o conteúdo salvo e as tentativas. Essas consultas exigem o vínculo ativo e selecionado e respeitam escopos próprios; a auditoria exclui estágios, documentos, concedentes e demais registros fora do escopo. O painel global apresenta totais de usuários, vínculos e campi e gráficos textuais por status de estágios, documentos e solicitações. A administração de contas permite editar nome, CPF e e-mail de login, administrar os vínculos administrativos e encerrá-los com os avisos e proteções previstos. A listagem de Usuários mostra contas com vínculo administrativo; o contador do painel considera todas as linhas da tabela `users`. As jornadas completas de solicitação, documentação, execução, avaliação e conclusão ainda não estão disponíveis. Consulte [Fase 03 — Activity Log](doc:fase-03-activity-log) e [Fase 04 — Integração de e-mail](doc:fase-04-integracao-de-email).\n\n## 3. Quem participa\n\n| Pessoa ou setor | Responsabilidade principal | Limite importante |\n| --- | --- | --- |\n| Discente | Inicia a solicitação, responde correções e acompanha o próprio estágio. | Não aprova a própria solicitação nem confirma assinaturas. |\n| Setor de Estágio | Analisa processos, formaliza, confere assinaturas, libera o estágio e trata pendências. | Não reescreve respostas do discente ou do supervisor. |\n| Supervisor | Acompanha o discente no local de estágio e preenche a avaliação quando liberada. | Não aprova a própria avaliação nem lança notas acadêmicas. |\n| Orientador | Acompanha a dimensão acadêmica e registra as notas sob sua responsabilidade. | Não substitui o supervisor na avaliação nem conduz a formalização. |\n| Coordenador de curso | Consulta o acompanhamento do curso e emite o atestado de orientação previsto. | Não herda as tarefas operacionais do Setor de Estágio. |\n| Administrador do Campus | Mantém cadastros e dados administrativos do próprio campus. | Não administra outros campi. |\n| Administrador do Sistema | Mantém a estrutura institucional geral. | Não passa a operar estágios por ter esse vínculo. |\n| Direção de Ensino | Consulta informações institucionais quando autorizada. | O escopo de relatórios ainda depende de definição institucional. |\n\n## 4. Jornada do estágio\n\n{{diagram:guia-completo-jornada}}\n\nO fluxo completo admite correções sem criar outro processo: quando uma solicitação ou avaliação é devolvida, a mesma pessoa corrige e reenvia o mesmo registro. A decisão continua com o Setor de Estágio e o histórico preserva as alterações relevantes.\n\n### 4.1 Solicitação e análise\n\nO discente inicia a solicitação, pode salvá-la como rascunho e a envia quando os dados obrigatórios estiverem completos. O Setor de Estágio pode aceitar, recusar ou devolver a solicitação com orientação sobre o que precisa ser corrigido.\n\nAntes do aceite, o processo valida os dados do estágio, da parte concedente, do supervisor, do curso, da jornada e, quando aplicável, da capacidade civil e do responsável legal. Um discente pode desistir antes de existir um estágio formalizado.\n\n### 4.2 Formalização\n\nDepois do aceite, o estágio nasce em formalização. O Setor prepara o documento aplicável, informa onde ele estará disponível para assinatura e seleciona os participantes que precisam ser avisados. A assinatura ocorre fora do SGE e precisa ser conferida antes da liberação.\n\nO SGE registra o processo e suas referências, mas não guarda o arquivo DOCX/PDF final ou o documento assinado. Templates, versões, dados resolvidos e histórico são tratados separadamente para preservar rastreabilidade sem duplicar acervo documental externo.\n\n### 4.3 Execução, mudanças e encerramento\n\nApós a liberação, o estágio inicia na data planejada. Pausas suspendem o cômputo da carga horária e atualizam a previsão de término; mudanças de jornada exigem aditivo formalizado. Cancelamentos exigem motivo, decisão do Setor e preservação do histórico.\n\nO supervisor preenche a avaliação quando ela for liberada e o orientador registra as notas acadêmicas. A conclusão do estágio depende da confirmação de que a carga horária integral foi cumprida; a data prevista, as avaliações e as notas não concluem o estágio sozinhas.\n\n## 5. Situações exibidas no processo\n\n### Solicitação de estágio\n\n| Situação | O que significa |\n| --- | --- |\n| Rascunho | O discente ainda está preenchendo e não enviou. |\n| Enviada | A solicitação aguarda análise. |\n| Em análise | O Setor de Estágio está conferindo as informações. |\n| Com pendência | Há uma correção para o discente responder. |\n| Aceita | O processo segue para formalização. |\n| Recusada | O processo foi encerrado antes da formalização. |\n| Desistida | O discente encerrou a solicitação antes da criação do estágio. |\n\n### Estágio\n\n| Situação | O que significa |\n| --- | --- |\n| Em formalização | O estágio foi criado e os documentos estão sendo preparados. |\n| Aguardando assinaturas | Os documentos aguardam conclusão e conferência das assinaturas. |\n| Com pendência documental | Alguma informação ou documento precisa ser corrigido. |\n| Liberado | As assinaturas foram conferidas; o estágio aguarda ou alcançou o início. |\n| Em andamento | O estágio está em execução. |\n| Pausado | Há uma pausa válida no período. |\n| Concluído | A carga horária integral foi confirmada. |\n| Cancelado | O processo terminou sem conclusão. |\n\n### Documentos e avaliação\n\n| Área | Situações | Regra central |\n| --- | --- | --- |\n| Documento | Gerado, aguardando assinatura, assinado, cancelado. | Cancelar um documento não cancela automaticamente o estágio. |\n| Avaliação do supervisor | Rascunho, enviada, devolvida, aprovada, cancelada. | A aprovação exige carga horária cumprida e não conclui o estágio por si só. |\n\n## 6. Regras de dados, segurança e privacidade\n\n- Cada ação é autorizada pelo vínculo ativo, pelo escopo institucional, pela relação com o registro e pela situação do fluxo.\n- Dados sensíveis, como CPF, dados de responsável legal e comprovantes de emancipação, têm acesso restrito e não devem aparecer em avisos gerais, e-mails, documentos gerados ou logs detalhados.\n- Alterações relevantes preservam histórico. Dados usados em um estágio podem ser congelados em snapshots para que uma mudança posterior de cadastro não altere o processo já formalizado.\n- Recuperação de senha usa o fluxo do Fortify. Tokens, URLs assinadas, senhas e credenciais nunca devem ser preservados em conteúdo, logs ou auditoria.\n- Não há confirmação adicional de endereço de e-mail no escopo atual.\n- Notificação dentro do sistema e envio de e-mail são trilhas separadas: uma falha de entrega não pode ocultar o aviso no SGE.\n\n## 7. Estado atual e próximos blocos de trabalho\n\n| Área | Estado | Próximo resultado esperado |\n| --- | --- | --- |\n| Preparação do projeto | **Concluída** | Manter ambiente, qualidade e fluxo de revisão. |\n| Conta e autenticação | **Implementada parcialmente** | Contexto, `admin:create`, administração de contas/vínculos administrativos, alteração própria de senha/e-mail e avisos existem; edição própria do perfil pessoal ainda falta. |\n| Fundação técnica | **Implementada parcialmente** | Models e migrations de domínio existem; completar autorizações, Actions transacionais e integração das jornadas. |\n| E-mails e documentos | **Implementada parcialmente** | Pipeline em fila e avisos de conta, vínculo e e-mail estão integrados; notificações operacionais de domínio, telas administrativas, geração e assinatura ainda faltam. |\n| Domínio de estágios | **Base de dados implementada; fluxos pendentes** | Entidades e estados existem no backend; implementar jornadas, decisões e interfaces. |\n\nA sequência é: 00 — preparação; 01 — fundação de dados; 02 — conta e contexto; 03 — Activity Log; 04 — integração de e-mail; 05 — administração; 06 — documentos; 07 — abertura do estágio; 08 — estágio em andamento; e 09 — avaliação e conclusão. As Fases 02–04 têm implementação parcial ou completa, com lacunas específicas descritas em seus checklists; as interfaces de domínio e fluxos operacionais ainda são as próximas entregas.\n\n## 8. Referência técnica resumida\n\nO projeto atual usa Laravel 13, PHP `^8.3` (ambiente atual: PHP 8.5), Livewire 4, Flux UI, Tailwind CSS, Vite, PostgreSQL, Laravel Fortify, Spatie Activitylog, Spatie Medialibrary, Laravel Scout e Meilisearch. A aplicação já possui autenticação, rotas protegidas, configurações de perfil e segurança, filas, cache, auditoria e infraestrutura de mídia.\n\nA base de Models e migrations do domínio de estágio já existe, assim como Policies para campi e para a administração de contas/vínculos administrativos. Há transporte de e-mail em fila, telas globais de campi e usuários e painel global do Administrador do Sistema. Ainda faltam a interface local, outros cadastros administrativos, autorizações e Actions para várias jornadas, geração documental e comandos agendados do domínio. O projeto já tem comandos Artisan de bootstrap e importação; `routes/console.php` ainda não agenda tarefas de domínio.\n\n## 9. Onde aprofundar\n\n- [Visão geral](doc:visao-geral) — objetivo e escopo do produto.\n- [Pessoas e responsabilidades](doc:pessoas-e-responsabilidades) — explicação completa dos papéis.\n- [Fluxos principais](doc:fluxos-principais) — jornada com todos os cenários.\n- [Ciclos de status](doc:ciclos-de-status) — transições e significados detalhados.\n- [Glossário](doc:glossario) — termos usados pelo SGE.\n- [Planejamento](doc:planejamento) — estado dos blocos de trabalho.\n- [Arquitetura atual](doc:arquitetura-atual) — tecnologias, infraestrutura e limites do código existente.", "sections": [ { "id": "1-o-que-e-o-sge", "level": 2, "title": "1. O que é o SGE", "text": "O Sistema de Gestão de Estágios (SGE) centraliza a solicitação, a formalização, o acompanhamento e a conclusão de estágios. Ele reduz a dependência de formulários dispersos, e-mails e planilhas, deixando claro o que falta, quem precisa agir e qual informação está válida para cada processo. O sistema trabalha com uma conta por pessoa e, quando aplicável, com um **vínculo** institucional. O vínculo informa a atuação da pessoa — por exemplo, discente, orientador ou integrante do Setor de Estágio — e limita o campus, o curso e as ações disponíveis naquele contexto.", "line": 7 }, { "id": "2-como-interpretar-este-guia", "level": 2, "title": "2. Como interpretar este guia", "text": "| Marca | Significado | | --- | --- | | **Implementado** | O artefato já existe no código atual; ainda pode faltar integração com o domínio. | | **Definido** | A regra foi aprovada para o produto, mas sua implementação completa ainda está pendente. | | **Planejado** | O trabalho ainda não começou ou depende de decisão anterior. | No estado atual, login, recuperação de senha, dashboard, seleção e troca de vínculo, configurações próprias de senha/e-mail e o comando `admin:create` estão disponíveis. O Administrador do Sistema também tem páginas para gerir campi e contas/vínculos administrativos, consultar alterações de auditoria e ver o histórico de e-mails associados a contas e vínculos administrativos, inclusive o conteúdo salvo e as tentativas. Essas consultas exigem o vínculo ativo e selecionado e respeitam escopos próprios; a auditoria exclui estágios, documentos, concedentes e demais registros fora do escopo. O painel global apresenta totais de usuários, vínculos e campi e gráficos textuais por status de estágios, documentos e solicitações. A administração de contas permite editar nome, CPF e e-mail de login, administrar os vínculos administrativos e encerrá-los com os avisos e proteções previstos. A listagem de Usuários mostra contas com vínculo administrativo; o contador do painel considera todas as linhas da tabela `users`. As jornadas completas de solicitação, documentação, execução, avaliação e conclusão ainda não estão disponíveis. Consulte [Fase 03 — Activity Log](doc:fase-03-activity-log) e [Fase 04 — Integração de e-mail](doc:fase-04-integracao-de-email).", "line": 13 }, { "id": "3-quem-participa", "level": 2, "title": "3. Quem participa", "text": "| Pessoa ou setor | Responsabilidade principal | Limite importante | | --- | --- | --- | | Discente | Inicia a solicitação, responde correções e acompanha o próprio estágio. | Não aprova a própria solicitação nem confirma assinaturas. | | Setor de Estágio | Analisa processos, formaliza, confere assinaturas, libera o estágio e trata pendências. | Não reescreve respostas do discente ou do supervisor. | | Supervisor | Acompanha o discente no local de estágio e preenche a avaliação quando liberada. | Não aprova a própria avaliação nem lança notas acadêmicas. | | Orientador | Acompanha a dimensão acadêmica e registra as notas sob sua responsabilidade. | Não substitui o supervisor na avaliação nem conduz a formalização. | | Coordenador de curso | Consulta o acompanhamento do curso e emite o atestado de orientação previsto. | Não herda as tarefas operacionais do Setor de Estágio. | | Administrador do Campus | Mantém cadastros e dados administrativos do próprio campus. | Não administra outros campi. | | Administrador do Sistema | Mantém a estrutura institucional geral. | Não passa a operar estágios por ter esse vínculo. | | Direção de Ensino | Consulta informações institucionais quando autorizada. | O escopo de relatórios ainda depende de definição institucional. |", "line": 23 }, { "id": "4-jornada-do-estagio", "level": 2, "title": "4. Jornada do estágio", "text": "O fluxo completo admite correções sem criar outro processo: quando uma solicitação ou avaliação é devolvida, a mesma pessoa corrige e reenvia o mesmo registro. A decisão continua com o Setor de Estágio e o histórico preserva as alterações relevantes.", "line": 36 }, { "id": "4-1-solicitacao-e-analise", "level": 3, "title": "4.1 Solicitação e análise", "text": "O discente inicia a solicitação, pode salvá-la como rascunho e a envia quando os dados obrigatórios estiverem completos. O Setor de Estágio pode aceitar, recusar ou devolver a solicitação com orientação sobre o que precisa ser corrigido. Antes do aceite, o processo valida os dados do estágio, da parte concedente, do supervisor, do curso, da jornada e, quando aplicável, da capacidade civil e do responsável legal. Um discente pode desistir antes de existir um estágio formalizado.", "line": 42 }, { "id": "4-2-formalizacao", "level": 3, "title": "4.2 Formalização", "text": "Depois do aceite, o estágio nasce em formalização. O Setor prepara o documento aplicável, informa onde ele estará disponível para assinatura e seleciona os participantes que precisam ser avisados. A assinatura ocorre fora do SGE e precisa ser conferida antes da liberação. O SGE registra o processo e suas referências, mas não guarda o arquivo DOCX/PDF final ou o documento assinado. Templates, versões, dados resolvidos e histórico são tratados separadamente para preservar rastreabilidade sem duplicar acervo documental externo.", "line": 48 }, { "id": "4-3-execucao-mudancas-e-encerramento", "level": 3, "title": "4.3 Execução, mudanças e encerramento", "text": "Após a liberação, o estágio inicia na data planejada. Pausas suspendem o cômputo da carga horária e atualizam a previsão de término; mudanças de jornada exigem aditivo formalizado. Cancelamentos exigem motivo, decisão do Setor e preservação do histórico. O supervisor preenche a avaliação quando ela for liberada e o orientador registra as notas acadêmicas. A conclusão do estágio depende da confirmação de que a carga horária integral foi cumprida; a data prevista, as avaliações e as notas não concluem o estágio sozinhas.", "line": 54 }, { "id": "5-situacoes-exibidas-no-processo", "level": 2, "title": "5. Situações exibidas no processo", "text": "", "line": 60 }, { "id": "solicitacao-de-estagio", "level": 3, "title": "Solicitação de estágio", "text": "| Situação | O que significa | | --- | --- | | Rascunho | O discente ainda está preenchendo e não enviou. | | Enviada | A solicitação aguarda análise. | | Em análise | O Setor de Estágio está conferindo as informações. | | Com pendência | Há uma correção para o discente responder. | | Aceita | O processo segue para formalização. | | Recusada | O processo foi encerrado antes da formalização. | | Desistida | O discente encerrou a solicitação antes da criação do estágio. |", "line": 62 }, { "id": "estagio", "level": 3, "title": "Estágio", "text": "| Situação | O que significa | | --- | --- | | Em formalização | O estágio foi criado e os documentos estão sendo preparados. | | Aguardando assinaturas | Os documentos aguardam conclusão e conferência das assinaturas. | | Com pendência documental | Alguma informação ou documento precisa ser corrigido. | | Liberado | As assinaturas foram conferidas; o estágio aguarda ou alcançou o início. | | Em andamento | O estágio está em execução. | | Pausado | Há uma pausa válida no período. | | Concluído | A carga horária integral foi confirmada. | | Cancelado | O processo terminou sem conclusão. |", "line": 74 }, { "id": "documentos-e-avaliacao", "level": 3, "title": "Documentos e avaliação", "text": "| Área | Situações | Regra central | | --- | --- | --- | | Documento | Gerado, aguardando assinatura, assinado, cancelado. | Cancelar um documento não cancela automaticamente o estágio. | | Avaliação do supervisor | Rascunho, enviada, devolvida, aprovada, cancelada. | A aprovação exige carga horária cumprida e não conclui o estágio por si só. |", "line": 87 }, { "id": "6-regras-de-dados-seguranca-e-privacidade", "level": 2, "title": "6. Regras de dados, segurança e privacidade", "text": "- Cada ação é autorizada pelo vínculo ativo, pelo escopo institucional, pela relação com o registro e pela situação do fluxo. - Dados sensíveis, como CPF, dados de responsável legal e comprovantes de emancipação, têm acesso restrito e não devem aparecer em avisos gerais, e-mails, documentos gerados ou logs detalhados. - Alterações relevantes preservam histórico. Dados usados em um estágio podem ser congelados em snapshots para que uma mudança posterior de cadastro não altere o processo já formalizado. - Recuperação de senha usa o fluxo do Fortify. Tokens, URLs assinadas, senhas e credenciais nunca devem ser preservados em conteúdo, logs ou auditoria. - Não há confirmação adicional de endereço de e-mail no escopo atual. - Notificação dentro do sistema e envio de e-mail são trilhas separadas: uma falha de entrega não pode ocultar o aviso no SGE.", "line": 94 }, { "id": "7-estado-atual-e-proximos-blocos-de-trabalho", "level": 2, "title": "7. Estado atual e próximos blocos de trabalho", "text": "| Área | Estado | Próximo resultado esperado | | --- | --- | --- | | Preparação do projeto | **Concluída** | Manter ambiente, qualidade e fluxo de revisão. | | Conta e autenticação | **Implementada parcialmente** | Contexto, `admin:create`, administração de contas/vínculos administrativos, alteração própria de senha/e-mail e avisos existem; edição própria do perfil pessoal ainda falta. | | Fundação técnica | **Implementada parcialmente** | Models e migrations de domínio existem; completar autorizações, Actions transacionais e integração das jornadas. | | E-mails e documentos | **Implementada parcialmente** | Pipeline em fila e avisos de conta, vínculo e e-mail estão integrados; notificações operacionais de domínio, telas administrativas, geração e assinatura ainda faltam. | | Domínio de estágios | **Base de dados implementada; fluxos pendentes** | Entidades e estados existem no backend; implementar jornadas, decisões e interfaces. | A sequência é: 00 — preparação; 01 — fundação de dados; 02 — conta e contexto; 03 — Activity Log; 04 — integração de e-mail; 05 — administração; 06 — documentos; 07 — abertura do estágio; 08 — estágio em andamento; e 09 — avaliação e conclusão. As Fases 02–04 têm implementação parcial ou completa, com lacunas específicas descritas em seus checklists; as interfaces de domínio e fluxos operacionais ainda são as próximas entregas.", "line": 103 }, { "id": "8-referencia-tecnica-resumida", "level": 2, "title": "8. Referência técnica resumida", "text": "O projeto atual usa Laravel 13, PHP `^8.3` (ambiente atual: PHP 8.5), Livewire 4, Flux UI, Tailwind CSS, Vite, PostgreSQL, Laravel Fortify, Spatie Activitylog, Spatie Medialibrary, Laravel Scout e Meilisearch. A aplicação já possui autenticação, rotas protegidas, configurações de perfil e segurança, filas, cache, auditoria e infraestrutura de mídia. A base de Models e migrations do domínio de estágio já existe, assim como Policies para campi e para a administração de contas/vínculos administrativos. Há transporte de e-mail em fila, telas globais de campi e usuários e painel global do Administrador do Sistema. Ainda faltam a interface local, outros cadastros administrativos, autorizações e Actions para várias jornadas, geração documental e comandos agendados do domínio. O projeto já tem comandos Artisan de bootstrap e importação; `routes/console.php` ainda não agenda tarefas de domínio.", "line": 115 }, { "id": "9-onde-aprofundar", "level": 2, "title": "9. Onde aprofundar", "text": "- [Visão geral](doc:visao-geral) — objetivo e escopo do produto. - [Pessoas e responsabilidades](doc:pessoas-e-responsabilidades) — explicação completa dos papéis. - [Fluxos principais](doc:fluxos-principais) — jornada com todos os cenários. - [Ciclos de status](doc:ciclos-de-status) — transições e significados detalhados. - [Glossário](doc:glossario) — termos usados pelo SGE. - [Planejamento](doc:planejamento) — estado dos blocos de trabalho. - [Arquitetura atual](doc:arquitetura-atual) — tecnologias, infraestrutura e limites do código existente.", "line": 121 } ], "sourcePath": "content/guia-completo.md", "visuals": [ { "id": "guia-completo-jornada", "kind": "flowchart", "title": "Jornada resumida do estágio", "description": "Visão compacta da solicitação, formalização, execução e conclusão do estágio.", "summary": "O processo começa com solicitação e análise, segue para formalização e assinaturas, e termina com a execução e a confirmação da carga horária cumprida.", "renderMode": "svg", "api": "api/diagrams/guia-completo-jornada.json", "human": "diagrams/guia-completo-jornada.html" } ], "apiVersion": 1 }