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>
This commit is contained in:
172
tools/s3_rewriter/P4脚本挂回实测报告.md
Normal file
172
tools/s3_rewriter/P4脚本挂回实测报告.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# 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。
|
||||
@@ -239,6 +239,31 @@ ArchUnit 架构纪律单测(保真层禁止依赖现代层)复跑 1 passed
|
||||
- 待 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 直对齐,前端回填生效)。
|
||||
|
||||
---
|
||||
|
||||
## 六、坑列表(新坑,已同步迁移手册)
|
||||
|
||||
Reference in New Issue
Block a user