- 新人上手 §1:托管地址/clone 命令改 <GIT_HOST>:<OWNER> 占位,SSH 端口细节改「向负责人索取」 - 路线图/用户管理Delta/总览 三处历史记录行、.gitea/ci.yml 注释:host 名改「私有 Gitea/私有远程」 - 全仓 grep 验证零残留 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
18 KiB
用户管理 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 片段(机制① 按钮)
- dialog 数据注入:选中行主键要从 dialog 级
data注入("data": {"USERID": "${selectedItems[0].SYS_USER_ID}"}),内层 form/source 引${USERID}。别在 form initApi 里直接写${selectedItems[0].X}——弹窗作用域取不到,radios 永远空。(复用 P0 navigation 验证过的模式。) - 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可渲染。 - 预选现任值:form
initApi.responseData用 amis 公式${ARRAYFILTER(items, item => item.ISMASTER == true || item.ISMASTER == 1)[0].SYS_POSITIONUSER_ID}算出默认值设给同名字段 → radios 自动选中。amis 支持 ARRAYFILTER +[0].field链式。 - 空数据 ≠ bug:无岗位的用户 radios 空是数据正确。测要选有数据的(如 000007 何新伟有岗位)。
- 只读树别用
disabled:true:整树变灰 + 不可展开/滚动(用户反馈差)。用searchable:true+heightAuto:true,去掉 disabled;弹窗只有「关闭」不入表单提交,选中无副作用。 - CHAR 补白 id:按钮 URL 用
${selectedItems[0].SYS_USER_ID}时,确认该字段在*_SEARCH响应里已 trim(用户管理的 SYS_USER_ID 是干净的 36 字符);后端 @PathVariable 也.trim()兜底。
3.2 默认引擎/转换器
- type=101 是「树形选择框」:
isTreeDialog原只认type==3,导致部门/岗位选择框(type=101,org→部门 / org→部门→岗位树)被当普通 SelectDialog 渲扁平 picker 查到树根 SYS_ORG(表现「主部门引用错,弹组织」)。修 = 认type IN (3,101);type=101 再加onlyLeaf:true(只选叶子实体),type=3 组织树任意级不加。 - tree 端点鉴权才返数据:
/api/template/{id}/tree无鉴权被数据权限过滤返 0(假象),鉴权后返完整层级。验证务必带 token。 - 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 部署
- 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 关键字)。 - schema 改动 vs 后端改动:机制① 按钮/converter 修 = 重转 + SchemaImportCli 导入即时生效免重启(PageSchemaController 直读 DB);后端 Java(新端点/PickerController)= 必须 rebuild app + 重启 8093。
- 登录 token 在顶层
d.token(不是d.data.token);POST /api/auth/login {account:admin, password:111111}。 - etag 文本抖动 vs 语义 diff:SchemaImportCli 的 etag 是文本敏感(转换器输出 key 顺序非确定 → 同语义不同文本 → 多余 upsert,无害);判「真变化」用语义 diff(解析 JSON 比对,见
/tmp/diff_*.py),别看 upsert 数。 - 备份 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 上的过滤参,过滤 + 重拉一次解决。
两端改动(均已上线):
- 转换器
TemplateToAmisConverter.applyFilterscriptCascade(新方法):字段循环里(convertViewPage+buildFormItemsFromPage都接)对每个有filterscript属性的 select,去pageScripts取脚本体,正则\.put\(\s*"COL"\s*,\s*getFieldValue\(\s*"TRIG"\s*\)\)抽(COL,TRIG)对 → 把&COL=${TRIG}追加进 source(幂等、跳过自引用)。非该模式的 filterscript(纯常量/复杂脚本)不改 source(P3 兜底另案)。 - 后端
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 重做时一并处理)。本轮按此收口:
- 性能①:不预拉(
initFetchOn)。原先表单一开,级联下拉就各发空参全量请求(如部门返回全 48)。改为:转换器给级联 select 设initFetchOn="${触发字段}"→ 触发字段空不初拉、选了上级才拉;编辑态触发字段有值则照常初拉;change 重拉不受影响。live 实证:71de2065 重载后零 picker 请求,选组织后部门带PARENTORGID=…正常重拉。 - 性能②(前缀 LIKE)放弃:引擎
GeneralPO对 String 列硬编码col like '%值%'(GeneralPO.java:1940),改它要动共享保真引擎、风险高;被过滤的都是小查找表(几十~几百行),全表扫描是微秒级 → 不值得。正确性顺带确认:数值列(如 STATUS)引擎走精确=(按列声明类型分派,L1936),不会%3%误匹配。 - 变体扩展(bracket 语法):识别
map["COL"]=getFieldValue("TRIG")→ 多覆盖 2 个 ComboBox 表单(费率配置 CALCBASICSCONFIGID/紧急放行 UNITPROJECTID 按 PROJECTID 级联,后端实测 500→31、56→1 匹配 DB)。 - 正确性护栏:
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。