Files
eip4-platform/docs/迁移手册.md
zhengwr 185c18d38f docs(P1): 服务流实测报告 + 迁移手册新增四坑(替换类/读写闸)
P1-2 第三步:交付文档。

platform-metadata/P1服务流实测报告.md:移植清单(31 com.dsasp 文件 + 门面 + 自举/单测)、
替换类/不移植类登记(Activator 不移植、juel 不引 activiti、SecureGroovy 去 Vaadin 默认导入、
两版 ScriptingEnginesManager 并存)、GetServicesFunction 桩回迁 diff、REST 契约、
6 条 REST 实测(端口 8085 客户库只读:T1-T6,total 与 DB 逐一核对一致 + 参数透传 + 二次一致 + POST)、
D 类 79 流识别结果(40 存在/39 orphan,38 非受控)、已知限制与 P2/P3 待办。

docs/迁移手册.md 新增四坑(四栏格式,[NEW 2026-06-11]):
  5.15 服务流脚本默认导入含 Vaadin UI 类缺失则每脚本编译失败
  5.16 流脚本 juel 来自 activiti,保真层不引 activiti(惰性注册适配)
  5.17 OSGi Activator 不移植,bean 靠组件扫描 + SpringBeanOsgiServices + LegacyXmlWiring
  5.18 REST 服务流入口不区分读写,需流定义审阅 + P2 三层防护

D 类识别 SQL/清单落档于 ../docs/P1/(D类报表服务流清单.csv + 识别.sql + REST证据/),
该目录在 eip4-platform 仓库外(eip3 工作区非 git,与 ../docs/M0交付 同级)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 12:06:24 +08:00

