# 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/
├── 项目总览/               # 项目基本信息和架构概览
│   ├── README.md          # 项目总览主文档
│   └── 项目总览模板.md     # 项目总览标准模板
├── 业务模块/               # 业务模块文档（为AI提供业务上下文）
│   ├── README.md          # 业务模块管理总览
│   ├── 业务模块开发模板.md  # 业务模块标准开发模板
│   ├── hq-satisfaction-survey/     # 后勤满意度调查模块
│   ├── hall-reservation/          # 报告厅预约模块
│   ├── system-management/         # 系统管理模块
│   └── user-management/           # 用户管理模块
├── 变更管理/               # 变更管理中心
│   ├── README.md          # 变更管理流程和规范
│   └── code-adjust-record.md      # 代码调整记录
├── 开发文档/               # 开发指南和技术规范
│   ├── README.md          # 开发文档总览
│   ├── API.md             # API接口完整文档
│   └── API文档模板.md      # API文档标准模板
├── 设计文档/               # 设计文档
│   ├── README.md          # 设计文档说明
│   └── database/          # 数据库设计
│       ├── hzdyjs_xg.sql         # 完整数据库模型
│       ├── 01-workflow-module.sql        # 工作流模块SQL
│       ├── 02-code-generator-module.sql  # 代码生成模块SQL
│       ├── 03-logistics-module.sql       # 后勤管理模块SQL
│       ├── 04-job-scheduler-module.sql   # 任务调度模块SQL
│       ├── 05-system-management-module.sql # 系统管理模块SQL
│       ├── 06-test-module.sql            # 测试模块SQL
│       ├── SQL文件说明.md                # SQL文件拆分说明
│       ├── mysql-database-standard.md   # MySQL数据库建设规范
│       ├── database_msg.md              # 环境配置信息
│       └── README.md                    # 数据库设计说明
├── 需求文档/               # 需求文档
│   ├── README.md          # 需求管理说明
│   ├── 后勤报告厅预约需求/ # 报告厅预约系统需求
│   └── 后勤满意度调查需求/ # 满意度调查系统需求
├── 测试文档/               # 测试文档
│   └── README.md          # 测试计划和用例
├── 部署文档/               # 部署文档
│   └── README.md          # 部署指南
├── 中间件配置/             # 中间件配置文档
│   ├── README.md          # 中间件配置说明
│   └── mysql-config.md    # MySQL配置文档
├── 知识库/                 # 知识库
├── 报告文档/               # 报告文档
├── structure-optimization-plan.md # 文档结构优化方案
└── README.md              # 文档体系总说明
```

### 🔴 重要文档说明
- **工程本地启动指导.md** (项目根目录)：包含完整的环境配置和启动指南
- **技术要求更新**：Node.js 20.15.x+, npm 10.7.x+
- **数据库环境**：支持本地安装或使用阿里云测试环境
- **前端访问地址**：http://localhost (非3000端口)

## 2. 🚨 强制性文档同步更新规则

### 📋 核心原则：代码与文档必须同步更新
**⚠️ 超级重要：每次使用Cursor AI进行代码调整后，必须立即同步更新相应的项目文档！**

### 🔴 强制更新触发条件
每次代码调整必须检查并更新以下文档：

#### 后端代码调整时的强制文档更新：
- **✅ API接口变更**：
  - 必须立即更新 `docs/开发文档/API.md`
  - 新增接口：添加完整接口文档（地址、参数、响应、权限、示例）
  - 修改接口：更新参数说明、响应格式、错误码
  - 删除接口：标记为已废弃，说明替代方案
  - 权限变更：更新权限要求说明

- **✅ 数据库变更**：
  - 更新 `docs/设计文档/database/` 下的相关文档
  - 新增表：添加表结构说明和字段注释
  - 修改表：更新字段变更和索引调整
  - 数据迁移：记录迁移脚本和注意事项

- **✅ 业务逻辑变更**：
  - 更新对应 `docs/业务模块/[模块名称]/` 下的业务文档
  - 更新业务流程图和业务规则说明
  - 修改用户故事和功能需求

- **✅ 配置变更**：
  - 更新 `docs/中间件配置/` 下的配置文档
  - 更新 `docs/部署文档/` 下的部署说明

#### 前端代码调整时的强制文档更新：
- **✅ 页面功能变更**：
  - 更新对应业务模块的用户操作文档
  - 更新UI设计规范文档

- **✅ API调用变更**：
  - 检查前端API调用是否与后端API文档一致
  - 更新API对接说明文档

- **✅ 组件变更**：
  - 更新组件使用说明和属性文档

#### 移动端代码调整时的强制文档更新：
- **✅ 功能变更**：更新移动端功能说明文档
- **✅ API对接变更**：更新移动端API调用文档
- **✅ 用户流程变更**：更新用户操作指南

#### 📚 docs文档变更时的强制同步更新规则：
**⚠️ 超级重要：每当docs/目录下的文档结构或重要内容发生变更时，必须立即同步更新.cursorrules文件！**

- **🔴 文档结构变更**：
  - 新增/删除目录：同步更新.cursorrules中的"文档目录组织"章节
  - 重命名目录：更新所有相关路径引用
  - 调整文档层级：更新文档结构说明

- **🔴 重要文档变更**：
  - 新增标准模板：在"文档模板体系"中添加说明
  - 更新开发规范：同步调整.cursorrules中对应的规范要求
  - 修改工作流程：更新"文档更新标准工作流程"

- **🔴 技术环境变更**：
  - 环境要求调整：更新.cursorrules中的技术栈规范
  - 配置信息变更：同步更新相关配置说明
  - 启动流程调整：更新开发指导相关内容

- **🔴 业务模块变更**：
  - 新增业务模块：在.cursorrules中添加模块说明
  - 模块架构调整：更新业务模块文档管理规范
  - API接口变更：确保.cursorrules中的API规范同步

**强制检查清单**：
- [ ] .cursorrules中的文档目录结构是否与实际一致
- [ ] 重要文档路径引用是否全部更新
- [ ] 新增的开发规范是否已同步到.cursorrules
- [ ] 技术要求和环境配置是否保持一致

### 🔄 文档更新标准工作流程

#### Cursor AI 辅助开发的文档更新流程：
```
1. **AI代码生成/修改完成**
   ↓
