docs+javadoc: 文档-代码对抗核查对齐 + 归档候选物理归档

5 路并行核对总览 §9/§10/§11 + A/B 矩阵声明 vs 两仓代码(48 条 46 条完全一致,无虚报),修正不一致处:
- A10 行 🔴→🟡:W1 Flyway(V1-V3)+W2-W4 容器化/nginx/compose 骨架 06-25 已合 main,文档此前低报;§10.2 Flyway/compose 两条标 ✅
- §9 P0② 表格「同族扩长」与对抗审查①矛盾(代码一律拒 TYPE 变更)改齐
- §10.2 render-plan 行号迁 AiDraftGateValidator.java:246(SRP 拆分后位置)
- §11 报表单测 73→79;§2「五步编排壳」改四步向导
- CandidateUsersHandler 类级 javadoc:scriptUser 已于 06-26 接入(resolveScriptUsers),删「WARN 降级未接入」陈旧表述(纯注释零行为变更)

归档整理(总览 §8 归档候选落地):
- 10 份已完成/被取代文档 git mv 入 docs/归档/(06-14×3/06-15/06-16/06-20 plans、CRUD-QA、C3/C5、总览-06-17)
- 引用同步改路径:README 索引、M0剩余项登记、通用模板收口计划、架构方向-design、新闻管理plan
- README 刷新至 07-02:补 06-22→06-26 增量一节、审批/报表行状态、§2 补登 06-25/06-26 四份 design/计划、§4 过时「未 push」表述修正

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-02 08:01:23 +08:00
parent b4baca5d94
commit 1b02036153
16 changed files with 46 additions and 37 deletions

View File

