@hed-hog/lms 0.0.270 → 0.0.274

package/README.md

@@ -0,0 +1,487 @@
+# @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.
+
+## 3. Endpoints
+
+> **Nota:** O código fonte fornecido não expõe endpoints REST ou GraphQL diretamente. Este README documenta as tabelas e estruturas de dados do módulo LMS. Para uso via API, consulte a documentação específica da API que consome este módulo.
+
+## 4. Regras de autenticação e autorização
+
+- O módulo define um papel (`role`) chamado `admin-lms` com permissão total para gestão do LMS.
+- A autenticação e autorização devem ser gerenciadas externamente, utilizando o papel `admin-lms` para operações administrativas.
+- Outras 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
+
+- Não aplicável diretamente, pois o módulo não expõe endpoints REST no código fornecido.
+- As operações devem ser realizadas via serviços internos ou APIs que consumam este módulo.
+
+## 6. Erros comuns
+
+- **Violação de integridade referencial:** ao tentar 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 tentar definir valores fora dos enums definidos para status de cursos, exames, matrículas, etc.
+- **Campos obrigatórios ausentes:** como títulos, slugs e chaves primárias.
+
+## 7. Banco de dados (tabelas YAML)
+
+### certificate
+
+- **Finalidade:** Armazena certificados emitidos para estudantes em cursos, exames, grupos de aulas ou trilhas de aprendizagem.
+- **Colunas principais:**
+  - `verification_code` (varchar 50, único): código para verificação do certificado.
+  - `student_id` (fk para person): estudante que recebeu o certificado.
+  - `course_enrollment_id` (fk opcional): matrícula relacionada.
+  - `certificate_type` (enum): tipo do certificado (`course`, `exam`, `course_class_group`, `learning_path`).
+  - `student_name`, `course_name` (varchar 255): nomes para exibição.
+  - `workload_hours` (int): carga horária.
+  - `issued_at`, `completed_at` (datetime): datas relevantes.
+  - `final_score` (int opcional): nota final.
+  - `verification_url`, `pdf_url` (varchar 500 opcionais): URLs para verificação e PDF.
+- **Integridade:** chaves estrangeiras com ações `CASCADE` ou `SET NULL`.
+- **Índices:** único em `verification_code`.
+
+### certificate_template
+
+- **Finalidade:** Modelos de certificados para emissão.
+- **Colunas principais:**
+  - `name`, `slug` (varchar 255, slug único).
+  - `description` (texto opcional).
+  - `template_content` (texto): conteúdo do template.
+  - `status` (enum): `draft`, `active`, `inactive` (default `draft`).
+- **Índices:** único em `slug`.
+
+### course
+
+- **Finalidade:** Cursos disponíveis no LMS.
+- **Colunas principais:**
+  - `title`, `slug` (varchar 255, slug único).
+  - `description`, `short_description` (texto e varchar 500 opcionais).
+  - `level` (enum): `beginner`, `intermediate`, `advanced` (default `beginner`).
+  - `duration_hours` (int, default 0).
+  - `status` (enum): `draft`, `published`, `archived` (default `draft`).
+  - Cores primárias e secundárias para personalização visual.
+  - `certificate_workload` (int opcional).
+  - `certificate_template_id` (fk opcional).
+  - `requirements`, `objectives`, `target_audience` (texto opcionais).
+- **Índices:** único em `slug`.
+
+### course_category
+
+- **Finalidade:** Associação entre cursos e categorias.
+- **Colunas principais:**
+  - `course_id` (fk).
+  - `category_id` (fk).
+- **Índices:** único em combinação `course_id` + `category_id`.
+
+### course_class_attendance
+
+- **Finalidade:** Registro de presença dos estudantes em sessões de aula.
+- **Colunas principais:**
+  - `course_class_session_id` (fk).
+  - `student_id` (fk).
+  - `present` (boolean, default false).
+  - `justification` (texto opcional).
+  - `recorded_by_id` (fk opcional).
+- **Índices:** único em combinação `course_class_session_id` + `student_id`.
+
+### course_class_group
+
+- **Finalidade:** Grupos de aulas de um curso.
+- **Colunas principais:**
+  - `course_id` (fk).
+  - `title`, `code` (varchar, código único).
+  - `description` (texto opcional).
+  - `delivery_mode` (enum): `presential`, `online`, `hybrid`.
+  - `status` (enum): `open`, `ongoing`, `completed`, `cancelled` (default `open`).
+  - Datas e horários de início e fim.
+  - `capacity` (int, default 30).
+  - `location`, `virtual_room_url` (texto e varchar 500 opcionais).
+- **Índices:** único em `code`.
+
+### course_class_session
+
+- **Finalidade:** Sessões específicas dentro de um grupo de aula.
+- **Colunas principais:**
+  - `course_class_group_id` (fk).
+  - `title`, `description` (varchar e texto opcional).
+  - `session_date` (datetime).
+  - Horários de início e fim.
+  - `location`, `meeting_url` (texto e varchar 500 opcionais).
+  - `status` (enum): `scheduled`, `completed`, `cancelled` (default `scheduled`).
+- **Índices:** combinação `course_class_group_id` + `session_date`.
+
+### course_class_session_instructor
+
+- **Finalidade:** Instrutores vinculados a sessões de aula.
+- **Colunas principais:**
+  - `course_class_session_id` (fk).
+  - `instructor_id` (fk).
+  - `role` (enum): `lead`, `assistant` (default `assistant`).
+- **Índices:** único em combinação `course_class_session_id` + `instructor_id`.
+
+### course_enrollment
+
+- **Finalidade:** Matrículas de pessoas em cursos ou grupos de aula.
+- **Colunas principais:**
+  - `person_id` (fk).
+  - `course_class_group_id` (fk opcional).
+  - `course_id` (fk).
+  - `status` (enum): `pending`, `active`, `completed`, `cancelled`, `paused` (default `active`).
+  - Datas de matrícula e conclusão.
+  - `progress_percent` (int, default 0).
+  - `final_score` (int opcional).
+- **Índices:** único em combinação `person_id` + `course_class_group_id`.
+
+### course_image
+
+- **Finalidade:** Imagens associadas a cursos.
+- **Colunas principais:**
+  - `course_id` (fk).
+  - `file_id` (fk).
+  - `image_type_id` (fk).
+  - `order` (int).
+  - `is_primary` (boolean, default false).
+- **Índices:** único em combinação `course_id` + `image_type_id` + `order`.
+
+### course_lesson
+
+- **Finalidade:** Aulas dentro de módulos de curso.
+- **Colunas principais:**
+  - `course_module_id` (fk).
+  - `title`, `description` (varchar e texto opcional).
+  - `type` (enum): `video`, `text`, `quiz` (default `video`).
+  - `content` (texto opcional).
+  - `duration_seconds` (int, default 0).
+  - `order` (int).
+  - `is_released` (boolean, default true).
+- **Índices:** único em combinação `course_module_id` + `order`.
+
+### course_lesson_file
+
+- **Finalidade:** Arquivos vinculados a aulas.
+- **Colunas principais:**
+  - `course_lesson_id` (fk).
+  - `file_id` (fk opcional).
+  - `title` (varchar).
+- **Índices:** em `course_lesson_id`.
+
+### course_lesson_instructor
+
+- **Finalidade:** Instrutores vinculados a aulas.
+- **Colunas principais:**
+  - `course_lesson_id` (fk).
+  - `instructor_id` (fk).
+  - `role` (enum): `lead`, `assistant` (default `assistant`).
+- **Índices:** único em combinação `course_lesson_id` + `instructor_id`.
+
+### course_lesson_progress
+
+- **Finalidade:** Progresso dos estudantes em aulas.
+- **Colunas principais:**
+  - `course_enrollment_id` (fk).
+  - `course_lesson_id` (fk).
+  - `status` (enum): `not_started`, `in_progress`, `completed` (default `not_started`).
+  - `progress_percent` (int, default 0).
+  - `video_progress_seconds` (int, default 0).
+  - Datas de início e conclusão.
+  - `time_spent_seconds` (int, default 0).
+- **Índices:** único em combinação `course_enrollment_id` + `course_lesson_id`.
+
+### course_lesson_question
+
+- **Finalidade:** Questões associadas a aulas do tipo quiz.
+- **Colunas principais:**
+  - `course_lesson_id` (fk).
+  - `question_id` (fk).
+  - `order` (int).
+- **Índices:** únicos em combinações `course_lesson_id` + `question_id` e `course_lesson_id` + `order`.
+
+### course_module
+
+- **Finalidade:** Módulos dentro de cursos.
+- **Colunas principais:**
+  - `course_id` (fk).
+  - `title`, `description` (varchar e texto opcional).
+  - `order` (int).
+  - `duration_minutes` (int, default 0).
+- **Índices:** único em combinação `course_id` + `order`.
+
+### course_prerequisite
+
+- **Finalidade:** Pré-requisitos para cursos.
+- **Colunas principais:**
+  - `course_id` (fk).
+  - `prerequisite_type` (enum): `course`, `learning_path`, `exam` (default `course`).
+  - FK para curso, trilha ou exame conforme tipo.
+- **Índices:** únicos para combinações de curso e pré-requisitos.
+
+### evaluation_rating
+
+- **Finalidade:** Avaliações e notas dadas a tópicos de avaliação.
+- **Colunas principais:**
+  - `evaluation_topic_id` (fk).
+  - `evaluator_id` (fk opcional).
+  - `score` (decimal 2,1).
+  - `comment` (texto opcional).
+- **Índices:** único em combinação `evaluation_topic_id` + `evaluator_id`.
+
+### evaluation_topic
+
+- **Finalidade:** Tópicos para avaliação dentro do LMS.
+- **Colunas principais:**
+  - `name`, `description` (varchar e texto opcional).
+  - `target_type` (enum): `course`, `course_lesson`, `course_class_session`, `question`, `exam`.
+  - FK opcionais para entidades alvo.
+  - `order` (int).
+  - `is_active` (boolean, default true).
+- **Índices:** únicos para combinações de alvo e ordem.
+
+### exam
+
+- **Finalidade:** Exames vinculados a cursos ou grupos de aula.
+- **Colunas principais:**
+  - FK para curso e grupo de aula (opcionais).
+  - `title`, `description`, `instructions` (varchar e textos opcionais).
+  - `exam_type` (enum): `quiz`, `test`, `assignment`, `project`.
+  - `status` (enum): `draft`, `published`, `closed`, `archived` (default `draft`).
+  - Cores para personalização.
+  - Datas de início e fim, limite de tempo.
+  - `attempts_allowed` (int, default 1).
+  - Notas mínima e máxima.
+  - Flags para embaralhamento e exibição de resultados.
+- **Índices:** em curso, grupo e status.
+
+### exam_answer
+
+- **Finalidade:** Respostas dadas em tentativas de exame.
+- **Colunas principais:**
+  - `exam_attempt_id` (fk).
+  - `question_id` (fk).
+  - `exam_option_id` (fk opcional).
+  - `answer_text` (texto opcional).
+  - `is_correct` (boolean opcional).
+  - `points_awarded` (int, default 0).
+  - `teacher_feedback` (texto opcional).
+- **Índices:** único em combinação `exam_attempt_id` + `question_id`.
+
+### exam_attempt
+
+- **Finalidade:** Tentativas de realização de exames por estudantes.
+- **Colunas principais:**
+  - `exam_id` (fk).
+  - `student_id` (fk).
+  - `course_enrollment_id` (fk opcional).
+  - `attempt_number` (int, default 1).
+  - Datas de início e fim.
+  - `duration_seconds` (int opcional).
+  - `score` (int opcional).
+  - `status` (enum): `in_progress`, `completed`, `abandoned`, `voided` (default `in_progress`).
+  - `ip_address` (varchar 45 opcional).
+- **Índices:** único em combinação `exam_id` + `student_id` + `attempt_number`.
+
+### exam_image
+
+- **Finalidade:** Imagens associadas a exames.
+- **Colunas principais:**
+  - `exam_id` (fk).
+  - `file_id` (fk).
+  - `image_type_id` (fk).
+  - `order` (int).
+  - `is_primary` (boolean, default false).
+- **Índices:** único em combinação `exam_id` + `image_type_id` + `order`.
+
+### exam_option
+
+- **Finalidade:** Opções de resposta para questões de exame.
+- **Colunas principais:**
+  - `question_id` (fk).
+  - `option_text` (texto).
+  - `is_correct` (boolean, default false).
+  - `position` (int, default 0).
+  - `feedback` (texto opcional).
+- **Índices:** único em combinação `question_id` + `position`.
+
+### exam_question
+
+- **Finalidade:** Questões associadas a exames.
+- **Colunas principais:**
+  - `exam_id` (fk).
+  - `question_id` (fk).
+  - `order` (int).
+- **Índices:** únicos em combinações `exam_id` + `question_id` e `exam_id` + `order`.
+
+### image_type
+
+- **Finalidade:** Tipos de imagens aplicáveis a cursos, exames e trilhas.
+- **Colunas principais:**
+  - `name`, `slug` (varchar 100, slug único).
+  - Flags para aplicação em curso, exame e trilha.
+  - `status` (enum): `active`, `inactive` (default `active`).
+- **Índices:** único em `slug`.
+
+### instructor
+
+- **Finalidade:** Instrutores cadastrados no LMS.
+- **Colunas principais:**
+  - `person_id` (fk único).
+  - `status` (enum): `active`, `inactive` (default `active`).
+  - `can_teach_courses` (boolean, default true).
+- **Índices:** único em `person_id`.
+
+### learning_path
+
+- **Finalidade:** Trilhas de aprendizagem compostas por cursos e exames.
+- **Colunas principais:**
+  - `title`, `slug` (varchar 255, slug único).
+  - `description`, `short_description` (texto e varchar 500 opcionais).
+  - `level` (enum): `beginner`, `intermediate`, `advanced` (default `beginner`).
+  - `duration_hours` (int, default 0).
+  - `status` (enum): `draft`, `active`, `archived` (default `draft`).
+  - Cores para personalização.
+- **Índices:** único em `slug`.
+
+### learning_path_enrollment
+
+- **Finalidade:** Matrículas em trilhas de aprendizagem.
+- **Colunas principais:**
+  - `learning_path_id` (fk).
+  - `person_id` (fk).
+  - `status` (enum): `active`, `completed`, `cancelled` (default `active`).
+  - `progress_percent` (int, default 0).
+  - Datas de matrícula e conclusão.
+- **Índices:** único em combinação `learning_path_id` + `person_id`.
+
+### learning_path_image
+
+- **Finalidade:** Imagens associadas a trilhas de aprendizagem.
+- **Colunas principais:**
+  - `learning_path_id` (fk).
+  - `file_id` (fk).
+  - `image_type_id` (fk).
+  - `order` (int).
+  - `is_primary` (boolean, default false).
+- **Índices:** único em combinação `learning_path_id` + `image_type_id` + `order`.
+
+### learning_path_step
+
+- **Finalidade:** Passos dentro de uma trilha, podendo ser cursos ou exames.
+- **Colunas principais:**
+  - `learning_path_id` (fk).
+  - `step_type` (enum): `course`, `exam`.
+  - FK para curso ou exame conforme tipo.
+  - `order` (int).
+  - `is_required` (boolean, default true).
+- **Índices:** únicos para combinações de trilha e ordem, curso ou exame.
+
+### question
+
+- **Finalidade:** Questões para avaliações e quizzes.
+- **Colunas principais:**
+  - `question_type` (enum): `multiple_choice`, `true_false`, `essay`, `fill_blank`, `matching`.
+  - `statement` (texto).
+  - `explanation` (texto opcional).
+  - `points` (int, default 1).
+
+## 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.
+
+## 9. Guia rápido de uso (exemplos)
+
+> Como o módulo não expõe endpoints diretamente, o uso típico envolve integração via serviços internos ou APIs do HedHog.
+
+### Exemplo: Criar um novo curso
+
+```ts
+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',
+  },
+});
+```
+
+### Exemplo: Matricular um estudante em um curso
+
+```ts
+const matricula = await prisma.course_enrollment.create({
+  data: {
+    person_id: estudanteId,
+    course_id: cursoId,
+    status: 'active',
+    enrolled_at: new Date(),
+  },
+});
+```
+
+### Exemplo: Registrar presença em uma sessão de aula
+
+```ts
+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,
+  },
+});
+```
+
+### Exemplo: Emitir um certificado
+
+```ts
+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,
+  },
+});
+```
+
+---
+
+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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/lms",
-  "version": "0.0.270",
+  "version": "0.0.274",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
@@ -10,13 +10,13 @@
     "@nestjs/jwt": "^11",
     "@nestjs/mapped-types": "*",
     "@hed-hog/api-pagination": "0.0.6",
-    "@hed-hog/core": "0.0.270",
+    "@hed-hog/core": "0.0.274",
     "@hed-hog/api": "0.0.4",
     "@hed-hog/api-locale": "0.0.13",
+    "@hed-hog/finance": "0.0.274",
     "@hed-hog/api-types": "0.0.1",
-    "@hed-hog/finance": "0.0.270",
-    "@hed-hog/contact": "0.0.270",
-    "@hed-hog/category": "0.0.270",
+    "@hed-hog/contact": "0.0.274",
+    "@hed-hog/category": "0.0.274",
     "@hed-hog/api-prisma": "0.0.5"
   },
   "exports": {