Files
eip4-platform/docs/plans/2026-06-14-onEvent脚本挂回修复-plan.md
zhengwr 624ffe8a15 docs: 06-21 进度文档对齐 + P0/P1 实施记录
- 新建 项目进度与路线-总览-2026-06-21(取代06-17版),刷新A/B矩阵+增量交付+下一步+§9实施记录
- README 索引刷新到06-21;旧总览+14份过时/已完成文档加状态横幅;落地路线图回写里程碑

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

329 lines
20 KiB
Markdown
Raw 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.
> ✅ **已完成·归档候选(2026-06-21)**:onEvent seq 映射已修复上线,计划执行完毕。可后续 `git mv` 入 `docs/归档/`。
# 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:写失败测试**
```java
@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:最小实现**
```java
/** 解析 <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:写失败测试**
```java
@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:最小实现**(新增内部记录类 + 递归扫描)
```java
/** 一条事件绑定:原始事件属性名 + 引用的脚本 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 用传入表达式)
```java
@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:写失败测试**
```java
@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 体)
```java
@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。