优化问卷回答界面及功能
This commit is contained in:
zlwu committed
1 parent
1ab9f9c458
commit
ed5eb9ca52
13 files changed
+6122
-86
No files matched your search
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,771 @@
|
||||
# API 接口文档
|
||||
|
||||
## 文档说明
|
||||
|
||||
本文档记录项目所有的 API 接口信息，包括请求方式、参数说明、响应格式等。所有接口遵循 RESTful 设计规范。
|
||||
|
||||
### 基础信息
|
||||
|
||||
- **基础路径**: `/api`
|
||||
- **响应格式**: JSON
|
||||
- **字符编码**: UTF-8
|
||||
- **权限认证**: Sa-Token + JWT
|
||||
- **版本**: v1.0
|
||||
|
||||
### 统一响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
#### 状态码说明
|
||||
|
||||
| 状态码 | 说明 | 备注 |
|
||||
| ------ | ---------- | ---------------------- |
|
||||
| 200 | 成功 | 请求成功 |
|
||||
| 400 | 参数错误 | 请求参数格式或内容错误 |
|
||||
| 401 | 未认证 | 需要登录 |
|
||||
| 403 | 无权限 | 无访问权限 |
|
||||
| 404 | 不存在 | 请求的资源不存在 |
|
||||
| 500 | 服务器错误 | 内部服务器错误 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问卷管理 API
|
||||
|
||||
### 1.1 问卷基础管理
|
||||
|
||||
#### 查询问卷列表
|
||||
|
||||
**接口地址**: `GET /hq/satSurvey/list`
|
||||
|
||||
**接口描述**: 分页查询问卷列表，支持权限过滤
|
||||
|
||||
**权限要求**: `hq:satSurvey:list`
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
| ----------- | ------ | ---- | --------------------- |
|
||||
| pageNum | int | 否 | 页码，默认 1 |
|
||||
| pageSize | int | 否 | 页大小，默认 10 |
|
||||
| surveyCode | string | 否 | 问卷编号 |
|
||||
| surveyTitle | string | 否 | 问卷标题 |
|
||||
| targetGroup | string | 否 | 目标群体 |
|
||||
| status | string | 否 | 问卷状态 |
|
||||
| isPublished | int | 否 | 是否发布（1 是 0 否） |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": {
|
||||
"total": 100,
|
||||
"rows": [
|
||||
{
|
||||
"id": 1,
|
||||
"surveyCode": "SURVEY001",
|
||||
"surveyTitle": "满意度调查",
|
||||
"surveyDesc": "学生满意度调查",
|
||||
"targetGroup": "1",
|
||||
"startTime": "2025-01-01 00:00:00",
|
||||
"endTime": "2025-01-31 23:59:59",
|
||||
"isAnonymous": 1,
|
||||
"isPublished": 1,
|
||||
"status": "1"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取问卷详情
|
||||
|
||||
**接口地址**: `GET /hq/satSurvey/{id}`
|
||||
|
||||
**接口描述**: 根据 ID 获取问卷详细信息
|
||||
|
||||
**权限要求**: `hq:satSurvey:query`
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
| ------ | ---- | ---- | ------- |
|
||||
| id | long | 是 | 问卷 ID |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"surveyCode": "SURVEY001",
|
||||
"surveyTitle": "满意度调查",
|
||||
"surveyDesc": "学生满意度调查",
|
||||
"surveyInstruction": "请认真填写",
|
||||
"targetGroup": "1",
|
||||
"startTime": "2025-01-01 00:00:00",
|
||||
"endTime": "2025-01-31 23:59:59",
|
||||
"maxSubmitTimes": 1,
|
||||
"isAnonymous": 1,
|
||||
"isPublished": 1,
|
||||
"status": "1",
|
||||
"remark": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 新增问卷
|
||||
|
||||
**接口地址**: `POST /hq/satSurvey`
|
||||
|
||||
**接口描述**: 创建新的问卷
|
||||
|
||||
**权限要求**: `hq:satSurvey:add`
|
||||
|
||||
**请求参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"surveyCode": "SURVEY001",
|
||||
"surveyTitle": "满意度调查",
|
||||
"surveyDesc": "学生满意度调查",
|
||||
"surveyInstruction": "请认真填写",
|
||||
"targetGroup": "1",
|
||||
"startTime": "2025-01-01 00:00:00",
|
||||
"endTime": "2025-01-31 23:59:59",
|
||||
"maxSubmitTimes": 1,
|
||||
"isAnonymous": 1,
|
||||
"remark": ""
|
||||
}
|
||||
```
|
||||
|
||||
#### 修改问卷
|
||||
|
||||
**接口地址**: `PUT /hq/satSurvey`
|
||||
|
||||
**接口描述**: 修改问卷信息
|
||||
|
||||
**权限要求**: `hq:satSurvey:edit`
|
||||
|
||||
#### 删除问卷
|
||||
|
||||
**接口地址**: `DELETE /hq/satSurvey/{ids}`
|
||||
|
||||
**接口描述**: 批量删除问卷
|
||||
|
||||
**权限要求**: `hq:satSurvey:remove`
|
||||
|
||||
#### 发布问卷
|
||||
|
||||
**接口地址**: `PUT /hq/satSurvey/{id}/publish`
|
||||
|
||||
**接口描述**: 发布问卷，将状态改为进行中
|
||||
|
||||
**权限要求**: `hq:satSurvey:publish`
|
||||
|
||||
#### 撤销发布问卷
|
||||
|
||||
**接口地址**: `PUT /hq/satSurvey/{id}/unpublish`
|
||||
|
||||
**接口描述**: 撤销发布问卷，将状态改为草稿
|
||||
|
||||
**权限要求**: `hq:satSurvey:unpublish`
|
||||
|
||||
### 1.2 问卷题目管理
|
||||
|
||||
#### 获取问卷题目列表
|
||||
|
||||
**接口地址**: `GET /hq/satSurvey/{surveyId}/questions`
|
||||
|
||||
**接口描述**: 获取问卷关联的题目列表，包含题目详细信息和选项
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
| -------- | ---- | ---- | ------- |
|
||||
| surveyId | long | 是 | 问卷 ID |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"surveyId": 1,
|
||||
"questionId": 1,
|
||||
"sortOrder": 1,
|
||||
"weight": 1,
|
||||
"isRequired": 1,
|
||||
"questionTitle": "您对服务质量的评价？",
|
||||
"questionType": "1",
|
||||
"questionDesc": "请选择一个选项",
|
||||
"options": [
|
||||
{
|
||||
"id": 1,
|
||||
"questionId": 1,
|
||||
"optionValue": "A",
|
||||
"optionText": "非常满意",
|
||||
"optionScore": 5,
|
||||
"sortOrder": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 更新问卷题目关联
|
||||
|
||||
**接口地址**: `PUT /hq/satSurvey/{surveyId}/questions`
|
||||
|
||||
**接口描述**: 批量更新问卷题目关联关系
|
||||
|
||||
**权限要求**: `hq:satSurvey:question`
|
||||
|
||||
---
|
||||
|
||||
## 2. 答题 API（新增）
|
||||
|
||||
### 2.1 答题提交
|
||||
|
||||
#### 提交问卷答案
|
||||
|
||||
**接口地址**: `POST /hq/satSurvey/answer/submit`
|
||||
|
||||
**接口描述**: 提交问卷答案，正式提交后不可修改
|
||||
|
||||
**权限要求**: 需要登录
|
||||
|
||||
**请求参数**:
|
||||
|
||||
```json
|
||||
{
|
||||
"surveyId": 1,
|
||||
"startTime": "2025-01-26T14:00:00.000Z",
|
||||
"endTime": "2025-01-26T14:15:00.000Z",
|
||||
"isAnonymous": 1,
|
||||
"answers": [
|
||||
{
|
||||
"questionId": 1,
|
||||
"questionType": "1",
|
||||
"answerValue": "A",
|
||||
"options": [
|
||||
{
|
||||
"optionId": 1,
|
||||
"optionValue": "A",
|
||||
"optionText": "非常满意",
|
||||
"isSelected": true
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"questionId": 2,
|
||||
"questionType": "2",
|
||||
"answerValue": "A,C,D",
|
||||
"options": [
|
||||
{
|
||||
"optionId": 2,
|
||||
"optionValue": "A",
|
||||
"optionText": "选项A",
|
||||
"isSelected": true
|
||||
},
|
||||
{
|
||||
"optionId": 4,
|
||||
"optionValue": "C",
|
||||
"optionText": "选项C",
|
||||
"isSelected": true
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"questionId": 3,
|
||||
"questionType": "3",
|
||||
"answerValue": "这是我的意见和建议内容",
|
||||
"options": []
|
||||
}
|
||||
],
|
||||
"remark": ""
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
| ----------- | ------ | ---- | ----------------------------- |
|
||||
| surveyId | long | 是 | 问卷 ID |
|
||||
| startTime | string | 是 | 答题开始时间（ISO 8601 格式） |
|
||||
| endTime | string | 是 | 答题结束时间（ISO 8601 格式） |
|
||||
| isAnonymous | int | 是 | 是否匿名（1 是 0 否） |
|
||||
| answers | array | 是 | 答案列表 |
|
||||
| remark | string | 否 | 备注 |
|
||||
|
||||
**answers 中每项参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
| ------------ | ------ | ---- | ------------------------------------------------ |
|
||||
| questionId | long | 是 | 题目 ID |
|
||||
| questionType | string | 是 | 题目类型（1 单选题 2 多选题 3 问答题） |
|
||||
| answerValue | string | 是 | 答案值（单选存选项值，多选逗号分隔，问答存文本） |
|
||||
| options | array | 否 | 选项详情（单选题和多选题需要） |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "答题提交成功",
|
||||
"data": {
|
||||
"id": 1001,
|
||||
"surveyId": 1,
|
||||
"userId": 1,
|
||||
"userType": "student",
|
||||
"submitTime": "2025-01-26T14:15:00.000Z",
|
||||
"totalScore": 0,
|
||||
"avgScore": 0,
|
||||
"remark": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**多次提交功能说明**（v1.0.3 新增，v1.0.4 优化）:
|
||||
|
||||
系统支持问卷多次提交功能，提交次数限制由问卷的 `max_submit_times` 字段控制：
|
||||
|
||||
1. **提交次数规则**:
|
||||
|
||||
- `max_submit_times = 0`: 不限制提交次数，用户可以无限次提交
|
||||
- `max_submit_times = 1`: 最多提交 1 次（默认行为，向后兼容）
|
||||
- `max_submit_times = N`: 最多提交 N 次
|
||||
|
||||
2. **数据存储策略**（v1.0.4 重要更新）:
|
||||
|
||||
- **软删除历史数据**: 用户提交新答案时，系统会自动将之前的答题记录标记为已删除（deleted=1）
|
||||
- **保持数据完整性**: 历史数据完整保留用于审计，但业务查询只返回最新有效数据
|
||||
- **关联删除**: 通过 record_id 关联，确保 hq_sat_record、hq_sat_detail、hq_sat_answer 三表数据状态同步
|
||||
|
||||
3. **数据状态管理**:
|
||||
|
||||
- `deleted = 0`: 有效数据，正常业务查询可见
|
||||
- `deleted = 1`: 历史数据，仅审计查询可见
|
||||
- 用户每次只能看到最新的有效答题记录
|
||||
|
||||
4. **处理流程**:
|
||||
|
||||
```
|
||||
用户提交新答案 → 标记历史数据为删除 → 保存新答题数据 → 返回最新记录
|
||||
```
|
||||
|
||||
5. **错误处理**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 500,
|
||||
"msg": "您已达到该问卷的最大提交次数限制（3次）",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
6. **使用场景**:
|
||||
|
||||
- **单次提交**: 正式考试、重要调研等
|
||||
- **多次提交**: 练习测试、阶段性评估等
|
||||
- **无限提交**: 学习练习、反馈收集等
|
||||
|
||||
7. **业务优势**:
|
||||
- ✅ **用户体验**: 查看答题记录始终是最新版本
|
||||
- ✅ **数据审计**: 历史记录完整保留，支持数据回溯
|
||||
- ✅ **查询性能**: 业务查询只涉及有效数据，提高效率
|
||||
- ✅ **数据一致性**: 避免多版本数据混乱问题
|
||||
|
||||
**数据保存说明**:
|
||||
|
||||
此接口在保存答题记录时，会同时保存详细的答案信息到两个表：
|
||||
|
||||
1. **hq_sat_detail 表**：保存答题概要信息
|
||||
|
||||
- 记录答题记录 ID、题目 ID、答案分数等基础信息
|
||||
- remark 字段存储答案内容的摘要信息
|
||||
|
||||
2. **hq_sat_answer 表**：保存具体的答案详情（v1.0.1 新增，v1.0.2 修复）
|
||||
- **单选题**：为选中的选项创建一条记录，包含选项 ID、选项标识（A/B/C/D）、选项文本、真实分值
|
||||
- **多选题**：为每个选中的选项创建一条记录，使用选项标识区分不同选项
|
||||
- **问答题**：创建一条记录，选项相关字段为 NULL，答案值存储用户输入的文本内容
|
||||
|
||||
**hq_sat_answer 表数据示例**（v1.0.2 修复后）:
|
||||
|
||||
```sql
|
||||
-- 单选题答案记录（用户选择"非常满意"选项）
|
||||
INSERT INTO hq_sat_answer VALUES (
|
||||
1, '000000', 1001, NOW(), 1, NOW(), 0, -- 基础字段
|
||||
123, 1, '1', 1, 'A', '非常满意', 'A', 5, NULL -- 答案字段
|
||||
);
|
||||
|
||||
-- 多选题答案记录（用户选中A、C两个选项）
|
||||
INSERT INTO hq_sat_answer VALUES
|
||||
(2, '000000', 1001, NOW(), 1, NOW(), 0, 123, 2, '2', 1, 'A', '非常满意', 'A,C', 5, NULL),
|
||||
(3, '000000', 1001, NOW(), 1, NOW(), 0, 123, 2, '2', 3, 'C', '一般', 'A,C', 1, NULL);
|
||||
|
||||
-- 问答题答案记录
|
||||
INSERT INTO hq_sat_answer VALUES (
|
||||
4, '000000', 1001, NOW(), 1, NOW(), 0, -- 基础字段
|
||||
123, 3, '3', NULL, NULL, NULL, '这是我的意见和建议', 0, NULL -- 答案字段
|
||||
);
|
||||
```
|
||||
|
||||
**字段说明**（修复后）:
|
||||
|
||||
- `option_value`: 存储选项标识（A、B、C、D），便于统计分析
|
||||
- `answer_score`: 存储真实分值（从 hq_sat_option 表查询获得）
|
||||
- `answer_value`: 单选题存选项标识，多选题存逗号分隔的多个标识，问答题存文本
|
||||
|
||||
#### 保存问卷答案草稿
|
||||
|
||||
**接口地址**: `POST /hq/satSurvey/answer/draft`
|
||||
|
||||
**接口描述**: 保存问卷答案草稿，可多次保存和修改
|
||||
|
||||
**权限要求**: 需要登录
|
||||
|
||||
**请求参数**: 同提交问卷答案
|
||||
|
||||
**响应示例**: 同提交问卷答案
|
||||
|
||||
### 2.2 答题状态查询
|
||||
|
||||
#### 检查用户是否已答过问卷
|
||||
|
||||
**接口地址**: `GET /hq/satSurvey/{surveyId}/answered`
|
||||
|
||||
**接口描述**: 检查当前用户是否已经答过指定问卷（v1.0.3 更新：支持多次提交检查）
|
||||
|
||||
**权限要求**: 需要登录
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
| -------- | ---- | ---- | ------- |
|
||||
| surveyId | long | 是 | 问卷 ID |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": true
|
||||
}
|
||||
```
|
||||
|
||||
**响应说明**（v1.0.3 更新）:
|
||||
|
||||
- `data` 为 `true` 表示用户已答过该问卷（至少提交过 1 次）
|
||||
- `data` 为 `false` 表示用户未答过该问卷
|
||||
|
||||
**多次提交支持**:
|
||||
此接口仅返回用户是否有答题记录，不考虑提交次数限制。要检查是否还能继续提交，请参考以下逻辑：
|
||||
|
||||
- 如果 `max_submit_times = 0`：始终可以提交
|
||||
- 如果 `max_submit_times > 0`：需要检查用户提交次数是否小于此限制
|
||||
- 具体的提交限制检查由"提交问卷答案"接口在提交时进行
|
||||
|
||||
#### 获取用户问卷答题记录
|
||||
|
||||
**接口地址**: `GET /hq/satSurvey/{surveyId}/answer`
|
||||
|
||||
**接口描述**: 获取当前用户对指定问卷的答题记录（v1.0.5 重大更新：优化数据源，支持前端答案回显）
|
||||
|
||||
**权限要求**: 需要登录
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
| -------- | ---- | ---- | ------- |
|
||||
| surveyId | long | 是 | 问卷 ID |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": {
|
||||
"id": 1001,
|
||||
"surveyId": 1,
|
||||
"userId": 1,
|
||||
"userType": "student",
|
||||
"submitTime": "2025-01-26T14:15:00.000Z",
|
||||
"totalScore": 0,
|
||||
"avgScore": 0,
|
||||
"remark": "ANSWERS_DATA:[{\"questionId\":1,\"questionType\":\"1\",\"answerValue\":\"A\"},{\"questionId\":2,\"questionType\":\"2\",\"answerValue\":\"A,C\"}]"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回数据说明**（v1.0.5 重大更新）:
|
||||
|
||||
- 此接口只返回用户最新的有效答题记录（deleted=0）
|
||||
- 如果用户进行了多次提交，历史记录已被软删除，查询不到
|
||||
- 返回的是用户最后一次提交的完整答题信息
|
||||
- 历史记录完整保留在数据库中，仅用于审计目的
|
||||
|
||||
**v1.0.5 新增功能 - 答案回显数据**:
|
||||
|
||||
为支持前端答题界面的历史答案回显功能，此接口现在会在 `remark` 字段中包含格式化的答案数据：
|
||||
|
||||
1. **数据格式**: `ANSWERS_DATA:[答案JSON数组]`
|
||||
2. **数据来源**: 直接从 `hq_sat_answer` 表查询，比 v1.0.4 之前的 `remark` 解析更准确
|
||||
3. **答案结构**:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"questionId": 1,
|
||||
"questionType": "1",
|
||||
"answerValue": "A"
|
||||
},
|
||||
{
|
||||
"questionId": 2,
|
||||
"questionType": "2",
|
||||
"answerValue": "A,C"
|
||||
},
|
||||
{
|
||||
"questionId": 3,
|
||||
"questionType": "3",
|
||||
"answerValue": "用户输入的文本内容"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**前端答案回显逻辑**:
|
||||
|
||||
- **单选题** (`questionType = "1"`): `answerValue` 直接设置到单选控件（如 "A"）
|
||||
- **多选题** (`questionType = "2"`): `answerValue` 按逗号分割成数组（如 ["A", "C"]）
|
||||
- **问答题** (`questionType = "3"`): `answerValue` 直接设置到文本框
|
||||
|
||||
**使用场景**:
|
||||
|
||||
- ✅ **首次答题**: 返回 404，前端正常显示空表单
|
||||
- ✅ **重新答题**: 返回历史答案，前端自动回显到表单
|
||||
- ✅ **多次修改**: 基于上次答案继续编辑，提升用户体验
|
||||
|
||||
---
|
||||
|
||||
## 3. 题目管理 API
|
||||
|
||||
### 3.1 题目基础管理
|
||||
|
||||
#### 查询题目列表
|
||||
|
||||
**接口地址**: `GET /hq/satQuestion/list`
|
||||
|
||||
**权限要求**: `hq:satQuestion:list`
|
||||
|
||||
#### 获取题目选项
|
||||
|
||||
**接口地址**: `GET /hq/satQuestion/{questionId}/options`
|
||||
|
||||
**接口描述**: 获取指定题目的所有选项
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
| ---------- | ---- | ---- | ------- |
|
||||
| questionId | long | 是 | 题目 ID |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"questionId": 1,
|
||||
"optionValue": "A",
|
||||
"optionText": "非常满意",
|
||||
"optionScore": 5,
|
||||
"sortOrder": 1
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"questionId": 1,
|
||||
"optionValue": "B",
|
||||
"optionText": "满意",
|
||||
"optionScore": 4,
|
||||
"sortOrder": 2
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 答题记录管理 API
|
||||
|
||||
### 4.1 答题记录查询
|
||||
|
||||
#### 查询答题记录列表
|
||||
|
||||
**接口地址**: `GET /hq/satRecord/list`
|
||||
|
||||
**权限要求**: `hq:satRecord:list`
|
||||
|
||||
#### 获取答题记录详情
|
||||
|
||||
**接口地址**: `GET /hq/satRecord/{id}`
|
||||
|
||||
**权限要求**: `hq:satRecord:query`
|
||||
|
||||
---
|
||||
|
||||
## 5. 错误码说明
|
||||
|
||||
### 业务错误码
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
| ------ | ------------------ | ------------------------ |
|
||||
| 40001 | 问卷不存在 | 检查问卷 ID 是否正确 |
|
||||
| 40002 | 问卷未在进行中状态 | 等待问卷开始或联系管理员 |
|
||||
| 40003 | 您已经答过这份问卷 | 不能重复答题 |
|
||||
| 40004 | 答题记录保存失败 | 重新提交或联系技术支持 |
|
||||
| 40005 | 题目类型不支持 | 检查题目类型是否正确 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 数据字典
|
||||
|
||||
### 6.1 问卷状态
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
| --- | ------ | -------------- |
|
||||
| 0 | 草稿 | 未发布状态 |
|
||||
| 1 | 进行中 | 已发布，可答题 |
|
||||
| 2 | 已结束 | 超过结束时间 |
|
||||
|
||||
### 6.2 目标群体
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
| --- | ------ | ---------- |
|
||||
| 1 | 学生 | 在校学生 |
|
||||
| 2 | 教职工 | 教师和职工 |
|
||||
| 3 | 全体 | 所有人员 |
|
||||
|
||||
### 6.4 用户类型
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
| --- | ---------- | --------------------------------------------------------- |
|
||||
| 1 | 学生 | student、学生、stu 等角色映射为此值 |
|
||||
| 2 | 教师 | teacher、老师、教师、教职工、tea 等角色映射为此值 |
|
||||
| 3 | 超级管理员 | admin、管理员、超级管理员、administrator 等角色映射为此值 |
|
||||
|
||||
### 6.3 题目类型
|
||||
|
||||
| 值 | 说明 | 备注 |
|
||||
| --- | ------ | ---------------- |
|
||||
| 1 | 单选题 | 只能选择一个选项 |
|
||||
| 2 | 多选题 | 可以选择多个选项 |
|
||||
| 3 | 问答题 | 文本输入 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 版本更新记录
|
||||
|
||||
### v1.0.5 (2025-01-26)
|
||||
|
||||
- 🚀 **重大更新**：实现答题界面历史答案回显功能，提升多次答题用户体验
|
||||
- 🔧 **数据源优化**：`GET /hq/satSurvey/{surveyId}/answer` 接口改用 hq_sat_answer 表直接查询
|
||||
- 📊 新增 `getAnswersFromSatAnswerTable()` 方法，提供更准确的答案数据聚合
|
||||
- ✨ 前端新增 `loadPreviousAnswers()` 方法，支持三种题型的智能答案回显
|
||||
- 🎯 智能用户体验：只在成功加载历史答案时显示提示，异常时优雅降级
|
||||
- 🛡️ 错误处理优化：404 错误不显示提示，历史答案加载失败不阻断答题流程
|
||||
|
||||
### v1.0.4 (2025-01-26)
|
||||
|
||||
- 🔄 **重要优化**：多次提交时实现历史数据软删除，确保用户只有一份有效答题记录
|
||||
- 🗃️ 保留历史数据用于审计，但业务查询只返回最新有效数据
|
||||
- ⚡ 优化查询性能，提交次数统计和答题记录查询只涉及有效数据
|
||||
- 🛡️ 增强数据一致性，通过 record_id 关联确保三表数据状态同步
|
||||
|
||||
### v1.0.3 (2025-01-26)
|
||||
|
||||
- 🚀 **新功能**：实现问卷多次提交功能，支持根据 max_submit_times 设置控制提交次数
|
||||
- 📊 优化提交次数检查逻辑，支持 0=无限制、N=最大 N 次的灵活配置
|
||||
- ✅ 保留完整的答题历史记录，每次提交创建新的答题记录
|
||||
- 🎯 增强用户体验，提供详细的提交次数限制提示信息
|
||||
|
||||
### v1.0.2 (2025-01-26)
|
||||
|
||||
- 🔧 **重要修复**：修复单选题和多选题答案未记录到 hq_sat_answer 表的问题
|
||||
- 🎯 修复前端选项绑定使用分值导致的数据类型不匹配问题
|
||||
- ✅ 优化答案保存逻辑，正确存储选项标识（A、B、C、D）和分值
|
||||
- 📊 增强答案数据查询，支持选项分值自动计算
|
||||
- 🐛 修复多选题答案保存逻辑错误
|
||||
|
||||
### v1.0.1 (2025-01-26)
|
||||
|
||||
- 🔧 修复答题提交时 user_type 字段长度问题
|
||||
- ✅ 新增用户角色到数字编码的转换逻辑
|
||||
- 📚 新增用户类型数据字典说明
|
||||
- 🆕 新增答案详情记录功能，同时保存到 hq_sat_answer 表
|
||||
- 📝 完善提交问卷答案接口的数据保存说明
|
||||
|
||||
### v1.0.0 (2025-01-26)
|
||||
|
||||
- ✅ 新增答题提交 API
|
||||
- ✅ 新增答题状态查询 API
|
||||
- ✅ 完善问卷管理 API
|
||||
- ✅ 新增题目选项查询 API
|
||||
- ✅ 建立完整的 API 文档体系
|
||||
|
||||
---
|
||||
|
||||
## 8. 开发说明
|
||||
|
||||
### 8.1 接口测试
|
||||
|
||||
推荐使用以下工具进行接口测试：
|
||||
|
||||
- **Postman**: 图形化接口测试工具
|
||||
- **Apifox**: 国产 API 管理工具
|
||||
- **curl**: 命令行工具
|
||||
|
||||
### 8.2 认证方式
|
||||
|
||||
所有需要权限的接口都需要在请求头中携带认证信息：
|
||||
|
||||
```http
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
### 8.3 时间格式
|
||||
|
||||
所有时间字段统一使用 ISO 8601 格式：
|
||||
|
||||
```
|
||||
2025-01-26T14:15:00.000Z
|
||||
```
|
||||
|
||||
### 8.4 分页参数
|
||||
|
||||
所有分页接口统一使用以下参数：
|
||||
|
||||
- `pageNum`: 页码，从 1 开始
|
||||
- `pageSize`: 页大小，默认 10
|
||||
|
||||
---
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有 API 相关问题，请联系开发团队或查看项目仓库的 Issues。
|
||||
@@ -143,7 +143,7 @@ CREATE TABLE `hq_sat_record` (
|
||||
`deleted` tinyint(1) DEFAULT '0' COMMENT '删除标志（0代表存在 1代表删除）',
|
||||
`survey_id` bigint(20) NOT NULL COMMENT '问卷ID',
|
||||
`user_id` bigint(20) DEFAULT NULL COMMENT '答题用户ID（匿名时为NULL）',
|
||||
`user_type` char(1) NOT NULL COMMENT '用户类型（1学生 2教职工）',
|
||||
`user_type` char(1) NOT NULL COMMENT '用户类型（1学生 2教职工 3超级管理员）',
|
||||
`user_dept` varchar(100) DEFAULT NULL COMMENT '用户部门（匿名时为NULL）',
|
||||
`submit_time` datetime NOT NULL COMMENT '提交时间',
|
||||
`total_score` decimal(10,2) DEFAULT '0.00' COMMENT '总分',
|
||||
@@ -180,6 +180,73 @@ CREATE TABLE `hq_sat_detail` (
|
||||
KEY `idx_answer_score` (`answer_score`)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='答题详情表';
|
||||
|
||||
-- ==========================================
|
||||
-- 答题答案表（新增）
|
||||
-- ==========================================
|
||||
DROP TABLE IF EXISTS `hq_sat_answer`;
|
||||
CREATE TABLE `hq_sat_answer` (
|
||||
`id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
|
||||
`tenant_id` varchar(20) NOT NULL COMMENT '租户编号',
|
||||
`create_dept` bigint(20) DEFAULT NULL COMMENT '创建部门',
|
||||
`create_by` bigint(20) DEFAULT NULL COMMENT '创建者',
|
||||
`create_time` datetime DEFAULT NULL COMMENT '创建时间',
|
||||
`update_by` bigint(20) DEFAULT NULL COMMENT '更新者',
|
||||
`update_time` datetime DEFAULT NULL COMMENT '更新时间',
|
||||
`deleted` tinyint(1) DEFAULT '0' COMMENT '删除标志（0代表存在 1代表删除）',
|
||||
`record_id` bigint(20) NOT NULL COMMENT '答题记录ID',
|
||||
`question_id` bigint(20) NOT NULL COMMENT '题目ID',
|
||||
`question_type` char(1) NOT NULL COMMENT '题目类型（1单选题 2多选题 3问答题）',
|
||||
`option_id` bigint(20) DEFAULT NULL COMMENT '选项ID（单选题、多选题用，问答题为NULL）',
|
||||
`option_value` varchar(50) DEFAULT NULL COMMENT '选项值（A、B、C、D等）',
|
||||
`option_text` varchar(500) DEFAULT NULL COMMENT '选项文本内容',
|
||||
`answer_value` text COMMENT '答案值（单选题存选项值，多选题存逗号分隔选项值，问答题存文本内容）',
|
||||
`answer_score` int(11) DEFAULT '0' COMMENT '该答案得分',
|
||||
`remark` varchar(500) DEFAULT NULL COMMENT '备注',
|
||||
PRIMARY KEY (`id`),
|
||||
KEY `idx_tenant_id` (`tenant_id`),
|
||||
KEY `idx_record_id` (`record_id`),
|
||||
KEY `idx_question_id` (`question_id`),
|
||||
KEY `idx_question_type` (`question_type`),
|
||||
KEY `idx_option_id` (`option_id`),
|
||||
KEY `idx_record_question` (`record_id`, `question_id`)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='答题答案表';
|
||||
|
||||
-- ==========================================
|
||||
-- 数据表索引和约束说明
|
||||
-- ==========================================
|
||||
/*
|
||||
hq_sat_answer 表设计说明：
|
||||
|
||||
1. 表用途：
|
||||
- 记录用户答题的具体答案内容
|
||||
- 支持单选题、多选题、问答题三种题型
|
||||
- 与 hq_sat_detail 表配合使用，detail表记录总体信息，answer表记录具体答案
|
||||
|
||||
2. 字段说明：
|
||||
- question_type：题目类型，便于按类型统计分析
|
||||
- option_id：选项ID，单选题和多选题需要关联到具体选项
|
||||
- option_value：选项值（如A、B、C、D），便于统计
|
||||
- option_text：选项文本，冗余存储便于查询
|
||||
- answer_value：核心字段，存储实际答案：
|
||||
* 单选题：存储选中的选项值，如 "A"
|
||||
* 多选题：存储多个选项值，如 "A,C,D"
|
||||
* 问答题：存储用户输入的文本内容
|
||||
- answer_score：该答案的得分
|
||||
|
||||
3. 数据存储示例：
|
||||
- 单选题：question_type='1', option_id=123, option_value='A', option_text='非常满意', answer_value='A', answer_score=5
|
||||
- 多选题：每个选中选项一条记录，或合并为一条记录存储 "A,C,D"
|
||||
- 问答题：question_type='3', option_id=NULL, answer_value='用户输入的文本内容', answer_score=0
|
||||
|
||||
4. 与其他表的关系：
|
||||
- record_id 关联 hq_sat_record.id
|
||||
- question_id 关联 hq_sat_question.id
|
||||
- option_id 关联 hq_sat_option.id（问答题为NULL）
|
||||
|
||||
5. 查询优化：
|
||||
- 建立复合索引 (record_id, question_id) 提高关联查询效率
|
||||
- 按题目类型、选项等建立索引便于统计分析
|
||||
*/
|
||||
|
||||
-- ==========================================================================
|
||||
-- 初始化数据
|
||||
|
||||
Reference in new issue
Block a user