Files
eip4-platform/docs/用户管理-Delta移植-实现过程与踩坑-2026-06-17.md
zhengwr dd3b048899 docs: 清除私有托管地址,改中性表述(取码地址向负责人索取)
- 新人上手 §1:托管地址/clone 命令改 <GIT_HOST>:<OWNER> 占位,SSH 端口细节改「向负责人索取」
- 路线图/用户管理Delta/总览 三处历史记录行、.gitea/ci.yml 注释:host 名改「私有 Gitea/私有远程」
- 全仓 grep 验证零残留

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 08:29:30 +08:00

18 KiB
Raw Permalink Blame History

用户管理 Delta 移植 — 实现过程与踩坑(2026-06-17 会话交接)

用途:本会话以「用户管理」为首个端到端案例,确立 engineclass Delta 移植方法 + 机制①骨架,并修了若干默认引擎缺口。本文档沉淀实现过程 + 踩坑,供下个会话续作其余 45 个 framework 定制视图的 Delta 改造时直接复用、不重蹈覆辙。


0. 一句话定性(用户拍板的真任务)

「framework 定制视图转换重新做」真任务 = 移植 engineclass 的 Java 定制 delta,不是手搓页、不是改菜单。

  • 转换器复刻「默认模板引擎页」(吃 view_template/view_page 的 XML)→ 大多数功能本就 OK。
  • 配了 engineclass 的视图,有个 Java 子类 EXTENDS 基类(GridTemplateComponent 等),在默认引擎之上加/改了东西(新按钮 / 重写按钮 / 重写服务 / 级联脚本)→ 转换器抓不到,要逐个分析移植。
  • 之前两轮「读 XML 审计」不可靠(看不懂 eip3 架构:isshow=false 故意 / treegrid 左树只读是对的)。正确审计 = 读 Java engineclass 抽 delta → docs/framework定制视图-engineclass移植backlog-2026-06-17.md(46 视图 236 移植项)。

1. 机制①(EngineclassDelta)—— 后续 60+ 按钮移植的复用骨架

文件:platform-converter/.../converter/EngineclassDelta.java(新增)。

  • 一个注册表:engineclass FQN → 工具栏按钮 amis 片段 builder 列表。
  • TemplateToAmisConverter:加 currentEngineclass 字段 + 6 参重载 convertGraded(xml, templateId, engineclass, name, notes, resolver);convertGradedInternal 末尾 EngineclassDelta.apply(schema, engineclass, result)(仅 body.type=crud 注入,插 pagination 前)。
  • BatchConvertCli:SQL 多查 engineclass 列传入。

加一个新 engineclass 按钮 = 在 EngineclassDelta 注册一行 + 写一个 builder 方法。范例见 masterPositionButton / userMenuButton。


2. 用户管理已交付(4 处,全部 live 验证通过)

# 项 类型 落点
1 设置主岗位 engineclass delta EngineclassDelta.masterPositionButton(SYS_POSITIONUSER_SEARCH 列岗位单选→SYS_POSITIONUSER_UPDATEMASTER)
2 查看用户菜单 engineclass delta + 后端 EngineclassDelta.userMenuButton(只读树)+ MenuController 新端点 /api/admin/user/{userId}/menu(复用 menuTreeFor,view_sys_usermenuid 裁剪)
3 主部门/主岗位 树选择 默认引擎修(通用,惠及 245 视图) TemplateToAmisConverter.isTreeDialog 认 type=101 → tree-select + onlyLeaf
4 picker 引用列显名 默认引擎修(通用,惠及所有 picker) PickerController 统一走 UserColumnResolver.resolveRows + remapReferenceColumnsToDisplay

后两项是用户逐字段 dogfood 揪出的默认引擎缺口(非 engineclass delta),但都是通用修复。


3. 踩坑清单 ⚠️(最重要,逐条避雷)

