Files
eip4-platform/docs/迁移手册.md
zhengwr 33d793b825 feat(auth): P2-2 Spring Security 无状态 JWT 认证链路 + UserSession 引擎上下文适配
- jjwt 0.12.6 HS256;密钥配置化(EIP4_AUTH_JWT_SECRET),启动期强度校验,不入仓库
- 密码兼容:复刻 framework EncryptUtil 无盐 MD5 + 常量时间比对(侦察证据见报告)
- JwtAuthFilter:SecurityContext + 引擎 UserSession(静态 ThreadLocal)请求级 set/finally clear,16线程×200次并发隔离单测
- SecurityConfig 双链:prod 严格 401 / 非 prod 保留对拍测试通道(单测断言生产关闭)
- EntityController.buildCtx 三级优先(asUser > JWT > ADMIN),修复 JWT ctx 被 ADMIN 默认覆盖
- 实测:登录签发/过滤 16 行与 DB 吻合/伪造过期全 401;ci.sh 全绿;手册新增 §5.29-5.31

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

542 lines
50 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 注册) | **Caffeine 版**(P1-4 由极简 HashMap 升级) | 待查 | 极简 | 调用方只用 Map API;**公共签名零改动**(仍 extends HashMap + 双构造器 + getName/reset),`get/put/remove/size/clear` 覆写代理到内部 Caffeine `Cache`。详见 5.15 |
| `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 层)。
### 5.19 标识符白名单——引擎裸拼点清单(安全第 1 层落地) [NEW 2026-06-11]
- **现象**:`POJOCRUDServiceImpl.listSelectSpecialCol` 把查询条件 Map 的 key 经 `get_SearchWhereClause(map)` 拼成 WHERE 列名;`ORDER` 键(值 `" ORDER BY ..."`)经 `sql = sql + order` **裸拼**到 SQL 末尾(见 POJOCRUDServiceImpl.java:101/309/318/388)——列名/排序列是残余注入面。
- **根因**:引擎值位置已经 `StringUtil.TO_STRING` 单引号转义,但标识符(列名/排序列/表名)位置无转义概念,只能靠白名单。
- **对策(P1-3 已落地)**:`com.eip4.platform.metadata.security.IdentifierWhitelist` 用「该实体 `SYS_ENTITYATTRIBUTE` 合法列集」做白名单,`EntityController.list` 的查询条件 key、`orderBy`、表名全过白名单,非法 → HTTP 400(不回显载荷);`orderDir` 限 `asc/desc`。保留键放行清单:`page/perPage/asUser/roles/orderBy/orderDir`。**新增列/排序参数进引擎前必过白名单**,这是现代层对引擎裸拼点的纪律。
- **影响范围**:所有经现代层进引擎拼接的标识符;新写 Controller 透传查询条件/排序时必须复用 `IdentifierWhitelist`;详见 platform-metadata/P1加固实测报告.md 第一节。
### 5.20 POInfo 缓存失效靠 setChangePOInfo,冷态需先装载 id_cache [NEW 2026-06-11]
- **现象**:C1 坑 3「POInfo 缓存元数据变更后不失效须重启」。引擎公共静态钩子 `AbstractPOJOInfo.setChangePOInfo(entityId)` 清 `id_cache[entityId]→tableName` 再清 `s_cache[tableName]`;但若 `id_cache` 冷态(该 entityId 未被读过),钩子拿不到 tableName,**清不掉 s_cache**。
- **根因**:`setChangePOInfo` 依赖 `id_cache` 已装载 entityId→tableName 映射;首次读才装载。
- **对策(P1-4 已落地)**:现代层 `PoInfoCacheInvalidator.evictByTable` **先 `POInfo.getPOInfo(table)` 装载映射(顺带拿 entityId)再调 `setChangePOInfo`**,保证冷态也能命中;`evictByEntityId` 用于已知 entityId 的删除场景。接入 `MetaController.createEntity/dropEntity` + 新增 `POST /api/meta/evict/{table}` 运维出口。**全程只用引擎公共 API,不改 com.dsasp**。8086 实测:旁路加列 → 未失效仍 400(复现坑)→ 调 evict(不重启)→ 200(修复)。
- **影响范围**:所有元数据旁路写入(直改 SYS_ENTITYATTRIBUTE 等)后须调失效钩子;CCache 换 Caffeine 后失效语义不变(reset/remove 仍即时生效)。
### 5.21 引擎 createTableSql 只建表不建索引,补索引须现代层后置 [NEW 2026-06-11]
- **现象**:`Entity.createTableSql` 只产 `CREATE TABLE` + 主键 + `unique`(标识符列),**不建普通索引**;外键列(REFERENCEID=36 位 uuid)、审计列 UPDATETIME 无索引,大表首页 count/扫描/排序慢(C3 客户库 34k 行 P95 1.18s)。
- **根因**:引擎 DDL 生成器设计只保证结构正确性,不含查询优化索引。
- **对策(P1-5 已落地)**:`com.eip4.platform.metadata.perf.IndexEnhancer` 现代层后置——建表后按元数据补 `CREATE INDEX IF NOT EXISTS`(外键 uuid 列 + UPDATETIME;**跳过** ISIDENTIFIER/ISCOMBIDENTIFIER 因引擎已建 unique);`BacklogIndexScriptGenerator` 为存量实体**只生成补索引 SQL 落盘,不对客户库执行**(执行排切流期变更窗口)。**不改引擎**。
- **诚实边界**:本地 20k 行口径索引延迟改善边际(planner 小表仍 Seq Scan);真实收益在 34k+ 行 + JOIN/count 档,需客户库副本切流期执行脚本后用 load_p95.py 同口径复测验证。
- **影响范围**:所有动态建表的业务实体;客户库存量补索引执行排变更窗口;新建实体经 MetaController 自动补索引。
### 5.22 物理冗余列(无活跃元数据)被误判 MISSING_RIGHT [NEW 2026-06-11]
- **现象**:P1-1 全库对拍中一批实体报「右缺列」(MISSING_RIGHT),如 GB_DEVICE.CHECKONLINE、SYS_CODERULE.ORGID/DEPARTID、VIEW_USER_KQ.PASSWORD、VIEW_SYS_MENU.SEQ、VIEW_PM_CONTRACT.SIGNUPTIME/PUTONRECORD、各 VIEW_* 的 CREATETIME/CREATEBY/UPDATETIME/UPDATEBY/ISACTIVE 审计列、VIEW_PM_LABORTEAM.UNITNAME/REGISTERDATE、office goods 的 MAXIMUMINVENTORY/BUYAMOUNT 等。物理表/视图**有**该列且有值,引擎 list 输出却没有。
- **根因**:这些列在 `SYS_ENTITYATTRIBUTE` **无任何记录**(连 isactive=0 都没有)——物理冗余列(历史遗留/视图多投影列)。引擎读路径是**元数据驱动**:只 SELECT 元数据声明的活跃列,故永不读它们。**新旧系统行为完全一致**(同一引擎元数据驱动),非移植缺陷。逐列查证:24 个(实体,列)对 attr_any 全 = 0。
- **对策**:对拍 harness 加「物理孤儿列」元数据感知豁免(platform-parity `RowDiff.physicalOrphanColumns`):MISSING_RIGHT 且列不在实体活跃元数据列集 → 整列登记 `physicalOrphanColumns` 不判负(报告可见)。**反向守门**:若列明明在活跃元数据却 MISSING_RIGHT → 真缺陷,不豁免。
- **影响范围**:全库带物理冗余列的表/视图;数据治理时这批列应与客户确认是否清理;前端/AI 消费 API 不应依赖元数据外的物理列。
### 5.23 PG xml 物理类型列:JDBC 与引擎读出表示不同 [NEW 2026-06-11]
- **现象**:VIEW_PAGE/VIEW_TEMPLATE/VIEW_WFTEMPLATE.XML、SYS_SERVICEFLOW.CONTENTXML 等 `xml` 物理类型列对拍报 VALUE 差异;差异表现为左侧带 `<?xml version="1.0" encoding="UTF-8"?>` 声明头或前导换行,右侧引擎无。
- **根因(两层)**:① **JDBC 读出的是 `java.sql.SQLXML`(PgSQLXML)对象**,不是 String——其 `toString()` 非 XML 正文且 Jackson 无法序列化(内含 binaryStream),直接比对/报告序列化都会出错。② 即便取 `getString()`,PG `xml::text` 会保留入库时的 XML 声明头/首尾空白,引擎读路径剥离——同一份 XML 的两种表示。
- **对策**:① 对拍读取侧(JdbcResultReader)对 SQLXML 统一 `getString()` 物化为文本,与引擎对齐(根治);② 再加 XML 归一化(`Normalizer.xmlEqual`:剥 `<?xml..?>` 声明 + trim 首尾空白后比正文)作二次兜底;正文实质差异仍判负(守门不吞)。VIEW_PAGE 1241 行实测:物化后 1090 完全相同、137 仅首尾空白、11 仅声明头,全部表示差异。
- **影响范围**:所有 `xml` 物理类型列(数据库 information_schema data_type='xml');任何 JDBC 直读 xml 列的代码必须 `getString()` 物化,不能持有 PgSQLXML。
### 5.24 引擎对 JSON/数组类型列的物理 null 渲染为空数组 [NEW 2026-06-11]
- **现象**:PM_CALCBASICSCONFIG.DETAILS(varchar,物理全 NULL)对拍报 VALUE 差异:左 null,右非 null。
- **根因**:引擎对该列按 JSON/数组显示类型解析,物理 NULL 序列化为 **JSON 空数组 `[]`**(经 EngineHttpClient `nodeValue` 的 `asText()` 落地为空串 `""`)。即「物理无值」的引擎渲染是空集合而非 null。新旧引擎渲染一致。
- **对策**:对拍 harness 加「引擎空值渲染」豁免(`RowDiff.engineEmptyForNullColumns` + `Normalizer.nullVsEngineEmpty`):仅自对拍模式、仅「左 null + 右空串」一个方向成立 → 语义等值整列登记;左有内容/右空串仍判负。
- **影响范围**:JSON/数组显示类型列;前端消费时「空数组」与「null」语义需对齐(均表示无值)。
### 5.25 SQL 视图无稳定唯一行键,逐行配对失效需多重集兜底 [NEW 2026-06-11]
- **现象**:VIEW_OA_MEETING(83 行,{表名}_ID 两侧各仅 5 distinct)、VIEW_ACT_RU_TASK、VIEW_PM_TURNOVERMATERIALBUYACCOUNT 等 SQL 视图对拍报满 onlyLeft/onlyRight(成对),一致率近 0,但逐列内容其实一致。
- **根因**:视图的 `{表名}_ID` 是 JOIN/生成列,**两侧表示不同且坍缩**(JDBC 是 UUID、引擎是 `4028_...` 拼接串,或大量重复);RowDiff 按该键配对必然撞车错位 → 假阳性。
- **对策**:对拍 harness 加多重集兜底(`RowDiff.diffMultiset`):主键在两侧不唯一(或逐行配对零命中)时,放弃配对、把两侧规范化为「行多重集」直接比较——行集语义一致即判一致;比对域排除不稳定 {表名}_ID 与物理孤儿/计算列;时间(epoch↔ISO)、整数↔等值小数用 `Normalizer.groupingKey` 与逐行 equal 同口径归一(否则同行因表示不同分到不同桶假阳性)。净增/净缺行仍登记 onlyLeft/onlyRight。
- **影响范围**:所有无稳定唯一行键的 SQL 视图;录制重放模式(新旧引擎两侧同源)仍走逐行配对,此兜底仅自对拍用。
### 5.26 大表/关联表对拍:抽样需 {表名}_ID,无则退全量;O(N) 重查询大表夜批 [NEW 2026-06-11]
- **现象**:① 关联/中间表(SYS_ROLE_ROLE、SYS_USERGROUPUSER、OA_*RELATION、各 *ANDSUBCATEGORY 等)行数超 maxFull 走抽样,但无 `{表名}_ID` 主键 → 抽样回查 IN(pk) 不成立,报「抽样模式需 {表名}_ID」;② GB_ATTENDANCEINFO(1,184,533 行)+ 复杂视图 O(N) 重查询(§5.14),perPage 200 仍单请求超时。
- **根因**:① 抽样实现按引擎首屏 {表名}_ID 回查 JDBC,无此列即失效;② 深页/大表每页重算 DISTINCT+LATERAL(§5.14)。
- **对策**:① harness 抽样无 {表名}_ID 时**自动退全量 check()**——其复合键/多重集兜底正确处理无主键关联表(实测 SYS_ROLE_ROLE 2914 行、OA_SEALUSEAPPLYANDSEALRRELATION 11059 行均 100%);② 1M+ 行 + 重查询实体列**夜间批跑**,用更小 perPage + sampleRows,在时间盒内做值级抽样验证。
- **影响范围**:全库无 {表名}_ID 的关联表(均可全量验证);GB_ATTENDANCEINFO 等超大表纳入夜批待办。
### 5.27 引擎对部分实体输出错误行集(读路径 SQL 生成缺陷)[NEW 2026-06-11]
- **现象**:PM_LABORTEAM(物理 71 行 71 唯一 ID)引擎 list 返回 71 行但 `PM_LABORTEAM_ID` 仅 **2 distinct**(一个 id 重复 70 次),排除所有 ID 列后每一列(LABORTEAMNAME/CREATETIME/SERIALNUMBER 等 30 列)multiset 都不齐;PM_SPIDER_JSBIDWIN(物理 315,035 行)引擎 list 单页 500 行**全为同一行**(distinct full row = 1)。
- **根因**:引擎 `POJOCRUDService.listSelect` 对这两个实体的动态拼 SQL 生成缺陷(疑笛卡尔/错误 JOIN 把单行复制 N×并覆盖 ID 与值)。**直连 JDBC `SELECT *` 正常**,故是引擎读路径而非数据问题。
- **对策**:这是**真缺陷**,属引擎读路径(`com.dsasp` 保真层 / 现代层 SQL 生成,需引擎侧排查),**对拍不豁免、完整取证**;harness 经多重集兜底正确报为 DIFF(净差异行 + 比对域留痕)。修复方向:对照旧系统同实体 listSelect 输出确认是移植引入还是旧系统固有。
- **影响范围**:PM_LABORTEAM、PM_SPIDER_JSBIDWIN 已确认;凡引擎 list 的 {表名}_ID distinct 数远小于行数的实体须排查(全库可加 distinct(pk)/count(*) 探针筛查)。
### 5.28 引擎 HTTP 500 读失败:元数据/物理漂移 + 视图读路径缺陷 [NEW 2026-06-11]
- **现象**:8 个实体引擎 list 稳定 HTTP 500(可复现),但直连 JDBC 查询正常出数。
- **根因(两类)**:① **元数据/物理漂移**:SYS_DATASTATUS(元数据声明 SYS_DATASTATUS_ID/CREATEBY/审计列,物理表仅 BUSINESSKEY/DATASTATUS/TABLENAME,无 PK)、SYS_UPDATE_LOG(元数据声明 ISACTIVE BOOLEAN,物理表无 isactive 列)→ 引擎 SELECT 引用不存在列报错;② **视图读路径缺陷**:VIEW_SYS_DIMENSIONDEPART/VIEW_PM_ARTIFICIALRELATION/VIEW_PM_MACHINERELATION/VIEW_PM_MATERIALRELATION/VIEW_OA_REIMBURSEMENTAPPLYSUM/VIEW_PM_PAYMENTAFFIRMSUM/VIEW_PROJECTCONTRACTNUMBER(元数据列全在物理视图、JDBC 直查正常,引擎仍 500)→ 引擎对视图的读路径 SQL 生成缺陷(疑 reference 显示 LATERAL/保留字未引号,如 VIEW_SYS_DIMENSIONDEPART 含 `LEVEL` 列)。
- **对策**:① 第一类按 §7.2 元数据漂移处置(对齐元数据或物理表,客户确认);② 第二类是引擎读路径真缺陷,取证待引擎侧修复。对拍 harness 如实记 ENGINE_ERROR + 500 body,不豁免。
- **影响范围**:8 个实体;与 §7.1/§7.2 PoC 计数级口径互证(本轮逐个落实根因)。
### 5.29 JWT 上下文被 EntityController 的 ADMIN 默认覆盖(认证集成坑)[NEW 2026-06-11]
- **现象**:`JwtAuthFilter` 已把 JWT claims(CURRENTUSER=真实 userId + ROLES)写入引擎 `UserSession`,但带令牌调 `/api/entity/{t}/list` 仍返回全量(不过滤)。
- **根因**:`EntityController.buildCtx(asUser, roles)` 在无 `asUser` 查询参时**无条件返回 `UserSession.getAdmin()`**,覆盖了过滤器刚绑定的请求级上下文;ADMIN 视角天然不触发行级过滤(引擎仅 `CURRENTUSER != ADMIN` 时调 `dataPrivilegeService`,见 §5.9)。
- **对策**:`buildCtx` 改为三级优先:① 显式 `asUser` 参(C2 对拍测试通道,CI 依赖)优先;② 否则复用 `UserSession.get()` 已绑定的非 ADMIN 上下文(JWT 驱动);③ 都没有才回退 ADMIN。如此 **JWT roles 替代 asUser/roles 参数**驱动过滤,且对拍旁路零回归(full CI 21/21 + C2 9/9 仍绿)。
- **影响范围**:凡「过滤器绑 ThreadLocal 上下文 + 控制器又自建 ctx」的端点都有此覆盖风险;新端点须遵循「过滤器绑定优先于控制器默认」。
### 5.30 引擎 UserSession 是静态 ThreadLocal,认证过滤器必须请求级 set/clear [NEW 2026-06-11]
- **现象/契约**:`com.dsasp.server.common.util.UserSession` 是**静态 `ThreadLocal<Properties>`**;引擎全程从当前线程取 `CURRENTUSER/CURRENTDEPART/CURRENTORG`(字符串)与 `ROLES`(**List,用 `put` 非 `setProperty`**——引擎 `ctx.get("ROLES")` 强转 `List<String>`)。
- **坑**:Tomcat 复用工作线程;若 filter 只 set 不 clear,下一请求会**继承上一请求身份**(跨请求泄漏)。
- **对策**:`JwtAuthFilter` 在 `try` 中 `EngineContextBinder.bind`,`finally` 中**无条件 `clear`**(即便下游抛异常)。并发隔离由 `EngineContextIsolationTest`(16 线程×200 次不同令牌)断言零串号 + 收尾零残留。`ROLES` 必须 `put(List)` 不可 `setProperty`,否则引擎强转 ClassCastException。
### 5.31 客户库 SYS_USER 口令哈希=无盐小写十六进制 MD5(侦察结论)[NEW 2026-06-11]
- **侦察证据**(读 framework 源码核实):`com.dsasp.server.common.util.EncryptUtil.encodeMD5String` = `MessageDigest("MD5").digest(str.getBytes())` 逐字节小写十六进制(`b<16` 补前导 0),32 字符,**无盐、无迭代**;登录比对为 `hash.equals(SYS_USER.PASSWORD)` 纯字符串相等(见 `AuthConstroller#login`、`ChangePasswordView`、`LoginWindow`→`SYS_USER_SEARCH` 流按 ACCOUNT+PASSWORD 查)。
- **落地**:platform-auth 在 `com.eip4` 侧**逐字节复刻** `PasswordHasher.md5Hex`(保真层 EncryptUtil 一行不改),用平台默认字符集 `getBytes()` 与旧系统一致;比对用 `MessageDigest.isEqual` 常量时间防时序侧信道。验证:`MD5("123456")=e10adc3949ba59abbe56e057f20f883e` 单测断言。
- **注意**:无盐 MD5 是**待现代化项**(口令存储弱),但本任务目标是兼容验证既有客户库口令,口令强化属后续独立议题(可在改密路径渐进迁移)。角色解析复刻 `RoleServiceImpl#findRolesByUserId`(`sys_usergrouprole ⋈ sys_usergroupuser`),org 表未移植时降级空角色不阻断登录。
## 六、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。