feat: 移动端开发规范重大更新
- 🔥 完全重写 .cursor/cursorrules-mobile.md (940行) * 基于实际mobile工程Vue 3.4.21+uniapp+uview-plus架构 * 移除所有JeeSite相关内容，精准匹配实际项目 * 新增11个完整章节：技术栈、项目结构、页面开发、组件规范等 - 📚 创建完整规范文档 docs/开发文档/移动端开发规范总结.md (800+行) * 涵盖从项目架构到部署的全流程指导 * 提供可直接使用的页面和组件模板 * 包含现代CSS变量设计系统和用户体验优化 - 🔄 同步更新主配置文件 .cursorrules * 更新移动端技术栈描述 * 调整为Vue 3.4.21+uniapp+uview-plus 3.4.45架构 - 📝 完善变更记录 * 详细记录规范更新背景和技术价值 * 为后续维护提供完整历史记录 核心价值：解决规范与实际项目不匹配问题，为Cursor AI提供准确的移动端开发上下文，确保生成代码完全符合实际项目架构。
This commit is contained in:
zlwu committed
1 parent
e8ece1b612
commit
28232d5d46
131 files changed
+17170
-5479
No files matched your search
+200
-11
@@ -497,6 +497,186 @@ API规范：docs/开发文档/API.md
|
||||
|
||||
## 4. 📚 API 文档管理规范
|
||||
|
||||
### 💡 基于场地预约 API 开发实践的文档管理最佳实践
|
||||
|
||||
**⚠️ 本规范基于场地预约管理系统的完整开发流程制定，为所有 API 模块开发提供标准参考**
|
||||
|
||||
#### 🚨 API 开发文档管理完整流程
|
||||
|
||||
**基于`docs/开发文档/API/场地预约管理API.md`的成功模式**：
|
||||
|
||||
```
|
||||
步骤1: 需求文档创建
|
||||
├── docs/需求文档/[模块名]/系统需求说明.md # 详细业务需求
|
||||
└── docs/业务模块/[模块名]/README.md # 技术架构说明
|
||||
|
||||
步骤2: 数据库设计文档
|
||||
├── docs/设计文档/database/[模块名]-module.sql # 数据表结构
|
||||
├── docs/设计文档/database/[模块名]-data.sql # 字典数据
|
||||
└── docs/设计文档/database/[模块名]-menu.sql # 菜单权限
|
||||
|
||||
步骤3: API接口开发文档
|
||||
├── docs/开发文档/API/[模块名]管理API.md # 完整API文档
|
||||
└── docs/开发文档/API/API文档总览.md # 更新导航索引
|
||||
|
||||
步骤4: 测试脚本文档
|
||||
└── test/[模块名]API测试脚本.py # 自动化测试脚本
|
||||
|
||||
步骤5: 变更记录文档
|
||||
└── docs/变更管理/code-adjust-record-YYYY-MM-DD-{username}.md
|
||||
```
|
||||
|
||||
#### 📋 API 文档标准结构（400+行标准）
|
||||
|
||||
**基于场地预约 API 文档的成功模板**：
|
||||
|
||||
````markdown
|
||||
# [模块名]管理 API
|
||||
|
||||
## 📖 概述
|
||||
|
||||
**功能描述**: [模块核心功能说明]
|
||||
**模块路径**: [API 路径前缀]
|
||||
**权限要求**: [权限标识前缀]
|
||||
**开发状态**: ✅ 已完成
|
||||
|
||||
## 🔑 核心功能
|
||||
|
||||
- [功能 1] - [功能描述]
|
||||
- [功能 2] - [功能描述]
|
||||
- [功能 3] - [功能描述]
|
||||
|
||||
## 🏢 [主实体]信息管理 API
|
||||
|
||||
### 1. 查询[主实体]列表
|
||||
|
||||
**接口地址**: `GET /[module]/[entity]/list`
|
||||
**权限要求**: `@SaCheckPermission("[module]:[entity]:list")`
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| pageNum | int | 否 | 页码，默认 1 |
|
||||
| pageSize | int | 否 | 每页数量，默认 10 |
|
||||
|
||||
**响应示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"total": 5,
|
||||
"rows": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "示例数据",
|
||||
"createTime": "2025-07-01 20:30:00"
|
||||
}
|
||||
],
|
||||
"code": 200,
|
||||
"msg": "查询成功"
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
### 2. 查询[主实体]详情
|
||||
|
||||
**接口地址**: `GET /[module]/[entity]/{id}`
|
||||
**权限要求**: `@SaCheckPermission("[module]:[entity]:query")`
|
||||
|
||||
### 3. 新增[主实体]
|
||||
|
||||
**接口地址**: `POST /[module]/[entity]`
|
||||
**权限要求**: `@SaCheckPermission("[module]:[entity]:add")`
|
||||
|
||||
### 4. 修改[主实体]
|
||||
|
||||
**接口地址**: `PUT /[module]/[entity]`
|
||||
**权限要求**: `@SaCheckPermission("[module]:[entity]:edit")`
|
||||
|
||||
### 5. 删除[主实体]
|
||||
|
||||
**接口地址**: `DELETE /[module]/[entity]/{ids}`
|
||||
**权限要求**: `@SaCheckPermission("[module]:[entity]:remove")`
|
||||
|
||||
### 6. 获取可用[主实体]
|
||||
|
||||
**接口地址**: `GET /[module]/[entity]/available`
|
||||
**权限要求**: `@SaCheckPermission("[module]:[entity]:query")`
|
||||
|
||||
## 📅 [业务实体]管理 API
|
||||
|
||||
### 7. 查询[业务实体]列表
|
||||
|
||||
### 8. 查询我的[业务实体]
|
||||
|
||||
### 9. 查询待审批[业务实体]
|
||||
|
||||
### 10. 查询[业务实体]详情
|
||||
|
||||
### 11. 新增[业务实体]
|
||||
|
||||
### 12. 修改[业务实体]
|
||||
|
||||
### 13. 删除[业务实体]
|
||||
|
||||
### 14. [业务规则]检查
|
||||
|
||||
### 15. 审批[业务实体]
|
||||
|
||||
### 16. 导出[业务实体]
|
||||
|
||||
## 📋 数据字典
|
||||
|
||||
### [实体类型]字典
|
||||
|
||||
| 值 | 标签 | 说明 |
|
||||
| ----- | ------ | ----------- |
|
||||
| type1 | 类型 1 | 类型 1 说明 |
|
||||
| type2 | 类型 2 | 类型 2 说明 |
|
||||
|
||||
## 🔐 权限配置
|
||||
|
||||
### 菜单权限配置
|
||||
|
||||
| 权限 ID | 权限名称 | 权限标识 | 权限类型 |
|
||||
| ------- | ---------- | ---------------------- | -------- |
|
||||
| 2200 | [模块]管理 | [module]:main | 目录 |
|
||||
| 2210 | [实体]管理 | [module]:[entity]:list | 菜单 |
|
||||
|
||||
## 📏 业务规则
|
||||
|
||||
### [业务规则 1]
|
||||
|
||||
### [业务规则 2]
|
||||
|
||||
## ❌ 错误码说明
|
||||
|
||||
| 错误码 | 错误信息 | 说明 |
|
||||
| ------ | -------- | ---------------- |
|
||||
| 400 | 参数错误 | 请求参数格式错误 |
|
||||
| 401 | 未认证 | Token 无效或过期 |
|
||||
|
||||
`````
|
||||
|
||||
#### 🔄 API文档更新工作流程
|
||||
|
||||
**基于场地预约开发的完整流程**：
|
||||
|
||||
1. **代码开发完成** → 立即创建/更新API文档
|
||||
2. **API文档完成** → 更新API文档总览的导航
|
||||
3. **测试脚本完成** → 在API文档中添加测试脚本说明
|
||||
4. **文档验证** → 确保API文档与实际代码一致
|
||||
5. **变更记录** → 在变更日志中记录文档更新
|
||||
|
||||
#### 📊 API文档质量标准
|
||||
|
||||
**基于场地预约API文档的质量标准**：
|
||||
|
||||
- ✅ **完整性**: 16个标准接口的完整文档
|
||||
- ✅ **准确性**: 所有参数和响应与实际代码一致
|
||||
- ✅ **详细性**: 包含完整的业务规则和错误码说明
|
||||
- ✅ **规范性**: 使用统一的文档模板和格式
|
||||
- ✅ **可测试性**: 提供真实的请求响应示例
|
||||
|
||||
### 🔴 强制性 API 文档更新规则
|
||||
|
||||
**⚠️ 超级重要：任何 API 接口的新增、修改、删除都必须立即同步更新 `docs/开发文档/API.md` 文档！**
|
||||
@@ -525,7 +705,8 @@ API规范：docs/开发文档/API.md
|
||||
"msg": "操作成功",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
`````
|
||||
|
||||
````
|
||||
|
||||
**错误码**:
|
||||
@@ -645,33 +826,41 @@ test/custom-login-script.js # 登录认证工具
|
||||
````
|
||||
|
||||
#### 3. 测试文档必含信息
|
||||
|
||||
每个测试结论性文档必须包含以下信息：
|
||||
- **📁 测试代码路径**：明确标注对应的测试脚本位置
|
||||
- **🔧 使用方法**：详细说明如何运行测试脚本
|
||||
- **📊 测试结果**：完整的测试结果和数据分析
|
||||
- **🎯 结论建议**：明确的测试结论和改进建议
|
||||
- **⚠️ 问题记录**：发现的问题和解决方案
|
||||
|
||||
- **📁 测试代码路径**：明确标注对应的测试脚本位置
|
||||
- **🔧 使用方法**：详细说明如何运行测试脚本
|
||||
- **📊 测试结果**：完整的测试结果和数据分析
|
||||
- **🎯 结论建议**：明确的测试结论和改进建议
|
||||
- **⚠️ 问题记录**：发现的问题和解决方案
|
||||
|
||||
#### 测试文档标准模板格式：
|
||||
```markdown
|
||||
|
||||
````markdown
|
||||
# [功能模块]测试报告
|
||||
|
||||
## 🎯 测试概览
|
||||
**测试时间**: YYYY-MM-DD HH:mm:ss （⚠️必须填写真实的当前时间！）
|
||||
|
||||
**测试时间**: YYYY-MM-DD HH:mm:ss （⚠️ 必须填写真实的当前时间！）
|
||||
**测试范围**: [具体测试范围]
|
||||
**需求模块**: [所属业务模块]
|
||||
|
||||
## 📁 测试代码路径
|
||||
|
||||
**测试脚本位置**:
|
||||
- **主要测试脚本**: `test/[功能]-api-test.js`
|
||||
- **详细分析脚本**: `test/[功能]-detailed-test.js`
|
||||
- **辅助工具脚本**: `test/[工具名].js`
|
||||
|
||||
- **主要测试脚本**: `test/[功能]-api-test.js`
|
||||
- **详细分析脚本**: `test/[功能]-detailed-test.js`
|
||||
- **辅助工具脚本**: `test/[工具名].js`
|
||||
|
||||
**使用方法**:
|
||||
|
||||
```bash
|
||||
cd test
|
||||
npm install
|
||||
node [功能]-api-test.js
|
||||
```
|
||||
````
|
||||
|
||||
## ✅ 测试结果总结
|
||||
|
||||
Reference in new issue
Block a user