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/` (uniapp + uView UI)
- **文档管理**: `docs/` (完整的项目文档体系)

---

## 📚 规范文件引用

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

### 🔗 专门规范文件
```
.cursor/
├── cursorrules-docs.md          # 📋 文档管理规范
├── cursorrules-frontend.md      # 🎨 前端开发规范 (Vue 3)
├── cursorrules-backend.md       # ⚙️ 后端开发规范 (Spring Boot)
├── cursorrules-mobile.md        # 📱 移动端开发规范 (uniapp)
└── 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)
- uni-app + uView UI 技术栈
- 页面和组件开发规范
- 与后端API对接规范
- 状态管理和配置规范
- 性能优化和测试

#### 🧪 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/部署文档/`

#### 变更记录规范
- **文件格式**: `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

---

## 🔄 Cursor AI 工作流程

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

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

---

## 🎯 快速开始

### 💡 开发提示
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自动识别和应用相关规范