silver-ridge-lark.md 17 KB

权限体系融合实施计划(perm_* 全系统化:菜单/操作入库 + 全面权限 + 动态导航 + 数据范围 + 账号口径合一)

Context

核心 RBAC 迁移(perm_* 九表、/perm/** 五页、登录改读 perm_user)已交付并端到端验证(test-reports-20261118-perm/)。本次执行 docs/design/pale-reef-swan.md 的「融合待办」并落实用户新增要求:系统全部菜单与操作入 perm_menu 库、全面启用权限。

已确认决策(用户选定):

  • D1 操作级权限码:每菜单页挂一组操作码(query/add/edit/remove/export/execute/detail/import),后端约 439 个无注解业务端点挂所属操作码;分析页统一 query/detail。
  • D2 工作台纳入统一体系:workbench 21 页菜单/操作入库为独立分组(主窗口导航不显示),工作台导航改 DB 驱动、按钮 v-auth、ai/** 162 端点加注解。
  • D3 data_scope 仅 perm 管理页启用(用户/部门/岗位查询);案件列表(仅本人)与 AI 审计(超管可查他人)语义不变。
  • D4 清引用+统一口径:清 sys_user 注释/脚本引用、perm.sql 自带 admin 种子不再依赖 sys_user、UserVO/LoginVO.status 统一 perm '0'/'1';sys_user 表保留不 DROP(回滚兜底)。

现状关键事实(已核实):

  • 前端 transformObjToRoute/flatMultiLevelRoutes/菜单渲染/多页签完全数据驱动(core/router/helper/routeHelper.ts:69-173)→ getRouters 返回 menu.json 同构 JSON 即可零改动复用;menu.json 31 叶子+4 目录,path 全绝对、component=/xxx/index、name=Views{Pascal}。
  • 后端 501 端点/97 Controller,48 注解全在 perm;GlobalExceptionHandler 已接 NotPermission/NotRole→HTTP200+code403;SaTokenWebConfig:72-78 isAnnotation(true) 全路径拦截,白名单 L40-62。
  • MybatisPlusConfig:16-23 仅分页插件(DbType.DUCKDB);perm*/ai*/case_info 在 PG master,案件明细在 DuckDB(无 dept_id 列)。
  • SSE 客户端全部 fetch+x-token(无 EventSource)→ preHandle 注解校验可行;异步线程无 sa-token 上下文 → 数据权限注解只落 perm mapper 即天然安全。
  • 前端无 userInfo.status 消费点(仅 core/api/auth/authApi.ts:52、workbench/api/user.ts:10 类型声明)。
  • biz-buddy 源可移植:getRouters 链(SysMenuServiceImpl:124-219)、数据权限 8 文件+2 注册+1 bean(ruoyi-common-mybatis)。

惯例:no-fallback(旧静态源直接删)、SQL 幂等可重跑、测试先行(契约测试打真实 dev 服务 localhost:8980/js/a)、前端手写组件、验证实测清单+截图交付。

P1 SQL 种子与菜单模型(sql/perm.sql 为主)

id 段与结构

  • 业务菜单沿用 menu.json id:目录 M 1002/1006/1017/10000;页面 C 1000,1001,1003-1005,1007-1016,1018-1024,1027-1029,10262,10001-10005。理由:硬编码依赖 path/name 而非 id;与 perm 10000 段隔离;存量重跑即补齐。
  • 工作台:根 M 20000(ext={"group":"workbench"}),组 M 20100/20200/20300/20400/20500,叶 C 20101-20107、20201-20203、20301-20303、20401-20403、20501-20505(21 页,含 menu.ts 缺失的 model/usage=20202,与 core/router/routes/index.ts:176-302 逐条对齐)。
  • 操作 F:menu_id = 父 C id × 100 + 序号(1000→100001…;10001→1000101…;20101→2010101…),与现有 5 位 perm F(10011-10054)无冲突。
  • 纯操作码容器(无路由):M 1090「系统操作」visible='1'+ext={"permsOnly":true},下挂 C 1091 案件管理(/case)、1092 模板管理(/tpl 内嵌组件)、1093 系统维护;getRouters 跳过 permsOnly 子树,权限码照常收集。
  • 隐藏页 1027/1029 visible='1'→meta.hideMenu;1000 的 affix 走 ext={"affix":true}。不加 perm_menu 新字段(ext/visible/active_menu 已具备)。

种子示例

-- C 1000 案件数据:path='data/index' component='data/index' perms='case:data:list' ext='{"affix":true}'
--   F 100001 查询/刷新 case:data:query | 100002 上传 case:data:upload
--   F 100003 治理/清洗/aiClean/gt case:data:govern | 100004 下载/导出 case:data:export | 100005 打开文件 case:data:detail
-- M 1002 通信分析 path='1002' component=NULL perms=''
--   C 1003 持续联系 perms='call:continuous:list'
--     F 100301 query | 100302 detail | 100303 通话记录共享 call:record:query

端点组→操作码归属(覆盖 439 端点)

端点组 归属 码
/eds/*(104) 1000 浏览查询→case:data:query;材料/媒体→detail;上传/处理→upload/govern
/govern、/gt、/aiClean*、/cleanLog 1000 case:data:govern(/govern/sse、/sse/put→query)
/dm、/dp、/intimacy、/pbi、/pg(40) 1001 dm:portrait:query/detail
/call/{continuous,night,sensitive}、/cr 1003-1005 call:{资源}:query/detail;/cr→call:record:*
/trans/*(29,含 cashKey/financialKey/fixedDepositKey) 1007-1016 一一对应 trans:{资源}:query/detail;/trans 原始记录→trans:record:*
/track/*、/expressInfo(15) 1018-1023 track:{资源}:query/detail
/search、/sdc、/otg/timeSeries 1024 otg:behavior:query/detail
/graph(9) 1027/1028/1029 graph:view:query/detail、graph:editor:execute/remove/edit、graph:relation:query
/tower 10262 tower:aibase:query/detail
/case(除 public) 1091 case:manage:query/add/edit/remove/execute(open/exit)/detail(current)
/tpl 1092 tpl:tpl:query/add/edit/remove/import/export
/sys 非白名单工具类 1093 sys:util:query;cleanCache/uploadUpgrade→sys:maint:execute(默认授 common,设置抽屉全员在用);/embedding→embedding:debug:execute(仅超管)
/auth/logout info changePwd
/ai/**(162) 20101-20505 chat→ai:chat:(含 oss/onboarding/attachment admin);agent→ai:agent:/ai:expert:*;session→ai:session:;memory/skill/pack→同名码;model/usage/compaction→ai:model:/ai:usage:*/ai:runtime:;kb/doc/retrieval→ai:kb:/ai:doc:*/ai:retrieval:;registry/mcp-server/mcp-client→ai:tool:/ai:mcpServer:*/ai:mcpClient:;audit/retention/trace/route-run/health→ai:audit:/ai:auditTool:/ai:trace:/ai:route:*/ai:health:*;/ai/workbench/open→ai:workbench:execute(F 挂 20101)

授权与幂等

  • common(2) 默认授全部业务+工作台+系统操作码(融合前普通账号无校验,全授=零回归;管理员后续回收): INSERT INTO perm_role_menu SELECT 2, m.menu_id FROM perm_menu m WHERE m.perms NOT LIKE 'perm:%' AND m.menu_id <> 10000 AND m.perms <> 'embedding:debug:execute' AND NOT EXISTS(...)(10000 目录 perms='' 需显式排除,避免普通账号导航空目录)。
  • superadmin(1) 沿用现幂等绑全段(重跑自动补新菜单)。全部种子 INSERT…SELECT…WHERE NOT EXISTS。
  • admin 自带种子替换 sys_user 迁移段(现 L390-407):perm_user id=1/admin/哈希常量 $2a$10$dwBgMS1xW2PbUsuce16g/ujiVEH2H4pAjWoyeSMqLClwfOs1N9fri(来源 sql/user.sql:52,与存量迁移结果一致)+ perm_user_role(1,1),均 NOT EXISTS 保护;头注释同步改写。
  • 存量路径口径幂等 UPDATE:10000 path 'perm'→'10000';10001-10005 path 'user'…→'perm/user/index'…。约定:C 的 path 存完整路由路径(无前导 /)、component 存 /views 后相对路径(无前导 /),写入菜单页帮助文案。
  • 归档:sql/user.sql→sql/archive/user.sql;清 sql/platform_snowflake_ids.sql:23-49,73 sys_user 段、sql/gateway.sql:69,76 引用改 perm_user。

P2 后端(getRouters + 注解 + data_scope + 口径)

getRouters(menu.json 同构,不用 RouterVo)

  • GET /perm/menu/getRouters(PermMenuController 新增,仅登录校验)→ R<List<JsonNode>>。
  • 节点:{id,name,path,component,redirect?,meta:{title,icon,hideMenu,affix,orderNo},children?};M component='LAYOUT'、path='/'+path、redirect=首个 visible='0' 子 path;C component='/'+component;name='Views'+path 按 '/'/'-' 分段 Pascal('/graph/g6-editor'→ViewsGraphG6Editor,与 multipleTab.ts:60 硬编码一致);visible='1'→hideMenu;ext 解析 affix/group/permsOnly。
  • 新增 XML(mappers/perm/SysMenuMapper.xml,复用现 join 范式):selectRouterMenuAll / selectRouterMenuListByUserId(menu_type in ('M','C') and status='0',含 visible='1');不复用 selectMenuListByUserId(服务菜单管理页)。服务层建树跳过 permsOnly 子树(PermMenuService 新增方法)。
  • 工作台=单端点+前端取子树(20000 根随全树返回;主窗口过滤 group==='workbench',工作台 store 取该子树)。

注解(映射表即 P1)

  • 纯查询控制器(eds/person/dm/otg/track/call/trans 分析类)类级 @SaCheckPermission("xxx:query"),detail/export/execute 方法级覆盖;混合控制器(case/tpl/graph/sys/ai 25 类)方法级逐挂。
  • 白名单不动;SSE(/govern/sse、/ai/chat/stream|resume|regenerate)正常加注解(preHandle 先于 SseEmitter 返回;长连接建立后不复查,回收授权下次请求/resume 生效,文档注明)。
  • 实施时逐模块 grep 前端 api 调用核对「在用端点都有码且 common 默认授予」。

data_scope(仅 perm,落 com.zsjz.ai.common.datapermission)

移植 biz-buddy ruoyi-common-mybatis 最小面:annotation/{DataPermission,DataColumn}、enums/DataScopeType(SpEL 模板+elseSql 1=0)、helper/{DataPermissionHelper,DataPermissionIgnoreContext}、aspect/{Pointcut,Advice,PointcutAdvisor}、interceptor/PlusDataPermissionInterceptor+handler/PlusDataPermissionHandler;裁剪 scopeRoles 接口级增强/租户/LoginUser 依赖。

  • 注册:MybatisPlusConfig 数据权限拦截器加在分页之前 + Advisor bean。
  • @Service("sdss") PermDataScopeService:getRoleCustom→perm_role_dept;getDeptAndChild→perm_dept ancestors 展开;内部查询无注解 + SpEL 求值包 DataPermissionHelper.ignore() 防递归。
  • 当前用户:请求级 SaStorage 缓存轻量 PermDataScopeUser{userId,deptId,roles[{roleId,dataScope}]}(无注解查询加载)→ 无跨请求缓存,授权变更即时生效。超管入口 LoginHelper.isSuperAdmin() 跳过。
  • 注解落点(default 方法委托范式,列名已核实):SysUserMapper selectPageUserList/selectUserList + XML allocated/unallocated(别名 u.)→ deptName=dept_id, userName=user_id(SELF 映射 user_id 而非 create_by,种子 create_by 全=1);SysDeptMapper/SysPostMapper 列表 default → deptName=dept_id, userName=create_by。服务改调 PermUserService:76-77、PermDeptService:50,56、PermPostService:44-51。登录/selectById/exists 不加注解。
  • D3 边界:CaseInfoService.listByOwner、AiAuditServiceImpl.resolveAuditUserId 不动;拦截器全局注册但只命中带注解的 perm mapper(PG),JSqlParser 改写与方言无关。

口径合一

  • UserVO.status Integer→String、SysUserService.toVO:268 删翻转直传;LoginVO 增 String status(toLoginVO:249 补 set)。
  • 前端仅改两处类型声明:core/api/auth/authApi.ts:52、workbench/api/user.ts:10 → status?: string。
  • 注释清理:common/compat/UserDTO.java:10、common/model/plat/entity/CaseInfo.java:85。

P3 前端主窗口(动态导航 + v-auth)

  • src/api/perm/menu.ts 增 getRouters();core/store/modules/permission.ts buildRoutesAction 改 await getRouters(),存 rawMenuTree(工作台复用),过滤 workbench 组后走现 transform 链(L113-127 保留);删 menu.json import 与 frontMenuList/permCodeList 死状态;删除 core/store/modules/menu.json。空树抛错走守卫兜底提示。
  • permissionGuard.ts 不改(已 await buildRoutesAction);usePermission.resume() 不改(切案件=重拉菜单);菜单管理页保存后调 refreshMenu 即时生效。
  • core/router/routes/index.ts DataRoute(L63-90)只删 index 子路由(消除 ViewsDataIndex 重名),保留 '/data' 壳+cluePush+redirect。
  • 图标约束:种子只复用 uno.config.ts safelist 现有图标(工作台图标已在 L81-188);菜单页新增图标须同步 safelist(文档+菜单页 remark 注明)。
  • v-auth(接受 mounted-only,头注释写明约定:权限会话内静态、resume/重登整体重挂载):
    • plat/views/tpl/tpl.vue:8 错码 sys:empUser:edit→tpl:tpl:edit,补 import/add/remove。
    • plat/views/case/case.vue:查询→case:manage:query、新建→add、打开→execute、编辑→edit、删除→remove。
    • case/views/data/index.vue:上传→upload、治理/治理设置→govern、查询/刷新→query、下载→export、打开文件→detail。
    • 分析页三件套(call/trans/track 各 index.vue):查询→xxx:query、详情→xxx:detail(重置不挂码)。
    • graph/views/g6Editor/index.vue:保存布局→execute、删快照/清空/节点删除→remove、设分析条件→edit。
    • perm 五页补齐遗漏按钮码。

P4 工作台融合

  • 新建 src/workbench/store/menu.ts:读 permission store rawMenuTree 取 group='workbench' 子树→SimpleMenu Menu[](空时兜底拉 getRouters)。
  • workbench/layouts/WorkbenchSider.vue:5,24 改读 store;删 workbench/config/menu.ts(workbenchPaths 无消费点)。
  • WorkbenchRoute 静态子路由保留(导航 DB 化≠路由动态化);WorkbenchLayout.vue 增守卫:当前 path 不在授权子树→redirect 首个授权页(后端 ai/** 注解兜底 403)。
  • 21 页按钮按 P1 ai 码表加 v-auth(chat 发送/停止→ai:chat:add/execute 等)。

P5 测试与端到端验证(测试先行,贯穿各期)

契约测试(扩展 PermMigrationContractTest 或新建 PermFusionContractTest,打真实 dev 服务):

  1. getRouters admin 全树与 menu.json 快照逐节点比对(path/name/component/hideMenu/affix/redirect);workbench 组在、permsOnly 不在。
  2. 角色过滤:临时角色仅授部分菜单→子树正确;common 无 perm 子树。
  3. 业务 403:回收某码→端点 200+code403;恢复→200。
  4. common 不回归:permissions 覆盖全部业务码;每模块抽 1 端点实调 200。
  5. data_scope:scope5 角色+perm:user:list→用户列表仅本人;scope1/超管→全量;部门/岗位同理;分页+scope 组合。
  6. 口径:login/info status='0' 字符串;停用拒登语义不变。
  7. SSE:带 token 建连 200、无 token 401、回收码后新建连 403。
  8. sql/perm.sql 连跑两遍行数/授权数不变(复用 test-reports-20261118-perm/PermSqlIdempotencyCheck.java)。

浏览器走查(截图+清单入 test-reports-20261118-fusion/):主导航 DB 化逐目录展开、首页页签/affix/cluePush 回归;菜单管理新增菜单→导航生效;工作台独立窗口导航+按钮权限;普通账号回收部分码→按钮隐藏+直调 403;scope5 账号 perm 用户列表演示;切案件 resume 重拉菜单;登录/占用/force/登出释放案件回归。

风险与回滚

风险 对策
导航空白 快照契约先行;空树抛错+守卫提示;menu.json 删除与切换同批、测试绿后合入
common 授权回归 默认全授业务码+每模块抽样契约
SSE/异步 preHandle 时机已核实;注解 confined 到 perm mapper;sdss ignore 包裹
DuckDB/PG 方言 数据权限仅命中 perm mapper;分页 DbType 维持
图标 safelist 种子只用现有图标;新增须改 safelist(文档约束)
多页签硬编码 name 规则保证 ViewsDataIndex;path 不变→PageEnum/multipleTab 零改动+契约断言
回滚 sys_user 保留;种子只增不删;前端 git revert 恢复静态导航;后端回退上一 jar;无开关(no-fallback)

关键文件清单

  • 改:sql/perm.sql、sql/user.sql(归档)、sql/platform_snowflake_ids.sql、sql/gateway.sql
  • 改:module/perm/controller/PermMenuController.java、module/perm/service/PermMenuService.java、resources/mappers/perm/SysMenuMapper.xml、module/perm/mapper/Sys{User,Dept,Post}Mapper.java、module/perm/service/Perm{User,Dept,Post}Service.java
  • 改:约 60 个业务 Controller(注解)、common/config/MybatisPlusConfig.java、common/model/plat/vo/{UserVO,LoginVO}.java、module/plat/service/SysUserService.java、common/compat/UserDTO.java、common/model/plat/entity/CaseInfo.java
  • 新建:common/datapermission/**(10 文件)、module/perm/service/PermDataScopeService.java
  • 改(前端):src/api/perm/menu.ts、core/store/modules/permission.ts、core/router/routes/index.ts、core/api/auth/authApi.ts、workbench/api/user.ts、workbench/layouts/{WorkbenchSider,WorkbenchLayout}.vue、业务页 v-auth(case/data/分析页/graph/tpl/perm/workbench 21 页)
  • 新建(前端):src/workbench/store/menu.ts
  • 删:core/store/modules/menu.json、workbench/config/menu.ts、DataRoute index 子路由
  • 测试:ai-server/src/test/java/com/zsjz/ai/module/perm/PermMigrationContractTest.java(扩展)