优化cursor使用形式，增加项目文档过程管理，方便cursor生成代码
This commit is contained in:
zlwu committed
1 parent
2f7e1a9c16
commit
65d2d71469
36 files changed
+8872
-1530
No files matched your search
@@ -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。
|
||||
@@ -0,0 +1,641 @@
|
||||
# API 文档模板
|
||||
|
||||
> 🎯 **模板用途**：本模板用于创建标准化的 API 接口文档，为 Cursor AI 提供 API 文档编写和维护的参考格式
|
||||
|
||||
## 📋 文档说明
|
||||
|
||||
### 适用场景
|
||||
|
||||
- 新增 API 接口时创建文档
|
||||
- 现有 API 接口修改时更新文档
|
||||
- 为 Cursor AI 提供接口开发上下文
|
||||
|
||||
### 使用方法
|
||||
|
||||
1. 复制本模板内容
|
||||
2. 替换所有 `[占位符]` 为实际内容
|
||||
3. 根据实际接口情况调整结构
|
||||
4. 确保示例代码可以正常运行
|
||||
|
||||
---
|
||||
|
||||
## 🔌 [模块名称] API 接口文档
|
||||
|
||||
### 模块概述
|
||||
|
||||
**模块名称**：[模块英文名] / [模块中文名]
|
||||
**基础路径**：`/api/[module]`
|
||||
**版本**：v1.0
|
||||
**负责人**：[开发负责人]
|
||||
**更新时间**：[最后更新时间]
|
||||
|
||||
### 模块功能
|
||||
|
||||
[模块的主要功能描述，包括业务价值和技术特点]
|
||||
|
||||
### 权限说明
|
||||
|
||||
- **权限前缀**：`[module]:`
|
||||
- **权限列表**：
|
||||
- `[module]:list` - 查询权限
|
||||
- `[module]:add` - 新增权限
|
||||
- `[module]:edit` - 编辑权限
|
||||
- `[module]:remove` - 删除权限
|
||||
|
||||
---
|
||||
|
||||
## 📊 接口概览
|
||||
|
||||
### 接口分类
|
||||
|
||||
#### 基础 CRUD 接口
|
||||
|
||||
| 接口名称 | HTTP 方法 | 路径 | 权限要求 | 功能描述 |
|
||||
| -------------- | --------- | --------------------- | ----------------- | ---------------------- |
|
||||
| 查询[实体]列表 | GET | `/api/[module]/list` | `[module]:list` | 分页查询[实体]列表 |
|
||||
| 查询[实体]详情 | GET | `/api/[module]/{id}` | `[module]:list` | 根据 ID 查询[实体]详情 |
|
||||
| 新增[实体] | POST | `/api/[module]` | `[module]:add` | 创建新的[实体] |
|
||||
| 修改[实体] | PUT | `/api/[module]` | `[module]:edit` | 更新[实体]信息 |
|
||||
| 删除[实体] | DELETE | `/api/[module]/{ids}` | `[module]:remove` | 批量删除[实体] |
|
||||
|
||||
#### 业务逻辑接口
|
||||
|
||||
| 接口名称 | HTTP 方法 | 路径 | 权限要求 | 功能描述 |
|
||||
| ------------ | --------- | ------------------------- | -------- | ---------- |
|
||||
| [业务接口 1] | [方法] | `/api/[module]/[action1]` | `[权限]` | [功能描述] |
|
||||
| [业务接口 2] | [方法] | `/api/[module]/[action2]` | `[权限]` | [功能描述] |
|
||||
| [业务接口 3] | [方法] | `/api/[module]/[action3]` | `[权限]` | [功能描述] |
|
||||
|
||||
### 通用响应格式
|
||||
|
||||
#### 成功响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
// 响应数据
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 分页响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"rows": [
|
||||
// 数据列表
|
||||
],
|
||||
"total": 100
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400001,
|
||||
"msg": "参数错误",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 接口详细说明
|
||||
|
||||
### 1. 查询[实体]列表
|
||||
|
||||
#### 接口信息
|
||||
|
||||
**接口地址**: `GET /api/[module]/list`
|
||||
|
||||
**接口描述**: 分页查询[实体]列表，支持多条件筛选
|
||||
|
||||
**权限要求**: `[module]:list`
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
| --------- | ------- | ---- | -------------------- | ------------ |
|
||||
| pageNum | Integer | N | 页码，默认 1 | 1 |
|
||||
| pageSize | Integer | N | 每页大小，默认 10 | 10 |
|
||||
| [field1] | String | N | [字段 1 说明] | "示例值" |
|
||||
| [field2] | Integer | N | [字段 2 说明] | 1 |
|
||||
| status | Integer | N | 状态：1 启用，0 禁用 | 1 |
|
||||
| beginTime | String | N | 开始时间 | "2024-01-01" |
|
||||
| endTime | String | N | 结束时间 | "2024-01-31" |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:8080/api/[module]/list?pageNum=1&pageSize=10&status=1" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"rows": [
|
||||
{
|
||||
"id": 1,
|
||||
"[field1]": "示例值1",
|
||||
"[field2]": 1,
|
||||
"status": 1,
|
||||
"createBy": 1,
|
||||
"createTime": "2024-01-01 10:00:00",
|
||||
"updateBy": 1,
|
||||
"updateTime": "2024-01-01 10:00:00"
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"[field1]": "示例值2",
|
||||
"[field2]": 2,
|
||||
"status": 1,
|
||||
"createBy": 1,
|
||||
"createTime": "2024-01-01 11:00:00",
|
||||
"updateBy": 1,
|
||||
"updateTime": "2024-01-01 11:00:00"
|
||||
}
|
||||
],
|
||||
"total": 100
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误码
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
| ------ | -------- | -------------------- |
|
||||
| 401001 | 未登录 | 请先登录获取 token |
|
||||
| 403001 | 无权限 | 请联系管理员分配权限 |
|
||||
| 400001 | 参数错误 | 检查请求参数格式 |
|
||||
|
||||
---
|
||||
|
||||
### 2. 查询[实体]详情
|
||||
|
||||
#### 接口信息
|
||||
|
||||
**接口地址**: `GET /api/[module]/{id}`
|
||||
|
||||
**接口描述**: 根据 ID 查询[实体]的详细信息
|
||||
|
||||
**权限要求**: `[module]:list`
|
||||
|
||||
#### 路径参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
| ------ | ---- | ---- | -------- | ------ |
|
||||
| id | Long | Y | [实体]ID | 1 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X GET "http://localhost:8080/api/[module]/1" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "查询成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"[field1]": "示例值",
|
||||
"[field2]": 1,
|
||||
"status": 1,
|
||||
"remark": "备注信息",
|
||||
"createBy": 1,
|
||||
"createTime": "2024-01-01 10:00:00",
|
||||
"updateBy": 1,
|
||||
"updateTime": "2024-01-01 10:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误码
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
| ------ | ---------- | -------------------- |
|
||||
| 404001 | 数据不存在 | 检查 ID 是否正确 |
|
||||
| 401001 | 未登录 | 请先登录获取 token |
|
||||
| 403001 | 无权限 | 请联系管理员分配权限 |
|
||||
|
||||
---
|
||||
|
||||
### 3. 新增[实体]
|
||||
|
||||
#### 接口信息
|
||||
|
||||
**接口地址**: `POST /api/[module]`
|
||||
|
||||
**接口描述**: 创建新的[实体]记录
|
||||
|
||||
**权限要求**: `[module]:add`
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
| -------- | ------- | ---- | ---------------------------- | ---------- |
|
||||
| [field1] | String | Y | [字段 1 说明] | "示例值" |
|
||||
| [field2] | Integer | Y | [字段 2 说明] | 1 |
|
||||
| status | Integer | N | 状态：1 启用，0 禁用，默认 1 | 1 |
|
||||
| remark | String | N | 备注信息 | "备注内容" |
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"[field1]": "示例值",
|
||||
"[field2]": 1,
|
||||
"status": 1,
|
||||
"remark": "备注信息"
|
||||
}
|
||||
```
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:8080/api/[module]" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"[field1]": "示例值",
|
||||
"[field2]": 1,
|
||||
"status": 1,
|
||||
"remark": "备注信息"
|
||||
}'
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "新增成功",
|
||||
"data": {
|
||||
"id": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误码
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
| ------ | ---------- | -------------------- |
|
||||
| 400001 | 参数错误 | 检查必填参数是否缺失 |
|
||||
| 400002 | 数据已存在 | 检查唯一字段是否重复 |
|
||||
| 401001 | 未登录 | 请先登录获取 token |
|
||||
| 403001 | 无权限 | 请联系管理员分配权限 |
|
||||
|
||||
#### 参数验证规则
|
||||
|
||||
- `[field1]`: 长度 2-50 字符，不能为空
|
||||
- `[field2]`: 必须为正整数
|
||||
- `status`: 只能为 0 或 1
|
||||
- `remark`: 最大长度 500 字符
|
||||
|
||||
---
|
||||
|
||||
### 4. 修改[实体]
|
||||
|
||||
#### 接口信息
|
||||
|
||||
**接口地址**: `PUT /api/[module]`
|
||||
|
||||
**接口描述**: 更新[实体]信息
|
||||
|
||||
**权限要求**: `[module]:edit`
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
| -------- | ------- | ---- | -------------------- | ---------- |
|
||||
| id | Long | Y | [实体]ID | 1 |
|
||||
| [field1] | String | Y | [字段 1 说明] | "示例值" |
|
||||
| [field2] | Integer | Y | [字段 2 说明] | 1 |
|
||||
| status | Integer | N | 状态：1 启用，0 禁用 | 1 |
|
||||
| remark | String | N | 备注信息 | "备注内容" |
|
||||
|
||||
#### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"[field1]": "修改后的值",
|
||||
"[field2]": 2,
|
||||
"status": 1,
|
||||
"remark": "修改后的备注"
|
||||
}
|
||||
```
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X PUT "http://localhost:8080/api/[module]" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"id": 1,
|
||||
"[field1]": "修改后的值",
|
||||
"[field2]": 2,
|
||||
"status": 1,
|
||||
"remark": "修改后的备注"
|
||||
}'
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "修改成功",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误码
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
| ------ | ---------- | -------------------- |
|
||||
| 404001 | 数据不存在 | 检查 ID 是否正确 |
|
||||
| 400001 | 参数错误 | 检查参数格式是否正确 |
|
||||
| 401001 | 未登录 | 请先登录获取 token |
|
||||
| 403001 | 无权限 | 请联系管理员分配权限 |
|
||||
|
||||
---
|
||||
|
||||
### 5. 删除[实体]
|
||||
|
||||
#### 接口信息
|
||||
|
||||
**接口地址**: `DELETE /api/[module]/{ids}`
|
||||
|
||||
**接口描述**: 批量删除[实体]，支持逻辑删除
|
||||
|
||||
**权限要求**: `[module]:remove`
|
||||
|
||||
#### 路径参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
| ------ | ------ | ---- | ----------------------------- | ------- |
|
||||
| ids | String | Y | [实体]ID 列表，多个用逗号分隔 | "1,2,3" |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X DELETE "http://localhost:8080/api/[module]/1,2,3" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "删除成功",
|
||||
"data": {
|
||||
"successCount": 2,
|
||||
"failCount": 1,
|
||||
"failIds": [3]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误码
|
||||
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
| ------ | ---------- | -------------------- |
|
||||
| 400001 | 参数错误 | 检查 ID 格式是否正确 |
|
||||
| 400003 | 数据被引用 | 请先删除关联数据 |
|
||||
| 401001 | 未登录 | 请先登录获取 token |
|
||||
| 403001 | 无权限 | 请联系管理员分配权限 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 业务逻辑接口
|
||||
|
||||
### 1. [业务接口 1 名称]
|
||||
|
||||
#### 接口信息
|
||||
|
||||
**接口地址**: `[HTTP方法] /api/[module]/[action]`
|
||||
|
||||
**接口描述**: [详细的业务功能描述]
|
||||
|
||||
**权限要求**: `[权限代码]`
|
||||
|
||||
#### 业务流程
|
||||
|
||||
1. [业务步骤 1]
|
||||
2. [业务步骤 2]
|
||||
3. [业务步骤 3]
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
| -------- | ------ | ----- | ---------- | -------- |
|
||||
| [param1] | [类型] | [Y/N] | [参数说明] | [示例值] |
|
||||
| [param2] | [类型] | [Y/N] | [参数说明] | [示例值] |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X [方法] "http://localhost:8080/api/[module]/[action]" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"[param1]": "[值1]",
|
||||
"[param2]": "[值2]"
|
||||
}'
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"[result1]": "[结果值1]",
|
||||
"[result2]": "[结果值2]"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 业务规则
|
||||
|
||||
- [业务规则 1]
|
||||
- [业务规则 2]
|
||||
- [业务规则 3]
|
||||
|
||||
#### 注意事项
|
||||
|
||||
- [注意事项 1]
|
||||
- [注意事项 2]
|
||||
|
||||
---
|
||||
|
||||
## 📋 数据字典
|
||||
|
||||
### [实体名称] 状态枚举
|
||||
|
||||
| 值 | 名称 | 说明 |
|
||||
| --- | ---- | -------- |
|
||||
| 0 | 禁用 | 不可使用 |
|
||||
| 1 | 启用 | 正常使用 |
|
||||
|
||||
### [其他枚举名称]
|
||||
|
||||
| 值 | 名称 | 说明 |
|
||||
| ------ | -------- | -------- |
|
||||
| [值 1] | [名称 1] | [说明 1] |
|
||||
| [值 2] | [名称 2] | [说明 2] |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 SDK 使用示例
|
||||
|
||||
### Java SDK
|
||||
|
||||
```java
|
||||
// 查询列表
|
||||
[Module]QueryBo queryBo = new [Module]QueryBo();
|
||||
queryBo.setStatus(1);
|
||||
PageQuery pageQuery = new PageQuery(1, 10);
|
||||
Result<PageResult<[Module]Vo>> result = [module]Api.list(queryBo, pageQuery);
|
||||
|
||||
// 新增记录
|
||||
[Module]Bo [module]Bo = new [Module]Bo();
|
||||
[module]Bo.set[Field1]("示例值");
|
||||
[module]Bo.set[Field2](1);
|
||||
Result<Long> addResult = [module]Api.add([module]Bo);
|
||||
|
||||
// 修改记录
|
||||
[module]Bo.setId(1L);
|
||||
[module]Bo.set[Field1]("修改后的值");
|
||||
Result<Void> updateResult = [module]Api.update([module]Bo);
|
||||
```
|
||||
|
||||
### JavaScript SDK
|
||||
|
||||
```javascript
|
||||
// 查询列表
|
||||
const queryParams = {
|
||||
pageNum: 1,
|
||||
pageSize: 10,
|
||||
status: 1
|
||||
};
|
||||
const listResult = await [module]Api.list(queryParams);
|
||||
|
||||
// 新增记录
|
||||
const [module]Data = {
|
||||
[field1]: "示例值",
|
||||
[field2]: 1,
|
||||
status: 1
|
||||
};
|
||||
const addResult = await [module]Api.add([module]Data);
|
||||
|
||||
// 修改记录
|
||||
[module]Data.id = 1;
|
||||
[module]Data.[field1] = "修改后的值";
|
||||
const updateResult = await [module]Api.update([module]Data);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试用例
|
||||
|
||||
### 接口测试
|
||||
|
||||
```javascript
|
||||
// Jest 测试示例
|
||||
describe('[Module] API Tests', () => {
|
||||
test('查询列表接口', async () => {
|
||||
const response = await request(app)
|
||||
.get('/api/[module]/list')
|
||||
.set('Authorization', `Bearer ${token}`)
|
||||
.expect(200);
|
||||
|
||||
expect(response.body.code).toBe(200);
|
||||
expect(response.body.rows).toBeDefined();
|
||||
expect(response.body.total).toBeGreaterThanOrEqual(0);
|
||||
});
|
||||
|
||||
test('新增接口', async () => {
|
||||
const [module]Data = {
|
||||
[field1]: "测试值",
|
||||
[field2]: 1
|
||||
};
|
||||
|
||||
const response = await request(app)
|
||||
.post('/api/[module]')
|
||||
.set('Authorization', `Bearer ${token}`)
|
||||
.send([module]Data)
|
||||
.expect(200);
|
||||
|
||||
expect(response.body.code).toBe(200);
|
||||
expect(response.body.data.id).toBeDefined();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 版本历史
|
||||
|
||||
### v1.0.0 - 2024-01-01
|
||||
|
||||
- ✅ 初始版本发布
|
||||
- ✅ 完成基础 CRUD 接口
|
||||
- ✅ 完成核心业务接口
|
||||
|
||||
### v1.0.1 - 2024-01-15
|
||||
|
||||
- 🔧 优化查询接口性能
|
||||
- 🐛 修复删除接口的权限检查问题
|
||||
- 📚 补充接口文档和示例
|
||||
|
||||
### v1.1.0 - 2024-02-01
|
||||
|
||||
- ✨ 新增[新功能 1]接口
|
||||
- ✨ 新增[新功能 2]接口
|
||||
- 🔧 优化错误处理机制
|
||||
|
||||
---
|
||||
|
||||
## 📖 相关文档
|
||||
|
||||
- **数据库设计**：[数据库设计文档](../设计文档/database/)
|
||||
- **业务需求**：[业务需求文档](../需求文档/)
|
||||
- **技术架构**：[技术架构文档](./技术架构/)
|
||||
- **开发规范**：[开发规范文档](./开发规范/)
|
||||
|
||||
---
|
||||
|
||||
## 📞 联系方式
|
||||
|
||||
**开发团队**：[团队名称]
|
||||
**负责人**：[负责人姓名]
|
||||
**邮箱**：[联系邮箱]
|
||||
**文档维护**：实时更新，如有问题请及时反馈
|
||||
|
||||
---
|
||||
|
||||
**📌 重要提醒**：
|
||||
|
||||
1. 所有接口都需要先登录获取 token
|
||||
2. 请求头必须包含 `Authorization: Bearer {token}`
|
||||
3. 参数验证失败会返回详细的错误信息
|
||||
4. 生产环境请使用 HTTPS 协议
|
||||
@@ -0,0 +1,649 @@
|
||||
# 开发文档中心
|
||||
|
||||
## 📋 开发文档概述
|
||||
|
||||
开发文档中心提供项目开发所需的所有技术文档和规范，为 **Cursor AI 辅助开发** 提供完整的技术上下文和开发指南。
|
||||
|
||||
## 🎯 文档目标
|
||||
|
||||
### 为 Cursor AI 提供的价值
|
||||
|
||||
- **🔧 技术规范**：统一的编码规范和开发标准
|
||||
- **📚 API 文档**：完整的接口定义和使用说明
|
||||
- **⚙️ 架构指南**：系统架构和技术选型说明
|
||||
- **🛠️ 工具配置**：开发工具和环境配置指南
|
||||
|
||||
### 文档维护原则
|
||||
|
||||
- **实时同步**：API 变更时立即更新文档
|
||||
- **详细准确**：提供完整的技术细节和示例
|
||||
- **版本管理**：记录文档版本和变更历史
|
||||
- **易于理解**：清晰的结构和标准化描述
|
||||
|
||||
## 📁 文档结构
|
||||
|
||||
```
|
||||
开发文档/
|
||||
├── README.md # 本文件 - 开发文档总览
|
||||
├── API.md # API接口完整文档
|
||||
├── 开发规范/
|
||||
│ ├── 后端开发规范.md # Java/Spring Boot开发规范
|
||||
│ ├── 前端开发规范.md # Vue3/TypeScript开发规范
|
||||
│ ├── 数据库规范.md # 数据库设计和操作规范
|
||||
│ ├── 代码审查规范.md # 代码审查流程和标准
|
||||
│ └── Git使用规范.md # Git分支和提交规范
|
||||
├── 技术架构/
|
||||
│ ├── 系统架构设计.md # 整体系统架构
|
||||
│ ├── 技术选型说明.md # 技术栈选择理由
|
||||
│ ├── 安全架构设计.md # 安全体系设计
|
||||
│ └── 性能优化指南.md # 性能优化策略
|
||||
├── 环境配置/
|
||||
│ ├── 开发环境搭建.md # 本地开发环境配置
|
||||
│ ├── 测试环境配置.md # 测试环境搭建
|
||||
│ ├── 生产环境部署.md # 生产环境部署指南
|
||||
│ └── 工具配置指南.md # IDE和工具配置
|
||||
├── 最佳实践/
|
||||
│ ├── 代码结构设计.md # 代码组织和结构设计
|
||||
│ ├── 异常处理规范.md # 异常处理最佳实践
|
||||
│ ├── 日志记录规范.md # 日志记录标准
|
||||
│ └── 测试策略指南.md # 测试策略和方法
|
||||
└── 第三方集成/
|
||||
├── 中间件集成.md # Redis、MQ等中间件集成
|
||||
├── 第三方服务.md # 第三方API和服务集成
|
||||
└── 工具库使用.md # 常用工具库使用指南
|
||||
```
|
||||
|
||||
## 🔌 API 文档管理
|
||||
|
||||
### API 文档结构
|
||||
|
||||
#### 1. 完整性要求
|
||||
|
||||
- **接口地址**：完整的请求路径和 HTTP 方法
|
||||
- **参数说明**：详细的请求参数和数据类型
|
||||
- **响应格式**：标准的响应体结构和示例
|
||||
- **错误码**：完整的错误码定义和处理
|
||||
|
||||
#### 2. 实时性要求
|
||||
|
||||
- **同步更新**：代码变更时立即更新 API 文档
|
||||
- **版本管理**：记录 API 版本变更历史
|
||||
- **兼容性说明**：重大变更的向后兼容性说明
|
||||
|
||||
#### 3. 标准格式
|
||||
|
||||
````markdown
|
||||
#### 接口名称
|
||||
|
||||
**接口地址**: `HTTP方法 /api/路径`
|
||||
|
||||
**接口描述**: 接口功能的详细描述
|
||||
|
||||
**权限要求**: 权限代码或"需要登录"
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||||
|--------|------|------|------|--------|
|
||||
| param1 | String | Y | 参数说明 | "example" |
|
||||
| param2 | Integer | N | 参数说明 | 100 |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"name": "示例"
|
||||
}
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**错误码**:
|
||||
| 错误码 | 说明 | 解决方案 |
|
||||
|--------|------|----------|
|
||||
| 400001 | 参数错误 | 检查请求参数 |
|
||||
| 401001 | 未登录 | 请先登录 |
|
||||
|
||||
````
|
||||
|
||||
### API 文档自动生成
|
||||
|
||||
#### Swagger/OpenAPI 集成
|
||||
```java
|
||||
@RestController
|
||||
@RequestMapping("/api/user")
|
||||
@Api(tags = "用户管理")
|
||||
public class UserController {
|
||||
|
||||
@ApiOperation(value = "获取用户列表", notes = "分页查询用户列表")
|
||||
@ApiImplicitParams({
|
||||
@ApiImplicitParam(name = "pageNum", value = "页码", defaultValue = "1"),
|
||||
@ApiImplicitParam(name = "pageSize", value = "每页大小", defaultValue = "10")
|
||||
})
|
||||
@GetMapping("/list")
|
||||
public Result<PageInfo<UserVo>> list(UserQueryBo queryBo, PageQuery pageQuery) {
|
||||
// 实现逻辑
|
||||
}
|
||||
}
|
||||
````
|
||||
|
||||
#### 文档生成脚本
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# API文档生成脚本
|
||||
generate_api_docs() {
|
||||
echo "生成API文档..."
|
||||
mvn clean compile
|
||||
mvn swagger2markup:convertSwagger2markup
|
||||
echo "API文档生成完成：docs/开发文档/API.md"
|
||||
}
|
||||
```
|
||||
|
||||
## 💻 开发规范体系
|
||||
|
||||
### 后端开发规范
|
||||
|
||||
#### 1. Java 编码规范
|
||||
|
||||
- **命名规范**：遵循 Java 命名约定
|
||||
- **代码结构**：标准的 MVC 分层架构
|
||||
- **注释规范**：完整的 JavaDoc 注释
|
||||
- **异常处理**：统一的异常处理机制
|
||||
|
||||
#### 2. Spring Boot 规范
|
||||
|
||||
```java
|
||||
// 标准Controller结构
|
||||
@RestController
|
||||
@RequestMapping("/api/module")
|
||||
@Slf4j
|
||||
public class ModuleController extends BaseController {
|
||||
|
||||
@Autowired
|
||||
private IModuleService moduleService;
|
||||
|
||||
@SaCheckPermission("module:list")
|
||||
@GetMapping("/list")
|
||||
@Operation(summary = "查询列表")
|
||||
public TableDataInfo<ModuleVo> list(ModuleBo bo, PageQuery pageQuery) {
|
||||
return moduleService.queryPageList(bo, pageQuery);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 数据库规范
|
||||
|
||||
```sql
|
||||
-- 标准表结构
|
||||
CREATE TABLE `module_table` (
|
||||
`id` BIGINT(20) NOT NULL COMMENT '主键ID',
|
||||
`name` VARCHAR(100) NOT NULL COMMENT '名称',
|
||||
`status` TINYINT(1) DEFAULT 1 COMMENT '状态：1启用，0禁用',
|
||||
`tenant_id` VARCHAR(20) NOT NULL COMMENT '租户ID',
|
||||
`create_by` BIGINT(20) NOT NULL COMMENT '创建人',
|
||||
`create_time` DATETIME NOT NULL COMMENT '创建时间',
|
||||
`update_by` BIGINT(20) DEFAULT NULL COMMENT '更新人',
|
||||
`update_time` DATETIME DEFAULT NULL COMMENT '更新时间',
|
||||
`deleted` TINYINT(1) DEFAULT 0 COMMENT '删除标记',
|
||||
PRIMARY KEY (`id`),
|
||||
KEY `idx_tenant_id` (`tenant_id`),
|
||||
KEY `idx_status` (`status`)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='模块表';
|
||||
```
|
||||
|
||||
### 前端开发规范
|
||||
|
||||
#### 1. Vue3 组件规范
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div class="module-container">
|
||||
<el-form ref="formRef" :model="formData" :rules="rules">
|
||||
<!-- 表单内容 -->
|
||||
</el-form>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts" name="ModuleForm">
|
||||
import { ref, reactive } from 'vue';
|
||||
import type { FormRules } from 'element-plus';
|
||||
|
||||
// 响应式数据
|
||||
const formRef = ref();
|
||||
const formData = reactive({
|
||||
name: '',
|
||||
status: 1,
|
||||
});
|
||||
|
||||
// 表单验证规则
|
||||
const rules: FormRules = {
|
||||
name: [{ required: true, message: '请输入名称', trigger: 'blur' }],
|
||||
};
|
||||
|
||||
// 方法定义
|
||||
const handleSubmit = () => {
|
||||
// 提交逻辑
|
||||
};
|
||||
</script>
|
||||
|
||||
<style lang="scss" scoped>
|
||||
.module-container {
|
||||
padding: 20px;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
#### 2. TypeScript 类型定义
|
||||
|
||||
```typescript
|
||||
// api/types.ts
|
||||
export interface ModuleVo {
|
||||
id: number;
|
||||
name: string;
|
||||
status: number;
|
||||
createTime: string;
|
||||
}
|
||||
|
||||
export interface ModuleBo {
|
||||
name?: string;
|
||||
status?: number;
|
||||
}
|
||||
|
||||
export interface ModuleForm {
|
||||
id?: number;
|
||||
name: string;
|
||||
status: number;
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. API 调用规范
|
||||
|
||||
```typescript
|
||||
// api/module.ts
|
||||
import request from '@/utils/request';
|
||||
import type { AxiosPromise } from 'axios';
|
||||
|
||||
export const listModule = (query?: ModuleBo): AxiosPromise<ModuleVo[]> => {
|
||||
return request({
|
||||
url: '/api/module/list',
|
||||
method: 'get',
|
||||
params: query,
|
||||
});
|
||||
};
|
||||
|
||||
export const createModule = (data: ModuleForm): AxiosPromise<void> => {
|
||||
return request({
|
||||
url: '/api/module',
|
||||
method: 'post',
|
||||
data: data,
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
## 🏗️ 技术架构指南
|
||||
|
||||
### 系统整体架构
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "前端层"
|
||||
A1[Web管理端<br/>Vue3 + Element Plus]
|
||||
A2[移动端<br/>UniApp + uView UI]
|
||||
end
|
||||
|
||||
subgraph "网关层"
|
||||
B1[API Gateway<br/>Spring Cloud Gateway]
|
||||
B2[负载均衡<br/>Nginx]
|
||||
end
|
||||
|
||||
subgraph "应用层"
|
||||
C1[用户服务<br/>Spring Boot]
|
||||
C2[业务服务<br/>Spring Boot]
|
||||
C3[文件服务<br/>Spring Boot]
|
||||
end
|
||||
|
||||
subgraph "数据层"
|
||||
D1[MySQL<br/>主数据库]
|
||||
D2[Redis<br/>缓存/会话]
|
||||
D3[MinIO<br/>文件存储]
|
||||
end
|
||||
|
||||
subgraph "基础设施"
|
||||
E1[Docker<br/>容器化]
|
||||
E2[Jenkins<br/>CI/CD]
|
||||
E3[ELK<br/>日志监控]
|
||||
end
|
||||
|
||||
A1 --> B2
|
||||
A2 --> B2
|
||||
B2 --> B1
|
||||
B1 --> C1
|
||||
B1 --> C2
|
||||
B1 --> C3
|
||||
|
||||
C1 --> D1
|
||||
C2 --> D1
|
||||
C3 --> D1
|
||||
|
||||
C1 --> D2
|
||||
C2 --> D2
|
||||
|
||||
C3 --> D3
|
||||
```
|
||||
|
||||
### 技术选型说明
|
||||
|
||||
#### 后端技术栈
|
||||
|
||||
- **Spring Boot 3.4.6**：主框架，提供依赖注入和自动配置
|
||||
- **Spring Cloud 2023.0.x**：微服务架构支持
|
||||
- **MyBatis-Plus 3.5.12**：ORM 框架，简化数据库操作
|
||||
- **Sa-Token 1.42.0**：权限认证框架
|
||||
- **Redis 7.0**：缓存和会话存储
|
||||
- **MySQL 8.0**：主数据库
|
||||
|
||||
#### 前端技术栈
|
||||
|
||||
- **Vue 3.5.13**：渐进式 JavaScript 框架
|
||||
- **TypeScript 5.8.3**：静态类型检查
|
||||
- **Element Plus 2.9.8**：UI 组件库
|
||||
- **Vite 7.0.9**：构建工具
|
||||
- **Pinia**：状态管理
|
||||
|
||||
## 🛠️ 开发工具配置
|
||||
|
||||
### IDE 配置
|
||||
|
||||
#### IntelliJ IDEA 配置
|
||||
|
||||
```xml
|
||||
<!-- .idea/codeStyles/Project.xml -->
|
||||
<component name="ProjectCodeStyleConfiguration">
|
||||
<code_scheme name="Project" version="173">
|
||||
<option name="LINE_SEPARATOR" value=" " />
|
||||
<option name="RIGHT_MARGIN" value="120" />
|
||||
<JavaCodeStyleSettings>
|
||||
<option name="IMPORT_LAYOUT_TABLE">
|
||||
<value>
|
||||
<package name="" withSubpackages="true" static="false" />
|
||||
</value>
|
||||
</option>
|
||||
</JavaCodeStyleSettings>
|
||||
</code_scheme>
|
||||
</component>
|
||||
```
|
||||
|
||||
#### VSCode 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"editor.formatOnSave": true,
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.fixAll.eslint": true
|
||||
},
|
||||
"typescript.preferences.importModuleSpecifier": "relative",
|
||||
"emmet.includeLanguages": {
|
||||
"vue": "html"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Git 配置
|
||||
|
||||
#### .gitignore 模板
|
||||
|
||||
```bash
|
||||
# 编译输出
|
||||
target/
|
||||
dist/
|
||||
build/
|
||||
|
||||
# 依赖目录
|
||||
node_modules/
|
||||
|
||||
# IDE文件
|
||||
.idea/
|
||||
.vscode/
|
||||
*.iml
|
||||
|
||||
# 日志文件
|
||||
logs/
|
||||
*.log
|
||||
|
||||
# 配置文件
|
||||
application-local.yml
|
||||
.env.local
|
||||
```
|
||||
|
||||
#### Git Hooks
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# pre-commit hook
|
||||
echo "运行代码检查..."
|
||||
|
||||
# Java代码检查
|
||||
mvn checkstyle:check
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Java代码规范检查失败！"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 前端代码检查
|
||||
cd web && npm run lint
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "前端代码规范检查失败！"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "代码检查通过！"
|
||||
```
|
||||
|
||||
## 🔧 Cursor AI 开发指南
|
||||
|
||||
### AI 辅助开发流程
|
||||
|
||||
#### 1. 需求理解阶段
|
||||
|
||||
```
|
||||
请根据以下需求文档和技术规范，为我开发[功能名称]：
|
||||
|
||||
业务需求：docs/需求文档/[具体需求文档]
|
||||
技术规范：docs/开发文档/[相关规范文档]
|
||||
API设计：docs/开发文档/API.md
|
||||
|
||||
请确保代码符合项目规范，包括：
|
||||
1. 遵循编码规范
|
||||
2. 添加完整注释
|
||||
3. 包含单元测试
|
||||
4. 更新API文档
|
||||
```
|
||||
|
||||
#### 2. 代码生成阶段
|
||||
|
||||
```
|
||||
基于以下技术架构生成代码：
|
||||
|
||||
后端：Spring Boot + MyBatis-Plus + Sa-Token
|
||||
前端：Vue3 + TypeScript + Element Plus
|
||||
数据库：MySQL 8.0
|
||||
|
||||
请生成以下文件：
|
||||
1. Controller层 - REST API接口
|
||||
2. Service层 - 业务逻辑
|
||||
3. Mapper层 - 数据访问
|
||||
4. DTO/VO类 - 数据传输对象
|
||||
5. 前端页面 - Vue3组件
|
||||
6. API调用 - TypeScript接口
|
||||
```
|
||||
|
||||
#### 3. 文档更新阶段
|
||||
|
||||
```
|
||||
根据刚才生成的代码，请更新以下文档：
|
||||
|
||||
1. API文档：docs/开发文档/API.md
|
||||
- 新增的接口定义
|
||||
- 请求参数说明
|
||||
- 响应示例
|
||||
|
||||
2. 数据库文档：docs/设计文档/database/
|
||||
- 新增的表结构
|
||||
- 字段说明
|
||||
|
||||
3. 变更记录：docs/变更管理/code-adjust-record.md
|
||||
- 本次变更的详细记录
|
||||
|
||||
请保持文档格式一致。
|
||||
```
|
||||
|
||||
### 提示词模板库
|
||||
|
||||
#### 后端开发模板
|
||||
|
||||
```
|
||||
# 生成Spring Boot Controller
|
||||
请为[实体名称]生成标准的Spring Boot Controller，要求：
|
||||
1. 包含CRUD操作接口
|
||||
2. 使用Sa-Token权限控制
|
||||
3. 参数验证和异常处理
|
||||
4. 完整的Swagger注解
|
||||
5. 统一响应格式
|
||||
|
||||
实体字段：[字段列表]
|
||||
权限前缀：[权限代码]
|
||||
```
|
||||
|
||||
#### 前端开发模板
|
||||
|
||||
```
|
||||
# 生成Vue3组件
|
||||
请为[功能名称]生成Vue3组件，要求：
|
||||
1. 使用TypeScript
|
||||
2. Element Plus组件
|
||||
3. 响应式设计
|
||||
4. 表单验证
|
||||
5. API调用集成
|
||||
|
||||
页面类型：[列表页/表单页/详情页]
|
||||
功能要求：[具体功能说明]
|
||||
```
|
||||
|
||||
#### 数据库设计模板
|
||||
|
||||
```
|
||||
# 生成数据库表
|
||||
请为[业务实体]设计MySQL表结构，要求：
|
||||
1. 符合项目命名规范
|
||||
2. 包含标准基础字段
|
||||
3. 合理的索引设计
|
||||
4. 外键关系定义
|
||||
5. 注释完整
|
||||
|
||||
业务字段：[字段需求]
|
||||
关联表：[关联关系]
|
||||
```
|
||||
|
||||
## 📋 质量控制标准
|
||||
|
||||
### 代码质量检查
|
||||
|
||||
#### 自动化检查
|
||||
|
||||
- **代码规范**：Checkstyle + ESLint
|
||||
- **代码覆盖率**：JaCoCo > 80%
|
||||
- **安全扫描**：SonarQube
|
||||
- **依赖检查**：OWASP Dependency Check
|
||||
|
||||
#### 人工审查
|
||||
|
||||
- **架构合理性**：是否符合系统架构
|
||||
- **业务逻辑正确性**：是否满足业务需求
|
||||
- **代码可读性**：注释完整，命名规范
|
||||
- **性能考虑**：是否有性能优化
|
||||
|
||||
### 文档质量标准
|
||||
|
||||
#### 完整性检查
|
||||
|
||||
- [ ] API 文档覆盖所有接口
|
||||
- [ ] 参数说明详细准确
|
||||
- [ ] 响应示例真实有效
|
||||
- [ ] 错误码定义完整
|
||||
|
||||
#### 准确性检查
|
||||
|
||||
- [ ] 文档与代码实现一致
|
||||
- [ ] 示例可以正常运行
|
||||
- [ ] 版本信息正确
|
||||
- [ ] 链接地址有效
|
||||
|
||||
### 版本管理
|
||||
|
||||
#### 文档版本规则
|
||||
|
||||
- **主版本**：重大架构变更
|
||||
- **次版本**：新增功能模块
|
||||
- **修订版本**：Bug 修复和文档更新
|
||||
|
||||
#### 变更记录
|
||||
|
||||
```markdown
|
||||
## 版本 1.2.3 - 2024-01-15
|
||||
|
||||
### 新增
|
||||
|
||||
- 新增用户管理 API 文档
|
||||
- 添加前端开发规范
|
||||
|
||||
### 修改
|
||||
|
||||
- 更新数据库设计规范
|
||||
- 优化 API 响应格式
|
||||
|
||||
### 修复
|
||||
|
||||
- 修正示例代码错误
|
||||
- 更新过期链接
|
||||
```
|
||||
|
||||
## 🚀 持续改进计划
|
||||
|
||||
### 短期目标（1 个月内）
|
||||
|
||||
- [ ] 完善 API 文档自动生成
|
||||
- [ ] 建立代码质量检查流程
|
||||
- [ ] 优化开发环境配置
|
||||
- [ ] 提升团队规范执行
|
||||
|
||||
### 中期目标（3 个月内）
|
||||
|
||||
- [ ] 建立文档质量评估体系
|
||||
- [ ] 实现开发流程自动化
|
||||
- [ ] 完善性能监控机制
|
||||
- [ ] 建立知识库体系
|
||||
|
||||
### 长期目标（6 个月内）
|
||||
|
||||
- [ ] 实现智能化代码审查
|
||||
- [ ] 建立自动化测试体系
|
||||
- [ ] 完善 DevOps 流程
|
||||
- [ ] 建立技术标准库
|
||||
|
||||
---
|
||||
|
||||
## 📖 相关文档
|
||||
|
||||
- **API 接口文档**：[API.md](./API.md)
|
||||
- **项目总览**：[项目总览](../项目总览/README.md)
|
||||
- **业务模块**：[业务模块](../业务模块/README.md)
|
||||
- **变更管理**：[变更管理](../变更管理/README.md)
|
||||
- **测试文档**：[测试文档](../测试文档/README.md)
|
||||
|
||||
---
|
||||
|
||||
**🎯 目标**：通过完善的开发文档体系，为团队提供统一的技术标准，为 Cursor AI 提供准确的开发上下文，提升开发效率和代码质量。
|
||||
Reference in new issue
Block a user