hzdyjs/.cursorrules

# Cursor Rules - 项目开发规范总览

## 🎯 项目概述

**项目名称**: 校园管理系统 (hzdyjs_xg)  
**技术架构**: 前后端分离 + 移动端  
**工作目录**: `/Users/wuzilong/work/00code/hzdyjs_xg`

### 项目结构
- **前端工程**: `web/` (Vue 3 + TypeScript + Element Plus)
- **后端工程**: `backend/` (Spring Boot 3.4.6 + MyBatis-Plus)
- **移动端工程**: `mobile/` (Vue 2.6.14 + uni-app 2.x + uview-ui 2.0.38 - 智慧校园移动应用)
- **文档管理**: `docs/` (完整的项目文档体系)

---

## 📚 规范文件引用

**重要说明**: 本项目的开发规范已按技术栈模块化拆分，请根据开发场景参考对应规范：

### 🔗 专门规范文件
```
.cursor/
├── cursorrules-docs.md          # 📋 文档管理规范
├── cursorrules-frontend.md      # 🎨 前端开发规范 (Vue 3)
├── cursorrules-backend.md       # ⚙️ 后端开发规范 (Spring Boot)
├── cursorrules-mobile.md        # 📱 移动端开发规范 (uniapp)
├── cursorrules-workflow.md      # 🔄 工作流开发规范 (Warm-Flow)
└── cursorrules-api-test.md      # 🧪 API测试规范
```

### 📖 规范文件详情

#### 📋 文档管理规范 (.cursor/cursorrules-docs.md)
- 文档目录组织（中文化架构）
- **🚨 强制性文档同步更新规则**
- 变更记录管理规范（按日期和用户分文件）
- 业务模块文档管理（为AI提供完整上下文）
- **📊 API文档拆分管理规范** (2025-07-01新增，文件夹重组):
  - **📁 文件夹结构**: 所有API文档统一存放在 `docs/开发文档/API/` 文件夹下
  - **📝 文件组织**: 按业务模块拆分：基础规范、认证登录、物业报修、满意度调查
  - **🔤 命名规范**: 中文文件命名，便于快速识别和查找
  - **🔗 模块化管理**: 独立维护，减少冲突，交叉引用基础规范
  - **📚 主入口**: API文档总览.md 作为统一导航入口
  - **📋 模板支持**: API文档模板.md 用于新API文档生成
  - **🔄 自动生成规则**: 新增API模块时，优先在API文件夹下创建对应文档
- 测试文档管理规范

#### 🎨 前端开发规范 (.cursor/cursorrules-frontend.md)
- Vue 3.5.13 + TypeScript 5.8.3 技术栈
- Art Design Pro UI 设计规范
- 轮廓式按钮设计系统
- 组件开发标准和页面模板
- API接口定义和状态管理
- 项目架构和性能优化

#### ⚙️ 后端开发规范 (.cursor/cursorrules-backend.md)
- Spring Boot 3.4.6 技术栈
- **🔴 数据库规范（强制性）** - 雪花ID、逻辑删除、多租户
- **🔴 API接口规范（强制性）** - 统一响应格式、Token认证
- **🔐 菜单界面和接口权限配置规范**
- 标准代码模板 (Controller/Service/Mapper)

#### 📱 移动端开发规范 (.cursor/cursorrules-mobile.md)
- Vue 2.6.14 + uni-app 2.x + uview-ui 2.0.38 技术栈（智慧校园移动应用）
- 基于Vue 2的响应式项目架构（包含Vuex状态管理）
- 现代CSS变量设计系统和响应式布局适配
- 完整的用户体验优化（动画、手势识别、无障碍访问）
- 智能缓存策略和网络请求优化
- 多端发布支持（H5、微信小程序、App、鸿蒙）

