Files
eip4-platform/docs/归档/EIP4-架构与缺口现状-2026-06-13.md
zhengwr 1b69f8b481
Some checks failed
ci / build-test-parity (push) Has been cancelled
docs: 统一项目文档进 eip4-platform/docs + 新增进度路线总览
- 从工作区根 docs/(非 git,未版本化)合并全部文档进版本控制,消除文档两头分裂
- 新增 README(状态总览+模块完成度+全文档索引)、项目进度与路线-总览-2026-06-17(A兼容/B新功能+关键路径+待拍板决策)
- 被取代的冲突状态/审计快照归入 归档/;对最易误导的两份("16视图已交付"实现交付报告、06-13架构快照)加"已归档"横幅
- 现行权威:engineclass移植backlog(46视图) + 用户管理Delta移植(方法论/交接) + 组件设计体系 + 通用模板收口 + 客户沟通
- 诚实口径:纵向模块仅用户管理 parity,横向引擎地基较全,余 153 定制视图(47 framework+106 业务)多为通用页已产·delta 未移植

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

291 lines
34 KiB
Markdown
Raw Permalink 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-17)**:本文是 2026-06-13 快照,早于「engineclass delta」重定性与 06-14~17 全部工作,**不再是权威状态视图**。当前状态以 `docs/README.md` 为准。
# EIP4 架构与缺口现状(2026-06-13)
> 本文档是对 EIP4 当前**技术状态**的权威快照,基于对当前代码 HEAD 的实测核对(非台账转述)。
> ⚠️ 取代 `docs/未完成工作清单.md` 作为技术状态视图——那份是 2026-06-12 修复**之前**的快照,其"列表不过滤/按钮死桩/弹窗嵌整页"等项**均已修复**(详见 §4)。
> 商务/人工依赖见 §8;架构总纲仍以 `eip4-platform/docs/架构设计.md` 为准。
>
> 对齐 HEAD:eip4-platform `f4b6e37`(2026-06-13 夜写路径主线后) / eip4-web `693a857`。
> **【2026-06-13 夜·写路径主线进展(本文档增量,§7 路线对应推进)】**
> 经 5-agent 对代码核验 workflow 拍板后,落地写路径全部前置 + 平台前置,**6+1 原子提交**(eip4-platform main):
> - **A0** `06dd127` UiTypeMapper 补 PasswordField→input-password / SingleFileUploadField→input-file / DateField→input-date(default 三控件)。
> - **A1** `b28bff2` EditGrid/FormEditGrid 子表列递归 mapField→quickEdit(子表内 Select/Combo/Number/Date 不再退化文本)。
> - **A2** `3735a9b` convertForm 解析 `<layout>` 多 `<tab>`→amis tabs(72 页多页签原塌平;正则提 `<div location>` 归位;width/colspan 像素版面后置)。
> - **A3** `9ee3ef2` **遗留②编辑表单迁移**:view_page(1241)→sys_page_schema(dispatcher 加 `case "page"`/key=raw view_page_id PK 冲突实测 0/resolveEditFormTemplateId 命中返 pageId)。全量重转上线(2757 产物,view_page 1241 入库 1238 为 form),运行时实证 `/api/page/schema/{view_page_id}` 返真实表单——**「查看」点亮**。
> - **B1** `72e4c6d` **遗留① JUEL**:platform-app 接 jakarta.el JSR-223 "juel" 引擎(惰性注册接缝,零改保真层 com.dsasp.*,不引 activiti)。
> - **B2** `c721bde` JUEL 跨流回归:153 真实 conditionExpression × 9 场景=1377 次新旧引擎差分,**完全等价 1376/真实偏移 0/良性差异 1**(null-base 方法调用)。
> - **C1** `f4b6e37` 补读 requirederror→validationErrors.required / minlength→minLength。
> - **运行时激活**:8093 重启为含 B1 的新 jar;**添加端到端实证落库**(OA_NOTICEMANAGE_ADD status:0,服务流设拟稿人/部门/时间)。
> - **依赖链现状**:删除✅ / 查看✅ / 添加·修改 表单+引擎+语义+端到端落库 均实证✅(余逐流写 QA)。**§4.2 中 projectRoleType、深链接 两条经代码核验已证伪,见下表更新。**
---
## 一、架构全景:双层制元数据引擎
EIP4 把老系统(EIP3:OSGi/Vaadin7/Activiti5 低代码平台)重构为 **amis + Spring Boot 3 + Flowable**。
**核心决策:"保真层供奉,现代层生长"** —— 1956 行 SQL 引擎**原样回迁不重写**(包名 `com.dsasp.*` 不动)。理由:它的价值就是和老系统逐字节一致,是逐行对拍的基线、业务数据零搬迁的载体、老员工认知的延续。新能力在外面长(`com.eip4.*`)。ArchUnit 固化纪律:`com.eip4.*` 可调 `com.dsasp.*`,反向禁止。
**单客户交付 = 4 进程**:`nginx + eip4-platform.jar + flowable-service.jar + postgres`。不上 Redis/MQ/ES(每多一个中间件 = 每个私有化客户终身多一份运维负担),元数据缓存用进程内 Caffeine。
### 模块全景(8 模块,Maven 单体)
| 模块 | 职责 | 状态 | 规模/测试 |
|---|---|---|---|
| **platform-legacy-core** | 保真层:回迁引擎(POJOCRUDService/服务流引擎/脚本引擎/数据权限) | ✅ 核心全通 | 21.4K LOC / 132 测试 |
| **platform-metadata** | 现代层:amis schema 端点、实体 CRUD、写流派发、picker、引用列解析 | ✅ P1 完成 | 7.3K LOC / 239 测试 |
| **platform-converter** | view_template.xml → amis schema 转换器 + CLI 跑批 | ✅ 核心通,缺高级模板 | 1.9K LOC / 58 测试 |
| **platform-auth** | JWT 无状态认证 + 角色/数据权限网关 | ✅ 真实现(非桩) | 1.2K LOC / 34 测试 |
| **platform-flow-gateway** | Flowable 客户端 + 待办/已办聚合 + 状态回写 | ✅ P3 可用 | 1.2K LOC / 34 测试 |
| **platform-parity** | 逐行对拍框架(C1 一级交付物) | ✅ 生产就绪 | 3.4K LOC |
| **platform-app** | Spring Boot 装配 + ArchUnit 边界纪律 | ✅ | 扫 `com.eip4.*`+`com.dsasp.*` |
| **platform-ai** | P5:MCP Server | 🔴 纯占位 | 0 LOC |
全工程 ~36K LOC,496 测试全过。脚本引擎有个小保留:`FlowScriptBindings`/`GeneralPOJOBindings` 各 9 个容器方法是 `UnsupportedOperationException`,但 get/put 可用,不阻断脚本执行。
前端 **eip4-web**(React 18 + amis 6.13.0):4 业务页 + 设计器入口;15 个 e2e spec / ~252 用例,7 个强断言(真渲染+DB校验)。**amis-fork 纯上游 6.13.0 零定制**,所有定制在 eip4-web(自定义 fetcher / orgId 注入 / 脚本重放)。
### 核心数据流(已打通)
```
view_template.xml ──BatchConvertCli──▶ amis schema ──入库──▶ sys_page_schema
│ (overlay 优先)
浏览器 /page/:id ──▶ PageRenderPage ──GET /api/page/schema/{id}──┘
列表查询 ──▶ GET /api/flow/{TABLE}_SEARCH (合成搜索流, 过滤+分页)
选人 ──▶ GET /api/picker/{dialogid}/list (搜索+分页+权限隔离)
写/动作 ──▶ POST /api/flow/{servicename} (服务流引擎: 拟稿人/时间戳/审批/级联)
脚本 ──▶ onEvent → /api/script/execute-template → 前端重放 facade 指令
```
写路径已正确接回服务流(不再绕过引擎裸存),读写门按 contentxml 真实方法分类(写流仅 POST + 真实用户上下文)。这是整个迁移最关键的架构正确性,已经立住。
---
## 二、已实现(按层)
- **后端引擎**:CRUD / 服务流 / 脚本引擎 / 数据权限全回迁生效;对拍 21 实体逐行 100% 一致
- **认证授权**:JWT 登录、行级数据权限(读端 `DataPrivilegeService` WHERE 下推 + 写端 `WritePrivilegeChecker` 逐行)、picker 权限隔离——都是真实现
- **元数据驱动 UI**:list/form/tree/report/group 五类模板转换;分页/排序/搜索/金额列/枚举映射(F2-16 `type:mapping`)/日期格式/人员列 id→姓名(运行时 `UserColumnResolver`,568 列)
- **编辑表单**(本会话修):显式行布局、富文本满行、单层标题、弹窗剥壳、`{ids}` 批量删除/审批扇出
- **Flowable**:待办/已办/发起/审批/trace 可用,独立 8089 服务
- **设计器**:amis-editor 三屏 + overlay 双层(标准层=转换器产物升级整体替换;overlay=管理员手调,优先级更高)
---
## 三、本会话已修(2026-06-12 ~ 06-13)
针对"添加界面不可用"截图(富文本塌成竖条 + 三层标题嵌套),已提交 4 个原子提交:
| 提交 | 内容 | 根因 |
|---|---|---|
| `52c7397` (converter) | 编辑表单显式行布局:废 `columnCount`/`colSize`,窄字段两两成 `group` 行、宽控件独占整行;去 `form.title` 重复;弹窗 `size:lg` | amis 6.13 的 `columnCount` 是纯 CSS 等宽列,`colSize` 在该模式下被整体忽略 → 富文本被塞半栏,TinyMCE 菜单挤成竖条 |
| `a021f33` (metadata) | `format=amis` 剥 page 壳:弹窗只渲表单本体 | 弹窗经 service 加载整页 schema,page.title 叠 dialog 标题 = 三层重复(D4 运行时修复) |
| `e2c5d43` (metadata) | amis `{ids}` 批量形态适配:按流 `<input>` 必填 `*_ID` 逐 id 扇出执行 | bulkActions 只送 `ids=主键逗号串`,而老服务流 `<input>` 声明单条必填主键 → 透传 ids 必填缺失 500、行未删(API 实证)。这是删除/提交审批/文件归档全链断裂的根因 |
| `aeecaac` (eip4-web) | 删除 e2e 断言对齐老系统软删语义(`ISDEL=1`,不动 `ISACTIVE`) | 删除已走服务流 `OA_NOTICEMANAGE_DELETE`(start 脚本 `map.put("ISDEL",1)`) |
| `662828c` (converter+metadata) | **列表引用列 id→显示名通用化**:resolver 推广到任意引用实体 + 产出 `<COL>_DISPLAY__` 平行字段保留原始 id;转换器引用列绑 `_DISPLAY__`;虚拟显示列兜底物理 NAME | 老引擎给每列算 `_DISPLAY__`、Vaadin grid 绑显示值;amis 后只补了用户列+枚举/日期,通用引用列显示裸 id(根因见 §5) |
验证:converter 60 测试 + metadata resolver 9 测试全过;e2e f2-17 5/5 绿;`{ids}` 删除 API 实证 status 0 + `isdel=1` 落库;浏览器真渲染确认弹窗单层标题/富文本满行,以及 OA_OFFICE_COLLARAPPLY 申请人=系统管理员[admin]/申请部门=法务合约部/用品仓=lll办公用品0412(原始 id 全保留,表单安全)。
---
## 四、已知缺口(与当前 HEAD 对齐)
### 4.1 已修复(核对确认,不在缺口内)
`未完成工作清单.md` 列为"待修"但实际已修:A1 列表过滤(`f5850a8`)、A2/A4 按钮死桩→EDITFORM 映射(`29199e6`/`34c2928`)、B1 弹窗嵌整页(`a021f33`)、E8 页面标题「测试」、E9 报表 500(`maven.compiler.release=21` 已设)、E12 登录跳转、A5 人员列裸 id(`UserColumnResolver`)、A6 富文本错配(`37db794`)。
### 4.2 真·剩余缺口
| 缺口 | 类别 | 影响面 | 状态 |
|---|---|---|---|
| ~~通用引用列 id→显示名~~ | 元数据机制 | 广(凡引用列) | ✅ **已修**(`662828c`+`2a6c1d0`,2026-06-13):resolver 推广到任意引用实体 + 产出 `_DISPLAY__` 保留原始 id;转换器引用列绑 `_DISPLAY__`;虚拟显示列(如 SYS_DEPART.FULLNAME)兜底物理 NAME。实证申请人/部门/仓库均出名称。(注:`662828c` 当时仅提交了通用化测试,resolver/converter 实现漏入暂存区,`2a6c1d0` 补齐使 HEAD 自洽) |
| ~~**SelectDialog 弹窗形态降级成下拉搜索**~~ | 控件走样 | 150 dialogId / 911 页 | ✅ **已修**(`9d92df2`,2026-06-13):SelectDialog/MultiSelectDialog → amis picker 多列对照弹窗(搜索+分页)。降级注释「6.13 schema 未纳入 picker」核实**失实**——picker 表单项过得了闸一(已加测固化)。列由运行时 `/api/picker` 随 `data.columns` 提供(转换器不解析跨模板 dialog XML,§6 对齐);PickerController 每行补 `_label` + 返回多列(displayname 友好标签)。浏览器实证:加班登记 USERID 弹窗多列(显示名称+帐号)、186 页分页、选中回填 `_id`(36 位 UUID)、chip 显显示名 |
| ~~initvalue/defaultvalue 两阶段求值未迁移~~ | 元数据机制 | 全库依赖初值的页(1288 模板) | ✅ **已修**(`009ddf8`+web`d823264`,2026-06-13):UiTypeMapper 相一字面进 `value`、相二动态 token({CURRENTUSER}→${currentUser}/{CURRENTORG}→${orgId}/{CURRENTTIME}→${now}/{CURRENTPROJECT}→${currentProject})由 AmisRenderer 注入数据域求值;AUTOGENERATECODE(6 模板)+未识别 token 诚实降级。实证外部邮件收件箱搜索携 FOLDER=0。 |
| **onselectedscript / filterscript 未挂回** | 脚本 hook | 行选中控按钮、选择框过滤 | ⏸️ **未做(依赖前置)**:核查发现 `full_auto_index.json`(507 条)只记 `{template_id,seq,rules}`,**不保留脚本来源事件类型**(onload/onselected/filter);现有 `attachScriptOnEvent` 把所有 seq 一律挂 `inited`+`change`。要把 onselected→CRUD 行选事件、filter→选项动态过滤分别接对,需先让 s3_rewriter 在索引里标注脚本来源事件类型 + 转换器按类型映射 amis 事件——属 rewriter 管线改造(跨 Python+Java+amis 事件语义),非纯接线,且本 dev 环境脚本管线未激活(index 路径错位致 onload/onchange 也未挂),无法端到端验。留待 rewriter 管线专项。 |
| ~~**高级模板类型缺失**~~ | 模板覆盖 | 子表/树表/日历/审批表单 | ✅ **数据判定不做**(`ba34487`,2026-06-13):频次审计精确口径下 EditGrid/MasterSubGrid/TreeGrid/Calendar/Wf 在本客户库 1489 模板**全 0 存量**;转换器既有 `EditGrid/FormEditGrid → input-table` 子表分支足以兜底任何未来出现。跨模板引用(group)仍为占位,但 group 根仅 20 模板,低优先 |
| ~~**真丢失控件**~~ | 控件覆盖 | TwinColSelect/PasswordField | ✅ **数据判定不做**(`ba34487`):TwinColSelect=0、PasswordField=0,零存量 |
| **LIKE 搜索裸拼 SQL** | 安全 | picker/list 查询端点 | 🟡 **风险已澄清(2026-06-13 实测)**:引擎 GeneralPO 对 String LIKE 条件**自动双写单引号**(实测 `TITLE=x'` → SQL `like '%x''%'`,注入不可逃逸),故 _SEARCH/list **非可注入**;picker 端另有 escapeLikeValue 兜底。残余仅「通配符 `%`/`_` 未中和」(list 端)——属搜索语义/性能,非注入,低优先。P2 渐进参数化仍可做防御纵深,但非开放漏洞 |
| ~~projectRoleType 候选人解析 ~91%~~ | Flowable | 528 处表达式 | ✅ **核实已闭环**(2026-06-13,`OrgDirectoryJdbc.java:33-46/116-144` 按 PROJECTID 直查 + 单测,非降级)。原描述失实;真正残留=`scriptUser`(26 处≈0.5%,仅 `System.out` 告警→宜升 `log.warn`) |
| **报表 B 图表 / C 类 JOR** | 报表 | 45 个 JOR 模板 | A 类 333✅;C 类待 univer 替换方案 |
| ~~深链接被 Tab 吞~~ | UX | 直开 /page/:id | ✅ **已修**(F2-13,`AppShell.tsx:80-95` 直开 /page/:id 自动建 Tab + 标题回填) |
### 4.3 静态审计"失明"项(运行时已修,审计数字不降)
`schema_reality_audit.py` 扫的是静态产物,以下项**已在运行时修复但审计数字不变**——这是审计工具盲区,不是真缺口,后续要改用 e2e 验:
- D1 人员列裸 id(603 页)→ `UserColumnResolver` 运行时解析
- D4 弹窗嵌整页(108 页)→ `format=amis` 剥 page 壳
- D6 不分页(1293 页)→ FlowController 分页翻译
> ~~**行动项**:审计脚本需升级~~ ✅ **已做**(`41eb339`,2026-06-13):`schema_reality_audit.py` 把 D1/D4/D5/D6 标「运行时已修(审计盲区)」、`--db` 加 **uitype × 模板根类型 × 频次**统计(扫 `view_template.xml` 存量真实用量)。真实基线见 `docs/F2-17-审计基线-2026-06-13-升级.md`。**关键发现**:SelectDialog 涉 940 模板(印证 picker 单点回报最大);**高级模板结构(EditGrid/MasterSubGrid/TreeGrid/Calendar/Wf)精确口径下全 0**(早期子串口径把脚本注释文本「addButton到EditGrid」虚计为 55,已修正);**真丢失控件 TwinColSelect=0、PasswordField=0**。即 §7-4 全部子项在本客户库零存量。picker 上线后 SelectDialog 降级 1783→225,分级 SUCCESS 114→283(+169 页)。
---
## 五、根因专题:列表显示 id vs 老系统显示名称
**结论:老系统的"id→名称"是引擎自带能力(给每列额外算显示值);EIP4 复用同一引擎,但换掉了消费这个显示值的前端层(Vaadin grid → amis),换的时候只补了部分列的解析,通用引用列漏了。**
### 老系统机制(代码实证)
老引擎每行经 `GeneralPO.toMap()`(`GeneralPO.java:2411`)给**每一列**输出两个键:
```java
map.put(key + "_DISPLAY__", po.get_DisplayValue(...)); // 显示值(名称)
map.put(key, po.get_Value(i)); // 原始值(id)
```
`get_DisplayValue`(`GeneralPO.java:1311-1313`)对引用列:
```java
} else if (dt.length() == 36) { // DisplayType 是 36 位 UUID = 引用了另一实体
return m_custom.get(columnName); // 返回预解析的目标实体显示名
}
```
即:列若引用别的实体(DisplayType = referenceid UUID),引擎按 `referenceid → SYS_REFERENCE → 目标实体显示列`,在查询时用 `LEFT JOIN lateral`(`POInfo.java:442-457`)把 id 解析成名称存进 `m_custom`。**Vaadin grid 列绑定的是 `_DISPLAY__` 值,不是原始 id**。所以老系统引用列/枚举/日期/金额全自动显示成人类可读值,前端零代码——这是元数据驱动引擎的内建红利。
### EIP4 为什么显示 id
EIP4 **回迁同一引擎**,这套能力其实还在,但链路两处断:
1. **序列化层不带显示值** —— 实测 `/api/flow/OA_NOTICEMANAGE_SEARCH` 返回 23 字段,`_DISPLAY__` 键数 = **0**,`USER_ID`/`ORGID` 全裸 id。合成搜索流 → FlowController → JSON 这条路没走 `toMap`,只吐原始值。
2. **amis 列绑原始列名** —— 转换器生成 `{name:"USER_ID"}`,amis 显示原始 id。
老系统的显示解析本在 Vaadin grid 层,被 amis 替换时只重新实现了部分列:枚举/状态(F2-16 `type:mapping`)✅、日期(`type:date`)✅、**用户引用列**(补丁 `UserColumnResolver` 运行时,只认 SYS_USER)✅、**其它引用列(项目/部门/单位/任意实体)→ 无人管,显示裸 id** ❌。
### 修复成本低(引擎已会算,缺的是接回前端)
- **首选**:把 `UserColumnResolver` 从"只认 SYS_USER"推广成"按 `referenceid` 解析任意引用实体的显示列"(复用 picker 已有的 `displayColumn` 逻辑)——一处改动覆盖全部引用列。
- 备选:让搜索流序列化带 `_DISPLAY__` + 转换器把引用列绑显示变体——更贴近老系统原生,但改序列化契约+转换器两处。
→ 采首选。它和"选择器统一"是**同一套 `displayColumn` 机制**,一起做最省(见 §7)。
---
## 六、新增功能架构(待拍板)
**问题:目前整套机器是迁移/兼容引擎(读老 XML → 转 amis → 渲染)。迁移完,新系统怎么加老系统没有的新功能?**
### 关键认知:系统里有两种"元数据",未来命运不同
| | 是什么 | 未来 |
|---|---|---|
| **数据/行为元数据** | `SYS_ENTITY`/`SYS_ENTITYATTRIBUTE`(实体模型)、`SYS_SERVICEFLOW`(业务逻辑)、引用/权限 | **保留,作为正向 authoring 模型** |
| **视图元数据** | `view_template.xml`/`view_page.xml`(Vaadin 时代 XML)→ 转换器 → amis | **冻结,只用于迁移,最终退役** |
因为后端引擎**本身就是元数据驱动**:往 `SYS_ENTITY` 插实体 → 引擎自动动态建表 + CRUD(`/api/entity`)+ 标识符白名单 + 类型强制 + 数据权限,全免费;往 `SYS_SERVICEFLOW` 写流 → 引擎自动跑默认值/校验/级联/审批。这套是平台真正可持续的价值。而 XML→amis 那条链是**为搬老页面才存在的翻译层**,新功能从没需要过翻译。
### 目标姿势:新增一个业务功能
1. **定义数据** → `SYS_ENTITY`/`SYS_ENTITYATTRIBUTE` 建实体 → 引擎自动给 CRUD/权限/建表
2. **定义行为**(若需要)→ 写服务流 contentxml(默认值/校验/审批触发)→ 引擎执行
3. **画页面** → amis 设计器**直接写 amis schema** 进 `sys_page_schema`,**不经过 XML、不经过转换器**;列表指向 `/api/flow/{TABLE}_SEARCH` 或 `/api/entity/{table}/list`,表单指向 `/api/flow/{servicename}` 或 `/api/entity/{table}/save`
4. **挂菜单** → templateId
一句话:**引擎 + amis 是运行时,XML 转换器是一次性导入工具,迁移完退役。新功能永远不碰 XML。**
### 要让它成真,缺三个工具 + 一个设计决策
**三个 authoring 工具(现在都没有):**
- **实体建模器**(计划 F4-L2):可视化建 `SYS_ENTITY`,不裸写 SQL
- **设计器"新建空白页"**:现在 `DesignerPage` 只能 overlay 已转换的存量页(templateId 必须已存在),不能从零建页
- **服务流设计器**(F4-L3)或至少 contentxml 编辑助手
**一个必须明确的设计决策——新页面的 source of truth 放哪:** 现在 `sys_page_schema` 是"标准层(转换器产物,重迁移整体替换)+ overlay(手调)",**假设底下永远有转换器基线**。但新建页没有 XML 基线——它本身就是基线。建议加来源标记 `source = 'converted' | 'authored'`:converted 页可被重转覆盖;authored 页是手写的、永不被转换器碰。这样重跑迁移不清掉新功能,新功能也有干净的家。
**逃生口:** 真正低代码表达不了的(自定义看板、第三方集成、复杂交互)→ 直接手写 Spring REST + React 路由,与 amis 页并存。别强行什么都塞进引擎。
### 时序建议
- **近期**:迁移收尾(§7),让存量可用。这期间**不再加深转换器对 XML 的耦合**,新机制一律按"amis 原生"形态做,为退役转换器铺路。
- **中期**:迁移到"大部分页能用 + overlay 兜底"水位后,启动 F4-L2 实体建模器 + 设计器新建空白页 + `sys_page_schema` 加 `source` 标记。这三件到位,新功能彻底脱离老系统,转换器降级成纯导入工具。
---
## 七、下一步路线
整个项目的架构骨架已立住(双层制 + 写回服务流 + 对拍守护),现在是 **P4 收尾期**——从"跑通"到"生产级可用"。按回报排序:
1. ✅ **通用引用列 id→显示名 + 选择器弹窗化(同源,已完成)** —— 单点回报最大。两者都用同一套 `displayColumn`(按 `referenceid` 找显示列)机制。
- ✅ **引用列"列表显示 id"已修**(`662828c`+`2a6c1d0`,2026-06-13,见 §3)
- ✅ **选择器弹窗化已修**(`9d92df2`,2026-06-13):SelectDialog/MultiSelectDialog → amis picker 多列对照弹窗。半小时复核结论:降级注释「6.13 schema 未纳入 picker」**失实**,picker 过得了闸一(已加测 `schemaGate_picker表单项过闸一`),无需改 amis-fork。列由运行时 PickerController 随 `data.columns` 提供(转换器零跨模板 XML 耦合,§6 对齐),浏览器端到端实证通过(多列+搜索+分页+回填 `_id`)
2. ✅ **审计工具升级 + 真实基线已做**(`41eb339`,2026-06-13)—— D1/D4/D5/D6 标运行时项改 e2e 验;`--db` 加 uitype/模板/频次统计。基线数据见 §4.3。
3. **initvalue 两阶段求值 + onselectedscript/filterscript 挂回** ——
- ✅ **initvalue 已修**(`009ddf8`+web`d823264`,2026-06-13,全库 1288 模板):字面进 value + 动态 token 前端数据域求值。见 §4.2。
- ⏸️ **onselectedscript/filterscript 未做**:核查发现非纯接线——`full_auto_index` 不保留脚本来源事件类型,需先改 s3_rewriter 管线标注事件类型再按类型映射 amis 事件,且本环境脚本管线未激活无法验。详见 §4.2 该行。
4. ✅ **高级模板类型 / 真丢失控件 —— 数据判定全部不做**(`ba34487`,见 §4.3 基线):精确口径下高级模板结构(EditGrid/MasterSubGrid/TreeGrid/Calendar/Wf)与真丢失控件(TwinColSelect/PasswordField)在本客户库**零存量**;转换器既有 EditGrid→input-table 分支兜底。§7-4 由数据判定关闭。
**本会话上线状态(2026-06-13)**:§7-1/§7-3 的转换器改进(picker / 引用列 _DISPLAY__ / initvalue)**已正式部署到服务层** —— 用正确 rewriter 路径(`output/`,保留 onEvent 380 模板)重跑 BatchConvertCli 生成 1489 产物,经 `SchemaImportCli` 导入 `sys_page_schema`,实证加班登记标准层无 overlay 直出 picker 多列选择窗 + onEvent。overlay 手调层不动。故这些改进对全部存量页生效,非仅代码。
**本会话 QA 巡检(2026-06-13,运行时 dogfooding 找成类 bug)**:静态扫全 1489 schema + 运行时 API 分层抽样,修复 5 类缺陷,均已重转+重导入上线:
- **空结果集列表崩**(凡 0 行列表页报「data.items 必须是数组」)→ FlowController.normalize 空集也拍平 {items:[],total:0}(`ea0b68d`)。
- **ComboBox 枚举下拉空数据**(51 模板,comboboxid 空+itemisenumerate)→ 取列 enumeratetype 作字典源(`ea0b68d`)。
- **YEAR/MONTH 下拉空**(27 字段)→ 转换器内建生成年/月静态选项(`012ab21`)。
- **report 无 selectservice 兜底端点 404**(12 报表页)→ 改兜合成 _SEARCH(`e6054a3`)。
- **引擎异常裸 500**(实体登记但物理视图缺失)→ FlowController 兜成 200+status:1 友好提示(`e6054a3`)。
- 剩余:静态 group「跨模板子模板」占位 87(架构项,§6 跨模板);5 个 itemisenumerate=false 无源 select(老系统本无源,诚实降级);运行时 ~10 个 `VIEW_*/VM_*` 报表视图在 dev 副本物理缺失(生产存在,现优雅降级,**非产品缺陷,属 dev 数据缺口**)。
**全量运行时巡检(2026-06-13,1489 页 list+499 去重 source 并发打端点)——最大发现是环境问题:**
- 🔴 **【关键环境】dev 平台须跑 JDK 21,不可用 JDK 26**:实测 JDK 26(class major 70)下,老引擎服务流的 **Groovy 4.0.27 脚本编译崩**(`AsmDecompiler: Unsupported class file major version 70`,`GroovyBugError`),致 **35+ 个带 Groovy 脚本的命名查询流(`*_SEARCH_LISTINFO`/`*_SZWJ` 等)直接 500**。换 JDK 21(项目 `maven.compiler.release=21` 目标、生产口径)后**全部恢复**(如 PM_LABORCOMPANY_SEARCH_LISTINFO 返 57 行、PM_SPECIALTY_SUBPACKAGE 1305 行)。已 `brew install openjdk@21` 并把平台切到 21。**启动命令须 `JAVA_HOME=/opt/homebrew/opt/openjdk@21`**(flowable-service 建议同切)。生产用 21 故无此问题。
- 巡检剩余分类(JDK 21 下):`LIST_DEVDATA_GRACEFUL` 289 + `VIEW_*_SEARCH` 404 共 ~320 = **dev 库缺视图/缺实体登记**(生产存在,非缺陷;404 类实体在 dev 连 SYS_ENTITY 都没登记);`LIST_ITEMS_NOT_ARRAY` 6 = 并发巡检假阳性(直连返正常 items);`SOURCE_EMPTY` 66 = 半为空 picker(dev 数据)半为 ComboBox 的 comboboxid 指向查询服务而非枚举(错配 /api/poc/dict)。
- ~~**真·剩余代码缺口**:`/api/template/{id}/tree|list` 占位端点 83 处 = TreeGrid 树模板渲染~~ ✅ **已修**(`4337720`,2026-06-13):新增 `TemplateTreeController` 运行时构树端点(`GET /api/template/{ref}/tree`,解析 `<node>/<levelnode>` 按各级 parentid 链父,支持自嵌套+跨实体);转换器 convertTreeGrid 改:左树走该端点 + onEvent 重载右表,右表复用 `/api/flow/{gridTable}_SEARCH?{rcol}=${tree}`(原 /api/template/list 不存在),右表列取自 gridtemplate 引用模板 display;并修 flex→grid 布局。浏览器实证「查看大事记管理」左树分类层级渲染 + 点节点右表 reload 携 EVENTID。重转分级 SUCCESS 283→328。
- ⚠️ **TreeGrid 二次 QA 发现 `4337720` 只做通 happy path,两处运行时缺陷已补修**(2026-06-13,浏览器 dogfooding):
1. **左树只显示一半**(全 45 个 treegrid 页):amis `.cxd-Tree--outline` 默认 `max-height:300px`,多级分类树露一半、下方大片留白。修法(终版):转换器给 input-tree 挂 `className=eip4-treegrid-tree`,eip4-web `amis-theme.css` 把该类内 `.cxd-Tree` max-height 抬到 `calc(100vh-230px)`+内部滚动(填满视口、超出树内滚)。注:先试过 `heightAuto`(随内容无限撑高,大树拉爆页面,用户否)与内联 `style`(只落外层 form-item、压不到内层滚动容器,无效),均弃用。浏览器实证树高 615px、底部 783<视口 845。
2. **点父/中间节点右表「暂无数据」**(29 个多级 type-4 树):右表按 `{rcol}=${tree}` 精确匹配点中节点自身 id,而业务行常只挂叶子(文件挂「技术部」非父级「技术中心」),点父级 0 行。**老系统点父级聚合整棵子树**。修法:新增 `GET /api/template/treegrid` 子树聚合端点——解析「点中节点+全部后代」id 列表,以 `List` 值委托合成 `_SEARCH`,引擎 `GeneralPO.get_SearchWhereClause` 见 List 即构 `rcol IN (...)`(已转义,无注入面,**无需改保真层**),复用 _DISPLAY__/数据权限/分页;转换器右表 api 改指该端点(`treeRef`/`gridTable`/`rcol`/`node=${tree}`)。`TemplateTreeController` 补 7 个单测(构树/子树/IDENT 守卫/委托),转换器 60 测全过。浏览器实证:资料库点父级「技术中心」现出子级「技术部」文件(修前空);单级树「通知收藏」点叶子仍正确过滤(无回归)。已重转 1489 产物 + SchemaImportCli 导入(445 更新)上线。
- ✅ **TreeGrid 三次 QA 补「操作」(2026-06-13,用户追问「列表上面的按钮都有了吗」)**:`convertTreeGrid` 此前只做「看」,45/45 页左树+右表操作按钮全丢。已补:
1. **树高度终版**改 className+CSS(见上,撤回 heightAuto)。
2. **右表工具栏**(添加/修改/删除/查看):读 gridtemplate 引用模板 `<button>`,复用 `collectButtons`/`buildToolbar`(与普通 list 同源,含 EDITFORM 映射 + 删除走 bulkActions `${ids}`)。
3. **左树分类节点增删改**:treetemplate 引用模板 `<node><buttons>` → amis InputTree 原生 `creatable`/`editable`/`removable`/`rootCreatable` + `addApi`/`editApi`/`deleteApi`(配 `source` 自动重拉刷新);add 送 `{名称列:${label},父列:${parent.value}}`、del 送 `{主键:${value}}`,名称列/父列由元数据(`isentitydisplay`/levelnode parentid)解析。转换器 60 测全过。浏览器实证:树高视口填满、右表 4 按钮渲染、左树 `➕添加一级节点`+悬停节点 `+−✎`、**删除端到端 `status:0` 通**。
- 🔴 **遗留①(写流引擎缺口,非接线问题)**:左树**添加/修改**(及右表文件新增等任何走 EL 表达式求值的写流)被引擎 `Can't find scripting engine for 'juel'` 阻断 → `status:1`。`juel` 字面在 4983 流 contentxml 中出现 **0 次**,是引擎对 EL 的**默认引擎名**——本运行时未注册 JUEL JSR-223 引擎。**影响面=所有 EL 写流,非仅 treegrid;属保真层相邻平台任务**:`platform-legacy-core`/装配层注册 JUEL ScriptEngineFactory + 跨流回归。删除流不走 EL 故正常。(用户拍板:登记为独立平台任务,本轮不动)
- 🔴 **遗留②(编辑表单迁移缺口,全系统级)**:按钮「添加/修改/查看」弹窗提示「该单据未配编辑表单」的根因——**编辑表单是 `view_page`(全库 1241 个,带完整 `<fields>`),而 `BatchConvertCli` 只遍历 `view_template`(1516),这 1241 个编辑表单从没转换/导入 `sys_page_schema`**;弹窗解析器 `resolveEditFormTemplateId` 只在 type=7 包壳模板(全库仅 70 个)里按 pageid/entityId 找,指向独立 view_page 的按钮(绝大多数)全部命中不到 → 降级占位。**这是 F2 写路径「编辑表单迁移」一直未做的步骤**,非 treegrid 特有(treegrid 右表按钮只是把它暴露出来)。修法:遍历 view_page→amis form(复用现有 `convertForm`/view_page 解析器字段逻辑)入 `sys_page_schema`,解析器命中已转 view_page 时直接返回 pageId。补完后**「查看」立即全可用**、添加/修改表单可显示(提交仍待 juel)。(用户拍板:登记为独立任务,本轮不做)
- 即:**真实「添加/修改」端到端可用 = 编辑表单迁移(遗留②,表单界面) + JUEL 引擎(遗留①,提交执行) 两个前置都补齐**;「查看」只需遗留②;「删除」已可用。
- 次要待办:ComboBox comboboxid=查询服务(非枚举)时应路由 /api/flow 或 /api/picker 而非 /api/poc/dict(SOURCE_EMPTY 约半数);group「跨模板子模板」占位 87(§6 跨模板,架构项)。**TreeGrid 仍后置**:type=3 声明式多级树 53 页仍走 `selectservice`+deferApi 占位未接 `/api/template/{ref}/tree` 端点。
**先不碰**:platform-ai(MCP,P5);转换器对 XML 的深度精度(已死格式,低 ROI)。
---
## 七·补、主动覆盖度审计缺口地图(2026-06-13)
> 前述缺口多是浏览器 dogfooding 被动撞出的;本节是**主动盘点**结论——按模板 type、编辑表单 uitype、编辑表单结构、运行时端点四维,把源数据存量对照转换器分支+运行时可达性扫出的缺口。
> **完整证据与计数见 `docs/转换器覆盖度审计-2026-06-13.md`**(4 并行审计 agent + curl/浏览器抽验 + 代码核对);此处仅列按优先级排序的清单。
**P1 — 正确性/安全(小量必修)**
- 🔴 **type=5 日历视图(2:单个员工排班/查看会议室调度)转成普通 crud 表格** → 班次/日历语义全丢(浏览器实证渲染成查询表单+空网格)。应映射 amis calendar/fullcalendar。
- 🔴 **编辑表单 default 控件**:PasswordField(明文,安全)/SingleFileUploadField(41,丢上传含证件照)/DateField(1,丢日期)落 `default→input-text`。各 1 行/复用即修,**迁移编辑表单前先补 UiTypeMapper**。
- 🔴 **VIEW_/VM_ 报表端点 ~46 个/影响 ~277 页**:dev 缺聚合视图,需 DBA 确认生产视图存在性(生产有=dev 数据缺口;无=真建视图+注册服务流)。
**P2 — 编辑表单迁移(遗留②)必须连带做的质量项**
- ⚠️ **EditGrid/FormEditGrid 子表列硬写 input-text 不递归 UiTypeMapper** → 637 子表里 SelectDialog/ComboBox/NumberField/Date 全退化文本、178 子表联动丢失 → buildEditGridColumns 改为对子表字段递归 mapField。
- ⚠️ **多页签 `<tab>` 布局(72 页)** + **width/colspan 精确布局(875+)** 丢失(convertForm 跳过 `<layout>`,平铺等宽两列)。
- ⚠️ **requirederror(1237)/minlength(1219)** 未读取。
- ⚠️ 编辑表单 **SelectDialog/MultiSelectDialog ~97% 无 dialogid** 降级 select、**ComboBox 339 查询服务源** SOURCE_EMPTY(需运行时按字段/实体元数据补数据源,列表页 picker 同源机制延伸)。
- ⚠️ **页面级 `<scripts>` 联动(601 页)** part-handled,依赖脚本改写器管线(与 §4.2 onselected/filter 不同管线、不同阻塞点)。
**P3 — 决策/低成本/已知后置**
- **type=6 group(20)**:子模板 62/62 已各有产物,前端 tabs 按 tempid 拉 `/api/page/schema/{tempid}` 即可激活(**前端路由活,非转换器缺口**)。
- **type=100/101(130)选择窗死页**:无菜单关联、运行时由 `/api/picker` 承接、不读这些 schema → 决策停转 or 留 F4 弹窗预览。
- **report B 图表(4,`ischart=true`)** 降级纯表格、**C 类 JOR 套打**版式丢失(另案 amis chart/univer)。
- **type=3 声明式多级树(53)** 未接 `/api/template/{ref}/tree` 端点。
**端点引用实况(修正并行 agent 误判)**:产物 `/api/flow *_SEARCH` 1345 页、**`/api/picker` 911 页(1948 次)**、**`/api/poc/dict` 728 页(1683 次)**、`/api/template/treegrid|tree` 45、`/api/page/schema` 109(多指向未迁移 view_page→「未配」)。`_SEARCH` 抽样(N=300):有数据 55% / 空(dev 缺口)42% / status:1 降级 2.3% / 错 0.7%。
**写功能依赖链(一句话)**:真实「添加/修改」端到端 = 遗留②编辑表单迁移(连带 P2 全部)+ 遗留① JUEL 引擎;「查看」只需遗留②(+P2 部分);「删除」已可用;P1 与之并行(小修+报表数据源确认)。
---
## 八、外部 / 人工依赖(技术线推不动)
| 阻塞 | 卡住什么 |
|---|---|
| **S1 止损评审会**(153 定制视图 7.56 人月三选一:分期/第三方组件/扩预算) | 卡 F3 主线启动 |
| **11 个引擎读路径缺陷待旧系统同病验证** | 同病=保真不改,独病=移植 bug 要修——优先级定不了 |
| **检查点①/② 商务闭环 + 客户签字矩阵** | 卡首批切流 |
| **1854 账号无盐 MD5 弱口令** | 安全建议书,切流后推升级 |
| **PG 9.4→15 / Flowable 5→6 生产升级窗口** | Runbook 就位,待客户隔离准生产环境演练 |
---
**维护**:本文档随 §7 路线推进滚动更新;§6 新增功能架构待拍板后,转为正式架构决策回写 `eip4-platform/docs/架构设计.md`。