docs: 统一项目文档进 eip4-platform/docs + 新增进度路线总览
Some checks failed
ci / build-test-parity (push) Has been cancelled
Some checks failed
ci / build-test-parity (push) Has been cancelled
- 从工作区根 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>
This commit is contained in:
158
docs/用户管理-Delta移植-实现过程与踩坑-2026-06-17.md
Normal file
158
docs/用户管理-Delta移植-实现过程与踩坑-2026-06-17.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 用户管理 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`。
|
||||
Reference in New Issue
Block a user