@hed-hog/lms 0.0.347 → 0.0.350

package/src/exam/exam.controller.ts

@@ -12,6 +12,7 @@ import {
 } from '@nestjs/common';
 import { CreateExamQuestionDto } from './dto/create-exam-question.dto';
 import { CreateExamDto } from './dto/create-exam.dto';
+import { CreateQuestionSubjectDto } from './dto/create-question-subject.dto';
 import { ReorderExamQuestionsDto } from './dto/reorder-exam-questions.dto';
 import { UpdateExamQuestionDto } from './dto/update-exam-question.dto';
 import { UpdateExamDto } from './dto/update-exam.dto';
@@ -22,6 +23,24 @@ import { ExamService } from './exam.service';
 export class ExamController {
   constructor(private readonly examService: ExamService) {}
 
+  @Get('question-subjects')
+  listQuestionSubjects(
+    @Query('page') page?: string,
+    @Query('pageSize') pageSize?: string,
+    @Query('search') search?: string,
+  ) {
+    return this.examService.listQuestionSubjects({
+      page: page ? Number(page) : 1,
+      pageSize: pageSize ? Number(pageSize) : 20,
+      search,
+    });
+  }
+
+  @Post('question-subjects')
+  createQuestionSubject(@Body() dto: CreateQuestionSubjectDto) {
+    return this.examService.createQuestionSubject(dto);
+  }
+
   @Get()
   list(
     @Query('page') page?: string,

package/src/exam/exam.mcp-tools.ts

@@ -0,0 +1,337 @@
+import { McpContext, McpTool } from '@hed-hog/core';
+import { Injectable } from '@nestjs/common';
+import { ExamAttemptService } from './exam-attempt.service';
+import { ExamService } from './exam.service';
+
+@Injectable()
+export class LmsExamMcpTools {
+  constructor(
+    private readonly examService: ExamService,
+    private readonly examAttemptService: ExamAttemptService,
+  ) {}
+
+  @McpTool({
+    name: 'lms.exams.list',
+    description: 'Lists exams with optional pagination and filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page: { type: 'number', description: 'Page number (default: 1)' },
+        pageSize: { type: 'number', description: 'Items per page (default: 20)' },
+        search: { type: 'string', description: 'Search term' },
+        status: { type: 'string', description: 'Filter by status (draft|published|closed|archived)' },
+      },
+    },
+    readOnly: true,
+  })
+  async listExams(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.examService.list(args);
+  }
+
+  @McpTool({
+    name: 'lms.exams.stats',
+    description: 'Returns aggregate statistics for exams.',
+    inputSchema: { type: 'object', properties: {} },
+    readOnly: true,
+  })
+  async getStats(_args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.examService.stats();
+  }
+
+  @McpTool({
+    name: 'lms.exams.get',
+    description: 'Returns a single exam by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Exam ID' },
+      },
+      required: ['id'],
+    },
+    readOnly: true,
+  })
+  async getExam(args: { id: number }, _context: McpContext): Promise<any> {
+    return this.examService.getById(args.id);
+  }
+
+  @McpTool({
+    name: 'lms.exams.create',
+    description: 'Creates a new exam.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Exam title (required, max 255)' },
+        code: { type: 'string', description: 'Exam code (max 32)' },
+        minScore: { type: 'number', description: 'Minimum passing score' },
+        timeLimit: { type: 'number', description: 'Time limit in minutes' },
+        shuffle: { type: 'boolean', description: 'Whether to shuffle questions' },
+        showAnswerKeyAfterFinish: { type: 'boolean', description: 'Whether to show answer key after submission' },
+        level: { type: 'string', description: 'Difficulty level (beginner|intermediate|advanced)' },
+        status: { type: 'string', description: 'Status (draft|published|closed|archived)' },
+      },
+      required: ['title'],
+    },
+  })
+  async createExam(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.examService.create(args as any);
+  }
+
+  @McpTool({
+    name: 'lms.exams.update',
+    description: 'Updates an existing exam.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Exam ID' },
+        title: { type: 'string', description: 'Exam title' },
+        minScore: { type: 'number', description: 'Minimum passing score' },
+        timeLimit: { type: 'number', description: 'Time limit in minutes' },
+        shuffle: { type: 'boolean', description: 'Whether to shuffle questions' },
+        showAnswerKeyAfterFinish: { type: 'boolean', description: 'Whether to show answer key after submission' },
+        level: { type: 'string', description: 'Difficulty level' },
+        status: { type: 'string', description: 'Status (draft|published|closed|archived)' },
+      },
+      required: ['id'],
+    },
+  })
+  async updateExam(args: { id: number; [key: string]: any }, _context: McpContext): Promise<any> {
+    const { id, ...dto } = args;
+    return this.examService.update(id, dto as any);
+  }
+
+  @McpTool({
+    name: 'lms.exams.delete',
+    description: 'Removes an exam by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Exam ID' },
+      },
+      required: ['id'],
+    },
+  })
+  async deleteExam(args: { id: number }, _context: McpContext): Promise<any> {
+    return this.examService.remove(args.id);
+  }
+
+  // ── Question Subjects ────────────────────────────────────────────────────────
+
+  @McpTool({
+    name: 'lms.exams.question-subjects.list',
+    description: 'Lists question subjects (topics) available for exam questions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page: { type: 'number', description: 'Page number' },
+        pageSize: { type: 'number', description: 'Items per page' },
+        search: { type: 'string', description: 'Search term' },
+      },
+    },
+    readOnly: true,
+  })
+  async listQuestionSubjects(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.examService.listQuestionSubjects(args);
+  }
+
+  @McpTool({
+    name: 'lms.exams.question-subjects.create',
+    description: 'Creates a new question subject.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Subject name (required)' },
+      },
+      required: ['name'],
+    },
+  })
+  async createQuestionSubject(args: Record<string, any>, _context: McpContext): Promise<any> {
+    return this.examService.createQuestionSubject(args as any);
+  }
+
+  // ── Questions ────────────────────────────────────────────────────────────────
+
+  @McpTool({
+    name: 'lms.exams.questions.list',
+    description: 'Lists all questions for an exam.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Exam ID' },
+      },
+      required: ['id'],
+    },
+    readOnly: true,
+  })
+  async listQuestions(args: { id: number }, _context: McpContext): Promise<any> {
+    return this.examService.listQuestions(args.id);
+  }
+
+  @McpTool({
+    name: 'lms.exams.questions.create',
+    description: 'Creates a new question for an exam.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Exam ID' },
+        text: { type: 'string', description: 'Question text (required)' },
+        type: { type: 'string', description: 'Question type (required): multiple_choice|true_false|essay|fill_blank|matching' },
+        points: { type: 'number', description: 'Points for this question' },
+        subjectId: { type: 'number', description: 'Question subject ID' },
+        alternatives: {
+          type: 'array',
+          description: 'Answer alternatives (for multiple_choice/true_false)',
+          items: {
+            type: 'object',
+            properties: {
+              text: { type: 'string' },
+              isCorrect: { type: 'boolean' },
+            },
+          },
+        },
+      },
+      required: ['id', 'text', 'type'],
+    },
+  })
+  async createQuestion(args: { id: number; [key: string]: any }, _context: McpContext): Promise<any> {
+    const { id, ...dto } = args;
+    return this.examService.createQuestion(id, dto as any);
+  }
+
+  @McpTool({
+    name: 'lms.exams.questions.update',
+    description: 'Updates a question in an exam.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Exam ID' },
+        questionId: { type: 'number', description: 'Question ID' },
+        text: { type: 'string', description: 'Question text' },
+        points: { type: 'number', description: 'Points for this question' },
+        alternatives: { type: 'array', description: 'Answer alternatives', items: { type: 'object' } },
+      },
+      required: ['id', 'questionId'],
+    },
+  })
+  async updateQuestion(args: { id: number; questionId: number; [key: string]: any }, _context: McpContext): Promise<any> {
+    const { id, questionId, ...dto } = args;
+    return this.examService.updateQuestion(id, questionId, dto as any);
+  }
+
+  @McpTool({
+    name: 'lms.exams.questions.delete',
+    description: 'Removes a question from an exam.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Exam ID' },
+        questionId: { type: 'number', description: 'Question ID' },
+      },
+      required: ['id', 'questionId'],
+    },
+  })
+  async deleteQuestion(args: { id: number; questionId: number }, _context: McpContext): Promise<any> {
+    return this.examService.removeQuestion(args.id, args.questionId);
+  }
+
+  @McpTool({
+    name: 'lms.exams.questions.reorder',
+    description: 'Reorders questions within an exam.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Exam ID' },
+        questionIds: { type: 'array', description: 'Question IDs in the desired order', items: { type: 'number' } },
+      },
+      required: ['id', 'questionIds'],
+    },
+  })
+  async reorderQuestions(args: { id: number; questionIds: number[] }, _context: McpContext): Promise<any> {
+    return this.examService.reorderQuestions(args.id, args.questionIds);
+  }
+
+  // ── Attempts ─────────────────────────────────────────────────────────────────
+
+  @McpTool({
+    name: 'lms.exams.attempt.get',
+    description: 'Returns the current attempt state for an exam for the authenticated user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        examId: { type: 'number', description: 'Exam ID' },
+        studentId: { type: 'number', description: 'Student person ID (admin use; defaults to authenticated user)' },
+      },
+      required: ['examId'],
+    },
+    readOnly: true,
+  })
+  async getAttemptState(args: { examId: number; studentId?: number }, context: McpContext): Promise<any> {
+    return this.examAttemptService.getAttemptState(args.examId, context.userId, args.studentId);
+  }
+
+  @McpTool({
+    name: 'lms.exams.attempt.start',
+    description: 'Starts a new exam attempt for the authenticated user.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        examId: { type: 'number', description: 'Exam ID' },
+        studentId: { type: 'number', description: 'Student person ID (for admin-initiated attempts)' },
+      },
+      required: ['examId'],
+    },
+  })
+  async startAttempt(args: { examId: number; [key: string]: any }, context: McpContext): Promise<any> {
+    const { examId, ...dto } = args;
+    return this.examAttemptService.startAttempt(examId, context.userId, 'mcp', dto as any);
+  }
+
+  @McpTool({
+    name: 'lms.exams.attempt.save-answers',
+    description: 'Saves answers for an in-progress exam attempt.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        examId: { type: 'number', description: 'Exam ID' },
+        attemptId: { type: 'number', description: 'Attempt ID' },
+        answers: {
+          type: 'array',
+          description: 'Answers array',
+          items: {
+            type: 'object',
+            properties: {
+              questionId: { type: 'number' },
+              selectedAlternativeId: { type: 'number' },
+              essayAnswer: { type: 'string' },
+            },
+          },
+        },
+      },
+      required: ['examId', 'attemptId', 'answers'],
+    },
+  })
+  async saveAnswers(args: { examId: number; attemptId: number; answers: any[] }, context: McpContext): Promise<any> {
+    return this.examAttemptService.saveAnswers(args.examId, args.attemptId, context.userId, { answers: args.answers } as any);
+  }
+
+  @McpTool({
+    name: 'lms.exams.attempt.submit',
+    description: 'Submits an exam attempt for grading.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        examId: { type: 'number', description: 'Exam ID' },
+        attemptId: { type: 'number', description: 'Attempt ID' },
+        answers: {
+          type: 'array',
+          description: 'Final answers (optional — include to save before submitting)',
+          items: { type: 'object' },
+        },
+      },
+      required: ['examId', 'attemptId'],
+    },
+  })
+  async submitAttempt(args: { examId: number; attemptId: number; [key: string]: any }, context: McpContext): Promise<any> {
+    const { examId, attemptId, ...dto } = args;
+    return this.examAttemptService.submitAttempt(examId, attemptId, context.userId, dto as any);
+  }
+}