3.1 amis schema 片段(机制① 按钮)

  1. dialog 数据注入:选中行主键要从 dialog 级 data 注入("data": {"USERID": "${selectedItems[0].SYS_USER_ID}"}),内层 form/source 引 ${USERID}。别在 form initApi 里直接写 ${selectedItems[0].X}——弹窗作用域取不到,radios 永远空。(复用 P0 navigation 验证过的模式。)
  2. radios/select 的 source 必须返 data.options:保真层 *_SEARCH 返 data.items,amis options 控件认 data.options。用 source API 的 responseData: {options: "${items}"} 映射。对照已验证可用的 /api/poc/dict/USERSTATE(返 {data:{options:[{label,value}]}})。raw 对象 + labelField/valueField 可渲染。
  3. 预选现任值:form initApi.responseData 用 amis 公式 ${ARRAYFILTER(items, item => item.ISMASTER == true || item.ISMASTER == 1)[0].SYS_POSITIONUSER_ID} 算出默认值设给同名字段 → radios 自动选中。amis 支持 ARRAYFILTER + [0].field 链式。
  4. 空数据 ≠ bug:无岗位的用户 radios 空是数据正确。测要选有数据的(如 000007 何新伟有岗位)。
  5. 只读树别用 disabled:true:整树变灰 + 不可展开/滚动(用户反馈差)。用 searchable:true + heightAuto:true,去掉 disabled;弹窗只有「关闭」不入表单提交,选中无副作用。
  6. CHAR 补白 id:按钮 URL 用 ${selectedItems[0].SYS_USER_ID} 时,确认该字段在 *_SEARCH 响应里已 trim(用户管理的 SYS_USER_ID 是干净的 36 字符);后端 @PathVariable 也 .trim() 兜底。

3.2 默认引擎/转换器

  1. type=101 是「树形选择框」:isTreeDialog 原只认 type==3,导致部门/岗位选择框(type=101,org→部门 / org→部门→岗位树)被当普通 SelectDialog 渲扁平 picker 查到树根 SYS_ORG(表现「主部门引用错,弹组织」)。修 = 认 type IN (3,101);type=101 再加 onlyLeaf:true(只选叶子实体),type=3 组织树任意级不加。
  2. tree 端点鉴权才返数据:/api/template/{id}/tree 无鉴权被数据权限过滤返 0(假象),鉴权后返完整层级。验证务必带 token。
  3. picker 列解析要与功能列表统一(用户洞察):功能列表 FlowController 走 UserColumnResolver.resolveRows 补 {COL}_DISPLAY__,PickerController 原走 pojoCRUDService.listSelect 不解析 → 引用列(PARENTID 等)显裸 id。修 = PickerController 注入 UserColumnResolver、resolveRows(table, rows) + remapReferenceColumnsToDisplay(列 name 改指 {COL}_DISPLAY__)。改构造器记得同步改 PickerControllerTest 的 new PickerController(...)(+1 参)。

3.3 部署

  1. maven 增量不重打 fat jar:改的是依赖模块(platform-metadata),platform-app 自身类没变 → mvn -pl platform-app -am package 的 spring-boot repackage 看 fat jar「up-to-date」跳过,jar 还是旧的、改动没进去(空重启白断会话)。必须 mvn -pl platform-app -am clean package -DskipTests 强制重建。部署前先验 jar 含改动再重启(unzip -l ...jar | grep platform-metadata 看时间戳 / 解 class strings grep 关键字)。
  2. schema 改动 vs 后端改动:机制① 按钮/converter 修 = 重转 + SchemaImportCli 导入即时生效免重启(PageSchemaController 直读 DB);后端 Java(新端点/PickerController)= 必须 rebuild app + 重启 8093。
  3. 登录 token 在顶层 d.token(不是 d.data.token);POST /api/auth/login {account:admin, password:111111}。
  4. etag 文本抖动 vs 语义 diff:SchemaImportCli 的 etag 是文本敏感(转换器输出 key 顺序非确定 → 同语义不同文本 → 多余 upsert,无害);判「真变化」用语义 diff(解析 JSON 比对,见 /tmp/diff_*.py),别看 upsert 数。
  5. 备份 jar /tmp/platform-app-BACKUP-running.jar 可回滚。

4. 部署 recipe(速查)

