Files
eip4-platform/docs/plans/2026-06-14-onEvent脚本挂回修复-plan.md
zhengwr f806653108 docs(plans): 新闻管理垂直切片 + onEvent 脚本挂回 实施计划
记录本轮垂直切片(WS-A 菜单/WS-B onEvent按钮联动/WS-C 收藏树/WS-D 附件+发布人/
WS-E 验收+3小修)的根因、设计与分阶段任务,作为其余功能的修复模板。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 19:44:01 +08:00

20 KiB
Raw Blame History

onEvent 脚本挂回修复(按钮联动 / 表单只读联动)Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 让转换器把老模板的事件脚本(onselectedscript 行选中按钮联动、onloadscript 加载联动)正确挂回 amis onEvent,使「列表选中行→按 STATUS 点亮/置灰按钮」「表单加载→字段只读/显隐」这类联动在新系统真实生效。

Architecture: 当前 attachScriptOnEvent 只挂 full_auto_index.json 里的 FULL_AUTO 脚本,且把每段同时挂 inited+change 不区分事件类型/组件 → onselectedscript(多为 NO_S3 标签)被系统性丢弃。改法:在转换期从 view_template.xml 解析事件绑定属性(onselectedscript/onloadscript = 脚本 key)→ 由 <scripts> 文档序解析 key→seq → 按事件类型挂到正确的 amis 事件(onselected→crud selectedChange、onload→inited)与正确组件,并给工具栏按钮补 id 以便 enableButton 指令能定位。覆盖 NO_S3 与 FULL_AUTO 两类脚本。运行时 RewrittenScriptStore 已能按 (templateId,seq) 加载任意脚本,无需改。

Tech Stack: Java 21(JAVA_HOME=/opt/homebrew/opt/openjdk@21,mvn 默认 Java26 会崩 Groovy)、dom4j(XML 解析)、JUnit5、amis 6.13(前端 TS/Vitest)、PG15(localhost:5433/eip4dev,schema eip3)。


背景与根因(已证据级核实,2026-06-14)

  • 用户实测:新闻管理列表选中行按钮不按老逻辑点亮 + 查看页弹 2 个「ajax 动作执行失败,原因:未知」。
  • P0(已修,前置):application-dev.yml rewritten-root 写成相对 ../tools/...,标准 jar 从 cwd=eip4-platform 启动 → 解析到不存在的 eip3/tools/... → 改写脚本全找不到。已改为 tools/s3_rewriter/output/rewritten 并验证(execute-template passed:true、浏览器 0 errors)。本 plan 不含 P0,但实施需在 P0 已生效的环境上做。
  • P0+(本 plan 修):即使路径修好,挂的也是错脚本。新闻管理 ddb75614 原始 XML 两段:
    • <script key="e2265024…" name="按钮状态控制"> = seq=1, NO_S3:enableButton("发布",false)… 按 STATUS/ISSEND = onselectedscript(行选中按钮联动)。
    • <script key="b944976c…" name="查看时设置内容只读"> = seq=2, FULL_AUTO:setFieldViewOnly("NEWSCONTENT",true) = onload 类。
    • full_auto_index.json 对 ddb75614 只列 seq=2 → attachScriptOnEvent(schema, id, [2]) → 只挂了 seq=2,seq=1 按钮联动从不挂;且 seq=2 被同时挂到列表的 inited+change(列表无 NEWSCONTENT,空操作)。

三重缺口(本 plan 全部覆盖)

  1. 覆盖缺口:只挂 FULL_AUTO(full_auto_index.json),NO_S3 事件脚本被丢。
  2. 事件类型缺口:每段同时挂 inited+change,不区分 onselected→选中事件 / onload→inited。
  3. 组件/定位缺口:① 不区分挂到列表 crud(工具栏按钮)还是表单;② 工具栏按钮无 id,enableButton 的 disabled/enabled 指令(componentId=按钮名)定位不到;③ crud 行选中事件是 selectedChange 不是 change,且 item 应取选中行 ${selectedItems[0]} 而非 ${&}。

影响面(DB/盘上实测数字)

  • onselectedscript:930 个模板;onloadscript:422 个;onclickscript/onchangescript:0(只需处理两类)。
  • 盘上改写脚本:NO_S3 815 + FULL_AUTO 507;full_auto_index 仅 507 条(全 FULL_AUTO)。
  • NO_S3 脚本含 enableButton 的:259 个文件 = 当前按钮联动失效的真实规模下限。

