permission-system

> 重要: 每次创建新功能模块时，必须 同时创建对应的菜单权限迁移 SQL 文件，否则功能将无法正常使用。

```

┌─────────────────────────────────────────────────────────────┐

│ 权限体系架构 │

├─────────────────────────────────────────────────────────────┤

│ │

│ 用户 (sys_user) │

│ │ │

│ └── 拥有多个 ──→ 角色 (sys_role) │

│ │ │

│ ├── 拥有多个 ──→ 菜单权限 (sys_menu) │

│ │ ├─ 目录 (type=0) │

│ │ ├─ 菜单 (type=1) │

│ │ └─ 按钮 (type=2) │

│ │ │

│ └── 数据权限 (data_scope) │

│ ├─ 全部数据 (1) │

│ ├─ 本部门 (2) │

│ ├─ 本部门及下级 (3) │

│ ├─ 仅本人 (4) │

│ └─ 自定义部门 (5) │

│ │

└─────────────────────────────────────────────────────────────┘

```

2.1 菜单表 (sys_menu)

| 字段 | 类型 | 说明 |

|------|------|------|

| id | bigint | 主键 |

| parent_id | bigint | 父菜单ID (0=顶级) |

| menu_name | varchar(50) | 菜单名称 |

| menu_type | tinyint | 类型: 0=目录, 1=菜单, 2=按钮 |

| path | varchar(200) | 路由路径 |

| component | varchar(255) | 组件路径 |

| permission | varchar(100) | 权限标识 |

| icon | varchar(100) | 图标 |

| sort | int | 排序 |

| visible | tinyint | 是否显示: 0=隐藏, 1=显示 |

| status | tinyint | 状态: 0=禁用, 1=启用 |

2.2 角色表 (sys_role)

| 字段 | 类型 | 说明 |

|------|------|------|

| id | bigint | 主键 |

| role_name | varchar(30) | 角色名称 |

| role_code | varchar(100) | 角色编码 |

| data_scope | tinyint | 数据权限范围 (1-5) |

| sort | int | 排序 |

| status | tinyint | 状态 |

2.3 关联表

• sys_user_role: 用户-角色关联
• sys_role_menu: 角色-菜单关联
• sys_role_dept: 角色-部门关联 (自定义数据权限)

3.1 格式

```

{模块}:{实体}:{操作}

```

3.2 标准操作

| 操作 | 权限标识 | 说明 |

|------|----------|------|

| 列表 | xxx:entity:list | 查看列表 |

| 详情 | xxx:entity:detail | 查看详情 |

| 新增 | xxx:entity:add | 新增数据 |

| 编辑 | xxx:entity:edit | 编辑数据 |

| 删除 | xxx:entity:delete | 删除数据 |

| 导出 | xxx:entity:export | 导出数据 |

| 导入 | xxx:entity:import | 导入数据 |

3.3 示例

```

# 系统管理模块

sys:user:list # 用户列表

sys:user:add # 新增用户

sys:role:assign # 分配角色权限

# 业务模块示例

emergency:event:list # 应急事件列表

emergency:event:handle # 处理事件

emergency:plan:approve # 审批预案

```

| 类型 | 值 | 说明 | 实现方式 |

|------|---|------|----------|

| 全部数据 | 1 | 无限制 | 不添加过滤条件 |

| 本部门 | 2 | 只看本部门 | WHERE dept_id = 用户部门ID |

| 本部门及下级 | 3 | 本部门树 | WHERE dept_id IN (部门及子部门ID) |

| 仅本人 | 4 | 只看自己创建的 | WHERE create_by = 用户ID |

| 自定义 | 5 | 指定部门 | WHERE dept_id IN (角色配置的部门) |

5.1 强制要求

当执行 /cx:do 或 /cx:plan 创建新功能模块时，必须 同时：

1. 创建 Flyway 迁移 SQL 文件
2. 包含菜单数据插入语句
3. 包含管理员角色菜单权限分配语句

5.2 迁移文件命名

```

V{版本号}__{描述}.sql

示例:

V4__add_emergency_module_menu.sql

V5__add_monitor_module_menu.sql

```

5.3 迁移 SQL 模板