export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home   # JDK21 红线
# A) 仅 schema 改动(机制①/converter):免重启
mvn -q -pl platform-converter -am install -DskipTests
java -cp "platform-converter/target/classes:$(cat /tmp/cp.txt)" com.eip4.platform.converter.BatchConvertCli \
  "jdbc:postgresql://localhost:5433/eip4dev?currentSchema=eip3" zhengwr zhengwr <outDir> tools/s3_rewriter/output
# 语义 diff(确认爆炸半径),再导入:
java -cp "platform-metadata/target/classes:$(cat /tmp/cp.txt)" com.eip4.platform.metadata.schema.SchemaImportCli \
  "jdbc:postgresql://localhost:5433/eip4dev?currentSchema=eip3" zhengwr zhengwr <outDir>/schema <outDir>/分级清单.csv
# B) 后端改动:clean 重建 + 重启
mvn -q -pl platform-app -am clean package -DskipTests           # 必须 clean
# 验 jar 含改动 → lsof -ti :8093 | kill → nohup java -jar platform-app/target/platform-app-*.jar --spring.profiles.active=dev

classpath:mvn -pl platform-converter dependency:build-classpath -Dmdep.outputFile=/tmp/cp.txt。


5. 剩余工作(下个会话)

5.1 用户管理本身剩余

  • 编辑页 org picker 补查询条件(老有 组织名称/描述/排序号/简称 查询区)+ 列对齐(创建时间等)。
  • 导出 Excel 按钮(GridTemplateComponent 默认能力,非 engineclass delta)。
  • 查看用户菜单增强(B):老版点菜单→右侧显授予该菜单的用户组/角色(master-detail);现为只读树。可做 tree onEvent→「菜单→该用户授权用户组」端点。
  • view_page 表单 filterscript 级联(C):见 §6,按计划走。

5.2 全局

  • 其余 45 个 framework 定制视图的 engineclass Delta 移植,按 docs/framework定制视图-engineclass移植backlog-2026-06-17.md(P1 picker全家 / 任务按钮 / 查看审批 等先做)。
  • 注意 backlog 里 override-service/button(45 个)最危险=默认行为被 Java 完全替换(不调 super),EIP4 默认页会调错服务/弹错表单,须重点移植 + 保真层补端点。

6. view_page 表单 filterscript 级联 — 实现计划(已批准,下会话执行)

现状:添加用户表单 71de2065 转换页 onEvent=0、零 setFilter/reload → 级联脚本完全没挂(通用缺口,影响所有有级联脚本的表单)。运行时脚本端点齐全(/api/script/execute-template-by-name 等)。

老脚本(用户管理添加页 <scripts>)→ amis 映射:

eip3 脚本 语义 amis 实现
根据组织过滤部门 MASTERDEPART.setFilter(PARENTORGID=USERORGID) 部门字段 source 带 ?PARENTORGID=${USERORGID}
组织改变后更新部门 onchange USERORGID → reload 部门 + AUTOGENERATECODE 账号 USERORGID onEvent.change → reload MASTERDEPART + 调取号端点 setValue ACCOUNT
根据部门过滤岗位 MASTERPOSITION.setFilter(PARENTDEPARTID=MASTERDEPART) 岗位 source 带 ?PARENTDEPARTID=${MASTERDEPART}
部门改变后更新岗位 onchange MASTERDEPART → reload 岗位 MASTERDEPART onEvent.change → reload MASTERPOSITION

P1 级联过滤(组织→部门→岗位,覆盖主体):转换器解析 view_page <scripts> 的 searchMap.put("<FILTERCOL>", getFieldValue("<TRIGGER>")); group.getField("<TARGET>").setFilter(...) + <TARGET>.reload() 模式 → 抽「TARGET 依赖 TRIGGER、按 FILTERCOL 过滤」→ 生成 amis(TARGET source 带过滤参 + TRIGGER onEvent.change→reload TARGET)。后端:部门/岗位按 org/dept 过滤查询端点(多半现成 picker/flow 加过滤参)。全库通用。


✅【2026-06-17 续会话】P1 级联过滤 —— 已实现 + 全库重转 + live 端到端验证

真正实现比上面计划更简洁(无需 onEvent):amis 对「source 含 ${var}」的 select 控件原生监听变量变化自动重拉(与 type=4 右表 node=${tree} 同机制),所以只需把 filterscript 译成 source 上的过滤参,过滤 + 重拉一次解决。

