Files
eip4-platform/tools/s3_rewriter/P4脚本迁移执行报告.md
zhengwr aefb0e2eb9 P4-2 脚本迁移线:全量改写产出 + facade 动词表运行时实现
任务1 全量改写执行:
- run_rewrite.py 对客户库缓存 1,427 条逐条改写,按 template_id+脚本序号落盘
  output/rewritten/(497 FULL_AUTO + 30 PARTIAL + 85 HARD + 815 NO_S3)
- 人工作业单 115 份(PARTIAL 30 + HARD 85),每份附原文/已改部分/余留模式/建议改法/工时口径
- 自动化率 81.2% 复现 C4 实测,0 误改

任务2 facade 动词表运行时:
- ScriptFacade 把 31 改写目标动词 + bindField 作为 Groovy 闭包注入 Bindings
  (PoC enableButton 模式扩展);服务端语义动词直接求值,UI 语义动词捕获为
  amis 事件动作指令 JSON(actionType/componentId/args)
- 保真层纪律:全在 com.eip4 现代层,com.dsasp 源码零改,ArchUnit 复跑通过
- ScriptExecuteController 提供 /api/script/execute 与 /api/script/execute-template

验证:
- 单测 17 方法逐动词覆盖,均经真实 Groovy 过保真层引擎,BUILD SUCCESS
- 集成 6 条真实 FULL_AUTO 改写脚本经 8086 执行,amis 指令协议合规
- 回归 PoC script-test 通过,ArchUnit 架构纪律通过

报告 tools/s3_rewriter/P4脚本迁移执行报告.md;新坑入 docs/迁移手册.md 5.39/9.3

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 16:10:22 +08:00

15 KiB
Raw Blame History

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 对齐口径)本报告已固定。

六、坑列表(新坑,已同步迁移手册)

  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 之一)。