Files
hzdyjs/.cursor/cursorrules-backend.md
T
zlwu 249b1dfeb4 feat: 完善项目开发规范和测试文档体系
📝 主要改进:
• Cursor配置模块化:拆分为前端、后端、移动端、文档、API测试5个专门规范文件
• API文档重新组织:按业务模块拆分到docs/开发文档/API/目录下
• 新增维修分类功能完整测试方案和自动化测试脚本
• 后端热启动脚本完善,支持Linux/Windows双平台
• 强化文档同步更新规范,确保代码与文档一致性

🔧 技术改进:
• 优化Cursor AI工作流程和代码生成质量
• 完善API测试规范(AES+RSA双重加密登录方法)
• 提升开发效率和代码质量标准化程度

�� 测试覆盖:
• 维修分类管理功能端到端测试验证通过
• 包含页面加载、CRUD操作、搜索功能等核心测试用例

更新时间:2025-07-01
2025-07-01 17:53:05 +08:00

1035 lines
31 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Cursor Rules - 后端开发规范
## 适用范围
- **项目目录**: `backend/` (基于 RuoYi-Vue-Plus + Spring Boot 3.4.6)
- **Java 版本**: JDK 17/21
- **后端服务**: http://localhost:8080
---
# 后端开发规范 (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 接口规范(强制性)
**⚠️ 超级重要:所有 API 接口必须严格遵循以下统一规范!**
#### 🔐 请求头规范(强制性)
**所有需要认证的接口必须在请求头中包含 Token,格式如下:**
```json
{
"Content-Type": "application/json;charset=utf-8",
"Authorization": "Bearer {access_token}",
"clientid": "e5cd7e4891bf95d1d19206ce24a7b32e",
"Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
"referer": "http://localhost/login?redirect=%252Findex"
}
```
**请求头字段说明**:
- **Authorization**: `Bearer ` + Token 值(⚠️ 注意 Bearer 后面有一个空格)
- **clientid**: 客户端 ID,用于权限验证
- **Content-Type**: 请求内容类型,必须为 application/json;charset=utf-8
- **Accept-Language**: 语言设置,用于国际化
- **referer**: 来源页面,用于安全验证
**Token 格式强制要求**:
- ✅ 正确:`"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."`
- ❌ 错误:`"Authorization": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."`(缺少 Bearer 前缀)
- ❌ 错误:`"Authorization": "Bearer eyJ0eXAi..."`(Bearer 后面没有空格)
#### 📊 统一响应格式(必须遵循)
**基础响应格式(分页列表)**:
```json
{
"total": 7,
"rows": [],
"code": 200,
"msg": "查询成功"
}
```
#### 🎯 响应格式详细说明
**1. 分页列表响应**
```json
{
"total": 100,
"rows": [
{
"id": 1,
"name": "示例数据1",
"createTime": "2025-06-30 12:00:00"
},
{
"id": 2,
"name": "示例数据2",
"createTime": "2025-06-30 12:01:00"
}
],
"code": 200,
"msg": "查询成功"
}
```
**2. 非分页列表响应**
```json
{
"code": 200,
"msg": "查询成功",
"data": [
{
"id": 1,
"name": "示例数据1"
},
{
"id": 2,
"name": "示例数据2"
}
]
}
```
**3. 单条数据响应**
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"id": 1,
"name": "示例数据",
"createTime": "2025-06-30 12:00:00"
}
}
```
**4. 操作成功响应(无数据)**
```json
{
"code": 200,
"msg": "操作成功",
"data": null
}
```
**5. 错误响应**
```json
{
"code": 400,
"msg": "参数错误:用户名不能为空",
"data": null
}
```
#### 📋 状态码规范
**成功状态码**:
- `200` - 操作成功
- `201` - 创建成功
**客户端错误(4xx)**:
- `400` - 请求参数错误
- `401` - 未认证/认证失败
- `403` - 无权限访问
- `404` - 资源不存在
- `409` - 数据冲突
**服务端错误(5xx)**:
- `500` - 服务器内部错误
- `502` - 网关错误
- `503` - 服务不可用
#### 🚨 接口开发强制要求
**1. Controller 返回格式**
```java
// ✅ 正确 - 分页接口直接返回TableDataInfo
@GetMapping("/list")
public TableDataInfo<UserVo> list(UserBo bo, PageQuery pageQuery) {
TableDataInfo<UserVo> result = userService.queryPageList(bo, pageQuery);
return result;
}
// ✅ 正确 - 非分页接口使用R类型包装
@GetMapping("/options")
public R<List<UserVo>> options() {
List<UserVo> list = userService.selectUserOptions();
return R.ok(list);
}
// ❌ 错误 - 分页接口使用R类型包装
@GetMapping("/list")
public R<TableDataInfo<UserVo>> list(UserBo bo, PageQuery pageQuery) {
TableDataInfo<UserVo> result = userService.queryPageList(bo, pageQuery);
return R.ok(result); // 这会产生多层嵌套
}
```
**2. 分页接口规范**
```java
// 分页查询直接返回 TableDataInfo 数据
@GetMapping("/list")
public TableDataInfo<UserVo> list(UserBo bo, PageQuery pageQuery) {
TableDataInfo<UserVo> result = userService.queryPageList(bo, pageQuery);
return result;
}
// 返回格式:
// {
// "total": 100,
// "rows": [...],
// "code": 200,
// "msg": "查询成功"
// }
```
**3. 非分页列表接口**
```java
// 非分页列表查询(下拉选项等)
@GetMapping("/options")
public R<List<UserVo>> options() {
List<UserVo> list = userService.selectUserOptions();
return R.ok(list);
}
// 返回格式:
// {
// "code": 200,
// "msg": "查询成功",
// "data": [...]
// }
```
**4. 单条数据接口**
```java
// 单条数据查询
@GetMapping("/{id}")
public R<UserVo> getInfo(@PathVariable Long id) {
UserVo user = userService.queryById(id);
return R.ok(user);
}
// 返回格式:
// {
// "code": 200,
// "msg": "操作成功",
// "data": {...}
// }
```
**5. 操作类接口**
```java
// 新增/修改/删除操作
@PostMapping
public R<Void> add(@RequestBody UserBo bo) {
boolean result = userService.insertByBo(bo);
return result ? R.ok() : R.fail("操作失败");
}
// 成功返回格式:
// {
// "code": 200,
// "msg": "操作成功",
// "data": null
// }
// 失败返回格式:
// {
// "code": 500,
// "msg": "操作失败",
// "data": null
// }
```
#### 🔍 接口命名规范
**RESTful 风格**:
- `GET /api/users` - 查询用户列表
- `GET /api/users/{id}` - 查询单个用户
- `POST /api/users` - 新增用户
- `PUT /api/users` - 修改用户(传完整对象)
- `PATCH /api/users/{id}` - 部分更新用户
- `DELETE /api/users/{id}` - 删除用户
**特殊功能接口**:
- `GET /api/users/options` - 获取用户下拉选项
- `GET /api/users/statistics` - 获取用户统计数据
- `POST /api/users/batch` - 批量操作用户
- `POST /api/users/{id}/enable` - 启用用户
- `POST /api/users/{id}/disable` - 禁用用户
#### 🛡️ 权限控制规范
```java
// 每个接口必须添加权限注解
@SaCheckPermission("system:user:list")
@GetMapping("/list")
public R<TableDataInfo<UserVo>> list(UserBo bo, PageQuery pageQuery) {
// 接口实现
}
```
#### 📝 参数验证规范
```java
// 使用Bean Validation进行参数校验
@PostMapping
public R<Void> add(@Validated(AddGroup.class) @RequestBody UserBo bo) {
// 接口实现
}
// VO类中的验证注解
public class UserBo {
@NotBlank(message = "用户名不能为空", groups = {AddGroup.class, EditGroup.class})
@Size(max = 30, message = "用户名长度不能超过30个字符")
private String userName;
@NotBlank(message = "手机号不能为空", groups = {AddGroup.class, EditGroup.class})
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
private String phone;
}
```
#### 🚨 接口开发检查清单
**每个新接口必须检查**:
- [ ] 是否在请求头中正确使用了 Bearer Token 格式?
- [ ] 分页接口是否直接返回 TableDataInfo 格式?
- [ ] 非分页接口是否使用 R 类型包装返回结果?
- [ ] 是否遵循了统一的响应格式规范?
- [ ] 是否添加了@SaCheckPermission 权限注解?
- [ ] 是否添加了@Operation 接口描述?
- [ ] 是否进行了参数校验?
- [ ] 是否符合 RESTful 命名规范?
- [ ] 是否包含了必要的请求头(clientid、Content-Type 等)?
- [ ] 是否在 API 文档中记录了接口信息?
#### 💥 违规后果
**如果发现接口不符合统一规范,必须立即修改!不符合规范的接口不允许合并到主分支。**
### 🔴 API 开发强制性工作流程
#### 步骤 1:编写后端代码
- 创建 Controller、Service、Mapper 等
- 实现业务逻辑和数据处理
- 添加权限控制和参数验证
#### 步骤 2:立即更新 API 文档(强制性)
**⚠️ 代码写完后立即执行,不得延后!**
- 打开 `docs/开发文档/API.md` 文件
- 按照 `docs/开发文档/API/API文档模板.md` 的标准格式添加或更新接口文档
- 包含完整的接口信息(地址、参数、响应、权限等)
- 添加真实的请求和响应示例
#### 步骤 3:记录代码调整日志
- 在 `docs/变更管理/code-adjust-record.md` 中记录本次变更
- 特别说明 API 接口的变更内容
- 标注文档已同步更新
#### 步骤 4:验证和测试
- 测试 API 接口功能是否正常
- 验证 API 文档的准确性
- 确保文档示例与实际响应一致
#### 🚨 违规后果
**如果发现 API 变更未同步更新文档,该代码变更将被视为不完整,必须立即补齐文档。**
## 4. 🔐 菜单界面和接口权限配置规范
### 🚨 权限配置核心原理
**⚠️ 超级重要:每个菜单界面和相关接口都必须在`sys_menu`表中配置对应的权限数据!**
#### 权限配置核心概念
1. **菜单权限**:控制用户是否能看到某个菜单项
2. **按钮权限**:控制用户是否能看到和使用某个功能按钮
3. **接口权限**:通过 Sa-Token 注解控制用户是否能调用某个 API 接口
4. **角色权限**:通过`sys_role_menu`表关联,控制哪个角色拥有哪些权限
#### 权限验证机制
```
用户登录 → 获取用户角色 → 查询角色权限(sys_role_menu) → 验证接口权限(@SaCheckPermission) → 允许/拒绝访问
```
### 🔴 sys_menu 表结构和权限配置
#### sys_menu 表核心字段说明
```sql
-- sys_menu表核心字段
`menu_id` bigint(20) 菜单ID(主键)
`menu_name` varchar(50) 菜单名称
`parent_id` bigint(20) 父菜单ID(0表示一级菜单)
`order_num` int(4) 显示顺序
`path` varchar(200) 路由地址
`component` varchar(255) 组件路径
`menu_type` char(1) 菜单类型(M目录 C菜单 F按钮)
`visible` char(1) 菜单状态(0显示 1隐藏)
`status` char(1) 菜单状态(0正常 1停用)
`perms` varchar(100) 权限标识(如:system:user:list)
`icon` varchar(100) 菜单图标
```
#### 权限标识(perms)命名规范
```
格式:[模块名]:[功能名]:[操作名]
示例:
- pm:repairOrder:list # 报修工单列表查询
- pm:repairOrder:add # 报修工单新增
- pm:repairOrder:edit # 报修工单修改
- pm:repairOrder:remove # 报修工单删除
- pm:repairOrder:statistics # 报修统计数据
- pm:category:list # 维修分类列表
- pm:category:options # 维修分类下拉选项
```
### 🔧 权限配置标准工作流程
#### 📋 新增功能权限配置流程
**步骤 1:分析权限需求**
```
1. 确定主菜单名称和路径
2. 列出所有功能按钮(新增、修改、删除、查询等)
3. 列出所有API接口及对应权限
4. 确定权限标识命名
```
**步骤 2:权限配置 SQL 编写**
使用 UPSERT 逻辑(先判断后操作):
```sql
-- 权限配置标准模板(UPSERT逻辑)
-- ==========================================
-- [模块名]权限配置脚本
-- 功能:为[模块名]添加完整权限配置
-- 时间:YYYY-MM-DD HH:mm:ss
-- 说明:使用UPSERT逻辑,避免重复插入
-- ==========================================
-- 第一步:检查并插入主菜单
INSERT INTO sys_menu (
menu_id, menu_name, parent_id, order_num, path, component,
query_param, is_frame, is_cache, menu_type, visible, status,
perms, icon, create_by, create_time, update_by, update_time, remark
)
SELECT
2100, '物业管理', 0, 6, 'pm', NULL,
'', 1, 0, 'M', '0', '0',
'', 'tool', 1, now(), 1, now(), '物业管理模块'
WHERE NOT EXISTS (SELECT 1 FROM sys_menu WHERE menu_id = 2100);
-- 第二步:检查并插入子菜单
INSERT INTO sys_menu (
menu_id, menu_name, parent_id, order_num, path, component,
query_param, is_frame, is_cache, menu_type, visible, status,
perms, icon, create_by, create_time, update_by, update_time, remark
)
SELECT
2110, '报修管理', 2100, 1, 'repairOrder', 'pm/repairOrder/index',
'', 1, 0, 'C', '0', '0',
'pm:repairOrder:list', 'form', 1, now(), 1, now(), '报修工单管理'
WHERE NOT EXISTS (SELECT 1 FROM sys_menu WHERE menu_id = 2110);
-- 第三步:批量插入功能权限(如果不存在)
INSERT INTO sys_menu (
menu_id, menu_name, parent_id, order_num, path, component,
query_param, is_frame, is_cache, menu_type, visible, status,
perms, icon, create_by, create_time, update_by, update_time, remark
)
SELECT * FROM (
SELECT 2111, '查询', 2110, 1, '', '', '', 1, 0, 'F', '0', '0', 'pm:repairOrder:query', '#', 1, now(), 1, now(), '查询权限' UNION ALL
SELECT 2112, '新增', 2110, 2, '', '', '', 1, 0, 'F', '0', '0', 'pm:repairOrder:add', '#', 1, now(), 1, now(), '新增权限' UNION ALL
SELECT 2113, '修改', 2110, 3, '', '', '', 1, 0, 'F', '0', '0', 'pm:repairOrder:edit', '#', 1, now(), 1, now(), '修改权限'
) AS temp
WHERE NOT EXISTS (SELECT 1 FROM sys_menu WHERE menu_id = temp.menu_id);
-- 第四步:为admin角色分配权限(如果未分配)
INSERT IGNORE INTO sys_role_menu (role_id, menu_id)
SELECT 1, menu_id FROM sys_menu WHERE menu_id BETWEEN 2100 AND 2199;
```
**步骤 3:更新现有权限**
```sql
-- 更新现有权限信息(如果需要修改)
UPDATE sys_menu
SET
menu_name = '新的菜单名称',
path = '新的路径',
perms = '新的权限标识',
update_time = now(),
update_by = 1,
remark = '权限更新说明'
WHERE menu_id = 2110 AND EXISTS (SELECT 1 FROM sys_menu WHERE menu_id = 2110);
```
### 🔄 权限配置操作规范
#### 🚨 强制性检查清单
**每次新增功能时必须检查**:
- [ ] 是否需要新增主菜单?
- [ ] 是否需要新增子菜单?
- [ ] 列出所有需要的功能权限(CRUD 等)
- [ ] 列出所有 API 接口及权限标识
- [ ] 确认权限标识命名符合规范
- [ ] 权限配置是否使用 UPSERT 逻辑?
- [ ] 是否为相关角色分配了权限?
#### 🔍 权限配置验证方法
**验证 SQL 模板**:
```sql
-- 1. 验证权限是否已正确配置
SELECT menu_id, menu_name, perms, menu_type
FROM sys_menu
WHERE perms LIKE 'pm:%'
ORDER BY menu_id;
-- 2. 验证角色权限分配
SELECT rm.role_id, r.role_name, m.menu_name, m.perms
FROM sys_role_menu rm
JOIN sys_role r ON rm.role_id = r.role_id
JOIN sys_menu m ON rm.menu_id = m.menu_id
WHERE m.perms LIKE 'pm:%'
ORDER BY rm.role_id, m.menu_id;
-- 3. 验证用户权限(通过角色)
SELECT u.user_name, r.role_name, m.menu_name, m.perms
FROM sys_user u
JOIN sys_user_role ur ON u.user_id = ur.user_id
JOIN sys_role r ON ur.role_id = r.role_id
JOIN sys_role_menu rm ON r.role_id = rm.role_id
JOIN sys_menu m ON rm.menu_id = m.menu_id
WHERE u.user_name = 'admin' AND m.perms LIKE 'pm:%'
ORDER BY m.menu_id;
```
### 🎯 Controller 权限注解规范
#### 标准权限注解使用
```java
@RestController
@RequestMapping("/pm/repairOrder")
@Api(tags = "报修工单管理")
public class PmRepairOrderController extends BaseController {
// 列表查询 - 对应菜单权限
@SaCheckPermission("pm:repairOrder:list")
@GetMapping("/list")
@Operation(summary = "查询报修工单列表")
public TableDataInfo<PmRepairOrderVo> list(PmRepairOrderBo bo, PageQuery pageQuery) {
return repairOrderService.queryPageList(bo, pageQuery);
}
// 详情查询 - 对应按钮权限
@SaCheckPermission("pm:repairOrder:query")
@GetMapping("/{id}")
@Operation(summary = "获取报修工单详细信息")
public R<PmRepairOrderVo> getInfo(@PathVariable Long id) {
return R.ok(repairOrderService.queryById(id));
}
// 新增功能 - 对应按钮权限
@SaCheckPermission("pm:repairOrder:add")
@PostMapping
@Operation(summary = "新增报修工单")
public R<Void> add(@RequestBody PmRepairOrderBo bo) {
return toAjax(repairOrderService.insertByBo(bo));
}
// 修改功能 - 对应按钮权限
@SaCheckPermission("pm:repairOrder:edit")
@PutMapping
@Operation(summary = "修改报修工单")
public R<Void> edit(@RequestBody PmRepairOrderBo bo) {
return toAjax(repairOrderService.updateByBo(bo));
}
// 删除功能 - 对应按钮权限
@SaCheckPermission("pm:repairOrder:remove")
@DeleteMapping("/{ids}")
@Operation(summary = "删除报修工单")
public R<Void> remove(@PathVariable Long[] ids) {
return toAjax(repairOrderService.deleteWithValidByIds(List.of(ids)));
}
// 统计数据 - 对应功能权限
@SaCheckPermission("pm:repairOrder:statistics")
@GetMapping("/statistics")
@Operation(summary = "获取报修统计数据")
public R<Map<String, Object>> statistics() {
return R.ok(repairOrderService.getStatistics());
}
// 下拉选项 - 对应功能权限
@SaCheckPermission("pm:repairOrder:generateOrderNo")
@PostMapping("/generateOrderNo")
@Operation(summary = "生成工单编号")
public R<String> generateOrderNo() {
return R.ok(repairOrderService.generateOrderNo());
}
}
```
#### 权限注解检查清单
- [ ] 每个 Controller 方法都有@SaCheckPermission 注解
- [ ] 权限标识与 sys_menu 表中的 perms 字段一致
- [ ] 权限标识命名符合[模块]:[功能]:[操作]规范
- [ ] 所有权限标识都已在 sys_menu 表中配置
### 🖥️ 前端权限控制规范
#### Vue 页面权限控制
```vue
<template>
<div class="app-container">
<!-- 功能按钮权限控制 -->
<el-row :gutter="10" class="mb8">
<el-col :span="1.5">
<el-button
v-hasPermi="['pm:repairOrder:add']"
type="primary"
plain
icon="Plus"
@click="handleAdd"
>
新增
</el-button>
</el-col>
<el-col :span="1.5">
<el-button
v-hasPermi="['pm:repairOrder:edit']"
type="success"
plain
icon="Edit"
:disabled="single"
@click="handleUpdate"
>
修改
</el-button>
</el-col>
<el-col :span="1.5">
<el-button
v-hasPermi="['pm:repairOrder:remove']"
type="danger"
plain
icon="Delete"
:disabled="multiple"
@click="handleDelete"
>
删除
</el-button>
</el-col>
</el-row>
<!-- 表格操作列权限控制 -->
<el-table-column label="操作" align="center" width="160">
<template #default="scope">
<el-tooltip content="修改" placement="top">
<el-button
v-hasPermi="['pm:repairOrder:edit']"
link
type="primary"
icon="Edit"
@click="handleUpdate(scope.row)"
></el-button>
</el-tooltip>
<el-tooltip content="删除" placement="top">
<el-button
v-hasPermi="['pm:repairOrder:remove']"
link
type="danger"
icon="Delete"
@click="handleDelete(scope.row)"
></el-button>
</el-tooltip>
</template>
</el-table-column>
</div>
</template>
```
#### API 调用权限检查
```typescript
// api调用前的权限检查(可选)
import { checkPermi } from '@/utils/permission';
// 在调用API前检查权限
const handleAdd = () => {
if (!checkPermi(['pm:repairOrder:add'])) {
ElMessage.error('您没有新增权限');
return;
}
// 执行新增操作
router.push('/pm/repairOrder/add');
};
const handleEdit = (row: any) => {
if (!checkPermi(['pm:repairOrder:edit'])) {
ElMessage.error('您没有修改权限');
return;
}
// 执行修改操作
router.push(`/pm/repairOrder/edit/${row.id}`);
};
```
### 📋 权限配置标准模板
#### 完整权限配置脚本模板
```sql
-- ==========================================
-- [模块名称]权限配置脚本
-- 功能:为[模块名称]添加完整权限配置
-- 时间:YYYY-MM-DD HH:mm:ss (⚠️必须填写真实时间!)
-- 说明:使用UPSERT逻辑,支持重复执行
-- ==========================================
-- 清理旧数据(谨慎使用,仅在测试环境)
-- DELETE FROM sys_role_menu WHERE menu_id BETWEEN [起始ID] AND [结束ID];
-- DELETE FROM sys_menu WHERE menu_id BETWEEN [起始ID] AND [结束ID];
-- 第一部分:主菜单配置
INSERT INTO sys_menu (
menu_id, menu_name, parent_id, order_num, path, component,
query_param, is_frame, is_cache, menu_type, visible, status,
perms, icon, create_by, create_time, update_by, update_time, remark
)
SELECT
[主菜单ID], '[主菜单名称]', 0, [排序号], '[路径]', NULL,
'', 1, 0, 'M', '0', '0',
'', '[图标]', 1, now(), 1, now(), '[模块描述]'
WHERE NOT EXISTS (SELECT 1 FROM sys_menu WHERE menu_id = [主菜单ID]);
-- 第二部分:子菜单配置
INSERT INTO sys_menu (
menu_id, menu_name, parent_id, order_num, path, component,
query_param, is_frame, is_cache, menu_type, visible, status,
perms, icon, create_by, create_time, update_by, update_time, remark
)
SELECT
[子菜单ID], '[子菜单名称]', [主菜单ID], [排序号], '[路径]', '[组件路径]',
'', 1, 0, 'C', '0', '0',
'[模块]:[功能]:list', '[图标]', 1, now(), 1, now(), '[功能描述]'
WHERE NOT EXISTS (SELECT 1 FROM sys_menu WHERE menu_id = [子菜单ID]);
-- 第三部分:功能权限配置(批量插入)
INSERT INTO sys_menu (
menu_id, menu_name, parent_id, order_num, path, component,
query_param, is_frame, is_cache, menu_type, visible, status,
perms, icon, create_by, create_time, update_by, update_time, remark
)
SELECT * FROM (
-- 基础CRUD权限
SELECT [权限ID1], '[功能名称]查询', [子菜单ID], 1, '', '', '', 1, 0, 'F', '0', '0', '[模块]:[功能]:query', '#', 1, now(), 1, now(), '查询权限' UNION ALL
SELECT [权限ID2], '[功能名称]新增', [子菜单ID], 2, '', '', '', 1, 0, 'F', '0', '0', '[模块]:[功能]:add', '#', 1, now(), 1, now(), '新增权限' UNION ALL
SELECT [权限ID3], '[功能名称]修改', [子菜单ID], 3, '', '', '', 1, 0, 'F', '0', '0', '[模块]:[功能]:edit', '#', 1, now(), 1, now(), '修改权限' UNION ALL
SELECT [权限ID4], '[功能名称]删除', [子菜单ID], 4, '', '', '', 1, 0, 'F', '0', '0', '[模块]:[功能]:remove', '#', 1, now(), 1, now(), '删除权限' UNION ALL
-- 特殊功能权限
SELECT [权限ID5], '[特殊功能名称]', [子菜单ID], 5, '', '', '', 1, 0, 'F', '0', '0', '[模块]:[功能]:[特殊操作]', '#', 1, now(), 1, now(), '[特殊功能描述]'
) AS temp
WHERE NOT EXISTS (SELECT 1 FROM sys_menu WHERE menu_id = temp.menu_id);
-- 第四部分:权限分配(为admin角色分配权限)
INSERT IGNORE INTO sys_role_menu (role_id, menu_id)
SELECT 1, menu_id FROM sys_menu WHERE menu_id BETWEEN [起始ID] AND [结束ID];
-- 第五部分:验证配置结果
SELECT '权限配置验证' as message,
COUNT(*) as menu_count,
(SELECT COUNT(*) FROM sys_role_menu WHERE role_id = 1 AND menu_id BETWEEN [起始ID] AND [结束ID]) as role_permission_count
FROM sys_menu
WHERE menu_id BETWEEN [起始ID] AND [结束ID];
```
### 🧪 权限配置测试和验证
#### 权限测试标准流程
```
1. **权限配置验证**
- 检查sys_menu表中权限记录
- 检查sys_role_menu表中角色权限分配
- 验证权限标识命名规范
↓
2. **后端接口测试**
- 使用Token调用接口
- 验证权限认证是否正常
- 测试无权限用户访问是否被拒绝
↓
3. **前端界面测试**
- 登录系统查看菜单是否显示
- 检查功能按钮是否根据权限显示/隐藏
- 验证无权限用户的界面表现
↓
4. **权限缓存测试**
- 重启服务后权限是否正常
- 重新登录后权限是否正确加载
- 权限变更后是否需要重新登录
```
#### 权限测试脚本模板
```javascript
// 权限验证测试脚本
async function testPermissions(token, permissions) {
const results = [];
for (const perm of permissions) {
try {
const response = await callAPIWithToken(token, perm.endpoint, perm.data, perm.method);
results.push({
permission: perm.name,
endpoint: perm.endpoint,
success: response.success,
status: response.status,
message: response.success ? '权限验证通过' : '权限验证失败',
});
} catch (error) {
results.push({
permission: perm.name,
endpoint: perm.endpoint,
success: false,
status: 'ERROR',
message: error.message,
});
}
}
return results;
}
// 使用示例
const permissionTests = [
{ name: 'pm:repairOrder:list', endpoint: '/pm/repairOrder/list', method: 'GET', data: null },
{ name: 'pm:repairOrder:add', endpoint: '/pm/repairOrder', method: 'POST', data: {} },
{
name: 'pm:repairOrder:statistics',
endpoint: '/pm/repairOrder/statistics',
method: 'GET',
data: null,
},
];
// 执行权限测试
testPermissions(token, permissionTests).then((results) => {
console.log('权限测试结果:', results);
});
```
### 🚨 权限配置强制要求总结
#### 必须遵循的规范
1. **⚠️ 每个新功能都必须配置权限**:菜单权限 + 按钮权限 + 接口权限
2. **⚠️ 使用 UPSERT 逻辑**:权限配置脚本必须支持重复执行
3. **⚠️ 权限标识规范**:严格按照[模块]:[功能]:[操作]格式命名
4. **⚠️ Controller 注解必须**:每个接口方法都要有@SaCheckPermission 注解
5. **⚠️ 前端权限控制**:功能按钮必须使用 v-hasPermi 指令控制
6. **⚠️ 权限测试验证**:配置完成后必须进行完整的权限测试
7. **⚠️ 文档同步更新**:权限配置必须在 API 文档中说明
#### 违规检查清单
- [ ] 新功能是否缺少权限配置?
- [ ] Controller 方法是否缺少权限注解?
- [ ] 权限标识命名是否符合规范?
- [ ] 前端按钮是否有权限控制?
- [ ] 权限配置是否支持重复执行?
- [ ] 是否进行了权限功能测试?
- [ ] API 文档是否更新了权限信息?
## 5. 标准代码模板
### 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);
}
}
```
### Mapper 模板
```java
@Mapper
public interface SysUserMapper extends BaseMapperPlus<SysUser, SysUserVo> {
/**
* 查询用户列表
*/
List<SysUserVo> selectUserList(SysUserBo bo);
/**
* 根据条件分页查询用户列表
*/
Page<SysUserVo> selectUserPage(Page<SysUser> page, @Param("bo") SysUserBo bo);
}
```