#### 🔄 工作流开发规范 (.cursor/cursorrules-workflow.md)
- **Warm-Flow工作流框架** - 基于dromara社区开源的轻量级工作流引擎
- **🔴 强制性VO类规范（避免MyBatis映射错误）** - 所有工作流业务VO类必须包含四个基础字段
- **工作流状态管理** - 7种标准业务状态（draft、waiting、complete等）
- **标准工作流模式** - 普通流程、排他网关、并行网关、会签等6种模式
- **前端工作流组件** - approvalButton、submitVerify、approvalRecord标准组件使用
- **工作流权限配置** - @ConditionalOnEnable条件开启和Sa-Token权限控制
- **请假工作流示例** - 完整的工作流开发实践模板

#### 🧪 API测试规范 (.cursor/cursorrules-api-test.md)
- **✅ AES+RSA双重加密登录方法（已完全解决）**
- API测试最佳实践和通用测试方法
- 自动化测试脚本和性能测试
- 测试记录模板

---

## 🚨 核心开发原则（必须遵循）

### 1. 📝 强制性文档同步更新
**⚠️ 超级重要**: 每次代码调整都必须立即同步更新相应文档！

#### 必须更新的文档
- **API变更** → 按业务模块更新对应的API文档(2025-07-01重新组织到API文件夹):
  - 基础规范变更 → `docs/开发文档/API/API文档基础规范.md`
  - 认证登录变更 → `docs/开发文档/API/用户认证登录API.md`
  - 物业报修变更 → `docs/开发文档/API/物业报修管理API.md`
  - 满意度调查变更 → `docs/开发文档/API/后勤满意度调查API.md`
  - API文档总览 → `docs/开发文档/API/API文档总览.md`
- **数据库变更** → `docs/设计文档/database/`
- **业务逻辑变更** → `docs/业务模块/[模块名称]/`
- **配置变更** → `docs/中间件配置/` 或 `docs/部署文档/`
- **📱 移动端变更** → 移动端工程相关文档必须同步更新:
  - **移动端API新增/变更** → 相应的API文档必须补充移动端实现章节
  - **移动端页面开发** → `docs/开发文档/` 移动端相关文档
  - **移动端功能变更** → `docs/业务模块/[模块名称]/` 移动端部分
  - **移动端技术规范变更** → `.cursor/cursorrules-mobile.md`

#### 变更记录规范
- **文件格式**: `docs/变更管理/code-adjust-record-YYYY-MM-DD-{username}.md`
- **排序要求**: 按时间倒序排列，最新记录在最上面
- **时间填写**: 必须填写真实的当前时间（YYYY-MM-DD HH:mm:ss）

### 2. 🔴 数据库开发强制要求
- **标准基础字段**: 所有业务表必须包含统一的基础字段
- **雪花ID主键**: 统一使用 `bigint(20)` 作为主键
- **逻辑删除**: 禁止物理删除，使用 `deleted` 字段
- **多租户支持**: 必须包含 `tenant_id` 字段
- **参考规范**: `docs/设计文档/database/mysql-database-standard.md`

### 3. 🔴 API接口开发强制要求
- **统一响应格式**: 分页用TableDataInfo，非分页用R类型
- **Token认证**: Bearer格式，包含clientid、referer等必需Header
- **权限注解**: 每个接口必须有@SaCheckPermission注解
- **参数验证**: 使用Bean Validation进行参数校验

### 4. 🎯 技术要求
- **Node.js**: 20.15.x+, npm 10.7.x+
- **Java**: JDK 17/21
- **前端访问**: http://localhost (默认80端口)
- **后端服务**: http://localhost:8080
- **移动端**: Vue 2.6.14 + uni-app 2.x + uview-ui 2.0.38（智慧校园移动应用，端口8081）

---

## 🔄 Cursor AI 工作流程

### 📋 开发工作流程
```
1. **确定开发场景** → 自动应用对应技术栈规范
2. **编写/修改代码** → 遵循相应的编码规范
3. **立即更新文档** → 同步更新API文档和相关文档
4. **记录变更日志** → 在当日变更文件中记录
5. **验证和测试** → 确保功能正常和文档准确
```