已确认可复用的下游(无需改或仅小改)

  • ScriptFacade.enableButton(name,enabled)(platform-metadata/.../ScriptFacade.java:311)→ emit("enabled"/"disabled", name, kind:button),已就绪。
  • 前端 scriptCommands.ts translateCommands:enabled/disabled/show/hidden/static/setValue… 均已映射到 amis 内置动作(按 componentId)。
  • 前端 registerReplayAction.ts:replayScriptCommands 自定义动作已注册,逐条 runActions。
  • 运行时 RewrittenScriptStore.load(templateId, seq)(platform-metadata)可加载任意 seq(含 NO_S3)。

关键文件清单(精确路径)

  • Modify: platform-converter/src/main/java/com/eip4/platform/converter/TemplateToAmisConverter.java
    • attachScriptOnEvent:约 :1644-1672(重写)
    • scriptActionChain:约 :1675-1698(增 item 表达式与事件参数)
    • buildToolbar:约 :421-470(按钮补 id)
    • convertCrud:约 :121-162(产出绑定信息或在此挂 onEvent)
  • Modify: platform-converter/src/main/java/com/eip4/platform/converter/BatchConvertCli.java::110-148(index 加载)、:185(attach 调用)
  • Test: platform-converter/src/test/java/com/eip4/platform/converter/TemplateToAmisConverterTest.java(:897-955 现有 attach 用例需改)
  • Test: platform-converter/src/test/java/com/eip4/platform/converter/BatchConvertCliTest.java(若有,否则新建)
  • 可能 Modify: eip4-web/src/amis/scriptCommands.ts / registerReplayAction.ts(仅当 Spike 0 发现 amis 启停/选中事件需适配)
  • 重转工具:tools/s3_rewriter/output(rewriter 产物,保 onEvent)、SchemaImportCli(入库)

Phase 0:Spike(先消除 amis 行为未知项,再写实现)

这些是写死实现前必须用真实 amis 验证的点。每个 spike 用浏览器(8093 live + 5173)或最小 schema 验证,记录结论到本文件「Spike 结论」节,再进 Phase 1。

Task 0.1:验证 amis crud 行选中事件名与 item 载荷

目的: 确认老 onselectedscript 该挂到 crud 的哪个事件、item 怎么取选中行。

Step 1: 在 eip4-web 临时给一个 crud 页 onEvent 加 selectedChange(再试 itemClick),动作里 toast 出 ${event.data.selectedItems} / ${event.data.item}。 Step 2: 浏览器(5173 登录 admin/111111)选中一行,看哪个事件触发、选中行数据在 selectedItems[0] 还是 item。 Step 3: 记录:①行选中事件名(预期 selectedChange)②选中行表达式(预期 ${selectedItems[0]})。 预期产出: 事件名 + item 表达式两个常量,写入「Spike 结论」。

Task 0.2:验证 disabled/enabled 动作能否按 id 定位 headerToolbar 按钮

目的: 工具栏按钮补什么 id、amis 内置 disabled/enabled 是否对 headerToolbar 按钮生效。

Step 1: 临时给某 crud 的 headerToolbar 一个按钮加 "id": "BTN_FABU",另一处放一个 disabled 动作(componentId=BTN_FABU)触发。 Step 2: 浏览器验证按钮是否真的置灰/点亮。 Step 3: 记录:①按钮 id 命名规则(建议 btn-<servicename> 或按名规范化,避免中文 id 兼容问题)②disabled/enabled 是否生效;若不生效,改用 static/可见性或 visibleOn 的替代方案并记录。 预期产出: 按钮 id 规则 + 启停可行性结论。

Task 0.3:确认 enableButton 指令的 componentId 与按钮 id 对齐方式

目的: facade 的 enableButton(name,…) 用的是按钮中文名(如「发布」)作 componentId;buildToolbar 现按 name|id|type 取 label。需让指令 componentId 与按钮 amis id 对得上。

Step 1: 读改写脚本里 enableButton("发布",…) 的实参(中文名)与原始 XML 按钮 name/id 的对应关系(抽 ddb75614 + 2 个 enableButton 模板)。 Step 2: 决策:是「按钮 id 用中文名」还是「facade emit 时做名→id 规范化」。优先按钮 id = 原始按钮 name(与 enableButton 实参同源),必要时 ScriptFacade.enableButton 同步规范化。 预期产出: componentId↔按钮 id 对齐方案(一句话决策)。


Phase 1:转换期解析事件绑定(key→seq→eventType)

