完成 helper 系统的 api 定义

helper/api/Question-问题.md

@@ -0,0 +1,93 @@
+# QUESTION - 题库
+
+> url 前缀：**question**
+>
+> 示例：**https://xxxxxxxxx/api/question**
+
+## 获得题目列表
+
+[TEACHER]
+
+```http
+get /
+```
+
+### Parameters
+
+| Name | Type    | Description  |
+| ---- | ------- | ------------ |
+| stem | string? | 模糊查找题目 |
+| size | number  | 页面展示条数 |
+| page | number  | 当前页码     |
+| sort | string? | 排序方式     |
+
+### Response
+
+```ts
+interface ResponseBody {
+  questions: QuestionSerializer[];
+  page: PageSerializer;
+}
+```
+
+see [QuestionSerializer](../serializer/QuestionSerializer.md), [PageSerializer](../serializer/PageSerializer.md)
+
+## 获得题目详情
+
+[TEACHER]
+
+```http
+get /:questionId
+```
+
+### Response
+
+```ts
+QuestionSerializer;
+```
+
+see [QuestionSerializer](../serializer/QuestionSerializer.md)
+
+## 创建题目
+
+[TEACHER]
+
+```http
+post /
+```
+
+### Parameters
+
+```ts
+interface QuestionDTO extends Omit<QuestionSerializer, "id"> {}
+```
+
+### Response
+
+```ts
+QuestionSerializer;
+```
+
+see [QuestionSerializer](../serializer/QuestionSerializer.md)
+
+## 更新题目
+
+[TEACHER]
+
+```http
+put /:questionId
+```
+
+### Parameters
+
+```ts
+QuestionSerializer;
+```
+
+### Response
+
+```ts
+QuestionSerializer;
+```
+
+see [QuestionSerializer](../serializer/QuestionSerializer.md)

helper/api/Quiz-测试.md

@@ -0,0 +1,114 @@
+# QUIZ - 测试
+
+> url 前缀：**quiz**
+>
+> 示例：**https://xxxxxxxxx/api/quiz**
+
+## 获得测试列表
+
+`TEACHER`, `STUDENT`
+
+```http
+get /
+```
+
+### Parameters
+
+| Name      | Type      | Description                |
+| --------- | --------- | -------------------------- |
+| slideId   | string    | slide id                   |
+| subscribe | boolean   | 学生订阅（学生相关）的测试 |
+| state     | QuizState | 测试状态                   |
+| size      | number    | 页面展示条数               |
+| page      | number    | 当前页码                   |
+| sort      | string?   | 排序方式                   |
+
+### Response
+
+```ts
+interface ResponseData {
+  quizs: QuizSerializer[];
+  page: PageSerializer;
+}
+```
+
+## 获得某一测试的详细内容
+
+`TEACHER`, `STUDENT`
+
+```http
+get /:quizId
+```
+
+### Response
+
+```ts
+QuizSerializer;
+```
+
+## 创建测试
+
+`TEACHER`, `STUDENT`
+
+```http
+post /
+```
+
+### Parameter
+
+`TEACHER`, `STUDENT`
+
+```ts
+interface QuizDTO {
+  name: string; // 测试名
+  quizTime: SlideState; // 测试时间
+  slideId: number; // 幻灯片 id
+  questions: number[]; // 题目 id;
+}
+```
+
+## 修改测试 (仅限未开始时可以修改)
+
+```http
+put /:quizId
+```
+
+### Parameter
+
+```ts
+interface QuizUpdateDTO {
+  id: number;
+  name: string; // 测试名
+  quizTime: SlideState; // 测试时间
+  slideId: number; // 幻灯片 id
+  questions: number[]; // 题目 id;
+}
+```
+
+## 提交答案
+
+```http
+put /:quizId/student-answer
+```
+
+### Parameter
+
+```ts
+interface AnswerDTO {
+  answers: QuestionWithStudentAnswerSerializer[];
+}
+```
+
+## 获得测试结果统计
+
+```http
+get /:quizId/result
+```
+
+### Parameter
+
+```ts
+interface Result {
+  avarage: number; // 平均值
+}
+```

helper/serializer/PageSerializer.md

@@ -0,0 +1,14 @@
+# 分页
+
+分页数据详情
+
+## Attribute
+
+```ts
+interface PageSerializer {
+  size: number;
+  totalElements: number;
+  totalPages: number;
+  number: number;
+}
+```

helper/serializer/QuestionSerializer.md

@@ -0,0 +1,52 @@
+# QuestionSerializer
+
+问题的详细定义
+
+## Attribute
+
+```ts
+type QuestionSerializer =
+  | ChoiceQuestionSerializer
+  | TrueOrFalseQuestionSerializer;
+
+type QuestionWithoutAnswerSerializer = Omit<
+  QuestionSerializer,
+  "answer" | "analysis"
+>;
+
+type QuestionWithStudentAnswerSerializer =
+  | ChoiceQuestionWithStudentAnswer
+  | TrueOrFalseQuestionWithStudentAnswer;
+
+interface Question {
+  id: number; // 题目id
+  kind: "CHOICE" | "TRUE_FALSE";
+  stem: string; // 题干
+}
+
+interface ChoiceQuestionSerializer extends Question {
+  kind: "CHOICE";
+  options: {
+    [key: string]: string;
+  };
+  answer: string; // 答案 [与 options 的 key 一致]
+  analysis?: string; // 解析
+}
+
+interface ChoiceQuestionWithStudentAnswer extends ChoiceQuestionSerializer {
+  studentAnswer: string;
+  pass: boolean; // 是否正确
+}
+
+interface TrueOrFalseQuestionSerializer extends Question {
+  kind: "TRUE_FALSE";
+  answer: boolean; // 答案
+  analysis?: string; // 解析
+}
+
+interface TrueOrFalseQuestionWithStudentAnswer
+  extends TrueOrFalseQuestionSerializer {
+  studentAnswer: boolean;
+  pass: boolean; // 是否正确
+}
+```

helper/serializer/QuizSerializer.md

@@ -0,0 +1,38 @@
+# QuizSerializer
+
+测试
+
+## Attribute
+
+```ts
+/** 已实现的枚举类 */
+type SlideState =
+  | "DRAFT"
+  | "BEFORE_CLASS" // 课前
+  | "IN_CLASS" // 课中
+  | "AFTER_CLASS" // 课后
+  | "FINISH"; // 最终截止
+
+type QuizState =
+  | "NOT_STARTED" // 未开始
+  | "ONGOING" // 正在进行
+  | "CLOSED"; // 已结束
+
+interface QuizSerializer<T extends QuizState> {
+  id: number;
+  name: string; // 测试名
+  state: T; // 考试状态
+  course: CourseSerializer; // 课程详情
+  quizTime: SlideState;
+  slide: SlideSerializer;
+  questions: Array<
+    T extends "CLOSED"
+      ? QuestionWithStudentAnswerSerializer
+      : QuestionWithoutAnswerSerializer
+  >;
+}
+
+interface QuizBasicSerialzer extends Omit<QuizSerialzier, "questions"> {
+  questionNumber: number; // 题目数量
+}
+```