```sql

-- V{N}__add_{module}_menu.sql

-- 作者: CX

-- 日期: {日期}

-- 描述: 添加{模块名}模块菜单和权限

-- =============================================

-- 获取当前最大菜单ID

-- =============================================

SET @max_menu_id = (SELECT COALESCE(MAX(id), 100) FROM sys_menu);

-- =============================================

-- 添加{模块名}目录

-- =============================================

INSERT INTO sys_menu (id, parent_id, menu_name, menu_type, path, component, permission, icon, sort, visible, status) VALUES

(@max_menu_id + 1, 0, '{模块中文名}', 0, '/{module}', NULL, NULL, '{icon}', {sort}, 1, 1);

-- =============================================

-- 添加{功能名}菜单

-- =============================================

INSERT INTO sys_menu (id, parent_id, menu_name, menu_type, path, component, permission, icon, sort, visible, status) VALUES

(@max_menu_id + 2, @max_menu_id + 1, '{功能中文名}', 1, '/{module}/{entity}', '/{module}/{entity}/index', '{module}:{entity}:list', '{icon}', 1, 1, 1),

(@max_menu_id + 3, @max_menu_id + 2, '{功能}新增', 2, NULL, NULL, '{module}:{entity}:add', NULL, 1, 1, 1),

(@max_menu_id + 4, @max_menu_id + 2, '{功能}编辑', 2, NULL, NULL, '{module}:{entity}:edit', NULL, 2, 1, 1),

(@max_menu_id + 5, @max_menu_id + 2, '{功能}删除', 2, NULL, NULL, '{module}:{entity}:delete', NULL, 3, 1, 1);

-- =============================================

-- 为超级管理员分配新菜单权限

-- =============================================

INSERT INTO sys_role_menu (role_id, menu_id)

SELECT 1, id FROM sys_menu WHERE id > @max_menu_id;

```

6.1 迁移文件: V4__add_emergency_event_menu.sql

```sql

-- V4__add_emergency_event_menu.sql

-- 作者: CX

-- 日期: 2026-01-13

-- 描述: 添加应急事件管理模块菜单和权限

-- =============================================

-- 获取当前最大菜单ID (避免ID冲突)

-- =============================================

SET @max_menu_id = (SELECT COALESCE(MAX(id), 100) FROM sys_menu);

-- =============================================

-- 添加应急管理目录

-- =============================================

INSERT INTO sys_menu (id, parent_id, menu_name, menu_type, path, component, permission, icon, sort, visible, status) VALUES

(@max_menu_id + 1, 0, '应急管理', 0, '/emergency', NULL, NULL, 'ant-design:alert-outlined', 10, 1, 1);

-- =============================================

-- 添加事件管理菜单及按钮

-- =============================================

INSERT INTO sys_menu (id, parent_id, menu_name, menu_type, path, component, permission, icon, sort, visible, status) VALUES

-- 事件管理菜单

(@max_menu_id + 2, @max_menu_id + 1, '事件管理', 1, '/emergency/event', '/emergency/event/index', 'emergency:event:list', 'ant-design:file-exclamation-outlined', 1, 1, 1),

-- 事件管理按钮

(@max_menu_id + 3, @max_menu_id + 2, '事件新增', 2, NULL, NULL, 'emergency:event:add', NULL, 1, 1, 1),

(@max_menu_id + 4, @max_menu_id + 2, '事件编辑', 2, NULL, NULL, 'emergency:event:edit', NULL, 2, 1, 1),

(@max_menu_id + 5, @max_menu_id + 2, '事件删除', 2, NULL, NULL, 'emergency:event:delete', NULL, 3, 1, 1),

(@max_menu_id + 6, @max_menu_id + 2, '事件处理', 2, NULL, NULL, 'emergency:event:handle', NULL, 4, 1, 1),

(@max_menu_id + 7, @max_menu_id + 2, '事件导出', 2, NULL, NULL, 'emergency:event:export', NULL, 5, 1, 1);

-- =============================================

-- 添加预案管理菜单及按钮

-- =============================================

INSERT INTO sys_menu (id, parent_id, menu_name, menu_type, path, component, permission, icon, sort, visible, status) VALUES

-- 预案管理菜单

(@max_menu_id + 8, @max_menu_id + 1, '预案管理', 1, '/emergency/plan', '/emergency/plan/index', 'emergency:plan:list', 'ant-design:solution-outlined', 2, 1, 1),

-- 预案管理按钮

(@max_menu_id + 9, @max_menu_id + 8, '预案新增', 2, NULL, NULL, 'emergency:plan:add', NULL, 1, 1, 1),

(@max_menu_id + 10, @max_menu_id + 8, '预案编辑', 2, NULL, NULL, 'emergency:plan:edit', NULL, 2, 1, 1),

(@max_menu_id + 11, @max_menu_id + 8, '预案删除', 2, NULL, NULL, 'emergency:plan:delete', NULL, 3, 1, 1),

(@max_menu_id + 12, @max_menu_id + 8, '预案审批', 2, NULL, NULL, 'emergency:plan:approve', NULL, 4, 1, 1);

-- =============================================

-- 为超级管理员角色分配新菜单权限

-- =============================================

INSERT INTO sys_role_menu (role_id, menu_id)

SELECT 1, id FROM sys_menu WHERE id > @max_menu_id;

```

