# 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 list(UserBo bo, PageQuery pageQuery) { TableDataInfo result = userService.queryPageList(bo, pageQuery); return result; } // ✅ 正确 - 非分页接口使用R类型包装 @GetMapping("/options") public R> options() { List list = userService.selectUserOptions(); return R.ok(list); } // ❌ 错误 - 分页接口使用R类型包装 @GetMapping("/list") public R> list(UserBo bo, PageQuery pageQuery) { TableDataInfo result = userService.queryPageList(bo, pageQuery); return R.ok(result); // 这会产生多层嵌套 } ``` **2. 分页接口规范** ```java // 分页查询直接返回 TableDataInfo 数据 @GetMapping("/list") public TableDataInfo list(UserBo bo, PageQuery pageQuery) { TableDataInfo result = userService.queryPageList(bo, pageQuery); return result; } // 返回格式: // { // "total": 100, // "rows": [...], // "code": 200, // "msg": "查询成功" // } ``` **3. 非分页列表接口** ```java // 非分页列表查询(下拉选项等) @GetMapping("/options") public R> options() { List list = userService.selectUserOptions(); return R.ok(list); } // 返回格式: // { // "code": 200, // "msg": "查询成功", // "data": [...] // } ``` **4. 单条数据接口** ```java // 单条数据查询 @GetMapping("/{id}") public R getInfo(@PathVariable Long id) { UserVo user = userService.queryById(id); return R.ok(user); } // 返回格式: // { // "code": 200, // "msg": "操作成功", // "data": {...} // } ``` **5. 操作类接口** ```java // 新增/修改/删除操作 @PostMapping public R 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> list(UserBo bo, PageQuery pageQuery) { // 接口实现 } ``` #### 📝 参数验证规范 ```java // 使用Bean Validation进行参数校验 @PostMapping public R 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 list(PmRepairOrderBo bo, PageQuery pageQuery) { return repairOrderService.queryPageList(bo, pageQuery); } // 详情查询 - 对应按钮权限 @SaCheckPermission("pm:repairOrder:query") @GetMapping("/{id}") @Operation(summary = "获取报修工单详细信息") public R getInfo(@PathVariable Long id) { return R.ok(repairOrderService.queryById(id)); } // 新增功能 - 对应按钮权限 @SaCheckPermission("pm:repairOrder:add") @PostMapping @Operation(summary = "新增报修工单") public R add(@RequestBody PmRepairOrderBo bo) { return toAjax(repairOrderService.insertByBo(bo)); } // 修改功能 - 对应按钮权限 @SaCheckPermission("pm:repairOrder:edit") @PutMapping @Operation(summary = "修改报修工单") public R edit(@RequestBody PmRepairOrderBo bo) { return toAjax(repairOrderService.updateByBo(bo)); } // 删除功能 - 对应按钮权限 @SaCheckPermission("pm:repairOrder:remove") @DeleteMapping("/{ids}") @Operation(summary = "删除报修工单") public R remove(@PathVariable Long[] ids) { return toAjax(repairOrderService.deleteWithValidByIds(List.of(ids))); } // 统计数据 - 对应功能权限 @SaCheckPermission("pm:repairOrder:statistics") @GetMapping("/statistics") @Operation(summary = "获取报修统计数据") public R> statistics() { return R.ok(repairOrderService.getStatistics()); } // 下拉选项 - 对应功能权限 @SaCheckPermission("pm:repairOrder:generateOrderNo") @PostMapping("/generateOrderNo") @Operation(summary = "生成工单编号") public R generateOrderNo() { return R.ok(repairOrderService.generateOrderNo()); } } ``` #### 权限注解检查清单 - [ ] 每个 Controller 方法都有@SaCheckPermission 注解 - [ ] 权限标识与 sys_menu 表中的 perms 字段一致 - [ ] 权限标识命名符合[模块]:[功能]:[操作]规范 - [ ] 所有权限标识都已在 sys_menu 表中配置 ### 🖥️ 前端权限控制规范 #### Vue 页面权限控制 ```vue ``` #### 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 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 queryPageList(SysUserBo bo, PageQuery pageQuery) { LambdaQueryWrapper lqw = buildQueryWrapper(bo); Page result = userMapper.selectVoPage(pageQuery.build(), lqw); return TableDataInfo.build(result); } } ``` ### Mapper 模板 ```java @Mapper public interface SysUserMapper extends BaseMapperPlus { /** * 查询用户列表 */ List selectUserList(SysUserBo bo); /** * 根据条件分页查询用户列表 */ Page selectUserPage(Page page, @Param("bo") SysUserBo bo); } ```