Task 1.1:解析 <scripts> 得 scriptKey→seq(1-based 文档序)

Files:

  • Modify: platform-converter/.../TemplateToAmisConverter.java(新增私有方法 scriptKeyToSeq)
  • Test: platform-converter/.../TemplateToAmisConverterTest.java

Step 1:写失败测试

@Test
void scriptKeyToSeq_按scripts文档序1based() {
    String xml = "<crud><scripts>"
        + "<script key=\"K1\" name=\"按钮状态控制\">a</script>"
        + "<script key=\"K2\" name=\"查看只读\">b</script>"
        + "</scripts></crud>";
    Element root = DocumentHelper.parseText(xml).getRootElement();
    Map<String,Integer> m = converter.scriptKeyToSeq(root);
    assertThat(m).containsEntry("K1", 1).containsEntry("K2", 2);
}

Step 2: 运行确认失败(方法不存在)。mvn -o -pl platform-converter test -Dtest=TemplateToAmisConverterTest#scriptKeyToSeq_按scripts文档序1based Step 3:最小实现

/** 解析 <scripts><script key=...> 的 key→seq(1-based 文档序,与 rewriter 落盘 seq 对齐)。 */
Map<String, Integer> scriptKeyToSeq(Element root) {
    Map<String, Integer> map = new LinkedHashMap<>();
    Element scripts = root.element("scripts");
    if (scripts == null) return map;
    int seq = 0;
    for (Element s : scripts.elements("script")) {
        seq++;
        String key = s.attributeValue("key");
        if (key != null && !key.isBlank()) map.put(key, seq);
    }
    return map;
}

Step 4: 运行通过。 Step 5: commit feat(converter): 解析 scripts key→seq 文档序

Task 1.2:从 XML 提取事件绑定 (eventType, scriptKey)

说明: onselectedscript/onloadscript 作为元素属性出现(930/422 模板)。需扫描根元素树上所有带这两个属性的元素,产出绑定列表。先用单测固化属性名与产出结构。

Step 1:写失败测试

@Test
void extractEventBindings_收集onselected与onload() {
    String xml = "<crud onselectedscript=\"K1\">"
        + "<scripts><script key=\"K1\">a</script><script key=\"K2\">b</script></scripts>"
        + "<form onloadscript=\"K2\"/></crud>";
    Element root = DocumentHelper.parseText(xml).getRootElement();
    List<TemplateToAmisConverter.EventBinding> bs = converter.extractEventBindings(root);
    assertThat(bs).extracting(b -> b.eventType + ":" + b.scriptKey)
        .containsExactlyInAnyOrder("onselectedscript:K1", "onloadscript:K2");
}

Step 2: 运行确认失败。 Step 3:最小实现(新增内部记录类 + 递归扫描)

/** 一条事件绑定:原始事件属性名 + 引用的脚本 key(后续解析 seq)。 */
public static final class EventBinding {
    public final String eventType; // onselectedscript | onloadscript
    public final String scriptKey;
    public EventBinding(String eventType, String scriptKey) { this.eventType = eventType; this.scriptKey = scriptKey; }
}
private static final List<String> EVENT_ATTRS = List.of("onselectedscript", "onloadscript");
List<EventBinding> extractEventBindings(Element root) {
    List<EventBinding> out = new ArrayList<>();
    collectBindings(root, out);
    return out;
}
private void collectBindings(Element el, List<EventBinding> out) {
    for (String attr : EVENT_ATTRS) {
        String v = el.attributeValue(attr);
        if (v != null && !v.isBlank()) out.add(new EventBinding(attr, v));
    }
    for (Element c : el.elements()) collectBindings(c, out);
}

Step 4: 运行通过。 Step 5: commit feat(converter): 提取 onselected/onload 事件绑定

注:Spike 若发现属性还挂在 <grid>/<page>/<button> 等具体元素且需区分组件,扩展 EventBinding 增 ownerTag;当前 930/422 全量以递归收集为安全默认。


Phase 2:attachScriptOnEvent 重写(按事件类型/组件正确挂)

Task 2.1:scriptActionChain 支持自定义 item 表达式

现状: scriptActionChain(templateId, seq) 固定 item:${&}。选中事件需 item:${selectedItems[0]}(取 Spike 0.1 结论)。

Step 1:写失败测试(断言 data.item 用传入表达式)

