gz-oarms/findings.md

# OARMS 权限体系设计 — 发现记录

## 现有代码分析

### 1. Sa-Token 框架集成现状

**配置**（application.yml）:
- token-name: `satoken`
- timeout: 2592000s（30 天）
- token-style: UUID
- is-concurrent: true（允许并发登录）

**拦截器**（SpringMvcConfig）:
- 已注册 SaInterceptor
- 当前仅 `StpUtil.checkLogin()`，无角色/权限校验
- 白名单路径: `/user/auth/**`, `/test/**`, `/doc.html**`, `/swagger*`, `/cms/**`, `/network/ping`
- 注释掉了按路由模块的权限检查（TODO）

### 2. 认证流程现状

**LoginController**:
- POST `/user/auth/login` — 硬编码 userId，无密码校验，admin 权限
- GET `/user/auth/login/info` — 从 session 取 UserBase
- GET `/user/auth/logout` — StpUtil.logout()
- GET `/user/auth/perm/list` — StpUtil.getPermissionList()（返回空列表）

**UserBaseServiceImpl**:
- login() — 返回 null（未实现）
- getCurrentUser() — 从 SaSession 取，异常时返回 guest
- getUserInfoByLoginId() — 返回 null

### 3. 框架 UserBase 类

**来源**: youfool-framework-springboot3:1.0.4
**包**: com.chinaweal.youfool.framework.springboot.user.entity.UserBase
**已知字段**: username (String), permission (Set<String>)
**已知方法**: setUsername(), setPermission()

**限制**: UserBase 字段较少，不满足 PRD 需求（需要 realName, roles, districtCode, orgName 等）
**方案**: 创建 LoginUserVO 扩展返回信息，session 中存储 LoginUserVO 替代 UserBase

### 4. 前端权限现状

**user.js store**:
- 登录响应取 headers 中的 satoken
- getInfo() 获取用户信息（userId, username, role, permission, nickname）
- roles 从 `data.role` 或 `data.permission` 转数组

**permission.js store**:
- `hasPermission(roles, route)` — 检查 route.meta.roles
- admin 角色直接放行所有路由
- 非 admin 按角色过滤

**routes.js**:
- constantRoutes: login, home, 404（roles: ['guest']）
- asyncRoutes: 业务路由，**无 roles 配置**（依赖 admin 全通）

### 5. PRD 权限矩阵（各模块详细）

#### BS-1 大屏基础信息

| 操作 | 市局 | 区局 | 运营商 |
|------|------|------|--------|
| 查看列表 | 全市 | 本辖区 | 本公司 |
| 新增 | Y | N | Y(本公司) |
| 编辑 | Y | N | Y(本公司) |
| 删除 | Y | N | N |
| 导出 | 全市 | 本辖区 | N |

#### AM-1 录屏设置

| 操作 | 市局 | 区局 | 运营商 |
|------|------|------|--------|
| 查看配置 | 全市 | 本辖区 | 本公司 |
| 新增/编辑 | Y | N | N |

#### AM-3 画面监控

| 操作 | 市局 | 区局 | 运营商 |
|------|------|------|--------|
| 查看监控 | 全市 | 本辖区 | 无权限 |
| 处理监控 | Y | Y(本辖区) | 无权限 |

#### MR-1 监测规则

| 操作 | 市局 | 区局 | 运营商 |
|------|------|------|--------|
| 查看规则 | Y | Y(只读) | 无权限 |
| 增删改 | Y | N | N |

#### CW-1~CW-4 预警流程

| 操作 | 市局 | 区局 | 运营商 |
|------|------|------|--------|
| 全部操作 | 全市 | 本辖区 | 无权限 |

### 6. 技术选型决策

| 决策点 | 选择 | 理由 |
|--------|------|------|
| 密码加密 | BCrypt | Spring Security 默认，安全可靠 |
| 权限模型 | RBAC + 数据权限 | PRD 要求操作权限 + 数据范围 |
| 权限粒度 | 模块:操作（如 screen:create） | 覆盖 PRD 全部场景 |
| 数据权限 | Service 层动态过滤 | 不引入 AOP 复杂度 |
| Session 存储 | SaSession 存 LoginUserVO | 复用现有 Sa-Token 机制 |
| 前端按钮控制 | v-permission 指令 | Element Plus 生态常见方案 |

### 7. 包路径规划

系统管理模块放在 `modules/system/` 下：

```
com.chinaweal.youfool.prj.modules.system/
├── entity/          # SysUser/SysRole/SysPermission 等
├── mapper/
├── service/
└── controller/
```

与其他业务模块（screen, law, rule, monitor, evidence）平级。

### 8. 数据权限实现思路

数据权限需要在查询时动态追加条件：

```java
// 在 Service 层
LoginUserVO user = (LoginUserVO) StpUtil.getSession().get(USER_KEY);

if (user.getRoles().contains("CITY_SUPERVISOR")) {
    // 不过滤
} else if (user.getRoles().contains("DISTRICT_SUPERVISOR")) {
    query.setDistrictCode(user.getDistrictCode());
} else if (user.getRoles().contains("OPERATOR")) {
    query.setOrgName(user.getOrgName());
}
```

**影响范围**: 现有 10 个模块的 query 方法可能需要增加 districtCode/orgName 参数。
**DDL 确认**: 现有表（如 bs_screen）已有 district 字段，可以用于辖区过滤。org_name 可通过大屏关联的业主/运营单位匹配。

---

## 风险与注意事项

1. **框架 UserBase 限制**: UserBase 字段少，需要扩展或替换 session 存储对象
2. **现有接口兼容**: /user/auth/login/info 返回类型改变可能影响前端
3. **数据权限复杂度**: 区局按辖区、运营商按公司，过滤条件不同
4. **密码策略**: 初始密码、密码强度要求需确认
5. **Swagger 分组**: 新增 system 模块需要加 springdoc 分组配置