### 🤖 Cursor AI 规范应用
- **前端开发**: 自动参考 `cursorrules-frontend.md`
- **后端开发**: 自动参考 `cursorrules-backend.md`
- **移动端开发**: 自动参考 `cursorrules-mobile.md`
- **工作流开发**: 自动参考 `cursorrules-workflow.md`
- **文档更新**: 自动参考 `cursorrules-docs.md`
- **API测试**: 自动参考 `cursorrules-api-test.md`

### 👍 点赞后知识总结机制

**⚠️ 重要提醒：当用户对Cursor回答点赞时，请主动询问是否需要进行总结归档**

#### 点赞触发规则
- **触发条件**: 用户对Cursor的回答点赞（👍）
- **自动提醒**: "检测到您对本次回答满意，是否需要将相关经验总结归档到项目规范中？"
- **总结目标**: 将成功的解决方案、最佳实践、经验教训整理到规范文档中

#### 总结内容建议
1. **技术解决方案**: 将有效的技术方案整理到对应的cursorrules文档
2. **开发流程优化**: 将改进的工作流程补充到开发规范中
3. **最佳实践**: 将成功经验添加到最佳实践文档
4. **问题解决方案**: 将常见问题和解决方案整理到知识库
5. **规范完善**: 根据实际应用效果完善和优化现有规范

#### 总结文档位置
- **技术规范**: 对应的`.cursor/cursorrules-*.md`文件
- **最佳实践**: `docs/开发文档/API开发最佳实践总结.md`
- **项目知识库**: `docs/知识库/`目录
- **变更记录**: `docs/变更管理/code-adjust-record-YYYY-MM-DD-{username}.md`

#### 总结流程
```
用户点赞 → Cursor主动询问 → 确认总结 → 分析价值点 → 整理到规范 → 更新相关文档
```

#### 价值目标
- 📚 **知识积累**: 将零散的经验系统化整理
- 🔄 **规范优化**: 基于实际应用持续改进规范
- 📖 **团队共享**: 将个人经验转化为团队资产
- 🚀 **效率提升**: 为后续类似问题提供标准解决方案

### 💡 API开发最佳实践

**⚠️ 基于场地预约管理系统开发实践制定的标准流程**

#### 完整开发流程（6个阶段）
1. **需求分析和文档创建** → 业务需求+技术架构文档
2. **数据库设计和初始化** → 表结构+字典+权限+示例数据
3. **后端模块开发** → 完整ruoyi模块（16个API接口）
4. **API文档编写** → 400+行详细API文档
5. **自动化测试脚本** → 450+行Python测试脚本
6. **变更记录和验证** → 完整的变更日志

#### 16个标准API接口模式
- **基础管理接口（6个）**: list、详情、新增、修改、删除、可用选项
- **业务功能接口（4个）**: 我的数据、待处理、规则检查、审批
- **辅助功能接口（6个）**: 导出、导入、统计、批量、启用、禁用

#### 🔴 VO类基础字段统一规范（新增 2025-07-01）

**⚠️ 超级重要：所有VO类必须包含统一的基础字段！**

**背景问题**：
- MyBatis-Plus自动查询：不包含继承字段
- 自定义SQL查询：明确包含字段，VO类必须有对应属性
- 导致运行时字段缺失错误：`Could not set property 'createBy'`

**统一解决方案**：
```java
// 所有VO类必须包含的四个基础字段
private Long createBy;      // 创建者
private Date createTime;    // 创建时间（含JSON格式化）
private Long updateBy;      // 更新者  
private Date updateTime;    // 更新时间（含JSON格式化）
```

**强制要求**：
- ✅ 新增VO类必须包含四个基础字段
- ✅ 修复现有VO类时必须补全缺失字段
- ✅ 时间字段使用`@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")`
- ✅ 详细规范见：`.cursor/cursorrules-backend.md` → "VO类基础字段规范"