@Test
void scriptActionChain_自定义item表达式() {
    List<Object> chain = converter.scriptActionChain("tid", 1, "${selectedItems[0]}");
    Map<?,?> ajax = (Map<?,?>) chain.get(0);
    Map<?,?> data = (Map<?,?>) ((Map<?,?>) ajax.get("api")).get("data");
    assertThat(data.get("item")).isEqualTo("${selectedItems[0]}");
}

Step 2: 失败。 Step 3: 重载 scriptActionChain(String templateId, int seq, String itemExpr),原方法委托新方法传 "${&}"。 Step 4: 通过。 Step 5: commit。

Task 2.2:attachScriptOnEvent 改为按绑定列表挂事件

新签名: attachScriptOnEvent(Map schema, String templateId, List<EventBinding> bindings, Map<String,Integer> keyToSeq)。映射规则(事件名取 Spike 0.1):

  • onselectedscript → crud selectedChange(item=${selectedItems[0]})
  • onloadscript → inited(item=${&})

Step 1:写失败测试

@Test
void attachScriptOnEvent_onselected挂selectedChange_onload挂inited() {
    Map<String,Object> schema = newPageWithCrudBody();
    var bindings = List.of(
        new TemplateToAmisConverter.EventBinding("onselectedscript","K1"),
        new TemplateToAmisConverter.EventBinding("onloadscript","K2"));
    converter.attachScriptOnEvent(schema, "tid", bindings, Map.of("K1",1,"K2",2));
    Map<?,?> body = (Map<?,?>) schema.get("body");
    Map<?,?> onEvent = (Map<?,?>) body.get("onEvent");
    assertThat(onEvent).containsKeys("selectedChange", "inited");
    // selectedChange 链调 seq=1 + item=${selectedItems[0]}
    // inited 链调 seq=2 + item=${&}
    // (断言 data.seq / data.item,略)
}

Step 2: 失败。 Step 3:实现(替换旧 1644-1672 体)

@SuppressWarnings("unchecked")
public Map<String,Object> attachScriptOnEvent(Map<String,Object> schema, String templateId,
        List<EventBinding> bindings, Map<String,Integer> keyToSeq) {
    if (schema == null || templateId == null || templateId.isBlank()
            || bindings == null || bindings.isEmpty() || keyToSeq == null) return schema;
    Object bodyObj = schema.get("body");
    if (!(bodyObj instanceof Map)) return schema;
    Map<String,Object> body = (Map<String,Object>) bodyObj;

    List<Object> selectedActions = new ArrayList<>();
    List<Object> initedActions = new ArrayList<>();
    for (EventBinding b : bindings) {
        Integer seq = keyToSeq.get(b.scriptKey);
        if (seq == null) continue;             // 绑定引用了不存在的 key,跳过(fail-closed)
        if ("onselectedscript".equals(b.eventType)) {
            selectedActions.addAll(scriptActionChain(templateId, seq, "${selectedItems[0]}"));
        } else if ("onloadscript".equals(b.eventType)) {
            initedActions.addAll(scriptActionChain(templateId, seq, "${&}"));
        }
    }
    Map<String,Object> onEvent = new LinkedHashMap<>();
    if (!selectedActions.isEmpty()) onEvent.put("selectedChange", Map.of("actions", selectedActions));
    if (!initedActions.isEmpty())   onEvent.put("inited", Map.of("actions", initedActions));
    if (!onEvent.isEmpty()) body.put("onEvent", onEvent);
    return schema;
}

事件名 selectedChange 以 Spike 0.1 实测为准;若实测为 itemClick/其他则同步改本方法与测试。 Step 4: 通过。 Step 5: commit feat(converter): onEvent 按事件类型挂(onselected→selectedChange/onload→inited)

Task 2.3:废弃旧 full_auto_index-only 路径,BatchConvertCli 改用绑定

Files: BatchConvertCli.java(:110-148 加载、:185 调用)

Step 1: 改 BatchConvertCli:转换得到 result 后,从源 XML 解析 keyToSeq + bindings(用 Task 1.1/1.2 方法),调用新 attachScriptOnEvent(schema, id, bindings, keyToSeq)。删除/旁置 full_auto_index 加载(不再决定挂哪段)。 Step 2: 改现有 TemplateToAmisConverterTest 旧 attach 用例(:897-955)到新签名(旧"只 FULL_AUTO/inited+change"语义作废)。 Step 3: 运行 mvn -o -pl platform-converter test,全绿。 Step 4: commit refactor(converter): onEvent 挂回改由 XML 事件绑定驱动,覆盖 NO_S3