@@ -1,328 +0,0 @@
> ✅ **已完成·归档候选(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。

View File

@@ -1,86 +0,0 @@
> ✅ **已完成·归档候选(2026-06-21)**:processCoreService 桥接 bean 已端到端实证落地。可后续 `git mv` 入 `docs/归档/`。
# 提交审批端到端 — processCoreService 桥接 bean 设计(MVP)
> 日期:2026-06-14
> 状态:设计已收敛(brainstorming 完成),待实施(writing-plans / TDD)。
> 触发:逐流写 QA dogfooding 深挖 `no service`——248 个 SUBMIT/审批写流调 `processCoreService.startWorkflow` 而该 bean 未在 platform-app 注册。
> 边界:**仅设计桥接 bean**;BPMN 部署 + processName→key 映射为显式前置依赖(见 §6)。
---
## 一、背景与根因
amis「提交审批」走 **SAVE_AND_SUBMIT 复合 meta-flow**:SERVICE 节点 `beanName="flowExcuteService"` 调子流 `_ADD/_UPDATE`(落库,pojoCRUDService)→ 子流 `_SUBMIT` 的节点 `beanName="processCoreService" method="startWorkflow"` 启动审批流程。
`SpringBeanOsgiServices.getBeanByName(name)` = `applicationContext.getBean(name)` 按**名字**查。全库无名为 `processCoreService` 的 bean → `FlowExcuteServiceImpl:304` 抛 `RuntimeException("no service")`。**影响 248 流**(SUBMIT 120 / ADDSUBMIT 32 / SZWJ 18 / …)。
**桥接原语多已就位**(platform-flow-gateway):
- `FlowableClient.start(Map startRequest) → ProcessInstanceDto`(POST flowable-service `/api/flow/process/start`)+ complete/todo/trace/delegate;flowable-service:8089 实测在跑。
- `StatusWriteback`(SYS_DATASTATUS 单一所有者):`updateStatus`(upsert)/`getStatus`/`afterComplete`(办理后 PROCESSING/PASS,单调守卫)。
- `candidateUsersHandler`(flowable-service,候选人解析,B2 已验)。
**唯缺**:注册名 `processCoreService`、含 `startWorkflow` 方法的桥接 bean。
旧 `ProcessCoreServiceImpl.startWorkflow(processDefinitionKey, variables, tableName, businessKey, ctx)` 编排 = `runtimeService.startProcessInstanceByKey` + `changeStatus` 状态机(NOSUBMIT 1→PROCESSING 2/PASS 3) + 自动过「流程发起」首任务 + 重提交(RESUBMIT 5)。
---
## 二、架构
platform-flow-gateway 新增 `@Component("processCoreService")` 的 com.eip4 桥接 bean,把保真层服务流引擎调的 `startWorkflow(...)` 桥到既有 `FlowableClient.start` + `StatusWriteback`。
- 引擎经 `SpringBeanOsgiServices.getBeanByName("processCoreService")` 取 bean,再 `obj.getClass().getMethod("startWorkflow", [String,Map,String,String,Properties])` **反射调用**——故**无需 implements 25 方法的 ProcessCoreService 接口**,只需一个签名匹配的公开方法。
- 零改保真层 `com.dsasp.*`;ArchUnit 不触发(com.eip4 可依赖 com.dsasp)。
## 三、组件
`ProcessCoreServiceBridge`(platform-flow-gateway,`@Component("processCoreService")`),构造注入 `FlowableClient` + `StatusWriteback`。
```
public boolean startWorkflow(String processName, Map variables,
String tableName, String businessKey, Properties ctx)
```
(参数类型须与引擎 `getClass(field)` 解析的 `<arg>` 类型逐一匹配:processName/tableName/businessKey=String、map=java.util.Map(用裸 Map 以匹配反射)、ctx=java.util.Properties;返回 boolean=`<result name="result">`。)
逻辑:
1. `businessKey` 空 → 抛 `ValidationException("定义启动流程提交的业务记录不存在,请联系开发商")`(对齐旧,且该消息干净可经 gracefulFlowError 透出)。
2. 注入发起人变量(对齐旧,复用 `ProcessCoreService` 常量名):`INITIATORUSERID=ctx[CURRENTUSER]`、`INITIATORDEPARTID=ctx[CURRENTDEPART]`(缺则补)、`INITIATORTIME=now`。
3. 构造 `startRequest = {processDefinitionKey: processName, businessKey: businessKey, variables: variables}` → `ProcessInstanceDto inst = flowableClient.start(startRequest)`。
4. `statusWriteback.updateStatus(businessKey, tableName, inst.ended()? STATUS_PASS(3): STATUS_PROCESSING(2))`——起审批的 NOSUBMIT 1→2/3。直接 `updateStatus`(非 `afterComplete`,起审批总是从 1 推进,无需单调守卫)。
5. `return true`。
## 四、数据流
```
amis 提交审批 → POST /api/flow/{SAVE_AND_SUBMIT}
→ 引擎跑 meta-flow:save 子流(pojoCRUDService 落库,状态 NOSUBMIT=1,提交事务)
→ submit 子流 → startWorkflow 节点 → ProcessCoreServiceBridge
→ FlowableClient.start(HTTP→8089) 起 Flowable 流程
→ StatusWriteback.updateStatus → PROCESSING=2
后续办理:网关 complete 端点 → FlowableClient.complete → StatusWriteback.afterComplete → 2→3(PASS)
```
## 五、错误与事务语义
- 业务落库与起审批**分属不同服务/事务**(platform-app DB vs flowable-service),无分布式事务,接受最终一致。
- 起审批失败(`FlowServiceUnavailableException` / 流程定义不存在 / 8089 不可达)→ bean 抛 RuntimeException → 经 `FlowController.gracefulFlowError` 兜泛化「数据查询失败…」(内部细节不泄露 + 记完整栈);**状态停留 NOSUBMIT(1)**——业务记录已存,用户可重新提交。
- 幂等:本 MVP 重提交 = 起新流程(去重/复用待**后置**,见 §6)。
## 六、测试
单测 `ProcessCoreServiceBridgeTest`(mock FlowableClient + StatusWriteback):
- 正常:断言 startRequest 含 processDefinitionKey=processName/businessKey/variables;发起人变量已注入;调 `flowableClient.start`;`inst.ended()=false` → `updateStatus(...,PROCESSING)`,`=true` → `updateStatus(...,PASS)`;返回 true。
- businessKey 空 → 抛 ValidationException。
- 反射可解析性:`getMethod("startWorkflow", String.class, Map.class, String.class, String.class, Properties.class)` 能解析(保证引擎按名+签名调得到)。
- dev e2e **后置**(需部署一个 key 匹配的审批 BPMN,出本设计边界)。
## 七、显式前置依赖(出本设计边界,需单独立项/记录)
1. **客户审批 BPMN 部署进 flowable-service**:dev `eip4flow` 库 `ACT_RE_PROCDEF` 仅 demo 流程(process/process2/TEST_REQUEST…),无客户业务审批流程定义。`processName="收房变更申请"`(中文显示名作 startProcessInstanceByKey 的 key,旧 Activiti 约定)→ flowable-service 须部署 key 匹配(中文名)的 BPMN,否则即便桥接 bean 就位,start 也会「流程定义不存在」。生产/客户库疑有那 1509 定义,dev 需部署代表性 BPMN 验证。
2. **ProcessCoreService 其它方法**:passProcess/backProcess/transferAssignee/getProcessInstanceIdByBusinessKey 等若被别的流节点引用(如审批办理/退回/转办的服务流),本 MVP 只实现 startWorkflow → 那些节点仍 `no service`,按需扩同一 bean(追加方法,复用 FlowableClient.complete/delegate 等)。
3. **「流程发起」首任务自动过 + 重提交(RESUBMIT 5)**:旧 startWorkflow 含此逻辑,本 MVP 后置(依赖 BPMN 形态,且可由 BPMN service task 自过;FlowableClient.start 需返回首任务信息才能在桥内自过)。
## 八、影响面与价值
打通 248 个 SUBMIT/审批写流的「启动审批」步——配合前置依赖①(BPMN 部署)即可让「提交审批」端到端可用,是写+审批路径(检查点② 之后的下一大集成)的关键拼图。

View File

@@ -1,136 +0,0 @@
> ✅ **已完成·归档候选(2026-06-21)**:新闻管理切片已修复上线 + live 验收。可后续 `git mv` 入 `docs/归档/`。
# 新闻管理 功能垂直切片 全 parity Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans / superpowers:subagent-driven-development 逐任务实施。每条修复 TDD + 浏览器端到端对老系统验收,修完作为其余 ~150 功能的模板再泛化。
**Goal:** 把「新闻管理」整套功能(管理列表/查看/新闻收藏/新闻收藏分类/查看审批)在 EIP4 做到与老系统 parity 可用,覆盖 5 个已 live 实测的缺口;每个修法可泛化到其余功能。
**Architecture:** 缺口分布在 4 层:菜单裁剪(MenuController)、转换器 onEvent 脚本挂回、转换器树可编辑性、转换器表单/显示列。逐层定位根因后最小修 + 全量重转(涉及产物的)+ 浏览器验收。
**Tech Stack:** Java 21(JAVA_HOME=/opt/homebrew/opt/openjdk@21,mvn 默认 Java26 崩 Groovy)、dom4j、JUnit5、Spring Boot 3、amis 6.13(前端 TS/Vitest)、PG15(localhost:5433/eip4dev schema eip3)。运行时 8093(platform)/8089(flowable)/5173(vite)。登录 admin/111111。
---
## 缺口总览(均 2026-06-14 live 实测 + 根因定位)
| WS | 现象(对老系统) | 根因 file:line | 修复层 | 是否需重转 |
|----|------|------|------|------|
| A | 管理列表菜单 admin 看不到(ddb75614 不可达) | `MenuController.java:102` 按 view_sys_usermenuid 裁剪;admin 未授权 b6d6be5a | 后端菜单/权限 | 否 |
| B | 列表选中按钮不联动 + 满屏 ajax 报错 | P0(已修) + `attachScriptOnEvent`:1644 只挂 FULL_AUTO 漏 NO_S3 + 不分事件/组件 | 转换器 onEvent | 是 |
| C | 新闻收藏(浏览)左树能编辑分类(应只读) + 新闻收藏分类(管理)只读且 label=undefined(应可编辑) | `convertTreeGrid`:1224 对 type=4 调 applyTreeNodeCrud 传播编辑按钮;`convertTree`:1185 对 type=3 只 degrade 不映射;tree source label 未解析 | 转换器树 | 是 |
| D | 查看页无附件下载列表 + 发布人列显「-」 | DOCUMENT→input-file 只读态空;发布人(USERSEND_ID)引用列 NVARCHAR 未解析 | 转换器表单/显示列 | 是 |
| E | (验收)查看审批入口未接业务页 | 见 `docs/EIP4-架构与缺口现状` / 待办中心已有 TraceTimeline | 接线 feature | — |
> **执行顺序建议**:B(已出详细计划,最高杠杆 ~380 页)→ C(树,影响 ~95 收藏/分类页)→ A(菜单,决策项小修)→ D(显示,P1)→ E(验收+查看审批,单独评估)。每 WS 修完即浏览器验收。
---
## WS-A:管理列表菜单可达(admin/超管见全部)
**根因(已证据级):** sys_menu 有叶子 `新闻管理 b6d6be5a → view_templateid=ddb75614`(seq10),但 `MenuController`(:85-102) `SELECT trim(menuid) FROM view_sys_usermenuid WHERE userid=?` 裁剪可见叶子;admin(ADMIN) 在该视图有 查看新闻/新闻收藏/收藏分类、**无 b6d6be5a** → 管理列表整页不可达。老系统截图 admin 在用该页。
**决策项(实施前与用户确认;默认推荐①):**
- ① **MenuController 对 admin/超管 bypass 裁剪**(见全部 isactive 菜单)——robust,符合"系统管理员见全部"直觉。需确认本系统超管判定信号(userid='ADMIN'?某超管角色?grep sys_user/role 超管标记)。
- ② 数据层给 admin 授权 b6d6be5a(view_sys_usermenuid 是计算视图,须溯源 role/user 授权表补授权)——更"忠实老数据"但需查老系统 admin 是否本就被授权。
### Task A.1(Spike):确认超管判定信号 + 老系统 admin 是否本应见全部
- 查 sys_user/sys_role 是否有超管标记;查老系统(EIP-3.0 / framework)菜单裁剪是否对 admin bypass。
- 产出:判定信号 + ①/②决策。
### Task A.2:实现(按决策,默认①)
**Files:** Modify `platform-metadata/src/main/java/com/eip4/platform/metadata/web/MenuController.java`(visibleLeaf 集合构建处);Test 同包 controller test。
- **Step1 失败测试**:mock 当前用户=admin/超管 → `/api/menu` roots 含 b6d6be5a(新闻管理 leaf, templateId=ddb75614)。
- **Step2** 运行失败。
- **Step3** 实现:超管短路——visibleMenuIds = 全部 isactive menuid(不 JOIN usermenuid)。
- **Step4** 通过。 **Step5** commit `feat(menu): admin/超管菜单见全部(管理列表可达)`。
- **Step6 浏览器验收**:admin 登录 → 信息站/新闻管理 下出现「新闻管理」管理列表叶子 → 点开 = ddb75614 列表(13 按钮)。
---
## WS-B:onEvent 脚本挂回(按钮联动 / 表单只读联动)
> P0(rewritten-root 路径)已修并提交 `7b76dce`。本 WS 修 P0+(seq 映射/覆盖/事件类型/组件)。**完整 TDD 细化见原稿** `docs/plans/2026-06-14-onEvent脚本挂回修复-plan.md`(Phase 0 Spike→Phase 4 验收),此处仅列要点,实施以原稿为准。
**根因:** `TemplateToAmisConverter.attachScriptOnEvent`:1644 只挂 `full_auto_index.json` 的 FULL_AUTO 脚本(漏 NO_S3 的「按钮状态控制」onselectedscript),且每段同挂 inited+change 不分事件/组件;工具栏按钮无 `id` 致 enableButton 指令定位不到。影响 930 onselected/422 onload/259 enableButton 模板。
**要点(详见原稿):**
- Phase 0 Spike:crud 行选中事件名(预期 selectedChange)/item 表达式(${selectedItems[0]});`disabled/enabled` 按 id 定位 headerToolbar 按钮可行性;componentId↔按钮 id 对齐。
- Phase 1:`scriptKeyToSeq`(解析 <scripts> 文档序) + `extractEventBindings`(onselectedscript/onloadscript 属性→key)。
- Phase 2:重写 `attachScriptOnEvent` 按事件类型挂(onselected→selectedChange item=选中行 / onload→inited),覆盖 NO_S3+FULL_AUTO;`scriptActionChain` 支持自定义 item 表达式;BatchConvertCli 改由 XML 绑定驱动。
- Phase 3:`buildToolbar` 按钮补 `id`(:431) + 必要时 ScriptFacade.enableButton/scriptCommands 适配。
- Phase 4:全量重转(rewriterDir=tools/s3_rewriter/output 保 onEvent)+SchemaImportCli 入库 + 重启 8093 + 浏览器强断言(选中 STATUS=3/ISSEND=0 行→发布点亮)+回归。
---
## WS-C:收藏树可编辑性(type=3 可编辑 / type=4 只读)+ undefined 标签
**根因(已证据级):**
- **type=4(新闻收藏 50ac13b2,convertTreeGrid:1197)**::1224 调 `applyTreeNodeCrud`,读被引用分类树(a763d48d)的 `<node><buttons>` → 给浏览页左树加 editable/removable/「新增分类」按钮。**浏览页本应只读导航。**
- **type=3(新闻收藏分类 a763d48d,convertTree:1165)**::1185 对 `<node><buttons>` **只 `result.degrade` 不映射** → 输出只读 input-tree。**管理页本应可编辑。**
- **undefined 标签**:type=3 树 source=`/api/flow/{selectservice}`(:1174),返回项的 label 字段未解析(树节点显「undefined」)——类同 GeneralPO 虚拟显示列问题(3feefb3)。
**修复策略:把可编辑逻辑从 type=4 挪到 type=3。** 即 `applyTreeNodeCrud` 抽成可复用的「给 input-tree 加节点 CRUD」,type=3 调用它(管理页可编辑),type=4 不调用(浏览页只读)。
### Task C.1(Spike):定位 undefined 标签源
- 浏览器/curl `/api/flow/{a763d48d 的 selectservice}` 看返回项字段(label/value/名称列),定位为什么 amis 树显 undefined(label 字段名不符 or 显示列未算)。读 TemplateTreeController / 树 source builder。
- 产出:label 解析修法(树 source 返回 {label:显示列, value:主键} 或转换器/后端补显示列)。
### Task C.2:type=3 convertTree 支持可编辑(含 undefined 修)
**Files:** Modify `TemplateToAmisConverter.java` convertTree(:1165-1194);复用/抽取 applyTreeNodeCrud 的按钮→editable/creatable/removable+addApi/editApi/deleteApi 映射;Test 同测试类。
- **Step1 失败测试**:type=3 树 XML 含 `<node><buttons>`(insert/update/delete/save+servicename) → 转出 input-tree 含 `creatable/editable/removable` + 对应 addApi/editApi/deleteApi(/api/flow/{svc})。
- **Step2** 失败。
- **Step3** 实现:convertTree 检测 buttons → 调抽取后的节点 CRUD 映射(取代 :1185 的纯 degrade);新增=弹窗表单(复用 buildTreeNodeAddButton)或内联 creatable(取 C.1 实体必填列结论)。label 按 C.1 修。
- **Step4** 通过。 **Step5** commit `feat(converter): type=3 声明式树支持节点增删改(收藏分类管理页可编辑)`。
### Task C.3:type=4 convertTreeGrid 左树只读
**Files:** Modify `convertTreeGrid`(:1224)。
- **Step1 失败测试**:type=4(tree+grid) 转出左 input-tree **不含** editable/removable/新增按钮(即不调 applyTreeNodeCrud 的编辑传播)。
- **Step2** 失败。
- **Step3** 实现:移除 :1224 的 applyTreeNodeCrud 调用(或改为只构树不加编辑);左 body 仅树。
- **Step4** 通过。 **Step5** commit `fix(converter): 树+列表浏览页左树只读(收藏页不再误带新增分类)`。
### Task C.4:重转 + 入库 + 浏览器验收
- 全量重转(保 onEvent)+SchemaImportCli + 重启 8093。
- 验收:新闻收藏(50ac13b2) 左树**无**新增分类、只读筛选;新闻收藏分类(a763d48d) 树**可**增/改/删节点、节点名正常(非 undefined)。通知收藏/通知收藏分类(22786b70/f359a080) 同样正确。
---
## WS-D:查看页附件下载列表 + 发布人显示列
### Task D.1(Spike):附件数据模型
- 查老系统附件如何存取(EIP-3.0/framework grep 附件/attachment/BLOB/file;DB 看 OA_NEWSMANAGE 附件挂在哪:DOCUMENT 列? 独立附件表 keyed by 业务id?)。
- 查 EIP4 现有 `/api/file/*`(FileController)能否按业务 id 列出已有附件。
- 产出:查看(只读)态渲染已有附件列表+下载的方案(amis input-file 静态值/只读 file 列表组件 + source api)。
### Task D.2:查看表单附件只读下载列表
**Files:** Modify `TemplateToAmisConverter`(DOCUMENT/附件字段映射,convertViewPage/convertForm 只读分支);可能后端补「按业务 id 列附件」端点。
- TDD:查看表单 DOCUMENT 字段 → 只读态渲染已有附件(文件名+大小+下载/全部下载),非空上传按钮。
- 浏览器验收:有附件的新闻查看 → 显示附件可下载(对齐老系统截图)。
### Task D.3:发布人等用户引用列显示
**Files:** Modify `UserColumnResolver`(CRUD QA 已记「用户类引用列 NVARCHAR 同病未覆盖」)——CREATEBY/USERSEND_ID/发布人列 id→姓名。
- TDD + 浏览器:查看新闻/新闻收藏列表 发布人显姓名(非「-」/裸 id)。
---
## WS-E:端到端验收 + 查看审批 + 泛化
### Task E.1:新闻管理整套端到端走查(对老系统截图逐屏)
- 管理列表(添加/修改/删除/查看/发布/显示/隐藏/置顶/文件归档/取消置顶/提交审批/查看审批/导出Excel 13 按钮,选中联动)、查看(附件)、新闻收藏(只读浏览)、新闻收藏分类(可编辑)、提交/查看审批。强断言+截图。
### Task E.2:查看审批入口(评估,可能拆独立 feature)
- 引擎层已统一(FlowableClient.trace+8089+ApprovalBar/TraceTimeline 在待办中心)。给列表/查看页注入「查看审批」按钮→复用 TraceTimeline 抽屉;BPMN 图为较大件可后置。详见 E 调查(本会话 agent 已出缺口清单)。
### Task E.3:泛化清单
- 每个 WS 修法对其余功能的影响面与回归点:WS-B 930/422 页;WS-C ~95 收藏/分类页(type3=50、type4=45);WS-A 全菜单;WS-D 全用户引用列/全附件查看页。记录回归比对口径。
---
## 全局验收 / 回滚
- 每 WS 改转换器后:`JAVA_HOME=…@21 mvn -o -pl platform-converter -am test` 绿 → 全量重转 → SchemaImportCli 入库(幂等 upsert) → 重启 8093 → 浏览器强断言。
- 回滚:转换器 git 还原 + 重转上一版;菜单/后端改动 git 还原。
- REQUIRED:superpowers:verification-before-completion(每 WS 浏览器实证后才算完成,不停在「组件出现」)。
## 提交
- 两仓本地 main、无 remote;按既有协议本地原子 commit,不自动 push。P0 已提交 7b76dce。

View File

@@ -1,56 +0,0 @@
> ✅ **已完成·归档候选(2026-06-21)**:菜单树模式 + 字段级树选择框已修复 live 验收。可后续 `git mv` 入 `docs/归档/`。
# 菜单维护改老系统模式 + 字段级树选择框修复 — 实施计划
日期:2026-06-15
触发:用户以"菜单维护"为例质疑树模板/树选择框是否真正实现,附老系统截图(左树 + 右表单 + 工具栏 添加/修改/删除/保存,上级菜单为树选择框)。
## 一、调查结论(均已证据坐实)
存在**两套并行实现**,用户看到的菜单管理走的是"没用转换器"的那套:
| 路径 | 树模板 | 树选择框 | 现状 |
|---|---|---|---|
| 通用转换器 `TemplateToAmisConverter` | ✅ type=3 → `input-tree` + 节点CRUD,多级 | 字段级 ❌(见下) | — |
| 手写后台 schema(菜单/用户/角色) | ❌ 扁平 CRUD | ❌ 扁平 `select` | **用户看到的就是这套** |
关键事实:
1. **菜单管理当前页 = 入库的手写扁平 CRUD**(`docs/sql/A1_sys_admin_menu_manage_upsert.sql`,templateId=`sys-admin-menu`,DB 覆盖 resource 文件)。上级所属分组是扁平 `select`,逐行弹窗加子菜单。
2. **菜单维护本就是 type=3 树模板**:id=`b38737be-aecf-44d9-b3d4-1823c5443fba`,绑 SYS_MENU,自引用列 PARENTID,节点按钮 insert/update/delete/save(= 截图工具栏)。编辑页 pageid=`4611e954-fa49-4926-82ce-7da5318e60b0`。
- 证据:`framework/com.dsasp.server.db/META-INF/sql/install/1.0.78/view_template.copy`、`view_page.copy`。
3. **该模板已被转换过**,产物在 `eip4-platform/转换产物/schema/b38737be-….json`,已是老系统模式:`<input-tree editable removable source=/api/template/b38737be/tree>` + "新增分类"弹窗(加载编辑页 4611e954 + SYS_MENU_ADD 保存)+ 行内改名/删除。**只是没被接成菜单管理入口。**
4. **上级菜单"列表选择框"根因**:编辑页 4611e954 转换产物里 `PARENTID → picker source=/api/picker/b38737be/list`。dialogid `b38737be` 是 type=3 树,但 `UiTypeMapper` 的 `case "SelectDialog"`(`platform-converter/.../UiTypeMapper.java:215-241`)不解析 dialogid 类型,一律产 `picker`。
5. **2 级限制根因**(手写路径):`AdminController.buildMenuChildren`(`platform-metadata/.../web/AdminController.java:204-237`,注释明写"两级")+ `MenuService.buildTree`(`menu/MenuService.java:32-99`,`buildLeafNode` 把叶子 children 硬设 `List.of()`)。但**改走 b38737be 后不再依赖此端点**——树数据来自 `/api/template/.../tree`(`TemplateTreeController.resolveLevels` 已递归任意层级)。
6. 字段级 uitype 全表里**没有 "TreeSelect"**;老系统树选择 = `SelectDialog` 的 dialogid 指向 type=3 树模板。运行时 `PickerController.resolveByViewTemplate` 已会按 dialog XML 根元素 `<tree>`/`<crud>` 区分树/列表,但转换期不区分。
## 二、改动收敛为两处
### 改动 A — 菜单维护页:接通已转换的 type=3 产物(修复第 1、2 点)
- 把后台导航"菜单管理"入口从手写扁平 CRUD 切到 templateId=`b38737be`(已转换的树页)。
- 步骤:
1. 确认/导入 `b38737be` + `4611e954` 进运行时 `sys_page_schema`(产物已在 `转换产物/`,用 SchemaImportCli 导入或核验 8093 已 live)。
2. 验证 `/api/template/b38737be/tree` 返回多级 SYS_MENU 树(自引用 PARENTID,TemplateTreeController 递归)→ 第 1 点解决。
3. 改菜单入口指向 b38737be(前端导航 / sys_menu 的 view_templateid,或用产物覆盖 sys-admin-menu 入库 schema)。
4. 废弃手写 `A1_sys_admin_menu_manage_upsert.sql`(保留备份)。
- 产物天然含 input-tree + 添加/修改(行内改名)/删除 + 新增弹窗 → 第 2 点(老系统模式)解决。
### 改动 B — 转换器 SelectDialog 树感知(修复第 3 点 + 全站 883 页)
- 改 `UiTypeMapper` `case "SelectDialog"`(及 `MultiSelectDialog`):转换期解析 dialogid 指向模板的 type;
- type==3(树)或目标自引用实体 → 产 amis `input-tree`(或 `tree-select`),source=`/api/template/{dialogid}/tree`(复用现成端点)。
- 否则维持 `picker`(不回归列表选择框场景)。
- 实现关键:转换器需在转换期拿到"dialogid → 模板 type"映射。`BatchConvertCli` 读取全量 view_template 行,可构建 id→type map 注入 UiTypeMapper;或复用 `TemplateTreeController.resolveLevels`/`PickerController` 的解析逻辑。**实现第一步先确认此映射可得**。
- TDD:新增单测——SelectDialog(树 dialogid) → input-tree;SelectDialog(crud dialogid) → picker(保 72 测试绿)。
- 全量重转 883 + 重导(BatchConvertCli / SchemaImportCli)。
## 三、风险与验证
- 转换器改动影响全站 → 重转后需回归(72 单测 + 抽样 diff)。
- MENUROOT(根级菜单, dialogid 80554409) 是 sys_menu_root 扁平列表,维持 picker 正确;功能(VIEW_TEMPLATEID, 8b89fd29) 是 type=4 树+grid,本期可暂留 picker(后续项)。
- 8093 重启 smoke + 浏览器验收菜单维护:多级树 / 添加修改删除保存 / 上级菜单为树选择框。
- 旁注:运行时左侧导航菜单(MenuService.buildTree)同样硬 2 级,属独立潜在问题,本期不在范围,单列后续。
## 四、执行顺序
1. 确认 dialogid→type 映射在转换期可得(读 BatchConvertCli)。
2. 改动 B(TDD:先写测试 → 改 UiTypeMapper → 绿)。
3. 重转 + 重导,核验 4611e954 PARENTID 变 input-tree/tree-select。
4. 改动 A(接入 b38737be,废弃手写 CRUD),导入/核验。
5. 8093 重启 + 浏览器端到端验收三点。

View File

@@ -1,122 +0,0 @@
> ✅ **已完成·归档候选(2026-06-21)**:Phase 0-4 全部实现 + live 验收。仍可作 WfTemplate 驱动审批机制参考;可后续 `git mv` 入 `docs/归档/`。
# WfTemplate 驱动审批界面 — 完整实现方案
日期:2026-06-16
状态:**已实现 + live 验收(2026-06-16)**。Phase 0/1/2/3/4 全做完,8093/8089 已跑新 jar。
- Phase0 实测修正:运行任务 form_key 仅 0.6%,靠 (procDefId,taskDefKey) 历史回补 99.98%(新增 `FormKeyResolver`);
实际用到的 286 模板均无内联 `<fields>`,业务表单走 pageid/businessTable→sys_page_schema(无需 fields→amis 转换)。
- 增量未做:load 脚本/action servicename 执行未接、assist/circulated 返 400、业务表单 ~79% 降级摘要(详见 memory `eip4-wftemplate-driven-approval`)。
触发:用户指出"审批按钮应由流程模板定义、动态加载,不该写死;流程模板还定义了脚本是否可用",以及更早"待办审批看不到业务表达就审批不合理"。三点同源。
---
## 一、根因(一句话)
新系统的待办/审批界面**把按钮、脚本、业务表单全写死/丢弃了,完全没用迁移过来的 1016 个 `WfTemplate`(审批流转模板)**。老系统的整个审批界面是由 WfTemplate 数据驱动的。三个问题(看不到业务表单 / 按钮写死 / 脚本丢失)是**同一个根**。
---
## 二、已查证的数据事实(实现依据,勿重复推翻)
### WfTemplate 存储与结构
- 表 **`view_wftemplate`**(库 eip4dev,schema eip3),**1016 行**已迁移。列:`view_wftemplate_id, xml, isactive, version, create*/update*`。
- 服务 `WfTemplateServiceImpl.saveOrUpdate → pojoCRUDService.update("VIEW_WFTEMPLATE")`。
- xml 结构(实测样例):
```xml
<form>
<load><method/></load> <!-- 页面加载脚本(脚本是否可用) -->
<toolbar showsend="false">
<action id="…" label="同意" type="approve"><method servicename=""/></action>
<action id="…" label="拒绝" type="reject"><method servicename=""/></action>
<action id="…" label="退回" type="reback"><method servicename=""/></action>
</toolbar> <!-- 审批按钮:按节点配置 -->
<fields>…</fields> <!-- 审批视图:单据业务表单字段 -->
</form>
```
### action(按钮)词表 — 实测全量分布
- **type**:approve(1016) / reback(972 退回) / reject(971 拒绝) / agent(2) / circulated(2 转阅) / assist(2 协办)
- **label**(高度定制,证明不能写死):退回(971)/拒绝(970)/同意(966) + 确认登记/整改完成/确认/接收/申请封闭/同意2/确认施工方案/转阅/确认封闭/转办/确认交底/意见填写完成/协办/提交审批/登记续签/保存合同及岗位信息/提交方案论证 …
- **375/1016** 的 action 带 `servicename`(自定义服务);**369/1016** 有 `<load>` 脚本;**1008/1016** 的 `<fields>` 非空(业务表单视图)。
### 任务 → WfTemplate 映射(关键,已坐实)
- **flowable 任务 `form_key_` = `view_wftemplate_id`**。eip4flow.`act_hi_taskinst` 56905 任务,**56900 有 form_key**;样例 form_key 在 eip4dev.view_wftemplate 命中=1。
- 老系统取法(`HisTaskDetailPage`/`TaskDetailPage`):
```java
formKey = FormService.getTaskFormKey(procDefId, taskDefinitionKey); // 任务级
if (empty) formKey = FormService.getStartFormKey(procDefId); // 流程级回退
pojo = wfTemplateService.getWfTemplate(formKey); // 取 WfTemplate
```
- 业务记录:任务 `businessKey`(=记录PK) + `businessTable` → `/api/entity/{table}/{businessKey}`。
---
## 三、现状代码位置(改动起点)
| 层 | 文件 | 现状 |
|---|---|---|
| 前端按钮(写死) | `eip4-web/src/components/ApprovalBar.tsx` | 同意/驳回/转办 写死,`handleComplete('agree'\|'reject')`+delegateTask |
| 前端待办页 | `eip4-web/src/pages/TodoPage.tsx` | 待办/已办 tab + 列表 + 内联 ApprovalBar;缺业务表单区 |
| 前端 api | `eip4-web/src/api/approval.ts`(completeTask/delegateTask/fetchTrace)、`todo.ts`(TodoItem 带 businessKey/businessTable) | — |
| 后端网关 | `platform-flow-gateway/.../web/TodoController.java`(`/api/todo`,`/api/task/{id}/complete`,`/delegate`,trace) + `FlowableClient.java` | complete/delegate 有;缺 approval-meta、reback、reject 终止 |
| 后端引擎 | `flowable-service/.../api/FlowController.java`、`TaskDto.java`(无 formKey 字段→要加) | — |
| 表→表单解析 | `platform-converter/.../TemplateToAmisConverter.java:resolveEditFormTemplateId`(911-975,实体级回退) | 逻辑可参考,需抽成运行时端点 |
| 老语义参考 | `framework/com.dsasp.client.viewframework.template.wf.WfTemplateComponent`(getActions/getActionMethod/拒绝终止流程)、`framework/com.dsasp.server.wf/.../ProcessCoreServiceImpl`(action 语义) | 还原依据 |
---
## 四、分阶段实现
### Phase 0 — 补充勘查(新会话先做,~0.5d)
1. dump 几个 `<fields>` 非空的 WfTemplate,看字段定义格式(和 view_page/view_template 的 `<field>` 是否同构 → 能否复用现有 amis field 渲染,还是要单独解析)。
2. 老 `WfTemplateComponent.getActionMethod(id)` + `ProcessCoreServiceImpl` 里 approve/reject/reback/agent/circulated/assist 各 type 的真实语义(尤其 reback 退回到哪、reject 是否终止+状态码)。
3. `<load><method>` 脚本格式 + 在新系统执行路径(保真层服务流 `/api/flow/{svc}`?JUEL?)。
4. eip4flow.`act_ru_task`(运行中任务,非历史)的 form_key 覆盖率——决定"新提交走 EIP4_DEFAULT_APPROVAL 通用流、无 form_key"时的降级策略。
### Phase 1 — 后端:审批元数据端点(WfTemplate 驱动)
- `TaskDto` 加 `formKey` 字段(flowable `task.getFormKey()`)。
- 新端点 **8093 `GET /api/task/{taskId}/approval-meta`**(TodoController + FlowableClient):
1. 取 task.form_key_(= wftemplate id);空 → `FormService.getTaskFormKey(procDef, taskDefKey)` → `getStartFormKey(procDef)` 回退。
2. 查 `view_wftemplate` by id,解析 `<toolbar showsend><action id label type><method servicename>`、`<load><method>`。
3. 返回 `{buttons:[{id,label,type,servicename}], loadScript, showsend, businessKey, businessTable, formTemplateId}`。
4. 无 form_key/无 wftemplate → 兜底默认按钮(同意 approve / 驳回 reject)。
- 表→编辑表单模板:把 `resolveEditFormTemplateId` 实体级逻辑抽成运行时 `GET /api/form/by-table/{table}`(表名→SYS_ENTITY→type=7/view_page editform),或把 `formTemplateId` 直接 enrich 进 approval-meta。
### Phase 2 — 后端:action type → flowable 操作
统一收口新端点 **`POST /api/task/{id}/action`**(body: `{actionType, comment, targetUserId?}`),内部按 type 分派:
- **approve(同意)** → `complete(approveResult=approve)` + StatusWriteback(已有;结束→3,未结束→2)。
- **reject(拒绝)** → 终止流程 `runtimeService.deleteProcessInstance` + 回写 SYS_DATASTATUS(老语义"拒绝终止",状态码 Phase0 确认 4驳回/6作废)。
- **reback(退回)** → 退回上一节点/发起人:flowable `runtimeService.createChangeActivityStateBuilder().moveExecutionsToSingleActivityId(...)`;`ProcessCoreServiceBridge` 补 `backProcess`(MVP 缺口)。
- **agent/assist/circulated(转办/协办/转阅)** → delegate / 加签(addCandidateUser) / 抄送。
- **带 servicename 的 action** → 调保真层 `/api/flow/{servicename}`。
### Phase 3 — 前端:数据驱动审批详情
- `ApprovalBar` 改:挂载时 `fetch /api/task/{taskId}/approval-meta` → **按 buttons 动态渲染**(label/type/颜色由 type 映射),点击调 `/api/task/{id}/action`。
- 审批详情布局(建议**抽屉**,用户上一轮倾向待定:抽屉/全页/行内三选一):
- 上半 = **业务单据表单(只读)**:amis `service`(`schemaApi:/api/page/schema/{formTemplateId}` + `api:/api/entity/{table}/{businessKey}` + `static:true`)。
- 下半 = 动态按钮条 + 审批意见 + 流程轨迹(复用现 ApprovalBar 的意见/轨迹)。
- `<fields>` 非空时优先用 WfTemplate 定义的字段视图(Phase0 定格式后决定复用 view_page 还是直接 amis form)。
- 执行 `loadScript`(若有)。
- eip4-web 是 vite 热更,前端改即时生效(无需重启)。
### Phase 4 — 部署 + 验收
- 后端重建重启:`JAVA_HOME=…@21 mvn -o package -pl platform-app,flowable-service -am -DskipTests` → `scripts/run-dev.sh both`。
- 验收(live):不同节点任务办理 → 按钮随 WfTemplate 变(同意/拒绝/退回 + 定制按钮如"确认施工方案");业务单据表单可见可读;退回/拒绝语义正确(退回回上一步、拒绝终止);轨迹正常。
---
## 五、风险 / 边界
- **新提交走通用流(EIP4_DEFAULT_APPROVAL)的任务可能无 form_key** → 数据驱动降级为默认按钮。完整数据驱动需客户 BPMN 部署(userTask formKey 指向 WfTemplate),属切流前置(见 153/审批桥接线)。
- **reback/reject 的 flowable 实现**(changeActivityState/deleteProcessInstance)与老 activiti API 有差异,要实测;ProcessCoreServiceBridge 当前是 MVP(仅 startWorkflow)。
- `<fields>` 字段格式 Phase0 必须确认能否复用现有渲染,否则要写 WfTemplate fields → amis 的小转换。
- **不碰 view_template.xml(冻结)、不动 153 bespoke**。本特性是审批框架级通用能力(覆盖所有审批流),非逐页 bespoke,价值高。
- 与已完成的审批A(提交按钮状态)/审批B(查看审批 trace)/全量部署 不冲突;本特性替换的是待办"办理"的写死按钮 + 补业务表单。
---
## 六、本会话已完成的审批相关(上下文)
- 审批A:提交审批按钮 STATUS-aware disabledOn(处理中禁用)✅ 上线。
- 审批B:列表「查看审批」按钮 + `/api/flow/business/{bk}/trace`(businessKey→flowable 历史轨迹)✅ 上线(日期 valueFormat:x 已修)。老新闻"通过"记录因老 activiti 历史未迁进 flowable 而空,属数据缺口(用户认可不纠结)。
- 待办工作台(TodoPage/ApprovalBar)实测**可用**:列表+办理+同意(推进流程)+驳回/转办+轨迹——但按钮写死、无业务表单、无 WfTemplate 驱动(= 本方案要解决的)。
- 详见 memory `eip4-generic-vs-custom-templates-plan`、`eip4-wftemplate-driven-approval`。

View File

@@ -1,7 +1,7 @@
# EIP4 开发平台 · 架构方向(与最初设计对齐版)
> 日期:2026-06-19 | 性质:方向级 design(brainstorm 收敛 + 最初设计考古 + 引擎代码核实 + 对抗审查产出)
> 配套权威:`项目进度与路线-总览-2026-06-17.md`(A 兼容 / B 新功能全景)、`架构设计.md`(双层制/选型/红线)、`决策与盘点/EIP4前端与收尾实施计划.md`(F4 低代码工具链原始定义)
> 配套权威:`项目进度与路线-总览-2026-06-21.md`(A 兼容 / B 新能力全景,取代 06-17 版)、`架构设计.md`(双层制/选型/红线)、`决策与盘点/EIP4前端与收尾实施计划.md`(F4 低代码工具链原始定义)
> 方法:9-agent workflow(7 路考古/代码核实 → 综合 → 对抗审查),逐行核实引擎实况。
---

File diff suppressed because it is too large Load Diff