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

173 lines
15 KiB
Markdown
Raw Permalink 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 脚本挂回实测报告(改写后脚本 → amis onEvent 重放链路)
> 任务编号:P4-5
> 日期:2026-06-11
> 责任:实装「改写后脚本挂回页面 schema」链路(onEvent 回填 + 执行端点指令重放 + componentId 大写列名对齐 + item 数据闭环)
> 范围:转换器侧 onEvent 生成段(platform-converter)+ 执行端点(platform-metadata ScriptExecuteController)+ 前端重放胶水(eip4-web AmisRenderer)+ 端到端 playwright 实测
> 诚实边界:链路三段均为真实代码 + 真实改写产物 + 真实保真层引擎执行(非桩)。端到端用前端 mock schema(onEvent 形态 = 转换器 `attachScriptOnEvent` 产出,已单测固定)承接,脚本与指令来自后端真实改写产物(`output/rewritten/`)经真实 facade 引擎执行。口径见 §四。
---
## 一、链路实装结论(与报告第五章设计的出入)
第五章给出衔接「设计」,本任务实装为可运行链路,**有三处与第五章设计的出入,以实装为准并已回写第五章 / 手册 §8.5、§8.6**:
| 衔接点 | 第五章设计 | 实装(以此为准) | 出入说明 |
|--------|-----------|-----------------|---------|
| **执行端点契约** | §5.2 衔接接口写为 `/api/script/execute`(前端直传 `{script, item}`);§3.2 端到端用 `/api/script/execute-template?template=<名>`(按名取库内 XML 原始脚本) | `/api/script/execute-template` 改为 `{templateId, seq, item}`(RequestBody),后端按 `(tid,seq)` 从**改写产物**取脚本正文执行 | 挂回的是**改写后脚本**(`output/rewritten/<tid>/<seq>.FULL_AUTO.groovy` 去头注释),非库内原始 S3 脚本;前端直传脚本文本有注入面,改为传 `(templateId,seq)` 取数键。原「按名取库内脚本」端点路径区隔为 `/api/script/execute-template-by-name`(保留 P4-2 兼容)。详见手册 §8.6 |
| **指令重放机制** | §5.2「前端在对应事件回调里 `dispatchEvent` 重放这些指令」 | 前端注册自定义 amis 动作 `replayScriptCommands`,对每条翻译后指令调 amis-core `runActions(action, renderer, event)`,带 `componentId` 者走组件级路由 | amis 6.13 的 show/hidden/setValue/static/reload **不是顶层注册动作**,是组件级动作(动作带 componentId 时由 amis 路由到组件实例 doAction);`toast` 是少数顶层动作。详见手册 §8.5 |
| **改写产物关联** | §5.1「FULL_AUTO 直接替换;改写后脚本回填模板」 | 转换器 `attachScriptOnEvent(schema, templateId, fullAutoSeqs)` 按 `templateId` 关联,FULL_AUTO 脚本序号取自 `full_auto_index.json`,挂上 `inited`+`change` 两类 onEvent | 与设计一致,补充实现细节:每段脚本生成 `inited`(页面渲染时跑一遍)+`change`(字段变更重跑)双触发;动作链 = ajax 调执行端点 → replayScriptCommands 重放 |
**§5.3 服务端语义动词数据闭环、§5.4 componentId 大写列名对齐:与设计完全一致,实测验证通过**(见 §三端到端证据,office-collar 用例的 `getFieldValue("STORE_ID")` 从 item 求值闭环 + OLD_STORE_ID componentId 直对齐)。
---
## 二、实装清单(三段)
### 2.1 转换器侧 onEvent 生成段(platform-converter,事件段归本任务)
```
platform-converter/src/main/java/com/eip4/platform/converter/
└── TemplateToAmisConverter.java # 新增 attachScriptOnEvent + scriptActionChain(84 行纯追加,不动 source/picker 段)
attachScriptOnEvent(pageSchema, templateId, fullAutoSeqs)
→ 在页面 body(form/crud)挂 onEvent: {inited, change}
→ 每段脚本动作链:
{ actionType:"ajax", api:{method:post, url:/api/script/execute-template,
data:{templateId, seq, item:"${&}"}}, outputVar:"scriptResultN" }
{ actionType:"replayScriptCommands",
args:{commands:"${event.data.scriptResultN.commands}"} }
```
- `item:"${&}"` = amis 当前全量数据域,作脚本 `item` 上下文(服务端语义动词从此求值)。
- componentId 用改写器输出大写列名,与 amis 字段 name 同源天然对齐(无映射表)。
### 2.2 执行端点(platform-metadata,ScriptExecuteController 归本任务)
```
platform-metadata/src/main/java/com/eip4/platform/metadata/
├── script/RewrittenScriptStore.java # 新增:按 (templateId, seq) 从改写产物取脚本正文(去头注释块)
│ load(templateId, seq) → output/rewritten/<tid>/<seq>.*.groovy 去头注释
│ 路径根 eip4.script.rewritten-root(默认 tools/s3_rewriter/output/rewritten)
└── web/ScriptExecuteController.java # 扩展:
POST /api/script/execute-template {templateId, seq, item} → 取改写脚本经 facade 执行 → 指令数组(P4-5 挂回主链路)
POST /api/script/execute-template-by-name 按模板名取库内 XML 原始脚本(原 P4-2 端点,路径区隔保留兼容)
POST /api/script/execute 直传 {script, item}(P4-2 既有,保留)
```
### 2.3 前端重放胶水(eip4-web,AmisRenderer embed 范式)
```
eip4-web/src/
├── amis/scriptCommands.ts # 指令 → amis 动作翻译(29 UI 动词逐分支:show/hidden/static/
│ setValue/setFilter/setOptions/addOption/addSubTableButton/
│ focus/reload/toast/... → amis ActionSchema)
├── amis/registerReplayAction.ts # 注册自定义动作 replayScriptCommands(幂等):
│ run 内 translateCommands → 逐条 runActions 重放
└── components/AmisRenderer.tsx # embed 前 registerReplayAction(amisRequire('amis'))(静默降级)
```
---
## 三、端到端证据(≥2 真实模板,playwright,后端 8086 + 前端 dev)
**起服务**:后端 `java -jar platform-app-0.1.0-SNAPSHOT.jar --server.port=8086`(连客户库 5435,default profile,jar 经反应堆 `mvn -pl platform-app -am package` 重建含新端点,规避手册坑#1);前端 `VITE_BACKEND_TARGET=http://localhost:8086 vite --port 5174`(/api 反代 8086)。
挑 **2 个真实 FULL_AUTO facade-only 模板**(取自 `full_auto_index.json` ∩ 296 facade-only 集,且模板在 1,489 转换产物中):
### 用例 1:inited 重放 —— 福利保险结算单(隐藏字段)
| 项 | 内容 |
|----|------|
| 模板 | 福利保险结算单 `0d9eac07-1978-4abb-ab1f-f1561f9bd902` seq=1 |
| 改写后脚本 | `setFieldVisible("BEGINDATE", false);`(FULL_AUTO,facade-only) |
| 后端实测 | `POST /api/script/execute-template {templateId, seq:1, item:{}}` → `passed:true, commands:[{actionType:"hidden", componentId:"BEGINDATE"}]` |
| 前端重放 | 页面渲染 → `inited` 触发 → ajax 取指令 → replayScriptCommands 重放 hidden → **BEGINDATE(起始日期)字段从 DOM 消失** |
| playwright 断言 | `起始年` 可见 + `起始日期` 隐藏(`toBeHidden`),passed |
| 截图 | `eip4-web/e2e/__screenshots__/welfare-hidden.png`(仅渲染出「起始年」,起始日期已被脚本隐藏) |
### 用例 2:change 重放 + 服务端 getFieldValue 闭环 —— 办公用品领用申请(回填字段值)
| 项 | 内容 |
|----|------|
| 模板 | 办公用品领用申请(按库领用)`021e3ba7-e03a-412a-9f0e-c20ef440a885` seq=2 |
| 改写后脚本 | `addSubTableButton("GOODSDETAIL", "SELECT", 0);`<br>`bindField("OLD_STORE_ID", getFieldValue("STORE_ID"));`(FULL_AUTO,facade-only) |
| 后端实测 | `{templateId, seq:2, item:{STORE_ID:"WH-7788"}}` → `passed:true, commands:[{addSubTableButton,GOODSDETAIL}, {setValue, OLD_STORE_ID, args:{value:"WH-7788", bind:true}}]`(**getFieldValue 服务端从 item 求值闭环**) |
| 前端重放 | 改 STORE_ID=WH-7788 → `change` 触发 → ajax 传 item(含 STORE_ID)→ 脚本服务端求值 → 重放 setValue → **OLD_STORE_ID 自动回填为 WH-7788** |
| playwright 断言 | `input[name=OLD_STORE_ID]` 值 == `WH-7788`(`toHaveValue`),passed |
| 截图 | `eip4-web/e2e/__screenshots__/office-collar-setvalue.png`(仓库=WH-7788,原仓库(脚本回填)=WH-7788) |
**playwright 结果**:`2 passed`(chromium)。两用例覆盖 inited/change 双触发、UI 语义动词(hidden/setValue/addSubTableButton)重放、服务端语义动词(getFieldValue)数据闭环、componentId 大写列名对齐——链路四要素全验。
---
## 四、测试与口径
### 4.1 单测/组件测试(≥6,实交付 24)
| 仓 | 测试文件 | 数 | 覆盖 |
|----|---------|----|------|
| platform-metadata | `RewrittenScriptStoreTest` | 4 | 头注释剥离(不误删正文中部注释)、(tid,seq) 定位、缺目录/缺序号返回 null |
| platform-metadata | `ScriptExecuteControllerTest` | 4 | 改写脚本取出执行产指令、服务端 getFieldValue 从 item 闭环、缺 templateId/未找到 passed=false、直执行兼容 |
| platform-converter | `TemplateToAmisConverterTest`(新增 4 例) | +4 | onEvent inited+change 挂上、动作链调执行端点传 templateId/seq/item:${&}、多段累加、空入参不挂 |
| eip4-web | `scriptCommands.test.ts` | 12 | 29 动词翻译核心分支(show/hidden/static/setValue/setOptions/addOption/setFilter/addSubTableButton/toast/reload/focus/未知跳过/数组过滤) |
| eip4-web | `registerReplayAction.test.ts` | 4 | 缺 registerAction 降级、幂等注册、run 翻译后逐条 runActions、空指令不调 |
| **小计** | | **24** | (后端 8 新增 + 转换器 4 新增 + 前端 16) |
### 4.2 两仓 build/test 全绿
| 仓 | 命令 | 结果 |
|----|------|------|
| eip4-platform | `mvn -o -pl platform-converter test` | Tests run: 28, Failures: 0, Errors: 0 ✅ |
| eip4-platform | `mvn -o -pl platform-metadata test` | Tests run: 77, Failures: 0, Errors: 0 ✅(含新增 8) |
| eip4-platform | `mvn -o -pl platform-app test -Dtest=ArchitectureRulesTest` | Tests run: 1, Failures: 0(**ArchUnit 保真层禁依赖现代层 复跑通过**)✅ |
| eip4-web | `npm run test`(vitest) | Test Files 2 passed, Tests 16 passed ✅ |
| eip4-web | `npm run build`(tsc -b && vite build) | 97 modules transformed, built ✅ |
### 4.3 端到端口径(诚实声明)
- **schema 来源**:前端 mock 源(`public/schemas/{welfare-settlement,office-collar}.json`),onEvent 形态 = 转换器 `attachScriptOnEvent` 产出(已单测固定,逐字段对齐)。原因:后端 schema 下发端点 `/api/page/schema/{id}`(`schema.ts` 契约)本期为 mock 源,未接后端转换器(属 picker/schema 代理范围,本任务不动);故 e2e 用 mock schema 承接 onEvent,**onEvent 真实性由转换器单测保证**。
- **脚本与指令**:来自后端真实改写产物 `output/rewritten/<tid>/<seq>.FULL_AUTO.groovy` 经真实保真层 facade 引擎执行(非桩,`/api/script/execute-template` 实测产指令)。
- **造数口径**:测试页字段(BEGINYEAR/BEGINDATE、STORE_ID/OLD_STORE_ID)为最小造数表单,字段 name = 脚本 componentId(大写列名)对齐;不依赖业务实体真实数据,纯验证「指令重放生效」(显隐/赋值)。本地库无这些业务实体数据,故用最小造数 form 承接,**这是验证「脚本挂回重放」机制的充分口径**(机制与具体实体数据正交)。
- **登录态**:种入任意非空令牌过 RequireAuth(schema 走 mock 免后端鉴权;`/api/script/execute-template` 走后端 POC 默认链不拦截)。
---
## 五、坑列表(新坑,已同步迁移手册 §8.5 / §8.6)
1. **amis show/hidden/setValue/static 不是顶层注册动作,须经组件级路由**(手册 §8.5):amis 6.13 `registerAction` 顶层动作仅 ajax/dialog/toast/... 30 个,无 show/hidden/setValue/static/reload;这些是组件级动作,动作带 componentId 时由 amis 路由到组件 doAction。对策:`replayScriptCommands` 里对每条指令调 `runActions(action, renderer, event)`,带 componentId 自动组件级路由,toast 走顶层。
2. **改写后脚本挂回走「改写产物按 templateId+seq 取数」而非「库内 XML 原始脚本」**(手册 §8.6):第五章衔接接口写法(前端直传脚本 / 按名取库内原始脚本)均非正解;挂回的是改写后脚本,取数键 `(templateId, seq)` 与落盘命名一致。对策:`/api/script/execute-template` 改 `{templateId,seq,item}` + RewrittenScriptStore 取数;原按名端点改 `-by-name` 保留兼容。
3. **setOptions/addOption 类「改组件 options」动词在原生 amis 无对应组件动作**:select 选项联动(clearFieldData + addFieldOption×N)翻译为 setValue/addOption 透传,但 amis 原生组件 doAction 不直接消费逐条 addOption;select 选项联动的稳妥落点是后端 source 或整体 setValue 替换 options(非逐条 addOption),落 P4 中段后续。本任务 e2e 选 hidden/setValue 这类原生组件动作可路由的动词验证机制,setOptions 类已在后端指令产出层验证(指令 JSON 正确),前端原生消费待 P4 中段补 select options 重放适配。
4. **改写产物随应用可达性**:执行端点按 `eip4.script.rewritten-root`(默认相对工作目录 `tools/s3_rewriter/output/rewritten`)读改写脚本;起服务工作目录须为工程根(否则取不到脚本,端点返回「改写后脚本未找到」)。部署须把改写产物随应用打包/挂载并配置该路径。
---
## 六、提交(两仓各自,只 add 本任务文件)
### eip4-platform(本任务文件,与 picker/schema/flow-gateway 代理文件隔离)
```
platform-converter/src/main/java/.../TemplateToAmisConverter.java # 仅 attachScriptOnEvent 段(84 行纯追加)
platform-converter/src/test/java/.../TemplateToAmisConverterTest.java # 仅新增 4 onEvent 例
platform-metadata/src/main/java/.../web/ScriptExecuteController.java
platform-metadata/src/main/java/.../script/RewrittenScriptStore.java
platform-metadata/src/test/java/.../web/ScriptExecuteControllerTest.java
platform-metadata/src/test/java/.../script/RewrittenScriptStoreTest.java
docs/迁移手册.md # §8.5 / §8.6 新坑
tools/s3_rewriter/P4脚本挂回实测报告.md # 本报告
```
**勿 add**:platform-flow-gateway/*、PickerController、PageSchemaController、schema/*、bootstrap/、docs/sql/(另两代理范围)。
### eip4-web
```
src/amis/scriptCommands.ts / scriptCommands.test.ts
src/amis/registerReplayAction.ts / registerReplayAction.test.ts
src/components/AmisRenderer.tsx # 注册 replayScriptCommands
src/api/schema.ts # mock map 加 2 个 e2e schema
public/schemas/{welfare-settlement,office-collar}.json
e2e/script-replay.spec.ts + e2e/__screenshots__/*.png
playwright.config.ts / vitest.config.ts
tsconfig.app.json(排除 *.test)/ .gitignore(忽略 test-results)
package.json / package-lock.json(devDeps: vitest/jsdom/testing-library/playwright + test script)
```
集成结束已 kill 8086 + dev 5174。