2. **立即检查文档更新需求**
   - 是否涉及API变更？
   - 是否涉及数据库变更？
   - 是否涉及业务逻辑变更？
   - 是否涉及配置变更？
   - 是否涉及docs文档结构变更？
   ↓
3. **立即更新相关文档**（不得延后！）
   - 使用标准模板格式
   - 确保信息准确完整
   - 添加真实示例
   ↓
4. **检查并更新.cursorrules文件**（重要！）
   - 如有docs文档结构变更，同步更新.cursorrules
   - 如有技术要求变更，同步更新技术栈规范
   - 如有开发流程变更，同步更新工作流程
   ↓
5. **记录变更日志**
   - 在 `docs/变更管理/code-adjust-record.md` 中记录
   - 标注已同步更新的文档列表
   - 标注是否已更新.cursorrules文件
   ↓
6. **验证文档准确性**
   - 确保文档与实际代码一致
   - 验证示例可以正常运行
   - 验证.cursorrules与实际项目状态一致
   ↓
7. **提交代码和文档变更**
```

### 📝 变更记录标准格式

**每次代码调整都必须在 `docs/变更管理/code-adjust-record.md` 中按以下格式记录：**

```markdown
## 调整记录 - YYYY-MM-DD HH:mm:ss

**变更ID**: CHG-YYYYMMDD-001
**变更时间**: YYYY-MM-DD HH:mm:ss
**变更人员**: [开发者姓名/Cursor AI辅助]
**变更类型**: 🆕新功能/🐛Bug修复/🔧重构优化/📚文档更新/⚙️配置调整
**影响级别**: 🔴重大变更/🟡中等变更/🟢小变更

### 📋 变更概述
**变更目的**: [简述变更原因和目标，1-2句话]
**影响范围**: [列出受影响的模块、功能或文件]