6.2 后端 Controller 权限注解

```java

@RestController

@RequestMapping("/api/emergency/event")

@RequiredArgsConstructor

@Tag(name = "应急事件管理")

public class EmergencyEventController {

private final EmergencyEventService eventService;

@GetMapping

@SaCheckPermission("emergency:event:list")

@Operation(summary = "事件列表")

public ApiResponse> list(EventQueryDTO query) {

return ApiResponse.success(eventService.findPage(query));

}

@PostMapping

@SaCheckPermission("emergency:event:add")

@Operation(summary = "新增事件")

public ApiResponse create(@Valid @RequestBody EventCreateDTO dto) {

return ApiResponse.success(eventService.create(dto));

}

@PutMapping("/{id}")

@SaCheckPermission("emergency:event:edit")

@Operation(summary = "编辑事件")

public ApiResponse update(@PathVariable Long id, @Valid @RequestBody EventUpdateDTO dto) {

return ApiResponse.success(eventService.update(id, dto));

}

@DeleteMapping("/{id}")

@SaCheckPermission("emergency:event:delete")

@Operation(summary = "删除事件")

public ApiResponse delete(@PathVariable Long id) {

eventService.delete(id);

return ApiResponse.success();

}

@PutMapping("/{id}/handle")

@SaCheckPermission("emergency:event:handle")

@Operation(summary = "处理事件")

public ApiResponse handle(@PathVariable Long id, @Valid @RequestBody EventHandleDTO dto) {

return ApiResponse.success(eventService.handle(id, dto));

}

}

```

6.3 前端路由配置 (由后端动态返回)

前端无需手动配置路由，菜单数据由后端 /api/auth/routes 接口动态返回。

7.1 Service 层添加数据权限注解

```java

@Service

@RequiredArgsConstructor

public class EmergencyEventServiceImpl implements EmergencyEventService {

private final EmergencyEventRepository eventRepository;

private final DataScopeHelper dataScopeHelper;

@Override

@DataScope(deptAlias = "", userAlias = "")

public Page findPage(EventQueryDTO query) {

Specification spec = (root, criteriaQuery, cb) -> {

List predicates = new ArrayList<>();

// 业务查询条件...

// 数据权限过滤 (必须添加)

Predicate dataScopePredicate = dataScopeHelper.buildDataScopePredicate(

root, cb, "deptId", "createBy");

if (dataScopePredicate != null) {

predicates.add(dataScopePredicate);

}

return cb.and(predicates.toArray(new Predicate[0]));

};

return eventRepository.findAll(spec, pageRequest).map(this::convertToVO);

}

}

```

| 图标 | 图标名称 | 适用场景 |

|------|----------|----------|

| ⚙️ | ant-design:setting-outlined | 系统设置 |

| 👤 | ant-design:user-outlined | 用户管理 |

| 👥 | ant-design:team-outlined | 角色/团队 |

| 📋 | ant-design:menu-outlined | 菜单管理 |

| 🏢 | ant-design:apartment-outlined | 部门/组织 |

| ⚠️ | ant-design:alert-outlined | 告警/应急 |

| 📄 | ant-design:file-outlined | 文件/文档 |

| 📊 | ant-design:bar-chart-outlined | 统计/报表 |

| 🔔 | ant-design:bell-outlined | 通知/消息 |

| 📁 | ant-design:folder-outlined | 目录/分类 |

| 🔐 | ant-design:safety-outlined | 安全/权限 |

| 📝 | ant-design:form-outlined | 表单 |

创建新功能模块时，请确认以下事项：

• [ ] 创建 Flyway 迁移 SQL 文件 (V{N}__add_{module}_menu.sql)
• [ ] 菜单 ID 使用 @max_menu_id + N 避免冲突
• [ ] 包含目录、菜单、按钮三级结构
• [ ] 权限标识符合 {module}:{entity}:{action} 规范
• [ ] 为超级管理员角色分配新菜单权限
• [ ] Controller 方法添加 @SaCheckPermission 注解
• [ ] 需要数据权限的查询添加 DataScopeHelper 过滤
• [ ] 前端页面组件路径与菜单 component 字段一致

---

> 项目: 应急管理系统

> 创建时间: 2026-01-13

> 更新时间: 2026-01-13