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>
This commit is contained in:
2026-06-11 16:10:22 +08:00
parent 3a13c50a01
commit aefb0e2eb9
1552 changed files with 41290 additions and 2 deletions

View File

@@ -0,0 +1,256 @@
# 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 之一)。