两端改动(均已上线):

  1. 转换器 TemplateToAmisConverter.applyFilterscriptCascade(新方法):字段循环里(convertViewPage + buildFormItemsFromPage 都接)对每个有 filterscript 属性的 select,去 pageScripts 取脚本体,正则 \.put\(\s*"COL"\s*,\s*getFieldValue\(\s*"TRIG"\s*\)\) 抽 (COL,TRIG) 对 → 把 &COL=${TRIG} 追加进 source(幂等、跳过自引用)。非该模式的 filterscript(纯常量/复杂脚本)不改 source(P3 兜底另案)。
  2. 后端 PickerController.list + applyColumnFilters(新方法):从 allParams 取「命中本表真实列名(大写白名单,控制参 q/page/perPage/op/... 排除)且非空值」的参 → escapeLikeValue 转义后加进 cond 等值条件。坑:CHAR(36) 主键/外键列库内带尾空格补白,col='uuid'/IN 因 padding 不匹配,而引擎对 String 条件走 col like '%值%' 恰好匹配 padded 值 → LIKE 是健壮选择。空值不下推(amis 触发器未选 → 列全部,不误清空)。

爆炸半径(干跑 diff 确认,纯增量)= 恰 4 个表单:用户新增页面(71de2065)/用户修改页面(de3a815b)/员工档案带证书编辑(b8f87393)/个人档案(2c672ea6)——全是 org→部门→岗位 级联表单,每页仅给 MASTERDEPART 加 &PARENTORGID=${USERORGID}、MASTERPOSITION 加 &PARENTDEPARTID=${MASTERDEPART},0 删除/0 改它字段/0 附带页。坑:语义 diff 必须用 Python 深度相等(int==float),否则 jsonb 把 Java Double vmax(如 9999999999.0)规范成整数 9999999999 → 24 个假阳性「变化」。另坑:后台跑 BatchConvertCli 被截断(122/2727 文件却 exit 0),改前台跑才完整。

live 验证(浏览器 dogfood,决定性证据):navigate /page/71de2065... 独立渲染表单 → 选组织「名城分公司」→ 网络实证 GET /api/picker/SYS_DEPART/list?...&PARENTORGID=402881...0006 自动重拉、部门下拉只显「名城分公司>经理室」→ 选该部门 → GET .../SYS_POSITION/list?...&PARENTDEPARTID=402881...0063、岗位下拉只显「经理室>科员/经理」。API 层亦验证(部门 48→28、岗位 75→6,匹配 DB)。「添加」按钮弹窗正常打开渲染该表单(无 bug;先前点击没弹是页面未就绪的时序问题,刷新后正常)。

部署:转换器=schema 改动,重转 + 只导这 4 页(避免 24 噪声页 churn)即时生效;PickerController=后端改动,已 mvn -pl platform-app -am clean package 重建 + 重启 8093(新 jar 验含 applyColumnFilters)。备份 /tmp/platform-app-NEW-filterscript.jar、回滚 /tmp/platform-app-BACKUP-running.jar。converter 149 测试绿 + PickerControllerTest 26 绿。改动未提交(TemplateToAmisConverter/PickerController + 2 测试,叠加在上一轮 7 文件之上;eip4-platform 现有私有远程)。

剩余(P2/P3):P2 AUTOGENERATECODE 账号自动生成(USERORGID change 调取号端点 → bind ACCOUNT,需补后端取号端点)+ MASTERDEPART 改变设 MASTERPOSITION 必填(可 requiredOn);P3 非模式脚本走 /api/script/execute-template-by-name 运行时兜底。


✅【2026-06-17 续2】filterscript 通用性盘点 + 性能优先收口(已上线 live 验证)

用户质疑"是否通用"→ 全库实测:576 个 filterscript 字段(381 页),我的简单等值译只覆盖 6(≈1%)。分类:527/576 是 picker(SelectDialog/Multi,非 ComboBox);~60%(345)内嵌原始 SQL(NOT IN/NOT EXISTS/子查询/CustomSearchConditional)静态查询参根本无法表达;24% 是常量过滤。结论:filterscript 没法统一静态化——真正通用 = P3 运行时跑老 Groovy(保真但慢,每次下拉/联动一次 JSR-223 Groovy eval + 自身查库,并发放大)。

