init

2025-06-26 18:30:03 +08:00
commit 1ab9f9c458
@@ -0,0 +1,643 @@
+# Cursor Rules - 项目开发规范
+
+## 项目结构说明
+- **前端工程**：`web/` (基于Vue 3 + TypeScript + Element Plus)
+- **后端工程**：`backend/` (基于RuoYi-Vue-Plus + Spring Boot 3.4.6)
+- **移动端工程**：`mobile/` (基于uniapp + uView UI构建的校园管理移动端应用)
+- **文档管理**：`docs/` (项目的需求、设计、开发、测试、部署文档)
+
+---
+
+# 第一部分：项目文档管理规范
+
+## 1. 文档结构管理 (docs/)
+
+### 文档目录组织
+```
+docs/
+├── requirements/         # 需求文档
+│   ├── README.md        # 需求管理说明
+│   └── [功能模块]/      # 具体功能需求文档
+├── design/              # 设计文档
+│   ├── README.md        # 设计文档说明
+│   ├── database/        # 数据库设计
+│   │   ├── hzdyjs_xg.sql       # 完整数据库模型
+│   │   ├── database_msg.md     # 环境配置信息
+│   │   └── README.md           # 数据库设计说明
+│   └── [模块设计]/      # 其他设计文档
+├── development/         # 开发文档
+│   └── README.md        # 开发指南
+├── testing/             # 测试文档
+│   └── README.md        # 测试计划和用例
+├── deployment/          # 部署文档
+│   └── README.md        # 部署指南
+├── middleware/          # 中间件配置文档
+│   ├── mysql-config.md  # MySQL配置文档
+│   └── README.md        # 中间件配置说明
+└── code-adjust-record.md # 代码调整记录
+```
+
+## 2. 代码调整记录管理
+
+### 📝 重要提醒：代码调整记录要求
+
+**每次使用Cursor修改任何代码时，都必须在 `docs/code-adjust-record.md` 文件中记录调整信息。**
+
+### 记录格式标准
+每次调整后请按以下格式记录：
+
+```markdown
+## 调整记录 - YYYY-MM-DD HH:mm:ss
+
+**调整时间**: YYYY-MM-DD HH:mm:ss
+**调整人**: [开发者姓名/Cursor AI辅助]
+**调整目的**: [简述调整原因和目标]
+**涉及文件**: 
+- [具体的文件路径]
+
+**调整内容详述**:
+1. 具体调整了哪些代码
+2. 修改了哪些功能
+3. 优化了哪些性能
+4. 修复了哪些问题
+
+**技术细节**:
+- 使用的技术栈: [技术栈信息]
+- 遵循的设计规范: [设计规范]
+- 其他重要技术决策
+
+**测试验证**:
+- [ ] 功能测试通过
+- [ ] 代码规范检查通过
+- [ ] 类型检查通过
+- [ ] 兼容性测试通过
+
+**备注**: 其他需要说明的内容
+
+---
+```
+
+### 记录要求
+1. **及时性**: 每次代码调整完成后立即记录
+2. **完整性**: 包含所有必要信息字段
+3. **准确性**: 详细描述实际的调整内容
+4. **可追溯性**: 便于后续查看和维护
+
+### ⚠️ 强制要求
+**所有通过Cursor AI进行的代码调整都必须在 `docs/code-adjust-record.md` 中留下记录，这是项目管理的强制性要求。**
+
+## 3. 文档同步更新规则
+
+### 📋 核心原则：代码与文档同步更新
+**⚠️ 重要规则：每次代码调整完成后，必须同步更新相应的项目文档，确保项目文档永远保持最新状态。**
+
+### 强制更新规则
+每次代码调整必须同步更新相关文档:
+- **API文档**: 接口变更时更新相关文档
+- **数据库文档**: 表结构变更时更新 `docs/design/database/` 下的所有相关文档
+- **配置文档**: 配置项变更时更新 `docs/middleware/` 下的配置说明
+- **部署文档**: 部署流程变更时更新 `docs/deployment/` 下的部署手册
+- **功能文档**: 新增功能时更新 `docs/requirements/` 下的需求文档
+- **设计文档**: 架构变更时更新 `docs/design/` 下的设计文档
+
+### 📝 文档同步更新清单
+每次代码调整后，请检查以下文档是否需要更新：
+
+#### 前端代码调整时需更新的文档：
+- [ ] **组件文档**: 新增或修改组件时，更新组件使用说明
+- [ ] **页面功能文档**: 页面功能变更时，更新用户操作手册
+- [ ] **API对接文档**: 前端API调用变更时，更新接口对接说明
+- [ ] **UI设计文档**: 界面样式重大变更时，更新设计规范文档
+
+#### 后端代码调整时需更新的文档：
+- [ ] **接口文档**: API接口变更时，更新接口文档和示例
+- [ ] **数据库文档**: 表结构变更时，更新数据库设计文档
+- [ ] **业务逻辑文档**: 业务规则变更时，更新业务流程文档
+- [ ] **配置文档**: 系统配置变更时，更新配置说明文档
+
+#### 移动端代码调整时需更新的文档：
+- [ ] **功能文档**: 移动端功能变更时，更新功能说明文档
+- [ ] **API对接文档**: 移动端API调用变更时，更新接口对接说明
+- [ ] **用户手册**: 用户操作流程变更时，更新操作指南
+
+### 🔄 文档更新工作流程
+1. **代码调整完成** → 2. **记录代码调整日志** → 3. **识别影响的文档** → 4. **更新相应文档** → 5. **验证文档完整性**
+
+### 版本管理
+- **文档版本**: 与代码版本保持同步
+- **变更记录**: 每次变更都要记录变更内容和原因
+- **向后兼容**: 接口变更需要考虑向后兼容性
+
+---
+
+# 第二部分：Web前端开发规范 (web/)
+
+## 1. 技术栈规范
+
+### 核心技术
+- **框架**: Vue 3.5.13 + TypeScript 5.8.3
+- **UI组件库**: Element Plus 2.9.8
+- **构建工具**: Vite 7.0.9
+- **状态管理**: Pinia
+- **路由管理**: Vue Router 4
+- **HTTP客户端**: Axios
+- **代码风格**: ESLint + Prettier
+
+## 2. Art Design Pro UI 规范
+
+### 设计理念
+基于 Art Design Pro 的设计语言，追求现代化、精致、用户友好的界面体验。注重细节、动效和用户交互的流畅性。
+
+### 颜色系统
+
+#### 主色调 (Primary Colors)
+```css
+--art-primary: 93, 135, 255;        /* 主品牌色 - 蓝色 */
+--art-secondary: 73, 190, 255;      /* 辅助色 - 天蓝色 */
+--art-success: 19, 222, 185;        /* 成功色 - 绿色 */
+--art-warning: 255, 174, 31;        /* 警告色 - 橙色 */
+--art-error: 250, 137, 107;         /* 错误色 - 红色 */
+--art-info: 83, 155, 255;           /* 信息色 - 蓝色 */
+--art-danger: 255, 77, 79;          /* 危险色 - 红色 */
+```
+
+#### 背景色系统
+```css
+/* 浅色主题 */
+--art-bg-color: #fafbfc;            /* 页面底色 */
+--art-main-bg-color: #ffffff;       /* 主要内容背景 */
+--art-bg-primary: 236, 242, 255;    /* 主色背景 */
+--art-bg-secondary: 232, 247, 255;  /* 辅助背景 */
+--art-bg-success: 230, 255, 250;    /* 成功背景 */
+--art-bg-warning: 254, 245, 229;    /* 警告背景 */
+--art-bg-error: 253, 237, 232;      /* 错误背景 */
+
+/* 暗色主题 */
+html.dark {
+  --art-bg-color: #070707;          /* 页面底色 */
+  --art-main-bg-color: #161618;     /* 主要内容背景 */
+}
+```
+
+### 轮廓式按钮设计系统
+
+#### 🎨 设计理念
+全面采用轮廓式（Outline）按钮设计，提供更加优雅、现代和一致的用户界面体验。
+
+#### 核心规范
+- **Primary按钮**: 轮廓式主色设计，主色边框和文字，5%透明度主色背景
+- **Success按钮**: 轮廓式成功色设计，成功色边框和文字，5%透明度成功色背景
+- **Warning按钮**: 轮廓式警告色设计，警告色边框和文字，5%透明度警告色背景
+- **Danger按钮**: 轮廓式危险色设计，危险色边框和文字，5%透明度危险色背景
+- **Info按钮**: 轮廓式信息色设计，信息色边框和文字，5%透明度信息色背景
+- **Default按钮**: 白色背景，灰色边框，灰色文字
+
+#### 交互效果
+- **悬浮状态**: 上移1px + 背景透明度变为10% + 边框透明度变为80% + 彩色阴影
+- **点击状态**: 98%缩放 + 0.1s快速过渡 + 背景透明度变为15%
+- **禁用状态**: 50%透明度，禁用所有交互和变换
+
+## 3. 组件开发规范
+
+### Vue组件结构标准
+```vue
+<template>
+  <div class="component-container">
+    <!-- 组件内容 -->
+  </div>
+</template>
+
+<script setup lang="ts" name="ComponentName">
+// 1. 引入依赖
+import { ref, reactive, computed, onMounted } from 'vue';
+import type { ComponentProps, ComponentEmits } from './types';
+
+// 2. 定义Props和Emits
+const props = defineProps<ComponentProps>();
+const emits = defineEmits<ComponentEmits>();
+
+// 3. 响应式数据
+const loading = ref(false);
+const formData = reactive({});
+
+// 4. 计算属性
+const computedValue = computed(() => {
+  return /* 计算逻辑 */;
+});
+
+// 5. 方法定义
+const handleClick = () => {
+  // 方法实现
+};
+
+// 6. 生命周期
+onMounted(() => {
+  // 组件挂载后的逻辑
+});
+</script>
+
+<style lang="scss" scoped>
+.component-container {
+  // 样式实现
+}
+</style>
+```
+
+### 页面开发规范
+
+#### 列表页面标准模板
+```vue
+<template>
+  <div class="p-2 page-container">
+    <!-- 搜索区域 -->
+    <transition :enter-active-class="proxy?.animate.searchAnimate.enter"
+                :leave-active-class="proxy?.animate.searchAnimate.leave">
+      <div v-show="showSearch" class="mb-[10px]">
+        <el-card shadow="hover">
+          <el-form ref="queryFormRef" :model="queryParams" :inline="true" label-width="100px">
+            <!-- 搜索表单项 -->
+            <el-form-item>
+              <el-button type="primary" icon="Search" @click="handleQuery">搜索</el-button>
+              <el-button icon="Refresh" @click="resetQuery">重置</el-button>
+            </el-form-item>
+          </el-form>
+        </el-card>
+      </div>
+    </transition>
+
+    <!-- 表格区域 -->
+    <el-card shadow="never" class="button-card table-card">
+      <template #header>
+        <el-row :gutter="10" class="mb8">
+          <el-col :span="1.5">
+            <el-button type="primary" plain icon="Plus" @click="handleAdd">新增</el-button>
+          </el-col>
+          <right-toolbar v-model:showSearch="showSearch" @queryTable="getList"></right-toolbar>
+        </el-row>
+      </template>
+
+      <!-- 数据表格 -->
+      <el-table v-loading="loading" border :data="dataList" :height="tableHeight">
+        <el-table-column type="selection" width="55" align="center" />
+        <!-- 数据列 -->
+        <el-table-column label="操作" align="center" width="160">
+          <template #default="scope">
+            <!-- 操作按钮 -->
+          </template>
+        </el-table-column>
+      </el-table>
+
+      <!-- 分页组件 -->
+      <pagination v-show="total > 0" :total="total"
+                  v-model:page="queryParams.pageNum"
+                  v-model:limit="queryParams.pageSize"
+                  @pagination="getList" />
+    </el-card>
+  </div>
+</template>
+```
+
+## 4. API开发规范
+
+### API接口定义标准
+```typescript
+// api/[module]/index.ts
+import request from '@/utils/request';
+import type { AxiosPromise } from 'axios';
+import type { DataVO, DataForm, DataQuery } from './types';
+
+/**
+ * 查询数据列表
+ * @param query 查询参数
+ */
+export const listData = (query?: DataQuery): AxiosPromise<DataVO[]> => {
+  return request({
+    url: '/api/data/list',
+    method: 'get',
+    params: query
+  });
+};
+```
+
+## 5. 项目架构规范
+
+### 目录结构标准
+```
+web/src/
+├── api/                    # API接口定义
+├── assets/                 # 静态资源
+├── components/             # 通用组件
+├── views/                  # 页面视图
+├── layout/                 # 布局组件
+├── router/                 # 路由配置
+├── store/                  # 状态管理
+├── utils/                  # 工具函数
+├── plugins/                # 插件配置
+├── types/                  # 全局类型定义
+└── main.ts                 # 应用入口
+```
+
+---
+
+# 第三部分：后端开发规范 (backend/)
+
+## 1. 技术栈规范
+
+### 核心技术
+- **框架**: Spring Boot 3.4.6
+- **Java版本**: JDK 17/21
+- **Web容器**: Undertow
+- **ORM框架**: MyBatis-Plus 3.5.12
+- **数据库**: MySQL/Oracle/PostgreSQL/SQLServer (多数据库支持)
+- **缓存**: Redis 5-7 + Redisson 3.45.1
+- **权限认证**: Sa-Token 1.42.0 + JWT
+- **任务调度**: SnailJob 1.5.0
+- **工作流**: Warm-Flow 1.7.3
+
+## 2. 项目结构规范
+
+### 后端模块结构
+```
+backend/
+├── ruoyi-admin/          # 管理后台启动模块
+├── ruoyi-common/         # 公共模块组
+│   ├── ruoyi-common-core/        # 核心模块
+│   ├── ruoyi-common-mybatis/     # MyBatis配置
+│   ├── ruoyi-common-redis/       # Redis配置
+│   ├── ruoyi-common-satoken/     # Sa-Token配置
+│   └── ... (其他公共模块)
+├── ruoyi-modules/        # 业务模块组
+│   ├── ruoyi-system/     # 系统管理模块
+│   ├── ruoyi-demo/       # 示例模块
+│   └── ... (其他业务模块)
+├── ruoyi-extend/         # 扩展模块组
+└── script/               # 脚本和SQL
+```
+
+## 3. 开发规范
+
+### 代码规范
+- **严格遵守**: Alibaba Java开发手册
+- **命名规范**:
+  - 类名: PascalCase (如: UserController)
+  - 方法名: camelCase (如: getUserList)
+  - 常量: UPPER_SNAKE_CASE (如: MAX_RETRY_COUNT)
+  - 包名: 全小写 (如: org.dromara.system)
+
+### 数据库规范
+- **现有数据库模型**: 参考 `docs/design/database/hzdyjs_xg.sql` 中的完整表结构
+- **环境配置**: 开发环境数据库信息见 `docs/design/database/database_msg.md`
+- **主键设计**: 使用雪花ID (ASSIGN_ID)，不使用数据库自增
+- **字段命名**: 下划线命名法 (如: user_name, create_time)
+- **基础字段**: 所有业务表必须包含以下字段
+  ```sql
+  id BIGINT PRIMARY KEY,
+  tenant_id VARCHAR(20),     -- 租户ID (多租户)
+  create_dept BIGINT,        -- 创建部门
+  create_by BIGINT,          -- 创建人
+  create_time DATETIME,      -- 创建时间
+  update_by BIGINT,          -- 更新人
+  update_time DATETIME,      -- 更新时间
+  deleted TINYINT DEFAULT 0  -- 逻辑删除标记
+  ```
+
+### API接口规范
+- **RESTful设计**: 遵循REST API设计原则
+- **统一响应格式**:
+  ```json
+  {
+    "code": 200,
+    "msg": "操作成功",
+    "data": {}
+  }
+  ```
+- **权限控制**: 使用Sa-Token注解进行权限校验
+  ```java
+  @SaCheckPermission("system:user:list")
+  ```
+
+## 4. 标准代码模板
+
+### Controller模板
+```java
+@RestController
+@RequestMapping("/system/user")
+@Api(tags = "用户管理")
+public class SysUserController extends BaseController {
+
+    @Autowired
+    private ISysUserService userService;
+
+    @SaCheckPermission("system:user:list")
+    @GetMapping("/list")
+    @Operation(summary = "查询用户列表")
+    public TableDataInfo<SysUserVo> list(SysUserBo user, PageQuery pageQuery) {
+        return userService.queryPageList(user, pageQuery);
+    }
+}
+```
+
+### Service模板
+```java
+@Service
+public class SysUserServiceImpl implements ISysUserService {
+
+    @Autowired
+    private SysUserMapper userMapper;
+
+    @Override
+    public TableDataInfo<SysUserVo> queryPageList(SysUserBo bo, PageQuery pageQuery) {
+        LambdaQueryWrapper<SysUser> lqw = buildQueryWrapper(bo);
+        Page<SysUserVo> result = userMapper.selectVoPage(pageQuery.build(), lqw);
+        return TableDataInfo.build(result);
+    }
+}
+```
+
+---
+
+# 第四部分：移动端开发规范 (mobile/)
+
+## 1. 技术栈规范
+
+### 核心技术
+- **框架**: uni-app
+- **UI组件库**: uView UI
+- **开发语言**: JavaScript/TypeScript
+- **状态管理**: Vuex
+- **HTTP客户端**: uni.request 封装
+
+## 2. 项目结构规范
+
+### 移动端目录结构
+```
+mobile/
+├── src/
+│   ├── api/              # API接口定义
+│   ├── components/       # 通用组件
+│   ├── pages/            # 页面文件
+│   │   ├── index/        # 首页
+│   │   ├── login/        # 登录页
+│   │   ├── mine/         # 个人中心
+│   │   └── workbench/    # 工作台
+│   ├── static/           # 静态资源
+│   ├── utils/            # 工具函数
+│   ├── App.vue           # 应用入口
+│   ├── config.js         # 配置文件
+│   └── main.js           # 主入口文件
+├── pages.json            # 页面配置
+├── manifest.json         # 应用配置
+└── uni.scss             # 全局样式
+```
+
+## 3. 开发规范
+
+### 页面开发规范
+- **页面命名**: 使用小写字母和连字符 (如: user-list)
+- **组件命名**: 使用PascalCase (如: UserCard)
+- **API调用**: 统一使用封装的request工具
+- **样式规范**: 使用uView UI组件和样式变量
+
+### 页面模板
+```vue
+<template>
+  <view class="page-container">
+    <u-navbar title="页面标题" @leftClick="handleBack"></u-navbar>
+    <!-- 页面内容 -->
+  </view>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      // 页面数据
+    }
+  },
+  onLoad() {
+    // 页面加载逻辑
+  },
+  methods: {
+    handleBack() {
+      uni.navigateBack();
+    }
+  }
+}
+</script>
+
+<style lang="scss" scoped>
+.page-container {
+  // 页面样式
+}
+</style>
+```
+
+## 4. 与后端API对接规范
+
+### 请求封装
+```javascript
+// utils/request.js
+const request = (options) => {
+  return new Promise((resolve, reject) => {
+    uni.request({
+      url: getApp().globalData.baseUrl + options.url,
+      method: options.method || 'GET',
+      data: options.data || {},
+      header: {
+        'Authorization': uni.getStorageSync('token'),
+        'Content-Type': 'application/json'
+      },
+      success: (res) => {
+        if (res.data.code === 200) {
+          resolve(res.data);
+        } else {
+          reject(res.data);
+        }
+      },
+      fail: (err) => {
+        reject(err);
+      }
+    });
+  });
+};
+```
+
+---
+
+# 通用开发原则
+
+## 1. 代码质量保证
+
+### 编码规范
+- 遵循各技术栈的官方编码规范
+- 使用统一的代码格式化工具
+- 添加适当的注释和文档
+- 进行代码审查
+
+### 测试要求
+- 单元测试覆盖核心业务逻辑
+- 集成测试验证API接口
+- UI测试确保界面交互正常
+- 性能测试保证系统响应速度
+
+## 2. 安全规范
+
+### 数据安全
+- 敏感数据脱敏处理
+- API接口权限控制
+- 输入参数严格校验
+- SQL注入防护
+
+### 系统安全
+- HTTPS协议传输
+- JWT token认证
+- 密码加密存储
+- 定期安全检查
+
+## 3. 性能优化
+
+### 前端优化
+- 代码分割和懒加载
+- 图片压缩和CDN
+- 缓存策略优化
+- 首屏加载优化
+
+### 后端优化
+- 数据库查询优化
+- Redis缓存策略
+- 异步处理耗时操作
+- JVM参数调优
+
+## 4. 文档维护
+
+### 同步更新
+- 代码变更必须同步更新文档
+- API文档自动生成和维护
+- 数据库变更记录追踪
+- 部署文档及时更新
+
+### 版本管理
+- 文档版本与代码版本保持一致
+- 重要变更记录详细说明
+- 保持向后兼容性考虑
+- 定期文档审查和整理
+
+---
+
+## 注意事项
+
+1. **严格遵循规范**: 所有开发必须按照本规范执行
+2. **代码调整记录**: 每次代码修改都必须在 `docs/code-adjust-record.md` 中记录
+3. **文档同步更新**: 代码变更必须同步更新相关文档
+4. **安全第一**: 所有功能开发都要考虑安全性
+5. **性能考虑**: 大数据量操作需要性能测试验证
+6. **团队协作**: 重要变更需要团队讨论和代码审查
+
+## 参考资源
+
+- **前端官方文档**: Vue 3、Element Plus、Vite
+- **后端官方文档**: Spring Boot、MyBatis-Plus、Sa-Token
+- **移动端官方文档**: uni-app、uView UI
+- **项目文档**: `docs/` 目录下的详细文档
+- **代码调整记录**: `docs/code-adjust-record.md`
+