Files
eip4-platform/tools/s3_rewriter/P4脚本迁移执行报告.md
zhengwr 082b439179 P4-5: 实装改写后脚本挂回 amis onEvent 重放链路
转换器侧(事件段):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>
2026-06-11 16:55:43 +08:00

282 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.
# P4 脚本迁移执行报告(脚本迁移线)
> 任务编号:P4-2
> 日期:2026-06-11
> 责任:S3 改写产出全量落盘 + facade 动词表运行时实现 + 集成/回归验证
> 诚实边界:全量改写以客户库落盘缓存 `scripts_cache.json`(dbname=postgres&currentSchema=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&currentSchema=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 之一)。