### 📁 涉及文件
**后端文件**:
- backend/[具体文件路径1]
- backend/[具体文件路径2]

**前端文件**:
- web/[具体文件路径1]  
- web/[具体文件路径2]

**配置文件**:
- [配置文件路径]

### 🔧 变更内容详述
**业务逻辑变更**:
1. [具体业务逻辑的变更说明]
2. [新增或修改的业务规则]

**技术实现变更**:
1. [技术方案的调整说明]
2. [代码结构的优化内容]

**接口变更**:
- **新增接口**: [新增接口列表]
- **修改接口**: [修改的接口及变更内容]
- **废弃接口**: [废弃的接口及替代方案]

**数据库变更**:
- **新增表**: [新增表及字段说明]
- **修改表**: [表结构变更内容]
- **数据迁移**: [数据迁移脚本或说明]

### 📖 文档同步更新记录
**API文档**: 
- [ ] ✅ 已更新 docs/开发文档/API.md
- [ ] ✅ 已更新模块API接口设计文档

**业务文档**:
- [ ] ✅ 已更新业务模块文档
- [ ] ✅ 已更新用户操作手册

**技术文档**:
- [ ] ✅ 已更新数据库设计文档
- [ ] ✅ 已更新架构设计文档

**其他文档**:
- [ ] ✅ 已更新部署文档
- [ ] ✅ 已更新配置文档

**规范文件**:
- [ ] ✅ 已检查并同步更新.cursorrules文件
- [ ] ✅ 已确认文档结构与.cursorrules一致

### 🧪 测试验证
**功能测试**:
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 功能验收测试通过

**文档验证**:
- [ ] 文档内容与代码实现一致
- [ ] 示例代码可以正常运行
- [ ] 接口文档已验证准确性

### 📝 备注
**已知问题**: [如有已知问题需要说明]
**后续计划**: [后续的改进或扩展计划]
**相关链接**: [相关的Issue、PR或文档链接]

---
```

## 3. 🔧 业务模块文档管理（为Cursor AI提供完整上下文）

### 业务模块文档标准结构
每个业务模块都必须包含以下完整文档：

```
业务模块/[模块名称]/
├── README.md                    # 模块总览
├── 需求分析/
│   ├── 业务需求说明.md           # 详细业务需求
│   ├── 功能需求清单.md           # 功能点清单
│   ├── 非功能需求.md             # 性能、安全要求
│   └── 用户故事.md               # 用户使用场景
├── 技术设计/
│   ├── 数据库设计.md             # 表结构设计
│   ├── API接口设计.md            # 接口定义
│   ├── 架构设计.md               # 模块架构
│   └── 技术选型.md               # 技术决策说明
├── 实现文档/
│   ├── 后端实现说明.md           # 后端代码结构
│   ├── 前端实现说明.md           # 前端代码结构
│   ├── 关键业务逻辑.md           # 核心算法逻辑
│   └── 代码规范.md               # 编码规范
├── 测试文档/
│   ├── 测试计划.md               # 测试策略
│   ├── 测试用例.md               # 具体测试用例
│   └── 测试报告.md               # 测试结果
└── 运维文档/
    ├── 部署指南.md               # 部署步骤
    ├── 监控配置.md               # 监控指标
    └── 故障处理.md               # 常见问题
```

### 🤖 Cursor AI 开发提示词模板

#### 新功能开发提示词：
```
基于以下业务模块文档为 [功能名称] 开发代码：

业务上下文：docs/业务模块/[模块名称]/需求分析/
技术规范：docs/业务模块/[模块名称]/技术设计/
代码结构：docs/业务模块/[模块名称]/实现文档/
API规范：docs/开发文档/API.md

请确保：
1. 遵循项目编码规范
2. 使用标准的代码结构
3. 添加完整的注释
4. 生成单元测试代码
5. 立即更新相关文档

开发完成后请同步更新：
- docs/开发文档/API.md（如涉及API）
- docs/业务模块/[模块名称]/相关文档
- docs/变更管理/code-adjust-record.md
```

#### 文档更新提示词：
```
根据刚才的代码变更，请更新以下文档：