#### 质量保证标准
- ✅ **完整交付物**: 2个需求文档+3个SQL脚本+18个代码文件+1个API文档+1个测试脚本
- ✅ **开发时长**: 约3.5天完成完整API模块
- ✅ **文档同步**: 代码完成立即更新相关文档
- ✅ **测试覆盖**: 强制AES+RSA加密登录+完整功能测试
- ✅ **VO类规范**: 所有VO类包含统一基础字段，避免MyBatis映射错误

#### 参考文档
- **完整实践总结**: `docs/开发文档/API开发最佳实践总结.md`
- **成功案例**: `docs/开发文档/API/场地预约管理API.md`
- **测试脚本模板**: `test/场地预约API测试脚本.py`
- **VO类规范**: `.cursor/cursorrules-backend.md` → "VO类基础字段规范（强制性）"

---

## 🎯 快速开始

### 💡 开发提示
1. **查看具体规范**: 打开对应的 `.cursor/cursorrules-*.md` 文件
2. **遵循强制要求**: 特别注意标记为🔴和🚨的强制性规范
3. **使用标准模板**: 参考各规范文件中的代码模板
4. **及时更新文档**: 代码完成后立即更新相关文档

### 📚 重要文档位置
- **项目启动指南**: `工程本地启动指导.md`
- **API文档拆分架构** (按业务模块拆分，2025-07-01优化并重新组织到API文件夹):
  - 📚 **API文档总览**: `docs/开发文档/API/API文档总览.md` (主入口导航)
  - 📋 **基础规范**: `docs/开发文档/API/API文档基础规范.md` (通用规范)
  - 🔐 **认证登录**: `docs/开发文档/API/用户认证登录API.md` (登录、用户信息)
  - 🛠️ **物业报修**: `docs/开发文档/API/物业报修管理API.md` (报修工单管理)
  - 📊 **满意度调查**: `docs/开发文档/API/后勤满意度调查API.md` (问卷答题)
  - 📝 **API文档模板**: `docs/开发文档/API/API文档模板.md` (新API文档生成模板)
- **数据库设计**: `docs/设计文档/database/`
- **业务模块文档**: `docs/业务模块/`
- **测试脚本**: `test/` 目录

---

## 📞 规范说明

### 🔧 规范更新
- **规范文件更新**: 直接编辑对应的专门文件
- **跨模块变更**: 需要在相关文件中保持一致
- **重大变更**: 需要同步更新本主配置文件

### 📋 使用原则
1. **技术栈导向**: 根据当前开发的技术栈参考对应规范
2. **强制性要求**: 必须严格遵循标记为强制性的规范
3. **文档同步**: 代码变更必须同步更新文档
4. **质量保证**: 确保代码和文档的一致性

---

**🎯 目标**: 通过模块化规范管理和强制性文档同步，为Cursor AI提供准确的开发上下文，确保高质量的代码生成和完善的项目文档！

**📝 维护**: 拆分完成于 2025-07-01，所有原有内容完整保留  
**📁 文件**: 5个专门规范文件 + 1个主配置文件  
**🔄 加载**: Cursor自动识别和应用相关规范

# 原型文件存放规范（2025-07-01 新增）
- 所有后续生成的原型文件（如HTML原型、交互原型等），必须统一存放在 docs/原型文件/ 目录下的相应子目录中。
- 子目录应按端（如 web、移动端、小程序等）或业务模块分类，确保结构清晰、便于查找和维护。
- 禁止将原型文件存放在源码目录（如 web/src、mobile/src 等）或其他非文档目录。
- 迁移或生成原型文件时，需同步更新目录结构说明文档（如 docs/原型文件/README.md ）。

# uview-ui 图标组件规范（2025-01-03 更新）
- 移动端UI开发中，图标组件统一使用 <u-icon />（uview-ui 2.x 官方标准），同时支持iconfont自定义图标。
- 推荐通过 easycom 自动全局注册，无需手动 import。
- 标准用法示例：
  ```vue
  <u-icon name="account" size="22" color="#b0b8c9" />
  <u-icon name="lock-open" size="22" color="#b0b8c9" />
  ```
- 图标名称请参考 uview-ui 官方文档：https://www.uviewui.com/components/icon.html