hzdyjs/.cursor/cursorrules.md

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 + uview-ui 2.0.38 - 智慧校园移动端)
• 文档管理: docs/ (完整的项目文档体系)

---

📚 规范文件引用

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

🔗 专门规范文件

.cursor/
├── cursorrules-docs.md          # 📋 文档管理规范
├── cursorrules-frontend.md      # 🎨 前端开发规范 (Vue 3)
├── cursorrules-backend.md       # ⚙️ 后端开发规范 (Spring Boot)
├── cursorrules-mobile.md        # 📱 移动端开发规范 (Vue 2 + uni-app + uview-ui)
├── 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 + uview-ui 2.0.38 技术栈（智慧校园移动端）
• 基于Vue 2的稳定架构（兼容性优先）
• uview-ui 2.0.38 成熟UI组件库（Vue 2版本）
• 现代CSS变量设计系统和响应式布局适配
• 完整的用户体验优化（动画、手势识别、无障碍访问）
• 智能缓存策略和网络请求优化
• 多端发布支持（H5、微信小程序、App、鸿蒙）
• iconfont图标系统（支持uview-ui的u-icon组件）

🔄 工作流开发规范 (.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 + uview-ui 2.0.38（智慧校园移动端）

---

🔄 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'

统一解决方案：

// 所有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 ）。

移动端技术栈规范（2025-01-27 更新）

🚨 重要变更说明

变更时间: 2025-01-27
变更内容: 移动端技术栈从 Vue 3 + uview-plus 调整为 Vue 2 + uview-ui
变更原因: 基于项目实际技术配置和稳定性考虑

📱 移动端技术栈调整

调整前（错误）

• Vue 3.4.21 + uview-plus 3.4.45
• 现代化架构但与实际项目不符

调整后（正确）

• Vue 2.6.14 + uview-ui 2.0.38
• 基于uni-app的稳定架构
• 与实际项目配置完全一致

🔄 相关文档更新

• ✅ 主规范文件: .cursor/cursorrules.md - 移动端技术栈描述已更新
• ✅ 移动端规范: .cursor/cursorrules-mobile.md - 完整重写为Vue 2技术栈
• 📝 变更记录: 本次调整将记录在变更管理文档中

📋 开发者注意事项

1. 图标使用: 支持 iconfont 图标系统 + uview-ui 的 u-icon 组件
2. 组件引用: 使用 <u-xxx> 格式引用 uview-ui 组件
3. 页面配置: easycom 自动注册："^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
4. 样式导入: @import 'uview-ui/index.scss'

🎯 技术选型原则

• 稳定性优先: Vue 2 生态成熟稳定
• 兼容性考虑: uview-ui 2.x 对 uni-app 兼容性更好
• 团队熟悉度: 基于实际项目经验
• 维护成本: 降低技术栈复杂度