- 新建 项目进度与路线-总览-2026-06-21(取代06-17版),刷新A/B矩阵+增量交付+下一步+§9实施记录 - README 索引刷新到06-21;旧总览+14份过时/已完成文档加状态横幅;落地路线图回写里程碑 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
20 KiB
✅ 已完成·归档候选(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.ymlrewritten-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 全部覆盖)
- 覆盖缺口:只挂 FULL_AUTO(
full_auto_index.json),NO_S3 事件脚本被丢。 - 事件类型缺口:每段同时挂 inited+change,不区分 onselected→选中事件 / onload→inited。
- 组件/定位缺口:① 不区分挂到列表 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.tstranslateCommands: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.javaattachScriptOnEvent:约 :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→ crudselectedChange(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: commitfeat(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。