Files
eip4-platform/docs/用户管理-Delta移植-实现过程与踩坑-2026-06-17.md
zhengwr 1b69f8b481
Some checks failed
ci / build-test-parity (push) Has been cancelled
docs: 统一项目文档进 eip4-platform/docs + 新增进度路线总览
- 从工作区根 docs/(非 git,未版本化)合并全部文档进版本控制,消除文档两头分裂
- 新增 README(状态总览+模块完成度+全文档索引)、项目进度与路线-总览-2026-06-17(A兼容/B新功能+关键路径+待拍板决策)
- 被取代的冲突状态/审计快照归入 归档/;对最易误导的两份("16视图已交付"实现交付报告、06-13架构快照)加"已归档"横幅
- 现行权威:engineclass移植backlog(46视图) + 用户管理Delta移植(方法论/交接) + 组件设计体系 + 通用模板收口 + 客户沟通
- 诚实口径:纵向模块仅用户管理 parity,横向引擎地基较全,余 153 定制视图(47 framework+106 业务)多为通用页已产·delta 未移植

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-17 14:53:29 +08:00

159 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 用户管理 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 默认引擎/转换器
7. **type=101 是「树形选择框」**:`isTreeDialog` 原只认 `type==3`,导致部门/岗位选择框(type=101,org→部门 / org→部门→岗位树)被当普通 SelectDialog 渲扁平 picker 查到树根 SYS_ORG(表现「主部门引用错,弹组织」)。修 = 认 `type IN (3,101)`;type=101 再加 `onlyLeaf:true`(只选叶子实体),type=3 组织树任意级不加。
8. **tree 端点鉴权才返数据**:`/api/template/{id}/tree` 无鉴权被数据权限过滤返 0(假象),鉴权后返完整层级。验证务必带 token。
9. **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 部署
10. **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 关键字)。
11. **schema 改动 vs 后端改动**:机制① 按钮/converter 修 = 重转 + SchemaImportCli 导入**即时生效免重启**(PageSchemaController 直读 DB);后端 Java(新端点/PickerController)= **必须 rebuild app + 重启 8093**。
12. **登录 token 在顶层 `d.token`**(不是 `d.data.token`);`POST /api/auth/login {account:admin, password:111111}`。
13. **etag 文本抖动 vs 语义 diff**:SchemaImportCli 的 etag 是**文本**敏感(转换器输出 key 顺序非确定 → 同语义不同文本 → 多余 upsert,无害);判「真变化」用语义 diff(解析 JSON 比对,见 `/tmp/diff_*.py`),别看 upsert 数。
14. 备份 jar `/tmp/platform-app-BACKUP-running.jar` 可回滚。
---
## 4. 部署 recipe(速查)
```bash
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 现有远程 git.latent.chat)。
**剩余(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`。