转换器侧(事件段):TemplateToAmisConverter.attachScriptOnEvent 在页面
body 挂 inited+change 两类 onEvent,动作链 ajax 调 /api/script/execute-template
(传 templateId/seq/item:${&})→ replayScriptCommands 重放返回指令。
执行端点:ScriptExecuteController /api/script/execute-template 改接
{templateId,seq,item},RewrittenScriptStore 按 (tid,seq) 从改写产物
output/rewritten 取脚本正文(去头注释)经 facade 执行;原按名端点改
-by-name 保留 P4-2 兼容。
测试:RewrittenScriptStoreTest 4 + ScriptExecuteControllerTest 4 +
TemplateToAmisConverterTest 新增 4 onEvent 例;converter 28 / metadata 77 /
ArchUnit 1 全绿。
出入回写报告第五章 §5.3;新坑入手册 §8.5(组件级动作路由)/§8.6(改写产物取数键)。
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
282 lines
18 KiB
Markdown
282 lines
18 KiB
Markdown
# P4 脚本迁移执行报告(脚本迁移线)
|
||
|
||
> 任务编号:P4-2
|
||
> 日期:2026-06-11
|
||
> 责任:S3 改写产出全量落盘 + facade 动词表运行时实现 + 集成/回归验证
|
||
> 诚实边界:全量改写以客户库落盘缓存 `scripts_cache.json`(dbname=postgres¤tSchema=eip3,
|
||
> 与 C4 报告 `--from-db` 同口径,**未连任何 ceshi 库**)为源,自动化率 81.2% 与 C4 实测一致复现。
|
||
> facade 运行时为真实代码 + 真实脚本经保真层引擎执行的端到端实证(非桩)。
|
||
|
||
---
|
||
|
||
## 一、全量改写产出统计
|
||
|
||
### 1.1 分类计数(1,427 条全量)
|
||
|
||
| 分类 | 条数 | 占比 | 处置 |
|
||
|------|------|------|------|
|
||
| FULL_AUTO | **497** | 34.8% | 全自动改写完成,直接入 P4 转换流水线 |
|
||
| PARTIAL | **30** | 2.1% | 大部分已自动改写,余留深层组件访问行人工补全 |
|
||
| HARD | **85** | 6.0% | 硬 S3(动态 Vaadin 组件/showConfirmDialog/UI.getCurrent),原文保留进人工排期 |
|
||
| NO_S3 | **815** | 57.1% | 无 S3 模式,原样进 P4 |
|
||
| **S3 小计** | **612** | — | FULL_AUTO + PARTIAL + HARD |
|
||
|
||
**★ 自动化率 = FULL_AUTO / S3 总数 = 497 / 612 = 81.2%(≥80% 预算线,锁定)**
|
||
**★ 与 C4 实测报告完全一致复现(497/30/85/815),0 误改。**
|
||
|
||
### 1.2 落盘产物
|
||
|
||
```
|
||
tools/s3_rewriter/
|
||
├── run_rewrite.py # 全量改写产出落盘驱动(本次新增)
|
||
└── output/
|
||
├── rewritten/<template_id>/<seq>.<label>.groovy # 改写后脚本库(1,427 文件)
|
||
│ - FULL_AUTO : 改写后脚本,头注释标 FULL_AUTO + 处置(直接可用)
|
||
│ - PARTIAL : 已改写部分,头注释标 PARTIAL + 余留模式(带余留标注)
|
||
│ - HARD : 原文保留,头注释标 HARD + 硬 S3 原因(人工标记)
|
||
│ - NO_S3 : 原样,头注释标 NO_S3
|
||
├── manual_workpackage/<序>_<label>_<tid>_<名>.md # 人工作业单(115 份)
|
||
├── stats.json # 全量产出统计
|
||
├── full_auto_index.json # 497 条 FULL_AUTO 索引(动词组合,集成挑样用)
|
||
├── integration_picks.json # 集成验证选中的 6 条 facade-only 脚本
|
||
└── integration_evidence.json # 集成验证证据(请求/捕获指令留档)
|
||
```
|
||
|
||
- 按 `template_id` 分目录、`template_id + 脚本序号` 命名落盘:721 个模板,单模板最多 9 段脚本,序号区分。
|
||
- 落盘文件数:1,427(FULL_AUTO 497 + PARTIAL 30 + HARD 85 + NO_S3 815)。
|
||
|
||
### 1.3 规则命中分布(与 C4 一致,Top)
|
||
|
||
| 规则 | 命中 | 规则 | 命中 |
|
||
|------|------|------|------|
|
||
| addFieldOption | 271 | group_setReadOnly | 28 |
|
||
| setFilter(平衡括号) | 187 | getDisplay / reload | 27 / 27 |
|
||
| getContainerDataSource | 159 | setVisible / setCaption | 26 / 25 |
|
||
| removeAllItems | 126 | setViewWithoutEditor | 16 |
|
||
| getValue | 122 | setEnabled | 10 |
|
||
| addSubTableButton | 108 | setNullSelectionItemId | 9 |
|
||
| setValue | 73 | Notification_show | 7 |
|
||
| setReadOnly_field | 64 | setRequired / showAddButton | 6 / 6 |
|
||
| setConvertedValue | 36 | setRequiredError / getModify/Detail | 3 / 3 / 3 |
|
||
| removeItem | 32 | showDeleteButton | 2 |
|
||
| propertyDataSource_setReadOnly | 30 | | |
|
||
|
||
---
|
||
|
||
## 二、facade 动词表运行时实现清单
|
||
|
||
改写器把 S3 改写成 31 个目标动词(见 C4 报告 §2.2)。本次在引擎侧落地:脚本经
|
||
`com.dsasp.server.dataDic.binding.ScriptingEnginesManager.evaluateGroovy(key, script, bindings)`
|
||
执行时,由现代层 `com.eip4.platform.metadata.script.ScriptFacade` 把每个动词作为 Groovy 闭包注入
|
||
`Bindings`(PoC enableButton 模式扩展到全动词表)。脚本文本零修改即可运行。
|
||
|
||
### 2.1 保真层纪律
|
||
|
||
- **零改 com.dsasp 源码**:facade 全部位于现代层 `com.eip4.platform.metadata.script.ScriptFacade`,
|
||
仅向保真层注入闭包,复用 PoC 已建的 facade 注入点(`ScriptingEnginesManager.evaluateGroovy` 的
|
||
`Bindings` 参数)。**无替换类登记**——没有动任何 com.dsasp 文件。
|
||
- ArchUnit「保真层禁止依赖现代层」单测复跑通过(`ArchitectureRulesTest`,1 passed)。
|
||
|
||
### 2.2 动词分类(服务端语义 vs UI 捕获)
|
||
|
||
**服务端语义动词(3 个,直接服务端求值并返回):**
|
||
|
||
| 动词 | 实现 | 说明 |
|
||
|------|------|------|
|
||
| getFieldValue("X") | 返回 `item.get("X")` | 脚本读行数据字段值做分支,不产生 UI 指令 |
|
||
| getFieldDisplay("X") | 返回 `item.get("X")` | 字段显示值(amis 侧由 label/map 渲染) |
|
||
| getFieldDataSource("X") | 返回轻量数据源句柄 | 兜底动态链 `.removeAllItems()/.addItem()/.setFilter()` 折叠回 facade |
|
||
|
||
**UI 语义动词(29 个,捕获为 amis 事件动作指令 JSON):**
|
||
指令统一形态 `{actionType, componentId?, args?}`(amis 事件动作协议口径,actionType 取
|
||
amis 标准动作名;平台扩展语义用自定义 actionType + args 表达)。
|
||
|
||
| 动词 | actionType | 形态 |
|
||
|------|-----------|------|
|
||
| setFieldVisible(X,b) | show / hidden | `{actionType:"show"/"hidden", componentId:X}` |
|
||
| setFieldEnabled(X,b) | enabled / disabled | `{..., componentId:X}` |
|
||
| setFieldReadOnly(X,b) / setFieldViewOnly | static / nonstatic | `{..., componentId:X}` |
|
||
| setFieldValue(X,v) | setValue | `{..., componentId:X, args:{value:v}}` |
|
||
| setFieldConvertedValue(X,v) | setValue | `args:{value:v, converted:true}` |
|
||
| setFieldCaption(X,s) | setLabel | `args:{label:s}` |
|
||
| setFieldRequired(X,b) | setRequired | `args:{required:b}` |
|
||
| setFieldRequiredError(X,msg) | setRequired | `args:{required:true, errorMessage:msg}` |
|
||
| setFieldFilter / setFilterMap / setFieldDataFilter | setFilter | `args:{filter:map}` |
|
||
| clearFieldData(X) | setOptions | `args:{options:[]}` |
|
||
| addFieldOption(X,v,d) | addOption | `args:{value:v, label:d}` |
|
||
| setFieldNullSelection(X,v) | setNullSelection | `args:{value:v}` |
|
||
| removeFieldItem(X,v) | removeOption | `args:{value:v}` |
|
||
| addFieldButton(X,文案,cb) | addButton | `args:{label:文案}` |
|
||
| addSubTableButton(L,SEL,i) | addSubTableButton | `args:{target:SEL, index:i}` |
|
||
| setSubTable{Add/Delete/Modify/Detail}ButtonVisible | setSubTableButtonVisible | `args:{button:..., visible:b}` |
|
||
| focusField(X) | focus | `{componentId:X}` |
|
||
| setFieldWidth / setFieldHeight | setStyle | `args:{width/height:...}` |
|
||
| reloadField(X) | reload | `{componentId:X}` |
|
||
| setGroupReadOnly(b) | static / nonstatic | `args:{scope:"group"}` |
|
||
| setGroupEnabled(b) | enabled / disabled | `args:{scope:"group"}` |
|
||
| showToast(msg) | toast | `args:{msg:...}` |
|
||
| enableButton(name,b) | enabled / disabled | `args:{kind:"button"}`(PoC 既有动词,保持兼容) |
|
||
| bindField(X,v) | setValue | `args:{value:v, bind:true}`(迁移手册 §161 四个基础 facade 之一) |
|
||
|
||
> 合计:服务端语义 3 + UI 语义 29 = **32 个动词闭包注入**(31 改写目标动词 + bindField 基础辅助函数)。
|
||
|
||
### 2.3 代码产物
|
||
|
||
```
|
||
platform-metadata/src/main/java/com/eip4/platform/metadata/
|
||
├── script/ScriptFacade.java # 32 动词 facade(buildBindings 注入闭包 + FieldDataSourceHandle 兜底)
|
||
└── web/ScriptExecuteController.java # 脚本执行端点
|
||
POST /api/script/execute (改写后脚本直接执行,行数据走请求体)
|
||
POST /api/script/execute-template (按模板名从客户库取真实脚本执行,端到端)
|
||
platform-metadata/src/test/java/com/eip4/platform/metadata/script/
|
||
└── ScriptFacadeTest.java # 17 个单测方法,逐动词覆盖(详见三、)
|
||
```
|
||
|
||
---
|
||
|
||
## 三、验证证据
|
||
|
||
### 3.1 单测(17 方法,覆盖 32 个动词)
|
||
|
||
```
|
||
mvn -o -pl platform-metadata test -Dtest=ScriptFacadeTest
|
||
→ Tests run: 17, Failures: 0, Errors: 0, Skipped: 0 BUILD SUCCESS
|
||
```
|
||
|
||
- 每条测试都把真实 Groovy 片段经保真层 `ScriptingEnginesManager` 跑通(非纯 Java 直调),
|
||
是「换 facade 实现、脚本零改」的端到端单测。
|
||
- 服务端语义动词:断言返回行数据值且脚本可据此分支(getFieldValue/getFieldDisplay/getFieldDataSource)。
|
||
- UI 语义动词:断言 actionType/componentId/args 符合 amis 事件动作协议(show/hidden/enabled/disabled/
|
||
static/setValue/setFilter/setOptions/addOption/toast/addSubTableButton/setSubTableButtonVisible/…)。
|
||
- 含 1 个多动词组合端到端测试(addSubTableButton + setFieldReadOnly + getFieldValue 分支 + setFieldVisible)。
|
||
|
||
全量 metadata 测试套件 51 passed(含本次 17 + 既有 34),0 失败,无回归。
|
||
|
||
### 3.2 集成(本地 8086,local 启动口径,≥5 条真实 FULL_AUTO 改写脚本)
|
||
|
||
启动:`java -jar platform-app/target/platform-app-*.jar --server.port=8086`(连客户库
|
||
dbname=postgres¤tSchema=eip3,VIEW_TEMPLATE 真实模板可解析)。挑 **6 条** facade-only 真实
|
||
FULL_AUTO 改写脚本(覆盖不同动词组合)经 `/api/script/execute` 跑通,全部产出 amis 事件动作 JSON:
|
||
|
||
| 脚本(模板) | 动词组合 | 捕获指令(amis) |
|
||
|------------|---------|-----------------|
|
||
| 办公用品领用申请 #2 | addSubTableButton + bindField + getFieldValue | `{actionType:addSubTableButton, componentId:GOODSDETAIL, args:{target:SELECT,index:0}}` + `{actionType:setValue, componentId:OLD_STORE_ID, args:{value,bind:true}}` |
|
||
| 查看单位信息 #1 | group_setReadOnly | `{actionType:static, args:{scope:group}}` |
|
||
| 工程选择框 #1 | setFieldFilter(平衡括号) | `{actionType:setFilter, componentId:BUILDCOMPANY, args:{filter:{UNITTYPE:7}}}` |
|
||
| 总包合同登记 #1 | setReadOnly_field | `{actionType:static, componentId:PM_PROJECTID}` |
|
||
| 福利保险结算单 #1 | setVisible | `{actionType:hidden, componentId:BEGINDATE}` |
|
||
| 物资供应商调查 #1 | addFieldOption + clearFieldData + getContainerDataSource | 7 条:`{setOptions, ELIGIBILITY, options:[]}` + 6×`{addOption, ELIGIBILITY, args:{value,label}}` |
|
||
|
||
**全部 6 条 passed=true,且每条指令的 actionType ∈ amis 标准动作集,符合事件动作协议
|
||
(actionType/componentId/args)。证据留档 `output/integration_evidence.json`。**
|
||
|
||
端到端补充:`POST /api/script/execute-template?template=通知管理归档&state=待归档` 取客户库真实模板脚本,
|
||
经 facade 执行捕获 `{actionType:enabled, componentId:归档, args:{kind:button}}`,passed=true。
|
||
|
||
### 3.3 回归(PoC script-test 仍通过)
|
||
|
||
```
|
||
POST http://localhost:8086/api/poc/script-test?template=通知管理归档
|
||
→ passed: true
|
||
runs: {
|
||
"ISPLACE=待归档": [{actionType:setButtonState, button:归档, enabled:true}],
|
||
"ISPLACE=已归档": [{actionType:setButtonState, button:退档, enabled:true}]
|
||
}
|
||
```
|
||
|
||
PoC 通知管理归档脚本(enableButton 分支)在新 jar 上分支行为不变,回归通过。
|
||
ArchUnit 架构纪律单测(保真层禁止依赖现代层)复跑 1 passed。
|
||
|
||
集成结束已 kill 8086。
|
||
|
||
---
|
||
|
||
## 四、人工工作包规模与口径
|
||
|
||
- **人工作业单 115 份**(PARTIAL 30 + HARD 85),落盘 `output/manual_workpackage/`,每份一个 md,
|
||
HARD 在前、PARTIAL 在后,按 template_id 排序。
|
||
- 每份作业单包含(0.5 人日/条作业单形态):
|
||
1. 原文(S3 原始 Groovy);
|
||
2. 已改写部分(PARTIAL 附自动产出;HARD 标「整条不自动改写」);
|
||
3. 余留模式(PARTIAL 自动诊断 `.comboBox`/`.table`/`.getItemProperty`/`.parent` 等深层组件访问;
|
||
HARD 标硬 S3 类型);
|
||
4. 建议改法(每种余留模式给出 amis 侧映射建议);
|
||
5. 工时口径(0.5 人日/条上界;PARTIAL 多为「仅余几行」,实际远低于此)。
|
||
|
||
- **工时估算(沿用 C4 §5 口径)**:
|
||
- 上界(PARTIAL 也全人工计):`(1 − 81.2%) × 612 × 0.5 人日 ≈ 57 人日 ≈ 2.8 人月`。
|
||
- 盘点口径(仅 76–85 条硬 S3):≈ 0.5–1 人月。
|
||
- 真实落点偏向盘点口径(PARTIAL 多为大部分已自动、仅余几行深层组件访问)。
|
||
|
||
---
|
||
|
||
## 五、与转换器(P4-1)的衔接说明
|
||
|
||
改写后脚本如何挂回转换后的 amis 页面 schema:
|
||
|
||
### 5.1 衔接设计(本报告给出,实装可标记 P4 中段)
|
||
|
||
1. **改写后脚本回填模板**:P4-1 转换器(platform-converter `TemplateToAmisConverter`)从 VIEW_TEMPLATE
|
||
XML 取 `//script` 节点(必须 `getText()` 保留换行,见迁移手册 §5.3)。衔接点:转换器在生成 amis
|
||
页面时,对脚本节点改用本线产出的**改写后脚本**(`output/rewritten/<tid>/<seq>.FULL_AUTO.groovy`
|
||
去头注释后的正文),而非原始 S3 脚本。FULL_AUTO(497)直接替换;PARTIAL/HARD(115)走人工后回填。
|
||
|
||
2. **脚本挂点 → amis 事件动作**:转换后页面以 amis form/crud 渲染,字段联动脚本挂在表单
|
||
`onEvent`(如 `change`/`inited`)。脚本经 `/api/script/execute` 执行后返回 amis 事件动作指令数组,
|
||
前端(eip4-web,amis-fork)在对应事件回调里 `dispatchEvent` 重放这些指令——componentId 对齐转换后
|
||
schema 的字段 name(大写列名,与改写器的字段名一致,天然对齐)。
|
||
|
||
3. **服务端语义动词的数据闭环**:getFieldValue/getFieldDisplay 在服务端从 `item`(amis 表单当前数据)
|
||
求值,故执行端点需要前端把当前表单数据作为 `item` 传入(`/api/script/execute` 请求体已支持
|
||
`{script, item}`)。转换器侧只需在 amis 事件动作里配置「调用 /api/script/execute,传 ${&}(全量表单数据)」。
|
||
|
||
4. **componentId 对齐**:改写器输出的字段名 = 大写列名(如 `BUILDCOMPANY`/`ELIGIBILITY`),与转换器
|
||
生成的 amis 字段 `name` 同源(均来自实体属性 COLUMNNAME),componentId 直接对齐,无需映射表。
|
||
|
||
### 5.2 实装边界(标记 P4 中段)
|
||
|
||
- 本线已交付:改写后脚本库(落盘)+ facade 动词运行时(引擎侧落地)+ 执行端点(/api/script/execute)。
|
||
- 待 P4 中段实装(与 P4-1 转换器协同):转换器把改写后脚本回填进 amis schema 的 onEvent 配置 +
|
||
前端事件动作重放胶水(eip4-web 侧)。衔接接口(执行端点契约、componentId 对齐口径)本报告已固定。
|
||
|
||
### 5.3 P4-5 实装回写(2026-06-11,以实装为准)
|
||
|
||
> 上述 §5.1/§5.2 为衔接「设计」。P4-5 已实装为可运行链路(onEvent 回填 + 执行端点指令重放 +
|
||
> componentId 大写列名对齐 + item 数据闭环),端到端 playwright 实测 2 真实模板通过。
|
||
> **有三处与设计出入,以下以实装为准**(详见 `tools/s3_rewriter/P4脚本挂回实测报告.md` §一、手册 §8.5/§8.6):
|
||
|
||
1. **执行端点契约**:§5.2 写「衔接接口 `/api/script/execute`(前端直传 `{script,item}`)」;实装改为
|
||
`/api/script/execute-template` 接受 `{templateId, seq, item}`(RequestBody),后端 `RewrittenScriptStore`
|
||
按 `(templateId, seq)` 从**改写产物** `output/rewritten/<tid>/<seq>.FULL_AUTO.groovy`(去头注释)取脚本执行——
|
||
挂回的是改写后脚本而非库内原始 S3,且免前端直传脚本文本的注入面。原「按模板名取库内 XML 脚本」端点
|
||
路径区隔为 `/api/script/execute-template-by-name`(保留 P4-2 §3.2 兼容)。
|
||
|
||
2. **指令重放机制**:§5.2 写「前端 `dispatchEvent` 重放」;实装为前端注册自定义 amis 动作
|
||
`replayScriptCommands`,对每条翻译后指令调 amis-core `runActions(action, renderer, event)`。原因:
|
||
amis 6.13 的 show/hidden/setValue/static/reload **不是顶层注册动作**,是组件级动作(动作带 componentId
|
||
时由 amis 路由到组件实例 doAction);toast 是少数顶层动作(手册 §8.5)。
|
||
|
||
3. **onEvent 回填实现**:转换器 `TemplateToAmisConverter.attachScriptOnEvent(schema, templateId, fullAutoSeqs)`
|
||
在页面 body(form/crud)挂 `inited`+`change` 两类 onEvent;每段脚本动作链 = ajax 调执行端点
|
||
(传 `templateId/seq` + `item:${&}` 全量表单数据)→ replayScriptCommands 重放返回的 commands 数组。
|
||
|
||
> §5.3 服务端语义动词数据闭环(getFieldValue 从 item 求值)、§5.4 componentId 大写列名对齐:**与设计完全一致,
|
||
> 实测通过**(office-collar 用例 `bindField("OLD_STORE_ID", getFieldValue("STORE_ID"))` 服务端求值 + OLD_STORE_ID
|
||
> componentId 直对齐,前端回填生效)。
|
||
|
||
---
|
||
|
||
## 六、坑列表(新坑,已同步迁移手册)
|
||
|
||
1. **spring-boot 离线打包不刷新上游模块 jar**:改了 platform-metadata 后单独 `mvn -pl platform-app package`
|
||
仍打进旧版 metadata jar(BOOT-INF/lib 时间戳停在改前),导致新动词运行时 `No signature of method`。
|
||
对策:改上游模块后必须用反应堆 `mvn -pl platform-app -am package` 连带重建上游,或确认
|
||
BOOT-INF/lib 内 jar 时间戳/字节码已更新再起服务。
|
||
2. **改写后 FULL_AUTO 脚本仍可能引用平台函数库**:FULL_AUTO 仅指「无残留 S3 UI 动词」,但脚本可能
|
||
并存 `GetServicesFunction`/`GetDefaultValueFunction`/`Console`/`CustomSearchConditional` 等平台
|
||
S2 函数库/领域类调用——这些需 WS3 回迁的 Java 函数库桩(迁移手册 §第三章),不在 31 动词 facade 覆盖内。
|
||
集成挑样须按「仅 facade 动词」筛选,端到端全量跑通需先补齐函数库桩。
|
||
3. **bindField 是基础 facade 辅助函数,须随 facade 动词表一并注入**:改写器不改 bindField(它本就是 S2
|
||
形态),但运行时若只注入 31 改写目标动词会漏掉 bindField,导致含 bindField 的 FULL_AUTO 脚本报
|
||
未定义方法。已在 facade 补 bindField(迁移手册 §161 四个基础 facade 之一)。
|