用户定调:既然没法统一,按性能优先取舍(= 守静态快路、不上运行时 Groovy;复杂的留 picker 重做时一并处理)。本轮按此收口:

  1. 性能①:不预拉(initFetchOn)。原先表单一开,级联下拉就各发空参全量请求(如部门返回全 48)。改为:转换器给级联 select 设 initFetchOn="${触发字段}" → 触发字段空不初拉、选了上级才拉;编辑态触发字段有值则照常初拉;change 重拉不受影响。live 实证:71de2065 重载后零 picker 请求,选组织后部门带 PARENTORGID=… 正常重拉。
  2. 性能②(前缀 LIKE)放弃:引擎 GeneralPO 对 String 列硬编码 col like '%值%'(GeneralPO.java:1940),改它要动共享保真引擎、风险高;被过滤的都是小查找表(几十~几百行),全表扫描是微秒级 → 不值得。正确性顺带确认:数值列(如 STATUS)引擎走精确 =(按列声明类型分派,L1936),不会 %3% 误匹配。
  3. 变体扩展(bracket 语法):识别 map["COL"]=getFieldValue("TRIG") → 多覆盖 2 个 ComboBox 表单(费率配置 CALCBASICSCONFIGID/紧急放行 UNITPROJECTID 按 PROJECTID 级联,后端实测 500→31、56→1 匹配 DB)。
  4. 正确性护栏:applyFilterscriptCascade 加 FILTER_COMPLEX_MARKER——脚本含 SQL/服务调用/控制流/WhereClause 则整条跳过(绝不"只搬一半"丢复杂限制→显多余数据),复杂的留 P3。同时统一支持 .put/方括号 的动态+常量。实测常量在 ComboBox 上全被护栏判复杂跳过(0 个落地)→ 无 %值% 过匹配风险。

部署:纯 schema 改动(initFetchOn + 2 新 bracket 级联参),重转→干跑 diff(深度相等,6 页纯增量:4 原表单加 initFetchOn + 2 新表单加 PROJECTID 参/initFetchOn)→只导 6 页,后端 applyColumnFilters 上轮已 live → 本次免重启。converter 133 测试绿。改动未提交。

filterscript 终局结论:静态可达的(ComboBox 简单等值)已收口(8 表单:org→部门→岗位 4 + PROJECTID 级联 2 +…);剩 ~150 个 picker filterscript + 345 个 SQL 复杂条件,全部推迟到 picker 机制④重做时处理(届时优先"调真实 search 服务带参"≈普通查询那么快,而非 per-request 跑 ad-hoc Groovy)。不再为 filterscript 反复改转换器。

P2 AUTOGENERATECODE 账号自动生成:解析该模式 → USERORGID change 调取号端点(等价 EnviromentGet.get(AUTOGENERATECODE,"SYS_USER","ACCOUNT",initMap))→ bind ACCOUNT。需补取号后端端点。

P3 通用脚本兜底:非模式脚本经 /api/script/execute-template-by-name 运行时执行、应用返回字段更新(保真高但重,兜底)。


7. git / 系统状态(本会话末)

未提交改动(两仓无远程,push 需先 add remote):

  • eip4-platform:EngineclassDelta.java(新增)+ TemplateToAmisConverter.java(机制①+isTreeDialog type=101+onlyLeaf)+ BatchConvertCli.java(穿 engineclass)+ MenuController.java(user-menu 端点)+ PickerController.java(统一解析)+ 对应 2 测试文件。
  • eip4-web:src/api/menu.ts(上轮 demo 菜单移除,未提交)。
  • 8093 跑 clean 重建的新 jar(含 MenuController + PickerController 改动);sys_page_schema 2729(机制① 按钮 + 245 tree-select + navigation 全 live)。converter 全测试 128 绿,PickerControllerTest 24 / MenuControllerTest 6 绿。
  • 登录 admin/111111。备份 jar /tmp/platform-app-BACKUP-running.jar。