796 lines
25 KiB
Plaintext
796 lines
25 KiB
Plaintext
# 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 # 开发指南
|
||
│ └── API.md # API接口文档（完整的后端接口说明）
|
||
├── 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` 中留下记录，这是项目管理的强制性要求。**
|
||
|
||
### 🔴 特别强调：API接口变更的强制性文档更新规则
|
||
|
||
**⚠️ 超级重要：任何API接口的新增、修改、删除操作都必须立即同步更新 `docs/development/API.md` 文档！**
|
||
|
||
#### API变更必须执行的步骤：
|
||
1. **代码修改完成** → 2. **立即更新API.md文档** → 3. **记录代码调整日志** → 4. **验证文档准确性**
|
||
|
||
#### API接口变更涉及的文档更新：
|
||
- ✅ **新增API接口**：在API.md中添加完整的接口文档（地址、参数、响应、权限等）
|
||
- ✅ **修改API接口**：更新API.md中对应接口的参数、响应格式、权限要求
|
||
- ✅ **删除API接口**：在API.md中标记接口为已废弃，说明替代方案
|
||
- ✅ **修改响应格式**：更新API.md中的响应示例和字段说明
|
||
- ✅ **修改权限要求**：更新API.md中的权限要求说明
|
||
|
||
## 3. 文档同步更新规则
|
||
|
||
### 📋 核心原则：代码与文档同步更新
|
||
**⚠️ 重要规则：每次代码调整完成后，必须同步更新相应的项目文档，确保项目文档永远保持最新状态。**
|
||
|
||
### 强制更新规则
|
||
每次代码调整必须同步更新相关文档:
|
||
- **API文档**: 接口变更时更新 `docs/development/API.md` 中的相关接口信息
|
||
- **数据库文档**: 表结构变更时更新 `docs/design/database/` 下的所有相关文档
|
||
- **配置文档**: 配置项变更时更新 `docs/middleware/` 下的配置说明
|
||
- **部署文档**: 部署流程变更时更新 `docs/deployment/` 下的部署手册
|
||
- **功能文档**: 新增功能时更新 `docs/requirements/` 下的需求文档
|
||
- **设计文档**: 架构变更时更新 `docs/design/` 下的设计文档
|
||
|
||
### 📝 文档同步更新清单
|
||
每次代码调整后，请检查以下文档是否需要更新：
|
||
|
||
#### 前端代码调整时需更新的文档：
|
||
- [ ] **组件文档**: 新增或修改组件时，更新组件使用说明
|
||
- [ ] **页面功能文档**: 页面功能变更时，更新用户操作手册
|
||
- [ ] **API对接文档**: 前端API调用变更时，更新接口对接说明
|
||
- [ ] **UI设计文档**: 界面样式重大变更时，更新设计规范文档
|
||
|
||
#### 后端代码调整时需更新的文档：
|
||
- [ ] **API接口文档**: API接口变更时，必须更新 `docs/development/API.md` 中的相关接口信息，包括：
|
||
- 新增接口：添加完整的接口说明、参数、响应示例
|
||
- 修改接口：更新参数说明、响应格式、错误码
|
||
- 删除接口：在文档中标记为已废弃，并说明替代方案
|
||
- 权限变更：更新权限要求说明
|
||
- [ ] **数据库文档**: 表结构变更时，更新数据库设计文档
|
||
- [ ] **业务逻辑文档**: 业务规则变更时，更新业务流程文档
|
||
- [ ] **配置文档**: 系统配置变更时，更新配置说明文档
|
||
|
||
#### 移动端代码调整时需更新的文档：
|
||
- [ ] **功能文档**: 移动端功能变更时，更新功能说明文档
|
||
- [ ] **API对接文档**: 移动端API调用变更时，更新接口对接说明
|
||
- [ ] **用户手册**: 用户操作流程变更时，更新操作指南
|
||
|
||
### 🔄 文档更新工作流程
|
||
|
||
#### 标准流程：
|
||
1. **代码调整完成** → 2. **立即更新相关文档** → 3. **记录代码调整日志** → 4. **验证文档完整性**
|
||
|
||
#### 🔴 API接口变更的特殊流程（强制性）：
|
||
1. **API代码开发完成**
|
||
2. **立即更新 `docs/development/API.md`** （不得延后）
|
||
3. **记录代码调整日志，标注API文档已更新**
|
||
4. **验证API文档与实际接口的一致性**
|
||
5. **提交代码和文档变更**
|
||
|
||
#### ⚠️ 重要原则：
|
||
- **API变更 = 必须更新API.md文档**
|
||
- **文档更新 = 代码开发的一部分，不是可选项**
|
||
- **未更新文档 = 开发任务未完成**
|
||
|
||
### 版本管理
|
||
- **文档版本**: 与代码版本保持同步
|
||
- **变更记录**: 每次变更都要记录变更内容和原因
|
||
- **向后兼容**: 接口变更需要考虑向后兼容性
|
||
|
||
## 4. API文档管理规范 (docs/development/API.md)
|
||
|
||
### 📄 API文档维护原则
|
||
**⚠️ 重要规则：任何后端API接口的新增、修改、删除都必须同步更新 `docs/development/API.md` 文档。**
|
||
|
||
### API文档更新时机
|
||
- **新增Controller**: 添加新的Controller时，必须在API.md中添加对应的接口说明
|
||
- **新增接口方法**: 在现有Controller中添加新方法时，更新对应模块的接口列表
|
||
- **修改接口参数**: 接口请求或响应参数变更时，更新参数说明表格
|
||
- **修改权限要求**: 接口权限变更时，更新权限要求说明
|
||
- **修改响应格式**: 响应数据结构变更时，更新响应示例
|
||
- **接口废弃**: 接口不再使用时，在文档中标记为已废弃并说明替代方案
|
||
|
||
### API文档标准格式
|
||
每个接口都必须包含以下信息：
|
||
```markdown
|
||
#### 接口标题
|
||
|
||
**接口地址**: `HTTP方法 /接口路径`
|
||
|
||
**接口描述**: 接口功能的详细描述
|
||
|
||
**权限要求**: 权限代码或"需要登录"
|
||
|
||
**请求参数**:
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### API文档分类规范
|
||
- **按业务模块分类**: 问卷管理、答题管理、题目管理等
|
||
- **按功能分组**: 基础CRUD操作、业务逻辑操作、状态查询等
|
||
- **统一命名规范**: 接口名称要与Controller方法名保持一致
|
||
|
||
### API文档版本控制
|
||
- **版本记录**: 在API.md底部维护版本更新记录
|
||
- **变更说明**: 每次更新都要记录具体的变更内容
|
||
- **兼容性说明**: 重大变更需要说明向后兼容性影响
|
||
|
||
### ⚠️ 强制执行规则
|
||
**所有通过Cursor AI进行的后端API开发都必须同时更新API文档，这是代码审查的强制性检查项。**
|
||
|
||
### 🚨 API文档更新检查清单
|
||
|
||
#### 当进行以下操作时，必须更新 `docs/development/API.md`：
|
||
|
||
**Controller层变更**：
|
||
- [ ] 新增Controller类 → 在API.md中添加新的模块章节
|
||
- [ ] 新增@RequestMapping方法 → 添加完整的接口文档
|
||
- [ ] 修改@RequestMapping路径 → 更新接口地址
|
||
- [ ] 修改HTTP方法（GET/POST/PUT/DELETE） → 更新接口方法
|
||
- [ ] 删除接口方法 → 标记为已废弃并说明替代方案
|
||
|
||
**参数和响应变更**：
|
||
- [ ] 新增请求参数 → 更新请求参数表格
|
||
- [ ] 修改参数类型或必填属性 → 更新参数说明
|
||
- [ ] 修改响应数据结构 → 更新响应示例
|
||
- [ ] 新增错误码 → 更新错误码说明表
|
||
|
||
**权限和安全变更**：
|
||
- [ ] 新增@SaCheckPermission注解 → 更新权限要求
|
||
- [ ] 修改权限代码 → 更新权限说明
|
||
- [ ] 修改接口访问级别 → 更新权限要求说明
|
||
|
||
#### 强制性文档更新格式要求：
|
||
```markdown
|
||
#### 接口名称
|
||
**接口地址**: `HTTP方法 /完整路径`
|
||
**接口描述**: 清晰描述接口功能
|
||
**权限要求**: 具体权限代码或"需要登录"
|
||
**请求参数**: 完整参数表格
|
||
**响应示例**: 真实的JSON响应示例
|
||
**错误码**: 可能的错误情况
|
||
**更新记录**: 接口变更历史
|
||
```
|
||
|
||
### 🔴 违规检查机制
|
||
- **代码审查时检查**：每次PR必须检查API文档是否同步更新
|
||
- **自动化提醒**：接口变更后立即更新文档，不得延误
|
||
- **文档版本控制**：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
|
||
|
||
## 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")
|
||
```
|
||
|
||
### 🔴 API开发强制性工作流程
|
||
|
||
#### 步骤1：编写后端代码
|
||
- 创建Controller、Service、Mapper等
|
||
- 实现业务逻辑和数据处理
|
||
- 添加权限控制和参数验证
|
||
|
||
#### 步骤2：立即更新API文档（强制性）
|
||
**⚠️ 代码写完后立即执行，不得延后！**
|
||
- 打开 `docs/development/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. **代码调整记录**: 每次代码修改都必须在 `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`
|
||
|