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

15 KiB
Raw Permalink Blame History

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);
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。