变更内容：[具体变更说明]
影响模块：[模块名称]

需要更新的文档：
1. docs/开发文档/API.md - [具体更新内容]
2. docs/业务模块/[模块名称]/[具体文档] - [具体更新内容]
3. docs/设计文档/database/ - [如涉及数据库变更]

请使用标准的文档模板格式，确保信息准确完整。
```

## 4. 📚 API文档管理规范

### 🔴 强制性API文档更新规则
**⚠️ 超级重要：任何API接口的新增、修改、删除都必须立即同步更新 `docs/开发文档/API.md` 文档！**

### API文档标准格式
使用 `docs/开发文档/API文档模板.md` 中的标准格式：

```markdown
#### 接口名称

**接口地址**: `HTTP方法 /api/路径`
**接口描述**: 接口功能的详细描述
**权限要求**: 权限代码或"需要登录"

**请求参数**: 
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| param1 | String | Y | 参数说明 | "example" |

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

**错误码**:
| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 400001 | 参数错误 | 检查请求参数 |
```

### 🚨 API变更强制检查清单

当进行以下操作时，必须更新 `docs/开发文档/API.md`：

**Controller层变更**：
- [ ] 新增Controller类 → 在API.md中添加新的模块章节
- [ ] 新增@RequestMapping方法 → 添加完整的接口文档
- [ ] 修改@RequestMapping路径 → 更新接口地址
- [ ] 修改HTTP方法 → 更新接口方法
- [ ] 删除接口方法 → 标记为已废弃并说明替代方案

**参数和响应变更**：
- [ ] 新增请求参数 → 更新请求参数表格
- [ ] 修改参数类型或必填属性 → 更新参数说明
- [ ] 修改响应数据结构 → 更新响应示例
- [ ] 新增错误码 → 更新错误码说明表

**权限和安全变更**：
- [ ] 新增@SaCheckPermission注解 → 更新权限要求
- [ ] 修改权限代码 → 更新权限说明
- [ ] 修改接口访问级别 → 更新权限要求说明

## 5. 📊 文档模板体系

### 已创建的标准模板：
- **`docs/项目总览/项目总览模板.md`** - 项目基本信息模板
- **`docs/业务模块/业务模块开发模板.md`** - 业务模块开发标准模板
- **`docs/开发文档/API文档模板.md`** - API接口文档标准模板

### 模板使用规范：
1. **新项目或模块开发时**：复制对应模板，替换占位符
2. **文档更新时**：参考模板格式，保持结构一致
3. **Cursor AI生成文档时**：使用模板作为格式参考

## 6. 🔍 文档质量控制

### 文档完整性检查清单：
- [ ] 文档结构符合标准模板
- [ ] 内容与实际代码实现一致
- [ ] API文档包含完整示例
- [ ] 业务逻辑描述清晰准确
- [ ] 技术实现说明详细
- [ ] 变更历史有完整记录
- [ ] 所有占位符已替换为真实内容

### 文档准确性验证：
- [ ] API接口示例可以正常调用
- [ ] 数据库脚本可以成功执行
- [ ] 配置文档与实际配置一致
- [ ] 部署文档可以成功部署

---

# 第二部分：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
- **Node.js**: 20.15.x+ (推荐 20.15.0)
- **npm**: 10.7.x+

### 环境要求
- **开发环境**: 支持本地环境或阿里云测试环境
- **数据库**: MySQL/Redis 支持本机安装或使用阿里云环境
- **前端访问**: http://localhost (默认80端口)
- **后端服务**: http://localhost:8080

## 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/设计文档/database/mysql-database-standard.md` 规范
- **现有数据库模型**: 参考 `docs/设计文档/database/hzdyjs_xg.sql` 中的完整表结构
- **环境配置**: 开发环境数据库信息见 `docs/设计文档/database/database_msg.md`