452 lines
35 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.
# EIP4 迁移手册 v1
> 版本:v1.0(2026-06-10)| 性质:M0 强制交付物,老员工知识转移 + PoC 坑位整编
> 适用对象:所有参与 eip4-platform 工程化的开发人员,新成员上手必读
> 维护原则:每个坑位必须补全「现象/根因/对策/影响范围」四栏后方可关闭;新发现的坑位在
> 对应章节追加,打 `[NEW]` 标记并注明发现时间
---
## 一、移植总则
### 1.1 双层制架构纪律
eip4-platform 采用**双层制**:
```
保真层(platform-legacy-core) 现代层(platform-metadata 等)
com.dsasp.* com.eip4.*
────────────────────────────── ──────────────────────────────
移植引擎原样保留 REST API / DTO / 转换器 / MCP
包名不动、行为不动 新代码、新范式
以对拍为完成定义 以评审+单测为完成定义
```
**纪律(ArchUnit 规则固化,编译期强制)**:
- `com.eip4.*` 可调用 `com.dsasp.*`,**反向绝对禁止**
- `com.dsasp.*` 与 framework 源码的 diff 保持最小——移植不是重构
- 保真层代码改动必须附一份对拍测试通过截图,否则 PR 不得合入
### 1.2 保真层纪律
| 原则 | 含义 | 违规后果 |
|------|------|---------|
| 不重写 | 610 行引擎、1,346 行 SQL 拼装,原样搬入,不"现代化" | 破坏对拍基线,视同 P1 返工 |
| 不改包名 | `com.dsasp.server.dataDic` 等包名不变 | 所有 import 和反射引用失效 |
| 不引 ORM | JdbcTemplate 是引擎的血液,JPA/MyBatis 不得引入保真层 | 动态 DDL 与 ORM 范式相克 |
| diff 最小化 | 每次修改记录为「必要改动」(API 断点修复)或「适配」(桩替换),不顺手改 | 下一次升级时无法 diff 溯源 |
### 1.3 对拍 = 完成定义
**移植代码的唯一完成标准是逐行对拍通过,不接受人工目测。**
- **计数级对拍(已完成)**:`tools/eip4_sweep.py`,全量 1,166 实体,0 计数不一致,通过率 99.1%
- **逐行对拍(C1,工程化第一周强制)**:在旧系统关键出口加 SQL 录制切面,新旧结果集逐行 diff。≥20 个代表性实体(含主子表/字典翻译/数据权限/深分页),一致率必须 100%
- **C1 前提**:旧系统需有可运行环境供 SQL 录制。若旧系统不可得,需设计生产流量旁路录制方案并报批(决策会开放项,P1 第一周第一个问题)
> 对外口径:「计数级一致性 99.1%(0 计数不一致),逐行对拍待工程化阶段 C1 补全」
> **禁止**在 C1 完成前使用「99.1% 一致」表述(决策会书面更正)
---
## 二、Spring 3.1 → Boot 3 API 断点台账
> 来源:eip4-poc Day 1 实测,framework/ 静态扫描 + 编译验证
> 结论:**断点仅此一类,已全部修复**;未发现其他不兼容 API
### 2.1 queryForInt / queryForLong(7 处)
| 栏目 | 内容 |
|------|------|
| **现象** | 编译期报错:`The method queryForInt(String) is undefined for the type JdbcTemplate` |
| **根因** | `JdbcTemplate.queryForInt()` 和 `queryForLong()` 在 Spring 4.2 已废弃,Spring 6(Boot 3 内置)彻底移除 |
| **对策** | 改为 `queryForObject(sql, Integer.class)` 或 `queryForObject(sql, Long.class)`;另有 1 处 `(String, Object[], Class)` 重载参数顺序变更,须同步调整 |
| **影响范围** | `com.dsasp.server.dataDic.POJOServiceImpl`(1,346 行内),共 7 处;已在 eip4-poc 全部修复 |
### 2.2 javax → jakarta(6 处)
| 栏目 | 内容 |
|------|------|
| **现象** | 编译期报错:`javax.servlet` 包找不到 |
| **根因** | Spring Boot 3 对应 Jakarta EE 9+,`javax.*` 命名空间已迁移为 `jakarta.*` |
| **对策** | dataDic + common + core 三模块内 6 处 `javax.servlet` 机械替换为 `jakarta.servlet`;`javax.script`(JSR-223,共 17 处)**不动**,JDK 17 原样可用 |
| **影响范围** | 仅 6 处,半天内完成;已在 eip4-poc 全部修复 |
### 2.3 数据源与事务 XML 配置(1 处)
| 栏目 | 内容 |
|------|------|
| **现象** | 旧 `META-INF/spring/db.xml` 用 Spring XML 配置 commons-dbcp 连接池与事务管理器,Boot 3 不识别 |
| **根因** | Spring Boot 3 推荐 Java Config;commons-dbcp 已被 HikariCP 替代 |
| **对策** | `com.dsasp.server.db/META-INF/spring/db.xml` 事务配置转换为 `@Configuration` Java Config;连接池替换为 HikariCP(Boot 3 默认);已在 eip4-poc 实测通过 |
| **影响范围** | 单处配置文件;业务代码无感知 |
### 2.4 SimpleJdbcTemplate(0 处)
| 栏目 | 内容 |
|------|------|
| **现象** | 预核查前担心此 API 大量使用(Spring 4.x 已删除) |
| **根因** | N/A |
| **对策** | **源码实测零使用**,此风险解除;无需任何改动 |
| **影响范围** | 无 |
> **完整结论**:Spring 3.1/JDK 6 → Boot 3/JDK 17 的移植,全部 API 断点仅 8 处(7 处 queryForInt/Long + 1 处重载顺序),已在 eip4-poc 全部修复,WS1 通过。
---
## 三、OSGi 解耦做法
> 来源:framework/ 源码实测(源码预核查报告核查 2)
> 结论:OSGi 耦合面高度集中,等价替换成本极低
### 3.1 替换类清单(6 个)
| 类名 | 原版(OSGi) | 替换实现 | 原版行数 | 替换行数 | 替换要点 |
|------|-------------|---------|---------|---------|---------|
| `SpringBeanOsgiServices` | OSGi BundleListener 服务定位器 | `ApplicationContext.getBean(name)` | 72 行 | 43 行 | 注入 `ApplicationContext`,按名取 bean;删除 BundleListener 逻辑 |
| `ScanServiceBeanXml` | OSGi bundle 启动期 SAX 扫描 service XML | no-op(保留 `classList` 契约) | 待查 | 极简 | 业务调用方只用 classList 返回值 |
| `CCache` | Adempiere 缓存(GPL 头 + CacheMgt 注册) | 极简 HashMap 版 | 待查 | 极简 | 调用方只用 Map API,实现可直接换 |
| `Console` | Vaadin 浏览器控制台推送 | `slf4j` | 待查 | 极简 | 日志语义等价 |
| `InstallOrUpdate` | 启动期按版本跑 install SQL | `isDevDB()=false` 桩 | 待查 | 极简 | 生产环境不触发 |
| `GetServicesFunction` 等 3 个 | Groovy 脚本函数库(约 2,600 行) | Java 桩(仅实现 `findCount`);WS3 回迁 | 约 2,600 行 | 最小桩 | P1/P3 阶段补全真实现 |
**注意**:替换时必须**保持包名/类名/方法签名完全一致**,旧引擎代码对这些类的引用不做任何修改——「旧代码零感知」是双层制的核心约定。
### 3.2 横切服务桩清单(P2 换真实现)
| 桩 | 包路径 | 当前行为 | P2 真实现要点 |
|----|--------|---------|-------------|
| ~~`dataPrivilegeService`~~ | ~~`com.eip4.poc.stub`~~ | **已由 M0/C2 真实现接管** | 桩已删除;保真层 `com.dsasp.server.privilege.service.DataPrivilegeServiceImpl`(原样移植)提供行级过滤原版语义;P2 在此之上接组织数据源 + 管理 UI(见 §5.8 / platform-auth/C2实测报告.md) |
| `fileService` | `com.eip4.poc.stub` | no-op | 本地盘 / MinIO 接口 |
| `projectSwitchService` | `com.eip4.poc.stub` | no-op | 项目上下文切换 |
| `systemLogManager` | `com.eip4.poc.stub` | slf4j | 业务操作日志入库 |
---
## 四、XML 装配补齐
> 来源:eip4-poc 移植台账,Day 1 实测发现
### 4.1 LegacyXmlWiring(setter 注入补齐)
| 栏目 | 内容 |
|------|------|
| **现象** | 旧 `service.xml` 用 `<property>` setter 注入 `systemLogManager` / `dataOperatorLog`(非 `@Autowired` 字段),Boot 3 注解驱动容器不会自动装配这些 setter |
| **根因** | 引擎代码是旧 Spring XML 编程模型,没有 `@Autowired` 注解;直接移植后 setter 未被调用,引用为 null |
| **对策** | 新增 `LegacyXmlWiring`(实现 `SmartInitializingSingleton`),在容器启动后手动将这些 bean 注入到引擎的对应 setter,等价于 XML `<property>` 注入行为 |
| **影响范围** | `systemLogManager`、`dataOperatorLog` 两个依赖;已在 eip4-poc 实测通过;**转换器和新模块不受影响** |
### 4.2 JodaModule(Jackson 序列化)
| 栏目 | 内容 |
|------|------|
| **现象** | 引擎内部日期值为 `joda.time.DateTime` 对象,REST 层序列化时 Jackson 抛 `InvalidDefinitionException: No serializer found` 或输出异常 JSON |
| **根因** | Spring Boot 3 不再自动注册 `JodaModule`(Boot 2.x 会自动注册) |
| **对策** | 显式在 `ObjectMapper` 配置中 `registerModule(new JodaModule())`;`jackson-datatype-joda` 依赖加入 pom.xml |
| **影响范围** | 所有包含 DATE 显示类型字段的实体查询响应;已在 eip4-poc 实测通过 |
---
## 五、引擎行为契约清单
> 来源:eip4-poc Day 2 移植对拍记录(README.md 坑位章节)
> 性质:这些是引擎内部**已经确认的行为**,不是 bug,移植工具和转换器必须遵守
### 5.1 updatePO 审计列强制追加
| 栏目 | 内容 |
|------|------|
| **现象** | 对某些表执行 update 路径时,引擎抛 SQL 错误:`column UPDATETIME does not exist` |
| **根因** | 引擎 `updatePO` 无条件追加 `UPDATETIME` / `UPDATEBY` 两个审计列到 UPDATE 语句,不判断目标表是否存在这两列 |
| **对策** | insert-only 设计的表(如 `SYS_DATA_LOGITEM`,物理表无这两列)**不可走 update 路径**,必须走 insert-only 路径;新建实体时审计列存在与否须与设计意图对齐;老系统行为一致(非新引入缺陷) |
| **影响范围** | 所有无 `UPDATETIME`/`UPDATEBY` 列的表;P2 数据权限迁移时需排查;write-test 已验证 |
### 5.2 DATE 类型 = joda DateTime(非 java.util.Date)
| 栏目 | 内容 |
|------|------|
| **现象** | REST 入参传 Long 型时间戳给 DATE 类型字段,引擎抛 `ClassCastException` |
| **根因** | 引擎内部 DATE 显示类型存储为 `org.joda.time.DateTime` 对象,不接受 `Long`;引擎从未把这个内部约定暴露为接口文档 |
| **对策** | REST 层适配器必须将前端传入的时间戳(Long)或 ISO 字符串转换为 `joda.time.DateTime` 后再传给引擎;反向序列化(引擎 → REST 响应)见 4.2 JodaModule |
| **影响范围** | 所有 DATE 显示类型字段的写入接口;P1 REST 层实现时必须加适配,P4 转换器生成 amis 日期组件时需对齐格式 |
### 5.3 dom4j 取脚本必须用 getText(),不得用 getTextTrim()
| 栏目 | 内容 |
|------|------|
| **现象** | 取出的 Groovy 脚本源码缩进/换行消失,执行时 `GroovyShell` 报语法错误 |
| **根因** | `getTextTrim()` 会压扁所有前后空白和换行符;Groovy 是换行敏感语言,多行脚本的换行是语法的一部分,压扁后源码损坏 |
| **对策** | 所有从 XML/dom4j 节点取脚本文本的地方**一律改用 `getText()`**;转换器(P4)和运行时的脚本读取处都须核对,已有问题处一并修复 |
| **影响范围** | `TemplateToAmisConverter` 的脚本提取逻辑;运行时 ScriptingEnginesManager 的脚本加载路径;全量 1,427 条脚本转换质量 |
### 5.4 PK 列名 = `{表名}_ID` 约定
| 栏目 | 内容 |
|------|------|
| **现象** | 克隆实体或用转换工具新建实体后,PK 列名与引擎预期不符,查询报 `column not found` |
| **根因** | 引擎的 DDL 生成器在创建 PK 属性时,列名硬编码为 `{表名}_ID`(例如 `SYS_USERGROUP` 的主键列为 `SYS_USERGROUP_ID`);这是设计器创建时的约定,但未在文档中明示 |
| **对策** | 克隆工具、批量转换工具、P4 的迁移脚本在新建或克隆实体元数据时**必须同步按此约定命名 PK 列**;引擎不接受其他命名的主键列 |
| **影响范围** | P4 批量转换 1,516 个模板;P1 对拍测试中克隆实体场景;所有新建实体的 DDL 生成 |
### 5.5 MIDTABLE 类型无主键子句
| 栏目 | 内容 |
|------|------|
| **现象** | MIDTABLE(中间表/关联表)类型实体的 DDL 中没有 PRIMARY KEY 子句,但调用了 CRUD 路径 |
| **根因** | 引擎设计:MIDTABLE 是多对多中间表,无业务主键,DDL 生成时故意不加 PRIMARY KEY |
| **对策** | 对 MIDTABLE 类型实体**不走引擎的 updatePO 路径**(见 5.1),只走 insert/delete;P2 数据权限中涉及关联表的场景需特别处理 |
| **影响范围** | 所有 MIDTABLE 类型实体(数量待 P1 统计);P4 转换器需识别并生成对应的 amis 组件 |
### 5.6 REFERENCES 外键自动生成
| 栏目 | 内容 |
|------|------|
| **现象** | 动态建表后,发现某些列带有外键约束,但元数据 XML 中并未显式声明 |
| **根因** | 引擎 DDL 生成器:引用类型(REFERENCE 属性)的列自动生成 `REFERENCES` 外键约束;这是引擎的内置行为 |
| **对策** | P0' PG 升级演练时需检查外键约束在 PG 15 下的行为;P4 转换器处理引用列时不需要额外指定外键,引擎自动处理;批量删除/清理测试数据时须注意外键级联 |
| **影响范围** | 所有引用类型属性;对拍测试中的数据清理逻辑;P0' PG 升级兼容性扫描 |
### 5.7 listSelect(String sql) 混合大小写表名在 PG 取值异常
| 栏目 | 内容 |
|------|------|
| **现象** | `DataDicServiceImpl.getEntityAttributes` 使用混合大小写表名(如 `"SYS_EntityAttribute"`)调用 `listSelect(sql,...)` 时,PG 返回空集或查询结果字段映射异常;使用条件 Map 的规范路径(全大写表名)正常 |
| **根因** | PostgreSQL 默认将未加双引号的标识符折叠为小写;混合大小写表名在未加引号时匹配不到实际的大写物理表名(EIP3 在 PG 下所有表名均大写);`listSelect(String sql)` 直接传 SQL 字符串时绕过了引擎的标准化处理 |
| **对策** | 正式移植时核查所有 `listSelect(String sql, ...)` 调用点,确认表名大小写;所有直接 SQL 路径中的表名统一用双引号包裹(`"SYS_EntityAttribute"`)或改用全大写;**优先改用条件 Map 路径,让引擎统一处理标识符** |
| **影响范围** | `DataDicServiceImpl` 中的直接 SQL 调用路径;P1 全量移植时的回归扫描重点;P4 转换器生成 SQL 片段时的命名规范 |
### 5.8 ROLES 多值列经 LIST + 中间表落地(数据权限规则装载)
> 来源:eip4-platform M0 任务 C2 实测(2026-06-11),详见 platform-auth/C2实测报告.md
| 栏目 | 内容 |
|------|------|
| **现象** | `SYS_FILTERRULE.ROLES` 是「一条规则关联多个角色」的多值列,`DataFilterHelper.converToDataFilterRule` 直接 `po.get_Value("ROLES")` 期望拿到 `List<String>`;但物理表上并无 ROLES 列,值如何加载不直观 |
| **根因** | 引擎对 `DisplayType.List`(REFERENCEID='LIST')列的多值加载走「中间表(MIDTABLE)」路径:ROLES 列的 `REFERENCEVALUE` 指向一条 `SYS_REFERENCEVALUE`,其 `ENTITYID`→中间表实体(`SYS_FILTERRULEROLE`,tabletype=2,恰 2 列),`ENTITYATTRIBUTEID`→回引列(`FILTERRULEID`)。`POJOServiceImpl.loadPOJO(isHierarchical=true)` 的 `hierarchicalQuery` 对 LIST 列查 `SELECT * FROM 中间表 WHERE 回引列=规则id`,收集「另一列」(`ROLEID`)全部值组成 `List<String>` 设回 ROLES(见 POInfo.getReferenceValueTable/ColumnName + POJOServiceImpl.java:1256-1262) |
| **对策** | 自举建模需三件齐备:①中间表 `SYS_FILTERRULEROLE`(恰 2 列 `FILTERRULEID`+`ROLEID`,tabletype=2,元数据 seq 决定 getColumnName(0/1) 次序,第 0 列必须是回引列);②ROLES 列 `REFERENCEID='LIST'` + `REFERENCEVALUE` 指向一条 `SYS_REFERENCEVALUE`(ENTITYID=中间表实体、ENTITYATTRIBUTEID=回引列属性);③配套一条 `SYS_REFERENCE`(ENTITYID=中间表实体)。读路径必须走 `loadPOJO(...,isHierarchical=true)`(getEntityDataFilterRule 已如此),否则 LIST 列不展开。本地用 bootstrap-privilege.sql 直插中间表行种规则角色 |
| **影响范围** | 所有 LIST(多值/子表)显示类型列的自举与对拍;P1 客户库副本不可达期间,凡需种多值列数据都按此三件套建模;P2 数据权限管理 UI 写规则时引擎自身的写路径(saveOrUpdateDataPrivilege)会按同口径落中间表 |
### 5.9 行级过滤仅在非 ADMIN 上下文触发
| 栏目 | 内容 |
|------|------|
| **现象** | 即便实体配了 `SYS_FILTERRULE` 规则,用默认(ADMIN)上下文 `listSelect` 仍返回全量,过滤「不生效」 |
| **根因** | `POJOCRUDServiceImpl.listSelectSpecialCol` 显式判断 `ctx.get(CURRENTUSER) != LoggedInUser.ADMIN` 才调 `dataPrivilegeService.getWhereClause`;ADMIN 视角天然不过滤(管理员看全量)。这是引擎设计而非缺陷 |
| **对策** | 对拍/验证行级过滤必须构造**非 ADMIN** 的 `ctx`(`CURRENTUSER`=具体用户 + `ROLES`=List)。C2 通过 EntityController 增 `asUser`/`roles` 查询参可选项构造该上下文驱动引擎过滤路径;不传则沿用 ADMIN(不过滤),向后兼容 |
| **影响范围** | 所有行级数据权限验证与对拍场景;P2 管理 UI / 网关须在请求上下文正确填充 CURRENTUSER + ROLES;`LoggedInUser.ADMIN` 是补足 36 位的 `'ADMIN'`(char(36) 比较口径) |
### 5.10 DataFilterHelper 用 Jackson 1.x(org.codehaus.jackson)
| 栏目 | 内容 |
|------|------|
| **现象** | 移植 `DataFilterHelper` 时其 import `org.codehaus.jackson.*`(Jackson 1.x,`ObjectMapper`/`JsonNode`/`ArrayNode`),与现代层用的 `com.fasterxml.jackson`(Jackson 2)是两套不兼容 API |
| **根因** | framework 原版即用 Jackson 1.x 做 FILTERRULE(Conditional[])的 JSON 互转;保真层纪律「com.dsasp 旧代码一行不改」,不得改写为 Jackson 2 |
| **对策** | platform-legacy-core pom 显式引入 `org.codehaus.jackson:jackson-mapper-asl:1.9.13`(传递带 jackson-core-asl),与 Jackson 2 共存(包名不同不冲突);代码原样保留 1.x API |
| **影响范围** | platform-legacy-core 依赖树(多一条 1.x 链);P1 全量移植中凡用 Jackson 1.x 的旧类同此处理;现代层序列化仍用 Jackson 2,互不干扰 |
---
### 5.11 引擎 JSON 对 null 值列整列省略 [NEW 2026-06-11]
- **现象**:对拍中物理列值为 NULL 的列(如 WF_HI_TASKINST.DUEDATE 全表 null),引擎 REST 输出的行 JSON 里整列缺失,被误判 MISSING_RIGHT。
- **根因**:GeneralPOJO.toRow / JSON 序列化跳过 null 值键。
- **对策**:对拍 harness 规则「右缺列 + 左值 NULL = 语义等值」(platform-parity RowDiff 自对拍模式);前端/AI 消费 API 时不可假设所有元数据列必出现。
- **影响范围**:所有 list/load REST 输出消费方。
### 5.12 BOOLEAN 列域外脏数据引擎归 null [NEW 2026-06-11]
- **现象**:BOOLEAN 元数据列物理值存在 2、-1 等域外值(旧库脏数据,如 PM_BUDGETRCJ.ISTURNOVERMATERIALS=2 共 1,094 行、PM_BUDGETLIST.ISLIST=-1),引擎读出为 null。
- **根因**:引擎布尔解析只认 0/1,域外值归 null;**旧系统行为相同**,非移植缺陷。
- **对策**:对拍按「已归因差异」处理(可见不判负);数据治理时这批脏值应与客户确认语义后清洗。
- **影响范围**:全库 BOOLEAN 列;涉及行数见 C1 客户库对拍报告。
### 5.13 "胖列"实体大结果集不可单次取全 [NEW 2026-06-11]
- **现象**:GB_PRJ_WORKER(15,814 行,含工人照片类大文本列)单次全量 REST 响应达 1.7GB,超 Jackson 1GB 字符串上限,解析失败。
- **根因**:引擎 SqlRowSet 全量物化 + 大文本列;消费端单响应承载有上限。
- **对策**:此类实体必须分页消费;对拍 harness 已做"单次抓取失败自动回退翻页"。架构第五节「大结果集流式导出」改造时此类实体优先。
- **影响范围**:含 BLOB/大文本列的实体;P4 导出功能设计。
### 5.14 复杂视图实体的分页查询是 O(N) 重算 [NEW 2026-06-11]
- **现象**:PM_PAYMENTAPPLY(38,138 行)引擎 SQL 为 DISTINCT + 4 个 LATERAL 子查询,**每页 500 行耗时 ≈61 秒**,深页更慢;全量遍历约 78 分钟。
- **根因**:每页请求都重新执行完整 DISTINCT/JOIN 再 OFFSET,计划缓存不可复用叠加显示列翻译子查询。
- **对策**:C3 压测已把此类实体列为热点;P2「渐进参数化 + Caffeine」与「DDL 索引增强」改造的优先验证对象;对拍用抽样模式(--sampleRows)。
- **影响范围**:带多引用显示列的大表;真实用户的列表页延迟(决策会风险 R2 直接证据)。
### 5.15 服务流脚本默认导入含 Vaadin UI 类,缺失则每个脚本编译失败 [NEW 2026-06-11]
- **现象**:服务流引擎移植后,**任何**带 groovy 脚本的服务流经 REST 执行报 HTTP 500,日志为 `MultipleCompilationErrorsException: unable to resolve class client.groovy.TestService` / `com.dsasp.client.viewframework.component.MainComponent`。
- **根因**:`SecureGroovyScriptEngineFactory.DEFAULTIMPORTSLIST` 经 `imports.addImport(it)` 把这两条 Vaadin 客户端 UI 类作为**默认导入逐脚本注入**;它们属已淘汰 Vaadin 表现层,eip4-platform 保真层不含,classpath 缺失令编译期解析失败。`IMPORTSWHITELIST`/`STARIMPORTSWHITELIST` 里的 Vaadin 类是 AST 白名单字符串(不加载),无害;只有 `DEFAULTIMPORTSLIST` 真加载。
- **对策**:`SecureGroovyScriptEngineFactory.groovy` 的 `DEFAULTIMPORTSLIST` 移除这两条 Vaadin 默认导入(原值在源码注释登记供 diff 溯源),保留 8 条服务端导入(GeneralPOJO/POJOCRUDService/StringUtil/三个 Get*Function/Console 等,均已就位)。属「确需替换的类按保包名/类名/签名纪律」适配。
- **影响范围**:**所有**含脚本的服务流(D 类 79 个全部含脚本);P4 脚本批量转换/运行时脚本加载;凡移植 SecureGroovy 工厂的环境必做此适配。
### 5.16 服务流脚本引擎的 juel 来自 activiti,保真层不引 activiti [NEW 2026-06-11]
- **现象**:`core.service.script.ScriptingEnginesManager` 原版 `new org.activiti.engine.impl.scripting.JuelScriptEngineFactory()` 注册 juel(`${...}`)引擎;保真层无 activiti 依赖,编译失败。
- **根因**:framework 的流脚本引擎复用了 activiti-engine-5.14 的 juel 工厂;架构设计第二节裁定 activiti/Flowable **仅存在于独立工作流服务**,禁止进入保真层运行时(EOL 工件 + 私有化部署中间件最小化)。
- **对策**:适配为 JSR-223 名称惰性注册(classpath 提供 juel 引擎则注册其 factory,否则跳过),groovy 路径与类签名逐字不变。juel 仅服务流**带条件转移**(`${...}` transition / initExpression)时触发;D 类查询/报表为线性流(start→service→end)不走 juel,不受影响。带分支流的 juel 支持随 P3 工作流(Flowable)落地补。
- **影响范围**:带条件分支的服务流(如 DefaultFlowHelper 的 SAVE_AND_SUBMIT);P3 工作流;不引入 activiti 是保真层依赖纪律(对照 §5.10 Jackson 1.x 是「引入共存」,此处是「不引入」)。
### 5.17 OSGi Activator 不移植,流引擎 bean 靠组件扫描 + SpringBeanOsgiServices 注册 [NEW 2026-06-11]
- **现象**:framework `com.dsasp.server.core.Activator` 是 OSGi `BundleActivator`(org.osgi.* + sun.awt.ComponentFactory + ServiceTracker),JDK17 不可用且无 OSGi 容器。
- **根因**:OSGi 生命周期类,服务注册/发现走 bundle 机制;Boot 3 用 Spring 容器替代。
- **对策**:**不移植 Activator**(PoC 全模块零 Activator 先例)。流引擎三 bean(`flowExcuteService`/`flowService`/`flowPrivilegeService`/`originServiceManager`)靠 `@Service(value=...)` + 组件扫描(scanBasePackages 含 com.dsasp)自动注册;运行期按名取 bean 走 `SpringBeanOsgiServices.getBeanByName`(已是 @Component 替换实现,§3.1)。`FlowServiceImpl.jdbcTemplate` 非 @Autowired 字段,在 `LegacyXmlWiring` 补 setter 注入(等价原 XML <property>,§4.1)。
- **影响范围**:凡移植带 Activator 的 framework 模块;bean 注册改由 @Service 名 + LegacyXmlWiring setter 补齐。
### 5.18 REST 服务流入口不区分读写,需流定义审阅 + P2 防护 [NEW 2026-06-11]
- **现象**:`/api/flow/{id}` 把任意服务流交给引擎 excute;引擎一个流既可挂 listSelect(读)也可挂 save/update/delete(写)service 节点,门面无法仅凭 flowId 区分读写。
- **根因**:服务流引擎设计为通用执行器(读写同入口 excute);读写语义在流定义 XML 的 service 节点 method 里,门面层不解析。
- **对策**:P1 不在门面做引擎级读写闸(避免误判);**调用方/运维按流定义 XML 审阅确认查询/报表类后放行**,客户库只读纪律下只执行已审阅无写动作的流。P2 补三层防护:①流定义静态扫描(service method 读白名单);②最小权限只读连接;③statement_timeout。
- **影响范围**:所有经 REST 执行的服务流;客户库只读期的流挑选;P2 安全加固(对齐架构第四节安全第 1/3/4 层)。
## 六、Flowable 升级三坑
> 来源:eip4-poc WS4 实测,flowable-poc / flowable5-poc 工程(2026-06-10)
> 背景:客户库引擎版本 **5.13-SNAPSHOT**(非评估报告所写 5.14);
> 全量 1,509 个 BPMN 定义,零 `activiti:class` 自定义扩展,
> 但有 3 个表达式 bean(见 6.3)
### 6.1 版本串 5.13-SNAPSHOT 不被升级链识别
| 栏目 | 内容 |
|------|------|
| **现象** | 将 ACT_* 表指给 Flowable 5.23 时报错 `"unknown version from database"`,升级脚本终止 |
| **根因** | Flowable 5.x 升级链通过 `act_ge_property` 表中 `schema.version` 字段识别当前版本,`5.13-SNAPSHOT` 不是正式版本号,升级链无法匹配版本范围 |
| **对策** | 升级前必须执行:`UPDATE act_ge_property SET value_='5.13' WHERE name_='schema.version'`;执行完成后再启动 Flowable 5.23 升级 |
| **影响范围** | **每一个客户库升级前的必执行步骤**,写入《Flowable 升级 Runbook》变更四要素前置;漏做则整个升级链中断 |
### 6.2 5.13 不能直接跳 6.x(两步升级强制)
| 栏目 | 内容 |
|------|------|
| **现象** | 尝试直接用 Flowable 6.8.1 连接 5.13 版本数据库时,迁移脚本因缺少 `TENANT_ID_` 列而报错并回滚 |
| **根因** | v5→v6 的 DDL 迁移脚本假设数据库已达到 Flowable 5.15 引入的 `TENANT_ID_` 列;5.13 没有该列,跳版直升会触发 DDL 错误 |
| **对策** | **强制两步升级路径**:① 先用 Flowable 5.23(v5 末版)引擎升级数据库到 v5 最终 schema;② 再换 Flowable 6.8.1(启用 `flowable5-compatibility`)升级到 v6;两步均需全量备份回退点 |
| **影响范围** | 生产升级 Runbook 中必须明确两步窗口(决策会已拍板 PG 升级与 Flowable 升级分两个独立停机窗口);PoC 已完整实测,1,509 定义 / 9,383 执行 / 9,321 待办 / 26,749 历史全部就地保留 |
### 6.3 表达式 handler bean 移植面(3 个类)
| 栏目 | 内容 |
|------|------|
| **现象** | Flowable 独立服务启动后,BPMN 流程中的候选人表达式 `${candidateUsersHandler.getUsers(...)}` 解析失败,抛 `FlowableException: Unknown property used in expression` |
| **根因** | 这 3 个 bean 定义在 `com.dsasp.server.wf` 模块中,Flowable 独立服务(`flowable-service.jar`)需要显式注册;PoC 扫描时遗漏了表达式 bean 层(仅扫描了 `activiti:class`,零结果),表达式层是独立入口 |
| **对策** | 将 3 个 handler 类从 `com.dsasp.server.wf` 移植到 `platform-flow-gateway` 模块;通过 `ProcessEngineConfiguration.setBeans(Map)` 注册(PoC 已验证注册机制有效);P3 阶段优先级最高 |
| **影响范围** | **引用量**:`candidateUsersHandler` × 4,761 处(全量 1,509 个 BPMN)、`wfContextService` × 175 处、`multiInstanceUsersHandler` × 33 处;这 3 个 bean 未移植则流程发起/审批全部无法运行 |
**三坑汇总检查清单(写入升级 Runbook)**:
```
□ 升级前:UPDATE act_ge_property SET value_='5.13' WHERE name_='schema.version'
□ 第一步:Flowable 5.23 完整升级 + 验证 schema.version 达到 5.x 末版
□ 第二步:Flowable 6.8.1 启用 flowable5-compatibility 升级
□ 升级后:验证 1,509 个定义可见 + 抽取 3 个运行中实例续跑 + 候选人表达式解析正常
□ platform-flow-gateway 已包含 3 个 handler bean + cfg.setBeans 注册
```
---
## 七、库内数据质量已知问题
> 来源:eip4-poc Day 2 全量扫描结果(tools/eip4_sweep.py)+ 移植台账
> 性质:旧系统库内存量问题,非移植缺陷;工程化前必须定性处置(决策会切流红线 3)
### 7.1 55 个孤儿元数据
| 栏目 | 内容 |
|------|------|
| **现象** | `eip4_sweep.py` 对拍时,55 个实体的 `listSelect` 返回 0 条但引擎无错——但直接查 `count(*)` 也返回 0(物理表不存在) |
| **根因** | `SYS_ENTITY` 中存在元数据定义,但对应的物理表已不存在于数据库——元数据孤儿,可能是历史删表未清元数据 |
| **对策** | **逐条定性**:① 已废弃(可归档元数据);② 需要重建物理表;③ 业务仍在使用(严重问题,需客户确认);定性结果需**客户书面确认**后方可进切流(决策会红线 3) |
| **影响范围** | 55 个实体从全量 1,166 中排除后,有效对拍范围为 1,111 个;P1 对拍框架建立时需排除或单独标记这 55 个 |
### 7.2 9 个元数据漂移
| 栏目 | 内容 |
|------|------|
| **现象** | 引擎查询返回 500 错误,但旧系统行为一致(老系统同样报错);全量扫描中 9 个 500 实体排除在通过率计算之外 |
| **根因** | 元数据声明与物理表结构不一致:典型案例 `SYS_DATASTATUS`,元数据声明为普通表但物理表无主键列;引擎拼出的 SQL 在 PG 下执行失败 |
| **对策** | 逐条排查漂移原因(元数据错误 vs 物理表被手工改过 vs 历史 bug);修复方向:对齐元数据或对齐物理表;需**客户书面确认**后处理(决策会红线 3) |
| **影响范围** | 9 个实体;`SYS_DATASTATUS` 已知 1 例;P1 对拍框架需将这 9 个标记为「已知漂移,人工定性中」 |
### 7.3 HR_ATTENDLOGDETAIL.UNITNAME 物理列缺失
| 栏目 | 内容 |
|------|------|
| **现象** | 主子表级联测试中,`HR_ATTENDLOGDETAIL` 的 `UNITNAME` 属性读取返回 null;写入时无报错但值丢失 |
| **根因** | `SYS_ENTITYATTRIBUTE` 中存在 `UNITNAME` 属性定义,但 `HR_ATTENDLOGDETAIL` 物理表中该列不存在——属于 7.2 元数据漂移的又一具体案例 |
| **对策** | 与 7.2 同:客户确认是否需要补列还是废弃该属性定义;**在客户确认前,涉及 UNITNAME 的查询/写入不得进切流** |
| **影响范围** | `HR_ATTENDLOGDETAIL` 相关的考勤详情功能;如有其他 HR 表存在类似问题需一并排查 |
### 7.4 entityid 非法字符孤儿模板
| 栏目 | 内容 |
|------|------|
| **现象** | WS2 转换器处理某些模板(如「信息价管理」)时,`entityid` 字段值包含非法字符,无法在 `SYS_ENTITY` 中找到对应实体 |
| **根因** | 部分老模板的 `entityid` 值使用了历史 ID 格式(含特殊字符或已被删除的实体 ID),指向已不存在的实体 |
| **对策** | P4 批量转换前需先跑一轮盘点 SQL,识别所有 entityid 异常的模板并单独标记;转换器需要 null-safe 处理(entityid 解析失败时输出错误日志而非抛异常终止批量任务) |
| **影响范围** | 全量 1,516 模板中的孤儿模板数量待 P1 盘点确认;P4 转换器需增加异常模板的旁路处理流程 |
---
## 八、amis 侧已知坑
> 来源:eip4-poc WS2 实测(2026-06-10)
> amis 版本:6.13.0(锁定,本地化部署,不依赖 CDN)
### 8.1 官方 schema.json 宽松语义与 additionalProperties 预处理
| 栏目 | 内容 |
|------|------|
| **现象** | 直接用 ajv(draft-07)加载官方 `schema.json` 进行校验时,大量结构上合法的 amis schema 被报错为「额外属性不被允许」,与实际浏览器渲染结果矛盾 |
| **根因** | 官方 `schema.json` 中大量位置存在 `{"$ref":..., "additionalProperties":true}` 的**兄弟键覆盖写法**;在 draft-07 严格语义下,兄弟键被忽略,引用定义的 `additionalProperties:false` 生效,拒绝一切额外属性;但 amis 官方编辑器(VS Code 插件等)使用更宽松的 JSON Schema 实现,会合并引用 schema 与兄弟键 |
| **对策** | 校验前做**预处理**:递归剥除所有含 `$ref` 节点的兄弟 `additionalProperties:false`;已在 `GET /api/poc/amis-validate` 实现,3 个真实模板转换后校验通过(0 错误) |
| **影响范围** | P4 双闸中的「官方 schema 校验」闸;MCP Server 的 validate-schema 工具;AI 生成管线的校验-重试环节;**所有使用 ajv 校验 amis schema 的地方都需要这个预处理步骤** |
### 8.2 双闸必要性(校验闸 + 渲染冒烟闸)
| 栏目 | 内容 |
|------|------|
| **现象** | schema 校验通过(0 错误)的页面,在浏览器 amis 渲染时出现组件类型未识别或渲染为空 |
| **根因** | schema.json 含 loose 宽松分支,「未知渲染器类型」会通过校验(schema 设计内)但运行时 amis 渲染器不识别;schema 校验只能抓结构错误/已知属性类型错误/必填缺失,无法保证可渲染性 |
| **对策** | **双闸缺一不可**:第一闸(schema 校验)抓结构问题;第二闸(headless 渲染冒烟,如 Puppeteer/Playwright 执行 `amis.embed`)抓渲染问题;P4 批量转换流水线必须两闸串联,两闸都过才入库 |
| **影响范围** | P4 全量 1,516 模板转换流水线;AI 生成管线;MCP Server validate-schema(需升级为双闸);决策会已将「双闸」作为质量门禁第 2 条 |
---
## 九、待补章节占位
> 以下章节在 M0 期间需要补充,当前为占位。责任人需在 M0 出口前完成。
### 9.1 知识 backup 人选(待定)
| 事项 | 状态 | 责任人 | 期限 |
|------|------|--------|------|
| 熟引擎老员工 backup 人选确定 | **待定** | 项目负责人 | M0 出口 |
| backup 人员与老员工 1:1 交接会(≥2 次) | **待定** | 老员工 + backup | P1 第一周 |
| backup 人员能独立运行 eip4-poc + 解释对拍结果 | **待定** | backup | P1 结束 |
**背景**:决策会将熟引擎老员工列为单点风险(R3),backup + 本手册是降险硬要求;立项决议含「backup 人选确定」为 M0 出口条件之一。
### 9.2 手册过评审记录(待补)
| 评审项 | 评审人 | 日期 | 结论 |
|--------|--------|------|------|
| 第二至八章坑位完整性 | 待定 | 待定 | 待定 |
| 对拍框架设计(C1)评审 | CTO + 老员工 | 待定 | 待定 |
| Flowable 升级三坑与 Runbook 对应 | P3 责任人 | 待定 | 待定 |
### 9.3 WS3 facade 动词表扩展(待补 P1)
当前已确认的 4 个基础辅助函数(`getFieldValue` / `bindField` / `setFieldReadOnly` / `showConfirmDialog`)之外,盘点报告 Top S3 API 调用显示需扩展至 ~20 个:
已知待补:`addButton`×100、`getValue`×68、`getContainerDataSource`×61、`setFilter`×56、`removeAllItems`×29、`group.setReadOnly`×27、`getDisplay`×27、`setVisible`×21、`setCaption`×16……
P1/P4 阶段由老员工与后端架构逐条补全,补全后回填本节。
---
**手册维护说明**:本手册随工程化进展持续更新;新坑位发现即追加,以 `[NEW yyyy-mm-dd]` 标记;章节完成后移除「待补」标记。任何对引擎行为契约的更改必须同步更新第五章并过 code review。