@hed-hog/lms
v0.0.357
Published
```markdown # @hed-hog/lms
Downloads
4,025
Readme
# @hed-hog/lms
## 1. Visão geral do módulo
O módulo `@hed-hog/lms` é responsável pela gestão do sistema de Learning Management System (LMS) dentro do monorepo HedHog. Ele oferece funcionalidades para gerenciamento de cursos, aulas, avaliações, certificados, matrículas, instrutores, trilhas de aprendizagem e demais componentes relacionados ao ambiente educacional digital.
## 2. Escopo e responsabilidades
- Gerenciamento de cursos, módulos, aulas e suas respectivas estruturas.
- Controle de matrículas em cursos e trilhas de aprendizagem.
- Administração de avaliações, tentativas e respostas.
- Emissão e verificação de certificados.
- Gestão de instrutores e suas atribuições.
- Controle de presenças em aulas presenciais ou online.
- Organização de trilhas de aprendizagem e seus passos.
- Suporte a imagens e arquivos relacionados a cursos, exames e trilhas.
- Avaliações e feedbacks sobre tópicos específicos do LMS.
- Gestão de turmas (class groups), sessões e presença.
- Administração de empresas (enterprises) e seus usuários, cursos, turmas e leads.
- Dashboard com KPIs e estatísticas do LMS.
## 3. Endpoints
### Certificados
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|-------------------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/certificates/templates | Sim | Lista templates de certificados com paginação e filtros. | Query: `page` (número), `pageSize` (número), `search` (string), `status` (draft|active|inactive) | Paginação com lista de templates e seus dados básicos. | Status inválido, parâmetros inválidos |
| GET | /lms/certificates/templates/:id | Sim | Obtém template de certificado pelo ID. | Param: `id` (número) | Dados do template de certificado. | Template não encontrado |
| POST | /lms/certificates/templates | Sim | Cria um novo template de certificado. | Body: `CreateCertificateTemplateDto` | Template criado com dados completos. | JSON inválido em templateContent, slug duplicado |
| PATCH | /lms/certificates/templates/:id | Sim | Atualiza template existente. | Param: `id` (número), Body: `UpdateCertificateTemplateDto` | Template atualizado. | Template não encontrado, JSON inválido |
| DELETE | /lms/certificates/templates/:id | Sim | Remove template de certificado pelo ID. | Param: `id` (número) | `{ success: true }` | Template não encontrado, restrição de exclusão |
| POST | /lms/certificates/templates/background-image | Sim | Upload de imagem de fundo para template. | Form-data: campo `file` (imagem) | Dados do arquivo enviado (id, url, filename, etc). | Arquivo ausente, tipo inválido |
| GET | /lms/certificates/issued | Sim | Lista certificados emitidos com paginação e filtros. | Query: `page`, `pageSize`, `search`, `type` (course|exam|course_class_group|learning_path) | Paginação com lista de certificados emitidos e dados relacionados. | Tipo inválido |
### Turmas (Class Groups)
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|----------------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/classes | Sim | Lista turmas com paginação e filtros. | Query: `page`, `pageSize`, `search`, `status` (open|ongoing|completed|cancelled), `deliveryMode` (presential|online|hybrid), `courseId` | Paginação com lista de turmas e dados resumidos. | Status ou deliveryMode inválidos |
| GET | /lms/classes/stats | Sim | Estatísticas gerais das turmas. | - | Estatísticas como total, vagas abertas, taxa de ocupação, etc. | - |
| GET | /lms/classes/:id | Sim | Obtém turma pelo ID. | Param: `id` (número) | Dados detalhados da turma, incluindo resumo de sessões. | Turma não encontrada |
| POST | /lms/classes | Sim | Cria nova turma. | Body: `CreateClassGroupDto` | Dados da turma criada. | Curso ou instrutor não encontrados, conflito de código |
| PATCH | /lms/classes/:id | Sim | Atualiza turma. | Param: `id` (número), Body: `UpdateClassGroupDto` | Dados da turma atualizada. | Turma não encontrada, conflito de código |
| DELETE | /lms/classes/:id | Sim | Remove turma pelo ID. | Param: `id` (número) | `{ success: true }` | Turma não encontrada |
#### Pessoas na turma (estudantes e instrutores)
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|----------------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/classes/:id/people/search | Sim | Pesquisa pessoas para adicionar na turma. | Param: `id` (número), Query: `q` (string) | Lista de pessoas com flags de instrutor e matrícula. | Turma não encontrada |
| GET | /lms/classes/:id/students | Sim | Lista estudantes matriculados na turma. | Param: `id` (número), Query: `search` (string) | Lista de estudantes com dados de contato e status. | Turma não encontrada |
| POST | /lms/classes/:id/students | Sim | Matricula estudante existente na turma. | Param: `id` (número), Body: `{ personId: number }` | Dados da matrícula criada ou atualizada. | Turma ou estudante não encontrados, matrícula duplicada |
| POST | /lms/classes/:id/students/create | Sim | Cria pessoa e matricula na turma. | Param: `id` (número), Body: `CreateStudentAndEnrollDto` | Dados da pessoa criada e matriculada. | Turma não encontrada, dados inválidos |
| GET | /lms/classes/:id/students/:personId | Sim | Obtém perfil do estudante na turma. | Param: `id` (número), `personId` (número) | Dados do estudante com contatos e status. | Matrícula não encontrada |
| PATCH | /lms/classes/:id/students/:personId | Sim | Atualiza perfil do estudante na turma. | Param: `id` (número), `personId` (número), Body: `UpdateStudentProfileDto` | Dados atualizados do estudante. | Matrícula não encontrada, dados inválidos |
| DELETE | /lms/classes/:id/students/:personId | Sim | Remove estudante da turma (status cancelado). | Param: `id` (número), `personId` (número) | `{ success: true }` | Matrícula não encontrada |
#### Sessões da turma
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|----------------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/classes/:id/sessions | Sim | Lista sessões da turma. | Param: `id` (número) | Lista de sessões com dados detalhados. | Turma não encontrada |
| POST | /lms/classes/:id/sessions | Sim | Cria sessão na turma. | Param: `id` (número), Body: `CreateSessionDto` | Dados da sessão criada. | Turma ou instrutor não encontrados, dados inválidos |
| PATCH | /lms/classes/:id/sessions/:sessionId | Sim | Atualiza sessão. | Param: `id` (número), `sessionId` (número), Body: `UpdateSessionDto` | Dados da sessão atualizada. | Sessão não encontrada, dados inválidos |
| DELETE | /lms/classes/:id/sessions/:sessionId | Sim | Remove sessão. | Param: `id` (número), `sessionId` (número), Query: `scope` = `single` ou `series` | `{ success: true }` | Sessão não encontrada |
#### Presença em sessões
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|------------------------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/classes/:id/sessions/:sessionId/attendance | Sim | Obtém lista de presenças na sessão. | Param: `id` (número), `sessionId` (número) | Lista de presenças com dados do estudante e status de presença. | Sessão não encontrada |
| POST | /lms/classes/:id/sessions/:sessionId/attendance | Sim | Salva presenças. | Param: `id` (número), `sessionId` (número), Body: `SaveAttendanceDto` | `{ success: true }` | Sessão não encontrada |
### Cursos
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|-----------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/courses | Sim | Lista cursos com paginação e filtros. | Query: `page`, `pageSize`, `search`, `status` (draft|published|archived), `level` (beginner|intermediate|advanced), `category` (slug) | Paginação com lista de cursos e dados resumidos. | Status ou level inválidos |
| GET | /lms/courses/stats | Sim | Estatísticas gerais dos cursos. | - | KPIs como total, publicados, estudantes, etc. | - |
| GET | /lms/courses/:id | Sim | Obtém curso pelo ID. | Param: `id` (número) | Dados detalhados do curso, incluindo módulos, aulas e instrutores. | Curso não encontrado |
| POST | /lms/courses | Sim | Cria novo curso. | Body: `CreateCourseDto` | Dados do curso criado. | Dados inválidos, slug duplicado |
| PATCH | /lms/courses/:id | Sim | Atualiza curso. | Param: `id` (número), Body: `UpdateCourseDto` | Dados do curso atualizado. | Curso não encontrado, dados inválidos |
| DELETE | /lms/courses/:id | Sim | Remove curso pelo ID. | Param: `id` (número) | `{ success: true }` | Curso não encontrado |
### Estrutura do curso
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|----------------------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/courses/:id/structure | Sim | Obtém estrutura do curso (módulos e aulas). | Param: `id` (número) | Estrutura com sessões (módulos) e aulas detalhadas. | Curso não encontrado |
| POST | /lms/courses/:id/structure/sessions | Sim | Cria módulo (sessão) no curso. | Param: `id` (número), Body: `CreateCourseStructureSessionDto` | Dados do módulo criado. | Curso não encontrado, dados inválidos |
| PATCH | /lms/courses/:id/structure/sessions/:sessionId | Sim | Atualiza módulo. | Param: `id` (número), `sessionId` (número), Body: `UpdateCourseStructureSessionDto` | Dados do módulo atualizado. | Módulo não encontrado |
| DELETE | /lms/courses/:id/structure/sessions/:sessionId | Sim | Remove módulo. | Param: `id` (número), `sessionId` (número) | `{ success: true }` | Módulo não encontrado |
| POST | /lms/courses/:id/structure/sessions/:sessionId/lessons | Sim | Cria aula no módulo. | Param: `id` (número), `sessionId` (número), Body: `CreateCourseStructureLessonDto` | Dados da aula criada. | Módulo não encontrado, dados inválidos |
| PATCH | /lms/courses/:id/structure/sessions/:sessionId/lessons/:lessonId | Sim | Atualiza aula. | Param: `id` (número), `sessionId` (número), `lessonId` (número), Body: `UpdateCourseStructureLessonDto` | Dados da aula atualizada. | Aula não encontrada |
| DELETE | /lms/courses/:id/structure/sessions/:sessionId/lessons/:lessonId | Sim | Remove aula. | Param: `id` (número), `sessionId` (número), `lessonId` (número) | `{ success: true }` | Aula não encontrada |
### Exames (tentativas)
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|----------------------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/exams/:id/attempt | Sim | Obtém estado da tentativa de exame para usuário. | Param: `id` (número), Query opcional: `studentId` (número) | Estado atual da tentativa ou nulo. | Exame não encontrado |
| POST | /lms/exams/:id/attempt/start | Sim | Inicia tentativa de exame. | Param: `id` (número), Body: `StartExamAttemptDto` | Dados da tentativa iniciada. | Exame não encontrado |
| PATCH | /lms/exams/:id/attempt/:attemptId/answers | Sim | Salva respostas da tentativa. | Param: `id` (número), `attemptId` (número), Body: `SaveExamAttemptAnswersDto` | Dados atualizados da tentativa. | Tentativa não encontrada |
| POST | /lms/exams/:id/attempt/:attemptId/submit | Sim | Submete tentativa de exame. | Param: `id` (número), `attemptId` (número), Body: `SubmitExamAttemptDto` | Resultado da submissão. | Tentativa não encontrada |
### Dashboard
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|-----------------|--------------|------------------------------------------------------------------------------------------------|------------------|--------------------------------------------------------------------------------------------|--------------|
| GET | /lms/dashboard | Sim | Obtém dados do dashboard do LMS com KPIs, gráficos, eventos, matrículas recentes e próximas turmas. | Header: `accept-language` (opcional) | Dados agregados para dashboard do LMS. | - |
### Enterprise (Empresas)
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/enterprise | Sim | Lista empresas com paginação e filtros. | Query: `page`, `pageSize`, `search`, `status`, `crmPersonId` | Paginação com lista de empresas. | - |
| POST | /lms/enterprise | Sim | Cria nova empresa. | Body: `CreateEnterpriseDto` | Dados da empresa criada. | Dados inválidos |
| GET | /lms/enterprise/:id | Sim | Obtém empresa pelo ID. | Param: `id` (número) | Dados da empresa. | Empresa não encontrada |
| PATCH | /lms/enterprise/:id | Sim | Atualiza empresa. | Param: `id` (número), Body: `UpdateEnterpriseDto` | Dados da empresa atualizada. | Empresa não encontrada |
| DELETE | /lms/enterprise/:id | Sim | Remove empresa pelo ID. | Param: `id` (número) | `{ success: true }` | Empresa não encontrada |
#### Usuários da empresa
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/enterprise/:id/users | Sim | Lista usuários da empresa com paginação e filtro. | Param: `id` (número), Query: `page`, `pageSize`, `search` | Paginação com lista de usuários. | Empresa não encontrada |
| POST | /lms/enterprise/:id/users | Sim | Adiciona usuário à empresa. | Param: `id` (número), Body: `AddEnterpriseUserDto` | Dados do usuário adicionado. | Empresa não encontrada, dados inválidos |
| PATCH | /lms/enterprise/:id/users/:userId | Sim | Atualiza usuário da empresa. | Param: `id` (número), `userId` (número), Body: `UpdateEnterpriseUserDto` | Dados do usuário atualizado. | Usuário ou empresa não encontrados |
| DELETE | /lms/enterprise/:id/users/:userId | Sim | Remove usuário da empresa. | Param: `id` (número), `userId` (número) | `{ success: true }` | Usuário ou empresa não encontrados |
#### Cursos da empresa
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/enterprise/:id/courses | Sim | Lista cursos da empresa com paginação e filtro. | Param: `id` (número), Query: `page`, `pageSize`, `search` | Paginação com lista de cursos. | Empresa não encontrada |
| POST | /lms/enterprise/:id/courses | Sim | Adiciona curso à empresa. | Param: `id` (número), Body: `AddEnterpriseCourseDto` | Dados do curso adicionado. | Empresa não encontrada, dados inválidos |
| DELETE | /lms/enterprise/:id/courses/:courseId | Sim | Remove curso da empresa. | Param: `id` (número), `courseId` (número) | `{ success: true }` | Curso ou empresa não encontrados |
#### Turmas da empresa
| Método | Path | Autenticação | Descrição | Params/Query/Body | Resposta | Erros Comuns |
|--------|------------------------------|--------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------|
| GET | /lms/enterprise/:id/classes | Sim | Lista turmas da empresa com paginação e filtro. | Param: `id` (número), Query: `page`, `pageSize`, `search` | Paginação com lista de turmas. | Empresa não encontrada |
| POST | /lms/enterprise/:id/classes | Sim | Adiciona turma à empresa. | Param: `id` (número), Body: `AddEnterpriseClassGroupDto` | Dados da turma adicionada. | Empresa não encontrada, dados inválidos |
| DELETE | /lms/enterprise/:id/classes/:classGroupId | Sim | Remove turma da empresa. | Param: `id` (número), `classGroupId` (número) | `{ success: true }` | Turma ou empresa não encontrados |
## 4. Regras de autenticação e autorização
- Existe o papel (`role`) `admin-lms` com permissão total para gestão do LMS.
- Autenticação e autorização são gerenciadas externamente, utilizando o papel `admin-lms` para operações administrativas.
- Regras específicas de acesso devem ser implementadas conforme a integração com o sistema de autenticação do HedHog.
## 5. Estruturas de request/response
### Exemplos principais de DTOs usados nos endpoints
- **CreateCertificateTemplateDto**
```ts
{
name: string; // obrigatório, max 255
slug?: string; // opcional, max 255
description?: string; // opcional
templateContent: string; // obrigatório, JSON válido
status?: 'draft' | 'active' | 'inactive'; // opcional
}CreateClassGroupDto
{ code: string; // obrigatório, max 50 courseId: number; // obrigatório instructorId?: number; // opcional title: string; // obrigatório, max 255 description?: string; // opcional deliveryMode: 'presential' | 'online' | 'hybrid'; // obrigatório status?: 'open' | 'ongoing' | 'completed' | 'cancelled'; // opcional startDate: string; // obrigatório, ISO8601 endDate?: string; // opcional, ISO8601 startTime?: string; // opcional, formato HH:mm endTime?: string; // opcional, formato HH:mm weekDays?: string; // opcional capacity?: number; // opcional, mínimo 1 location?: string; // opcional virtualRoomUrl?: string; // opcional, URL sessionTemplate?: { title: string; description?: string; location?: string; meetingUrl?: string; color?: string; // formato #RRGGBB recurrence?: { frequency: 'daily' | 'weekly' | 'monthly' | 'yearly'; interval?: number; until: string; // ISO8601 daysOfWeek?: Array<'MO' | 'TU' | 'WE' | 'TH' | 'FR' | 'SA' | 'SU'>; }; }; }EnrollStudentDto
{ personId: number; // obrigatório }SaveAttendanceDto
{ attendance: Array<{ studentId: number; // obrigatório present: boolean; // obrigatório justification?: string; // opcional }>; }CreateCourseDto
{ code?: string; // opcional, max 32 slug: string; // obrigatório, max 255 title?: string; // opcional, max 255 description?: string; // opcional requirements?: string; // opcional objectives?: string; // opcional targetAudience?: string; // opcional durationHours?: number; // opcional certificateWorkload?: number; // opcional level?: 'beginner' | 'intermediate' | 'advanced'; // opcional status?: 'draft' | 'published' | 'archived'; // opcional offeringType?: 'scheduled' | 'on_demand' | 'blended'; // opcional isFeatured?: boolean; // opcional hasCertificate?: boolean; // opcional isListed?: boolean; // opcional primaryColor?: string; // opcional, formato #RRGGBB primaryContrastColor?: string; // opcional, formato #RRGGBB secondaryColor?: string; // opcional, formato #RRGGBB secondaryContrastColor?: string; // opcional, formato #RRGGBB categorySlugs?: string[]; // opcional instructorIds?: number[]; // opcional logoFileId?: number; // opcional bannerFileId?: number; // opcional }CreateCourseStructureLessonDto
{ codigo?: string; // opcional, max 32 titulo: string; // obrigatório, max 255 descricaoPublica?: string; // opcional descricaoPrivada?: string; // opcional tipo: 'video' | 'questao' | 'post' | 'exercicio'; // obrigatório duracao: number; // obrigatório, minutos videoProvedor?: 'youtube' | 'vimeo' | 'bunny' | 'custom'; // opcional videoUrl?: string; // opcional duracaoAutomatica?: boolean; // opcional transcricao?: string; // opcional exameVinculado?: number; // opcional conteudoPost?: string; // opcional instructorIds?: number[]; // opcional recursos?: Array<{ nome: string; // obrigatório fileId?: number; // opcional tipo?: string; // opcional publico?: boolean; // opcional }>; }CreateSessionDto
{ title: string; // obrigatório, max 255 description?: string; // opcional sessionDate: string; // obrigatório, ISO8601 startTime: string; // obrigatório, formato HH:mm endTime: string; // obrigatório, formato HH:mm location?: string; // opcional meetingUrl?: string; // opcional, max 500 color?: string; // opcional, formato #RRGGBB status?: 'scheduled' | 'completed' | 'cancelled'; // opcional instructorId?: number; // opcional recurrence?: { frequency: 'daily' | 'weekly' | 'monthly' | 'yearly'; interval?: number; until: string; // ISO8601 daysOfWeek?: Array<'MO' | 'TU' | 'WE' | 'TH' | 'FR' | 'SA' | 'SU'>; }; // opcional }StartExamAttemptDto
{ studentId?: number; // opcional }SaveExamAttemptAnswersDto
{ answers: Array<{ questionId: number; examOptionId?: number | null; answerText?: string | null; matchingPairs?: Array<{ leftId: string; rightId: string; }>; }>; }SubmitExamAttemptDto
Extende
SaveExamAttemptAnswersDtocom:{ force?: boolean; // opcional }CreateEnterpriseDto
{ name: string; // obrigatório, max 255 slug?: string; // opcional, max 255 status?: 'active' | 'trial' | 'inactive' | 'suspended'; // opcional crmPersonId?: number | null; // opcional portalEnabled?: boolean; // opcional licenseLimit?: number | null; // opcional notes?: string; // opcional }AddEnterpriseUserDto
{ userId: number; // obrigatório personId?: number | null; // opcional role: 'student' | 'hr_manager' | 'enterprise_admin' | 'viewer'; // obrigatório status?: 'active' | 'inactive' | 'pending'; // opcional }
6. Erros comuns
- Violação de integridade referencial: ao inserir ou atualizar registros com chaves estrangeiras inválidas.
- Duplicidade de registros únicos: como códigos únicos de certificado, slugs de cursos ou templates.
- Status inválidos: ao definir valores fora dos enums para status de cursos, exames, matrículas, etc.
- Campos obrigatórios ausentes: como títulos, slugs e chaves primárias.
- Datas ou horários inválidos: datas mal formatadas ou horários inconsistentes (ex: hora fim antes da hora início).
- Tentativa de matrícula duplicada: ao tentar matricular estudante já matriculado ativo.
- Arquivo inválido no upload: ao enviar arquivo não-imagem para upload de background de template.
- Entidades não encontradas: ao referenciar IDs inexistentes (curso, turma, sessão, usuário, etc).
- Conflito de código: ao tentar criar ou atualizar turma com código já existente.
7. Banco de dados (tabelas YAML)
Abaixo estão as principais tabelas do módulo LMS com suas finalidades e detalhes.
certificate
- Finalidade: Armazena certificados emitidos para estudantes em cursos, exames, grupos de aulas ou trilhas de aprendizagem.
- Colunas:
id(PK)verification_code(varchar 50, único): código para verificação do certificado.student_id(FK paraperson.id, onDelete CASCADE)course_enrollment_id(FK opcional paracourse_enrollment.id, onDelete SET NULL)course_id(FK opcional paracourse.id, onDelete SET NULL)exam_id(FK opcional paraexam.id, onDelete SET NULL)course_class_group_id(FK opcional paracourse_class_group.id, onDelete SET NULL)learning_path_id(FK opcional paralearning_path.id, onDelete SET NULL)certificate_template_id(FK paracertificate_template.id)certificate_type(enum:course,exam,course_class_group,learning_path)student_name(varchar 255)course_name(varchar 255)workload_hours(int)issued_at(datetime)completed_at(datetime)final_score(int, nullable)verification_url(varchar 500, nullable)pdf_url(varchar 500, nullable)created_at,updated_at
- Defaults: timestamps automáticos.
- Nulabilidade: campos opcionais indicados.
- Integridade: chaves estrangeiras com regras onDelete conforme descrito.
- Índices: único em
verification_code.
certificate_template
- Finalidade: Modelos de certificados para emissão.
- Colunas:
id(PK)name(varchar 255)slug(varchar 255, único)description(text, nullable)template_content(text)status(enum:draft,active,inactive, defaultdraft)created_at,updated_at
- Defaults:
statusdefaultdraft. - Nulabilidade:
descriptionnullable. - Integridade: -
- Índices: único em
slug.
course_class_group
- Finalidade: Grupos de aulas de um curso.
- Colunas:
id(PK)course_id(FK paracourse.id, onDelete CASCADE)title(varchar 255)code(varchar 50, único)description(text, nullable)delivery_mode(enum:presential,online,hybrid)status(enum:open,ongoing,completed,cancelled, defaultopen)start_date(datetime)end_date(datetime, nullable)start_time(varchar 5, nullable)end_time(varchar 5, nullable)week_days(text, nullable)capacity(int, default 30)location(text, nullable)virtual_room_url(varchar 500, nullable)created_at,updated_at
- Defaults:
statusdefaultopen,capacitydefault 30. - Nulabilidade: campos opcionais indicados.
- Integridade: FK com onDelete CASCADE.
- Índices: único em
code.
course_class_session
- Finalidade: Sessões específicas dentro de um grupo de aula.
- Colunas:
id(PK)course_class_group_id(FK paracourse_class_group.id, onDelete CASCADE)title(varchar 255)description(text, nullable)session_date(datetime)start_time(varchar 5)end_time(varchar 5)location(text, nullable)meeting_url(varchar 500, nullable)status(enum:scheduled,completed,cancelled, defaultscheduled)recurrence_id(uuid, nullable)recurrence_rule(text, nullable)occurrence_index(int, nullable)is_exception(boolean, default false)parent_session_id(FK opcional paracourse_class_session.id, onDelete SET NULL)created_at,updated_at
- Defaults:
statusdefaultscheduled,is_exceptiondefault false. - Nulabilidade: campos opcionais indicados.
- Integridade: FK com onDelete CASCADE.
- Índices: combinação
course_class_group_id+session_date.
course_enrollment
- Finalidade: Matrículas de pessoas em cursos ou grupos de aula.
- Colunas:
id(PK)person_id(FK paraperson.id, onDelete CASCADE)course_class_group_id(FK opcional paracourse_class_group.id, onDelete SET NULL)course_id(FK paracourse.id, onDelete CASCADE)status(enum:pending,active,completed,cancelled,paused, defaultactive)enrolled_at(datetime)completed_at(datetime, nullable)progress_percent(int, default 0)final_score(int, nullable)created_at,updated_at
- Defaults:
statusdefaultactive,progress_percentdefault 0. - Nulabilidade: campos opcionais indicados.
- Integridade: FK com onDelete conforme descrito.
- Índices: único em combinação
person_id+course_class_group_id.
course
- Finalidade: Cursos disponíveis no LMS.
- Colunas:
id(PK)title(varchar 255)slug(varchar 255, único)description(text, nullable)short_description(varchar 500, nullable)level(enum:beginner,intermediate,advanced, defaultbeginner)duration_hours(int, default 0)status(enum:draft,published,archived, defaultdraft)primary_color,primary_contrast_color,secondary_color,secondary_contrast_color(varchar 9, nullable)certificate_workload(int, nullable)certificate_template_id(FK opcional paracertificate_template.id, onDelete SET NULL)requirements,objectives,target_audience(text, nullable)created_at,updated_at
- Defaults:
leveldefaultbeginner,duration_hoursdefault 0,statusdefaultdraft. - Nulabilidade: campos opcionais indicados.
- Integridade: FK para
certificate_templatecom onDelete SET NULL. - Índices: único em
slug.
instructor
- Finalidade: Instrutores cadastrados no LMS.
- Colunas:
id(PK)person_id(FK único paraperson.id, onDelete CASCADE)status(enum:active,inactive, defaultactive)can_teach_courses(boolean, default true)created_at,updated_at
- Defaults:
statusdefaultactive,can_teach_coursesdefault true. - Integridade: FK único com onDelete CASCADE.
- Índices: único em
person_id.
learning_path
- Finalidade: Trilhas de aprendizagem compostas por cursos e exames.
- Colunas:
id(PK)title(varchar 255)slug(varchar 255, único)description(text, nullable)short_description(varchar 500, nullable)level(enum:beginner,intermediate,advanced, defaultbeginner)duration_hours(int, default 0)status(enum:draft,active,archived, defaultdraft)primary_color,primary_contrast_color,secondary_color,secondary_contrast_color(varchar 9, nullable)created_at,updated_at
- Defaults:
leveldefaultbeginner,duration_hoursdefault 0,statusdefaultdraft. - Nulabilidade: campos opcionais indicados.
- Integridade: -
- Índices: único em
slug.
learning_path_enrollment
- Finalidade: Matrículas em trilhas de aprendizagem.
- Colunas:
id(PK)learning_path_id(FK paralearning_path.id, onDelete CASCADE)person_id(FK paraperson.id, onDelete CASCADE)status(enum:active,completed,cancelled, defaultactive)progress_percent(int, default 0)enrolled_at(datetime)completed_at(datetime, nullable)created_at,updated_at
- Defaults:
statusdefaultactive,progress_percentdefault 0. - Nulabilidade:
completed_atopcional. - Integridade: FK com onDelete CASCADE.
- Índices: único em combinação
learning_path_id+person_id.
8. Regras de negócio relevantes
- Certificados são vinculados a estudantes e podem estar associados a diferentes tipos de atividades (curso, exame, grupo de aula, trilha).
- Cursos, exames e trilhas possuem status que controlam sua visibilidade e disponibilidade.
- Matrículas e inscrições possuem status que refletem o progresso e situação do aluno.
- Avaliações e tentativas de exame são controladas para permitir múltiplas tentativas e registrar resultados detalhados.
- Instrutores podem ter papéis distintos (líder ou assistente) em aulas e sessões.
- Trilhas de aprendizagem são compostas por passos ordenados que podem ser cursos ou exames, podendo ser obrigatórios ou opcionais.
- Progresso em aulas e cursos é monitorado para permitir acompanhamento detalhado do aluno.
- Imagens e arquivos são organizados por tipo e podem ser marcados como primários para exibição.
- Turmas possuem capacidade máxima e status que impactam matrículas e ocupação.
- Sessões podem ser recorrentes com regras de recorrência definidas e exceções.
- Presença em sessões é registrada individualmente com possibilidade de justificativas.
- Ao criar ou atualizar templates de certificado, o conteúdo deve ser JSON válido.
- Slugs de templates são únicos e gerados automaticamente se não fornecidos.
- Ao matricular estudantes, verifica-se se já existe matrícula ativa para evitar duplicidade.
- Atualizações em séries de sessões podem ser aplicadas a uma única sessão ou a toda a série.
- Empresas (enterprises) gerenciam usuários, cursos, turmas e leads com papéis e status específicos.
- Dashboard agrega dados e estatísticas para monitoramento do LMS.
9. Guia rápido de uso (exemplos)
Como o módulo é consumido via APIs internas do HedHog, os exemplos abaixo ilustram chamadas típicas usando Prisma ORM.
Criar um novo curso
const novoCurso = await prisma.course.create({
data: {
title: 'Introdução ao HedHog LMS',
slug: 'introducao-hedhog-lms',
description: 'Curso básico para entender o LMS HedHog',
level: 'beginner',
duration_hours: 10,
status: 'draft',
},
});Matricular um estudante em uma turma
const matricula = await prisma.course_enrollment.create({
data: {
person_id: estudanteId,
course_class_group_id: turmaId,
course_id: cursoId,
status: 'active',
enrolled_at: new Date(),
},
});Registrar presença em uma sessão de aula
const presenca = await prisma.course_class_attendance.upsert({
where: {
course_class_session_id_student_id: {
course_class_session_id: sessaoId,
student_id: estudanteId,
},
},
update: { present: true },
create: {
course_class_session_id: sessaoId,
student_id: estudanteId,
present: true,
},
});Emitir um certificado
const certificado = await prisma.certificate.create({
data: {
verification_code: gerarCodigoUnico(),
student_id: estudanteId,
course_id: cursoId,
certificate_template_id: templateId,
certificate_type: 'course',
student_name: nomeEstudante,
course_name: nomeCurso,
workload_hours: cargaHoraria,
issued_at: new Date(),
completed_at: dataConclusao,
final_score: notaFinal,
verification_url: urlVerificacao,
pdf_url: urlPdf,
},
});Criar uma turma (class group)
const turma = await prisma.course_class_group.create({
data: {
code: 'TURMA001',
course_id: cursoId,
title: 'Turma de Exemplo',
delivery_mode: 'online',
status: 'open',
start_date: new Date('2024-07-01'),
capacity: 30,
},
});Criar sessão em turma
const sessao = await prisma.course_class_session.create({
data: {
course_class_group_id: turma.id,
title: 'Sessão 1',
session_date: new Date('2024-07-02'),
start_time: '09:00',
end_time: '11:00',
status: 'scheduled',
},
});Para mais detalhes sobre integração e uso, consulte a documentação geral do HedHog e os serviços que consomem o módulo @hed-hog/lms.