package/src/exam/exam.module.ts

@@ -2,13 +2,14 @@ import { PrismaModule } from '@hed-hog/api-prisma';
 import { forwardRef, Module } from '@nestjs/common';
 import { ExamAttemptController } from './exam-attempt.controller';
 import { ExamAttemptService } from './exam-attempt.service';
+import { LmsExamMcpTools } from './exam.mcp-tools';
 import { ExamController } from './exam.controller';
 import { ExamService } from './exam.service';
 
 @Module({
   imports: [forwardRef(() => PrismaModule)],
   controllers: [ExamController, ExamAttemptController],
-  providers: [ExamService, ExamAttemptService],
+  providers: [ExamService, ExamAttemptService, LmsExamMcpTools],
   exports: [forwardRef(() => ExamService), forwardRef(() => ExamAttemptService)],
 })
 export class ExamModule {}

package/src/exam/exam.service.ts

@@ -10,6 +10,7 @@ import {
     type ExamQuestionType,
 } from './dto/create-exam-question.dto';
 import { CreateExamDto } from './dto/create-exam.dto';
+import { CreateQuestionSubjectDto } from './dto/create-question-subject.dto';
 import { UpdateExamQuestionDto } from './dto/update-exam-question.dto';
 import { UpdateExamDto } from './dto/update-exam.dto';
 
