优化问卷回答界面及功能

This commit is contained in:
zlwu committed 2025-06-27 11:47:00 +08:00
1 parent 1ab9f9c458
commit ed5eb9ca52
13 files changed
+6122 -86

No files matched your search

+156 -4
View File
@@ -26,7 +26,8 @@ docs/
│ │ └── README.md # 数据库设计说明
│ └── [模块设计]/ # 其他设计文档
├── development/ # 开发文档
│ └── README.md # 开发指南
│ ├── README.md # 开发指南
│ └── API.md # API接口文档(完整的后端接口说明)
├── testing/ # 测试文档
│ └── README.md # 测试计划和用例
├── deployment/ # 部署文档
@@ -86,6 +87,20 @@ docs/
### ⚠️ 强制要求
**所有通过Cursor AI进行的代码调整都必须在 `docs/code-adjust-record.md` 中留下记录,这是项目管理的强制性要求。**
### 🔴 特别强调:API接口变更的强制性文档更新规则
**⚠️ 超级重要:任何API接口的新增、修改、删除操作都必须立即同步更新 `docs/development/API.md` 文档!**
#### API变更必须执行的步骤:
1. **代码修改完成** → 2. **立即更新API.md文档** → 3. **记录代码调整日志** → 4. **验证文档准确性**
#### API接口变更涉及的文档更新:
- ✅ **新增API接口**:在API.md中添加完整的接口文档(地址、参数、响应、权限等)
- ✅ **修改API接口**:更新API.md中对应接口的参数、响应格式、权限要求
- ✅ **删除API接口**:在API.md中标记接口为已废弃,说明替代方案
- ✅ **修改响应格式**:更新API.md中的响应示例和字段说明
- ✅ **修改权限要求**:更新API.md中的权限要求说明
## 3. 文档同步更新规则
### 📋 核心原则:代码与文档同步更新
@@ -93,7 +108,7 @@ docs/
### 强制更新规则
每次代码调整必须同步更新相关文档:
- **API文档**: 接口变更时更新相关文档
- **API文档**: 接口变更时更新 `docs/development/API.md` 中的相关接口信息
- **数据库文档**: 表结构变更时更新 `docs/design/database/` 下的所有相关文档
- **配置文档**: 配置项变更时更新 `docs/middleware/` 下的配置说明
- **部署文档**: 部署流程变更时更新 `docs/deployment/` 下的部署手册
@@ -110,7 +125,11 @@ docs/
- [ ] **UI设计文档**: 界面样式重大变更时,更新设计规范文档
#### 后端代码调整时需更新的文档:
- [ ] **接口文档**: API接口变更时,更新接口文档和示例
- [ ] **API接口文档**: API接口变更时,必须更新 `docs/development/API.md` 中的相关接口信息,包括:
- 新增接口:添加完整的接口说明、参数、响应示例
- 修改接口:更新参数说明、响应格式、错误码
- 删除接口:在文档中标记为已废弃,并说明替代方案
- 权限变更:更新权限要求说明
- [ ] **数据库文档**: 表结构变更时,更新数据库设计文档
- [ ] **业务逻辑文档**: 业务规则变更时,更新业务流程文档
- [ ] **配置文档**: 系统配置变更时,更新配置说明文档
@@ -121,13 +140,119 @@ docs/
- [ ] **用户手册**: 用户操作流程变更时,更新操作指南
### 🔄 文档更新工作流程
1. **代码调整完成** → 2. **记录代码调整日志** → 3. **识别影响的文档** → 4. **更新相应文档** → 5. **验证文档完整性**
#### 标准流程:
1. **代码调整完成** → 2. **立即更新相关文档** → 3. **记录代码调整日志** → 4. **验证文档完整性**
#### 🔴 API接口变更的特殊流程(强制性):
1. **API代码开发完成**
2. **立即更新 `docs/development/API.md`** (不得延后)
3. **记录代码调整日志,标注API文档已更新**
4. **验证API文档与实际接口的一致性**
5. **提交代码和文档变更**
#### ⚠️ 重要原则:
- **API变更 = 必须更新API.md文档**
- **文档更新 = 代码开发的一部分,不是可选项**
- **未更新文档 = 开发任务未完成**
### 版本管理
- **文档版本**: 与代码版本保持同步
- **变更记录**: 每次变更都要记录变更内容和原因
- **向后兼容**: 接口变更需要考虑向后兼容性
## 4. API文档管理规范 (docs/development/API.md)
### 📄 API文档维护原则
**⚠️ 重要规则:任何后端API接口的新增、修改、删除都必须同步更新 `docs/development/API.md` 文档。**
### API文档更新时机
- **新增Controller**: 添加新的Controller时,必须在API.md中添加对应的接口说明
- **新增接口方法**: 在现有Controller中添加新方法时,更新对应模块的接口列表
- **修改接口参数**: 接口请求或响应参数变更时,更新参数说明表格
- **修改权限要求**: 接口权限变更时,更新权限要求说明
- **修改响应格式**: 响应数据结构变更时,更新响应示例
- **接口废弃**: 接口不再使用时,在文档中标记为已废弃并说明替代方案
### API文档标准格式
每个接口都必须包含以下信息:
```markdown
#### 接口标题
**接口地址**: `HTTP方法 /接口路径`
**接口描述**: 接口功能的详细描述
**权限要求**: 权限代码或"需要登录"
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
**响应示例**:
```json
{
"code": 200,
"msg": "操作成功",
"data": {}
}
```
### API文档分类规范
- **按业务模块分类**: 问卷管理、答题管理、题目管理等
- **按功能分组**: 基础CRUD操作、业务逻辑操作、状态查询等
- **统一命名规范**: 接口名称要与Controller方法名保持一致
### API文档版本控制
- **版本记录**: 在API.md底部维护版本更新记录
- **变更说明**: 每次更新都要记录具体的变更内容
- **兼容性说明**: 重大变更需要说明向后兼容性影响
### ⚠️ 强制执行规则
**所有通过Cursor AI进行的后端API开发都必须同时更新API文档,这是代码审查的强制性检查项。**
### 🚨 API文档更新检查清单
#### 当进行以下操作时,必须更新 `docs/development/API.md`:
**Controller层变更**:
- [ ] 新增Controller类 → 在API.md中添加新的模块章节
- [ ] 新增@RequestMapping方法 → 添加完整的接口文档
- [ ] 修改@RequestMapping路径 → 更新接口地址
- [ ] 修改HTTP方法(GET/POST/PUT/DELETE) → 更新接口方法
- [ ] 删除接口方法 → 标记为已废弃并说明替代方案
**参数和响应变更**:
- [ ] 新增请求参数 → 更新请求参数表格
- [ ] 修改参数类型或必填属性 → 更新参数说明
- [ ] 修改响应数据结构 → 更新响应示例
- [ ] 新增错误码 → 更新错误码说明表
**权限和安全变更**:
- [ ] 新增@SaCheckPermission注解 → 更新权限要求
- [ ] 修改权限代码 → 更新权限说明
- [ ] 修改接口访问级别 → 更新权限要求说明
#### 强制性文档更新格式要求:
```markdown
#### 接口名称
**接口地址**: `HTTP方法 /完整路径`
**接口描述**: 清晰描述接口功能
**权限要求**: 具体权限代码或"需要登录"
**请求参数**: 完整参数表格
**响应示例**: 真实的JSON响应示例
**错误码**: 可能的错误情况
**更新记录**: 接口变更历史
```
### 🔴 违规检查机制
- **代码审查时检查**:每次PR必须检查API文档是否同步更新
- **自动化提醒**:接口变更后立即更新文档,不得延误
- **文档版本控制**:API文档版本必须与代码版本保持一致
### ⚠️ 重要提醒
**不更新API文档的代码变更将被视为不完整的开发任务,必须补齐文档后才能认为任务完成!**
---
# 第二部分:Web前端开发规范 (web/)
@@ -416,6 +541,33 @@ backend/
@SaCheckPermission("system:user:list")
```
### 🔴 API开发强制性工作流程
#### 步骤1:编写后端代码
- 创建Controller、Service、Mapper等
- 实现业务逻辑和数据处理
- 添加权限控制和参数验证
#### 步骤2:立即更新API文档(强制性)
**⚠️ 代码写完后立即执行,不得延后!**
- 打开 `docs/development/API.md` 文件
- 按照标准格式添加或更新接口文档
- 包含完整的接口信息(地址、参数、响应、权限等)
- 添加真实的请求和响应示例
#### 步骤3:记录代码调整日志
- 在 `docs/code-adjust-record.md` 中记录本次变更
- 特别说明API接口的变更内容
- 标注文档已同步更新
#### 步骤4:验证和测试
- 测试API接口功能是否正常
- 验证API文档的准确性
- 确保文档示例与实际响应一致
#### 🚨 违规后果
**如果发现API变更未同步更新文档,该代码变更将被视为不完整,必须立即补齐文档。**
## 4. 标准代码模板
### Controller模板