Phase 3:工具栏按钮补 id(让 enableButton 指令可定位)

Task 3.1:buildToolbar 给按钮补 id(取 Spike 0.2/0.3 规则)

Files: TemplateToAmisConverter.java buildToolbar(:421-470)

Step 1:写失败测试:断言转出的 headerToolbar 按钮含 id,且 id 与 enableButton 实参(按钮 name)对齐规则一致。 Step 2: 失败。 Step 3: 在 btn.put("type","button") 后加 btn.put("id", buttonId(btnName));(buttonId 实现取 Spike 0.3 决策:默认 id=btnName;若中文 id 不可用则规范化,并同步 ScriptFacade.enableButton 的 componentId)。 Step 4: 通过。 Step 5: commit feat(converter): 工具栏按钮补 id 供脚本启停定位

Task 3.2(条件):前端/facade 适配

仅当 Spike 0.2/0.3 发现 amis disabled/enabled 对 headerToolbar 按钮无效或 componentId 不匹配时执行:

  • 选项 A:ScriptFacade.enableButton(:311) emit 的 componentId 做名→id 规范化(同 Task 3.1 规则)。
  • 选项 B:scriptCommands.ts 对 enabled/disabled+kind:button 走 amis 可用动作。 每改一处配单测(Java/Vitest),commit。

Phase 4:重转 + 重入库 + 回归 + 浏览器验收

Task 4.1:单元/集成全绿

Run(JDK21):JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -o -pl platform-converter -am test,预期全绿(含改写的 attach 用例)。前端:cd eip4-web && npm test(若动了 scriptCommands/registerReplayAction)。

Task 4.2:全量重转 + 入库

cd /Users/zhengwr/workspace/eip3/eip4-platform
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -o -pl platform-converter exec:java -Dexec.mainClass=...BatchConvertCli \
  -Dexec.args="<...既有参数...> tools/s3_rewriter/output"   # rewriterDir 保 onEvent
JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -o -pl platform-converter exec:java -Dexec.mainClass=...SchemaImportCli   # upsert 入库

预期:sys_page_schema 产物 onEvent 含 selectedChange(onselected 模板);DB 抽查 ddb75614 产物 onEvent.selectedChange 调 seq=1。

Task 4.3:重启 8093(标准口径,cwd=eip4-platform,无需 flag,P0 已修)

PID=$(lsof -nP -iTCP:8093 -sTCP:LISTEN -t); kill $PID; sleep 3
/opt/homebrew/opt/openjdk@21/bin/java -jar platform-app/target/platform-app-0.1.0-SNAPSHOT.jar --spring.profiles.active=dev > /tmp/eip4-8093.log 2>&1 &

Task 4.4:浏览器端到端验收(强断言,REQUIRED SUB-SKILL: superpowers:verification-before-completion)

  • 新闻管理列表:选中一行 STATUS=3/ISSEND=0 的新闻 → 「发布」按钮点亮、未通过的行「发布」置灰;console 0 errors。
  • 抽查 259 个 enableButton 模板中的 3-5 个代表页同样验证选中联动。
  • 查看页:onload 只读脚本仍生效(NEWSCONTENT 只读),console 0 errors。
  • 截图存 eip4-web/e2e/artifacts/ 留证。

Task 4.5:回归

  • mvn -o -am test(platform 全 reactor 关键模块绿)。
  • DB 抽查:原 onload 模板 inited 不丢;onselected 模板新增 selectedChange;产物总数无异常缩水。

Spike 结论(实施时填写)

  • 0.1 行选中事件名 = ______;选中行 item 表达式 = ______
  • 0.2 按钮 id 规则 = ______;disabled/enabled 对 headerToolbar 是否生效 = ______
  • 0.3 componentId↔按钮 id 对齐方案 = ______

风险与回滚

  • 事件名/启停行为依赖 amis 6.13 实测(Spike 兜底);若 selectedChange 不可用,退化为给每行加「选中」联动或 disabledOn 表达式直算(次选,丢失脚本动态语义)。
  • 全量重转是幂等 upsert,回滚 = 重转上一版(git 还原转换器 + 重跑)。
  • 改动范围大(影响 ~930+422 模板产物),务必 Task 4.5 回归比对产物数量与既有 onload 不丢。

提交说明

  • 两仓本地 main、无 remote;按既有协议本地 commit,不自动 push。
  • 配置 P0 修复(application-dev.yml)若尚未提交,建议与本 plan 实施分开 commit。