@@ -17,6 +18,84 @@ import { UpdateExamDto } from './dto/update-exam.dto';
 export class ExamService {
   constructor(private readonly prisma: PrismaService) {}
 
+  async listQuestionSubjects(params: {
+    page?: number;
+    pageSize?: number;
+    search?: string;
+  }) {
+    const page = Math.max(Number(params.page) || 1, 1);
+    const pageSize = Math.max(Number(params.pageSize) || 20, 1);
+    const skip = (page - 1) * pageSize;
+    const search = params.search?.trim();
+
+    const where = {
+      ...(search
+        ? {
+            OR: [
+              { name: { contains: search, mode: 'insensitive' as const } },
+              {
+                description: {
+                  contains: search,
+                  mode: 'insensitive' as const,
+                },
+              },
+            ],
+          }
+        : {}),
+    };
+
+    const [subjects, total] = await Promise.all([
+      this.prisma.question_subject.findMany({
+        where,
+        skip,
+        take: pageSize,
+        orderBy: { name: 'asc' },
+      }),
+      this.prisma.question_subject.count({ where }),
+    ]);
+
+    return {
+      total,
+      page,
+      pageSize,
+      lastPage: Math.max(1, Math.ceil(total / pageSize)),
+      data: subjects.map((subject) => ({
+        id: subject.id,
+        name: subject.name,
+        description: subject.description,
+      })),
+    };
+  }
+
+  async createQuestionSubject(dto: CreateQuestionSubjectDto) {
+    const name = dto.name.trim();
+    if (!name) {
+      throw new BadRequestException('Question subject name is required');
+    }
+
+    const existing = await this.prisma.question_subject.findFirst({
+      where: { name: { equals: name, mode: 'insensitive' } },
+      select: { id: true },
+    });
+
+    if (existing) {
+      throw new BadRequestException('Question subject already exists');
+    }
+
+    const subject = await this.prisma.question_subject.create({
+      data: {
+        name,
+        description: dto.description?.trim() || null,
+      },
+    });
+
+    return {
+      id: subject.id,
+      name: subject.name,
+      description: subject.description,
+    };
+  }
+
   async list(params: {
     page?: number;
     pageSize?: number;
@@ -132,6 +211,7 @@ export class ExamService {
           include: {
             question: {
               include: {
+                question_subject: true,
                 exam_option: {
                   orderBy: { position: 'asc' },
                 },
@@ -163,6 +243,15 @@ export class ExamService {
       throw new NotFoundException('Exam not found');
     }
 
+    const subject = await this.prisma.question_subject.findUnique({
+      where: { id: dto.subjectId },
+      select: { id: true },
+    });
+
+    if (!subject) {
+      throw new NotFoundException('Question subject not found');
+    }
+
     const last = await this.prisma.exam_question.findFirst({
       where: { exam_id: examId },
       orderBy: { order: 'desc' },
@@ -193,8 +282,10 @@ export class ExamService {
     const created = await this.prisma.$transaction(async (tx) => {
       const question = await tx.question.create({
         data: {
+          question_subject_id: dto.subjectId,
           question_type: questionType,
           statement: dto.statement,
+          explanation: dto.explanation ?? null,
           points: dto.points,
         },
       });
@@ -233,6 +324,7 @@ export class ExamService {
         include: {
           question: {
             include: {
+              question_subject: true,
               exam_option: {
                 orderBy: { position: 'asc' },
               },
@@ -270,6 +362,17 @@ export class ExamService {
       throw new NotFoundException('Question not found in exam');
     }
 
+    if (dto.subjectId !== undefined) {
+      const subject = await this.prisma.question_subject.findUnique({
+        where: { id: dto.subjectId },
+        select: { id: true },
+      });
+
+      if (!subject) {
+        throw new NotFoundException('Question subject not found');
+      }
+    }
+
     const nextQuestionType = this.resolveQuestionType(
       dto.questionType ?? relation.question.question_type,
     );
@@ -317,10 +420,16 @@ export class ExamService {
       await tx.question.update({
         where: { id: relation.question_id },
         data: {
+          ...(dto.subjectId !== undefined && {
+            question_subject_id: dto.subjectId,
+          }),
           ...(dto.questionType !== undefined && {
             question_type: nextQuestionType,
           }),
           ...(dto.statement !== undefined && { statement: dto.statement }),
+          ...(dto.explanation !== undefined && {
+            explanation: dto.explanation,
+          }),
           ...(dto.points !== undefined && { points: dto.points }),
         },
       });
@@ -356,6 +465,7 @@ export class ExamService {
         include: {
           question: {
             include: {
+              question_subject: true,
               exam_option: {
                 orderBy: { position: 'asc' },
               },
@@ -433,6 +543,8 @@ export class ExamService {
         min_score: this.scoreFromTen(dto.minScore ?? 7),
         time_limit_minutes: dto.timeLimit ?? 60,
         shuffle_questions: dto.shuffle ?? false,
+        show_answer_key: dto.showAnswerKeyAfterFinish ?? false,
+        level: dto.level ?? 'beginner',
         ...(dto.primaryColor !== undefined && {
           primary_color: dto.primaryColor,
         }),
@@ -468,6 +580,10 @@ export class ExamService {
         ...(dto.shuffle !== undefined && {
           shuffle_questions: dto.shuffle,
         }),
+        ...(dto.showAnswerKeyAfterFinish !== undefined && {
+          show_answer_key: dto.showAnswerKeyAfterFinish,
+        }),
+        ...(dto.level !== undefined && { level: dto.level }),
         ...(dto.primaryColor !== undefined && {
           primary_color: dto.primaryColor,
         }),
@@ -520,9 +636,11 @@ export class ExamService {
       id: exam.id,
       code: this.idToCode(exam.id),
       title: exam.title,
+      level: exam.level,
       minScore: this.scoreToTen(exam.min_score ?? 0),
       timeLimit: exam.time_limit_minutes ?? 0,
       shuffle: Boolean(exam.shuffle_questions),
+      showAnswerKeyAfterFinish: Boolean(exam.show_answer_key ?? false),
       status: exam.status,
       questions: exam._count?.exam_question ?? 0,
       attempts: exam._count?.exam_attempt ?? 0,
@@ -544,7 +662,10 @@ export class ExamService {
       examQuestionId: item.id,
       order: item.order,
       questionType,
+      subjectId: item.question.question_subject_id,
+      subjectName: item.question.question_subject?.name ?? null,
       statement: item.question.statement,
+      explanation: item.question.explanation ?? null,
       points: item.question.points,
       fillBlankAnswers: parsedOptions.fillBlankAnswers,
       matchingPairs: parsedOptions.matchingPairs,

package/src/index.ts

@@ -1,6 +1,15 @@
+export * from './achievement/achievement.controller';
+export * from './achievement/achievement.module';
+export * from './achievement/achievement.service';
+export * from './bitcode-wallet/bitcode-wallet.controller';
+export * from './bitcode-wallet/bitcode-wallet.module';
+export * from './bitcode-wallet/bitcode-wallet.service';
 export * from './class-group/class-group.controller';
 export * from './class-group/class-group.module';
 export * from './class-group/class-group.service';
+export * from './course-lesson-note/course-lesson-note.controller';
+export * from './course-lesson-note/course-lesson-note.module';
+export * from './course-lesson-note/course-lesson-note.service';
 export * from './course/course-structure.controller';
 export * from './course/course-structure.service';
 export * from './course/course.controller';