转换器侧(事件段):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>
18 KiB
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 人日/条作业单形态):
- 原文(S3 原始 Groovy);
- 已改写部分(PARTIAL 附自动产出;HARD 标「整条不自动改写」);
- 余留模式(PARTIAL 自动诊断
.comboBox/.table/.getItemProperty/.parent等深层组件访问; HARD 标硬 S3 类型); - 建议改法(每种余留模式给出 amis 侧映射建议);
- 工时口径(0.5 人日/条上界;PARTIAL 多为「仅余几行」,实际远低于此)。
-
工时估算(沿用 C4 §5 口径):
- 上界(PARTIAL 也全人工计):
(1 − 81.2%) × 612 × 0.5 人日 ≈ 57 人日 ≈ 2.8 人月。 - 盘点口径(仅 76–85 条硬 S3):≈ 0.5–1 人月。
- 真实落点偏向盘点口径(PARTIAL 多为大部分已自动、仅余几行深层组件访问)。
- 上界(PARTIAL 也全人工计):
五、与转换器(P4-1)的衔接说明
改写后脚本如何挂回转换后的 amis 页面 schema:
5.1 衔接设计(本报告给出,实装可标记 P4 中段)
-
改写后脚本回填模板: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)走人工后回填。 -
脚本挂点 → amis 事件动作:转换后页面以 amis form/crud 渲染,字段联动脚本挂在表单
onEvent(如change/inited)。脚本经/api/script/execute执行后返回 amis 事件动作指令数组, 前端(eip4-web,amis-fork)在对应事件回调里dispatchEvent重放这些指令——componentId 对齐转换后 schema 的字段 name(大写列名,与改写器的字段名一致,天然对齐)。 -
服务端语义动词的数据闭环:getFieldValue/getFieldDisplay 在服务端从
item(amis 表单当前数据) 求值,故执行端点需要前端把当前表单数据作为item传入(/api/script/execute请求体已支持{script, item})。转换器侧只需在 amis 事件动作里配置「调用 /api/script/execute,传 ${&}(全量表单数据)」。 -
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):
-
执行端点契约:§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 兼容)。 -
指令重放机制:§5.2 写「前端
dispatchEvent重放」;实装为前端注册自定义 amis 动作replayScriptCommands,对每条翻译后指令调 amis-corerunActions(action, renderer, event)。原因: amis 6.13 的 show/hidden/setValue/static/reload 不是顶层注册动作,是组件级动作(动作带 componentId 时由 amis 路由到组件实例 doAction);toast 是少数顶层动作(手册 §8.5)。 -
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 直对齐,前端回填生效)。
六、坑列表(新坑,已同步迁移手册)
- 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 时间戳/字节码已更新再起服务。 - 改写后 FULL_AUTO 脚本仍可能引用平台函数库:FULL_AUTO 仅指「无残留 S3 UI 动词」,但脚本可能
并存
GetServicesFunction/GetDefaultValueFunction/Console/CustomSearchConditional等平台 S2 函数库/领域类调用——这些需 WS3 回迁的 Java 函数库桩(迁移手册 §第三章),不在 31 动词 facade 覆盖内。 集成挑样须按「仅 facade 动词」筛选,端到端全量跑通需先补齐函数库桩。 - bindField 是基础 facade 辅助函数,须随 facade 动词表一并注入:改写器不改 bindField(它本就是 S2 形态),但运行时若只注入 31 改写目标动词会漏掉 bindField,导致含 bindField 的 FULL_AUTO 脚本报 未定义方法。已在 facade 补 bindField(迁移手册 §161 四个基础 facade 之一)。