#### 🚨 强制性核心规范
1. **所有业务表必须包含标准基础字段**
2. **统一使用雪花ID (bigint(20)) 作为主键**
3. **强制使用逻辑删除，禁止物理删除**
4. **所有表必须支持多租户**
5. **完整的中文注释是必须的**
6. **禁止使用数据库外键约束**，关联关系通过应用层维护

#### 🔴 强制性基础字段模板
```sql
-- 所有业务表必须包含以下字段（顺序和类型必须完全一致）
`id` bigint(20) NOT NULL COMMENT '主键ID',
`tenant_id` varchar(20) NOT NULL DEFAULT '000000' COMMENT '租户编号',
`create_dept` bigint(20) DEFAULT NULL COMMENT '创建部门',
`create_by` bigint(20) DEFAULT NULL COMMENT '创建者',
`create_time` datetime DEFAULT NULL COMMENT '创建时间',
`update_by` bigint(20) DEFAULT NULL COMMENT '更新者',
`update_time` datetime DEFAULT NULL COMMENT '更新时间',
`deleted` tinyint(1) DEFAULT 0 COMMENT '删除标志（0代表存在 1代表删除）',

-- 业务字段在此处添加

PRIMARY KEY (`id`) USING BTREE,
KEY `idx_tenant_id` (`tenant_id`),
KEY `idx_deleted` (`deleted`),
KEY `idx_create_time` (`create_time`)
```

#### 🔴 AI开发强制要求
当使用AI进行数据库开发时：
1. **必须先阅读** `docs/设计文档/database/mysql-database-standard.md` 规范
2. **必须使用标准模板**，不得随意修改基础字段
3. **必须保持与现有表结构的一致性**
4. **建表后必须立即更新** `hzdyjs_xg.sql` 文件
5. **必须在变更记录中记录** 数据库变更

### API接口规范
- **RESTful设计**: 遵循REST API设计原则
- **统一响应格式**:
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {}
  }
  ```
- **权限控制**: 使用Sa-Token注解进行权限校验
  ```java
  @SaCheckPermission("system:user:list")
  ```

### 🔴 API开发强制性工作流程

#### 步骤1：编写后端代码
- 创建Controller、Service、Mapper等
- 实现业务逻辑和数据处理
- 添加权限控制和参数验证

#### 步骤2：立即更新API文档（强制性）
**⚠️ 代码写完后立即执行，不得延后！**
- 打开 `docs/开发文档/API.md` 文件
- 按照 `docs/开发文档/API文档模板.md` 的标准格式添加或更新接口文档
- 包含完整的接口信息（地址、参数、响应、权限等）
- 添加真实的请求和响应示例

#### 步骤3：记录代码调整日志
- 在 `docs/变更管理/code-adjust-record.md` 中记录本次变更
- 特别说明API接口的变更内容
- 标注文档已同步更新

#### 步骤4：验证和测试
- 测试API接口功能是否正常
- 验证API文档的准确性
- 确保文档示例与实际响应一致

#### 🚨 违规后果
**如果发现API变更未同步更新文档，该代码变更将被视为不完整，必须立即补齐文档。**

## 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. **🔴 API文档管理**：API接口变更必须立即更新 `docs/开发文档/API.md` 文档
3. **📋 变更记录**：每次调整都必须在 `docs/变更管理/code-adjust-record.md` 中记录
4. **🎯 业务上下文**：充分利用 `docs/业务模块/` 下的文档为AI提供完整业务上下文
5. **📚 模板使用**：使用标准文档模板，确保格式一致性
6. **🔍 质量控制**：确保文档内容与代码实现完全一致
7. **⚡ 实时性**：文档更新不得延后，必须与代码变更同步进行

## 参考资源

- **项目文档体系**：`docs/` 目录下的完整文档
- **业务模块文档**：`docs/业务模块/` 各模块的详细文档
- **开发文档**：`docs/开发文档/` 技术规范和API文档
- **变更记录**：`docs/变更管理/code-adjust-record.md`
- **标准模板**：各目录下的模板文件

**🎯 目标**：通过完善的文档管理体系，为Cursor AI提供准确的开发上下文，确保高质量的代码生成和文档同步更新！