Files
eip4-platform/docs/迁移手册.md
zhengwr d137577759 eip4dev: 构建本地开发库,日常开发完全脱离 5435
- tools/local-devdb/build_devdb.sh: 幂等构建脚本,分层 dump/restore
  (ACT_* schema-only / 超500MB巨表 schema-only / 其余全量),
  内置 5435/ceshi 库安全守门,参数化源/目标/阈值/巨表清单
- tools/local-devdb/sql/data-tables.txt: 必须全量的引擎元数据/组织表清单
- tools/local-devdb/本地开发库构建报告.md: 实跑报告(2738MB/345s/94.1%对拍通过)
- application-dev.yml: dev profile 指向 localhost:5433/eip4dev,端口 8093
- README.md: 补三套 profile 说明(dev/local/默认)及常用命令
- SysUserService.java: 修复 MASTERDEPART 列不存在导致登录 500 的 bug
- docs/迁移手册.md: 追加三条新坑位(MASTERDEPART/sys_page_schema/shell 中文变量名)

验证: 登录 OK / list(1079行) / picker(5条) / ParityCli 1166实体 803 OK_FULL+294 OK_SAMPLE
完全本地: pg_stat_activity 全部连接来自 127.0.0.1:eip4dev,无 5435 连接

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

813 lines
95 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 阶段补全真实现 |
| `FTPClientTemplate` | FTP 远端存储后端(commons-net + DB 内 FTPServer/FTPPort/FTPUserName/FTPUserPassword 配置)| **本地盘后端**(P2-3,附件横切服务真实现移植)| 308 行 | 约 150 行 | **保包名/类名/对外签名**(`uploadFileAndZip`/`downloadFile`/`delete`/`fileExists`);后端 FTP→本地盘,根目录=`MainApp.destPath`(默认 `./data/files`,经 `eip4.file.root` 配置化注入)。`FileServiceImpl`/`ZipUtil` call site 零改动。安全:`resolveSafe` 归一 canonical path 拒绝 `../` 逃逸出根。详见 §5.36 / platform-auth/P2横切服务实测报告.md |
**注意**:替换时必须**保持包名/类名/方法签名完全一致**,旧引擎代码对这些类的引用不做任何修改——「旧代码零感知」是双层制的核心约定。
### 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.platform.auth.stub`~~ | **已由 P2-3 真实现接管** | 桩已删除;保真层 `com.dsasp.server.file.service.FileServiceImpl`(原样移植,bean `fileService`)接管;存储后端经替换类 `FTPClientTemplate`(本地盘,根目录 `eip4.file.root` 配置化)。详见 §3.1 / §5.36 / platform-auth/P2横切服务实测报告.md |
| `projectSwitchService` | `com.eip4.platform.auth.stub` | no-op(**保留**) | **viewframework 域,非 P2-3 文件/日志/消息范畴**;P2 计划未列其真实现归属,保留桩待 viewFramework 域专项移植接管 |
| ~~`systemLogManager`~~ | ~~`com.eip4.platform.auth.stub`~~ | **已由 P2-3 真实现接管** | 桩已删除;保真层 `com.dsasp.server.log.service.SystemLogManagerImpl`(bean `systemLogManager`)+ `DataOperatorLogger`(bean `dataOperatorLog`)+ `DataLogRecorderImpl`(bean `dataLogRecorder`)原样移植,异步批量落 SYS_LOG / SYS_DATA_LOG / SYS_DATA_LOGITEM。`StubDataOperatorLog` 同步删除 |
| ~~`systemEmailService`~~ | (原无桩) | **P2-3 移植 + 降级装配** | 保真层 `com.dsasp.server.mail.service.SystemEmailServiceImpl`(bean `systemEmailService`)+ `SystemEmail`/`SystemEmailService` 移植;**SMTP 配置缺省时降级 no-op + WARN,不阻塞启动**。详见 §5.37 |
---
## 四、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 表未移植时降级空角色不阻断登录。
### 5.32 客户库 sys_usergroupuser.userid 列长度不一致(36 padding vs 32),varchar 等值只匹配同表示行 [NEW 2026-06-11]
- **现象**:P2-1 组织模块移植后,`GET /api/org/user/{id}/roles`(底座 `RoleServiceImpl.findRolesByUserId`)某用户返回 360 角色,但「直觉版」对账 SQL(给 userid 加 trim 或不加)得 0 或别的数,难以对账。
- **根因**:`sys_usergroupuser.userid` 是 `character varying` 但**数据混存两种长度**——36 字符(空格补足到 36 位,客户库 5101 行)与 32 字符(无补足,198 行)。`findRolesByUserId` 的 `WHERE ugu.userid='<32位id>'` 走 varchar `=`(**PG varchar 等值不忽略尾空格**,区别于 bpchar),只命中 32 位的非补足行 → 该用户得 215 条 direct 角色,再经 `SYS_ROLE_ROLE`(OPERATORROLE IN 215)派生 145 → 列表共 **360**(含重)。用 DB 完整复现引擎两步 SQL(保持「'<32位id>' 不补空格、varchar 等值」语义)= 360,**逐字节一致**。**新旧系统行为相同**(同一引擎 SQL),非移植缺陷;是客户库历史数据 ID 表示不一致。
- **对策**:① 对账/对拍此类用户-角色关系**必须用引擎精确 SQL**(不擅自加 trim/pad,否则与引擎口径背离产生假差异);② OrgController 用户-角色端点直接委托保真层 `roleService`,语义零偏移;③ 数据治理时这批 32/36 混存 ID 应与客户确认统一(决策会红线 3 口径)。
- **影响范围**:所有按 userid 等值过滤 `sys_usergroupuser` 的路径(角色解析、岗位用户查询);凡跨 char/varchar 等值比较且数据有补足不一致的列(对照 §5.7 混合大小写表名,此为「长度/补足不一致」同族坑)。
### 5.33 真实数据权限规则形态多样,对拍只纳入可确定性复现形态做正例 [NEW 2026-06-11]
- **现象**:P2-1 权限对拍扩容做「真实实体只读权限对拍」时,客户库 `SYS_FILTERRULE` 有 **1079 条活跃规则**(`SELECT entityid,count(*) FROM sys_filterrule WHERE isactive=1 GROUP BY 1` 反查 tablename:PM_PAYMENTAPPLY 31/VIEW_PM_CONTRACT 23/PM_CONTRACTACCOUNTS 22/HR_SAFETYCARD 13…),`filterrule` 列 JSON 形态多样:`[]`(查看全部)、`[{USERID={CURRENTUSERID}}]`(查看自己)、`[{KIND=N}]`(静态)、`[{USERID in (select … where userorgid={CURRENTUSERORGID})}]`(本公司)、OWNNERPROJECT 等。
- **根因**:`{CURRENTUSERORGID}`/`{CURRENTUSERDEPART}`/OWNNERPROJECT 等动态规则的等价 WHERE 依赖运行期 ctx(org/depart/project)且含子查询,在对拍侧**精确重建脆弱**(易因 ctx 取值口径偏差产生假阳性);而引擎 OR-合并用户**全部**命中角色的规则,单条难隔离。
- **对策**:`RealEntityPrivilegeRunner`(`ParityCli --realprivilege`)只挑两类**可确定性复现等价 WHERE** 的形态做正例:① `[]`→全表;② `[{USERID={CURRENTUSERID}}]`→`WHERE userid='<uid>'`。且**仅当真实用户对该实体的全部交集规则都属可复现形态**才取为正例(否则引擎 OR 进不可复现规则,等价 WHERE 不成立);其余真实形态语义虽真实,**如实登记不纳入正例**(避免假阳性)。负例(无命中角色→`PrivilegeException`)对所有有规则实体均可验。**全程只读,绝不向客户库写规则**(任务红线)。实测:HR_SAFETYCARD/HR_OTHERCARD/HR_CONSTRUCTORCARD/HR_MEMBERCARD 共 4 实体 805 行 100% 逐行一致 + 5/5 负例被拒(见 platform-auth/P2组织权限实测报告.md §七)。
- **影响范围**:所有真实规则权限对拍;`{CURRENTUSERORGID}`/OWNNERPROJECT 等动态形态的对拍待 P2 管理 UI 落地后,用「写规则→读回 ctx 一致性」闭环验(届时有真实 ctx 来源),非本期只读对拍能覆盖。
### 5.34 多维权限对拍:引擎需 CURRENTDEPART/CURRENTORG,EntityController 测试通道须加 asDepart/asOrg [NEW 2026-06-11]
- **现象**:P2-4 实测多维隔离(部门/组织/项目维)时,引擎 `DataPrivilegeServiceImpl.getFilterSql` 对 `CURRENTUSERDEPARTID`/`CURRENTUSERORGID` 类型条件读 `ctx.CURRENTDEPART`/`ctx.CURRENTORG`,但 `EntityController.buildCtx` 的 `asUser`/`roles` 测试通道**只注入 CURRENTUSER + ROLES**,部门/机构维 ctx 为空 → 多维过滤拼出 `P.DEPARTID =''`(空串)致结果恒空,无法对拍。
- **根因**:C2/P2-1 仅验单维(CREATEBY/USERID/view-all),测试通道未覆盖部门/机构维 ctx。
- **对策**:`EntityController.list` 增 `asDepart`/`asOrg` 两个**测试通道**查询参(与 `asUser` 同性质,加入 `RESERVED_KEYS` 放行),`buildCtx` 在 asUser 分支可选 `ctx.setProperty(CURRENTDEPART/CURRENTORG, …)`。不传则维持单维行为(零回归)。对拍执行器 `MultiDimPrivilegeRunner`(`ParityCli --multidim`)据此驱动 `asUser+asDepart+asOrg+roles` 多维 ctx vs JDBC 等价 WHERE 逐行 diff。实测 **14 形态(单维部门/组织/SPECIALDEPART/OWNNERPROJECT、op=AND 串联、多规则角色 OR、建筑三维 OWNER×部门×项目)100% 逐行一致 + 7/7 负例被拒**(见 platform-auth/P2多维数据权限实测报告.md)。
- **影响范围**:凡需多维 ctx 的对拍/集成测试同此(测试通道补维度键,生产经 JWT/UserSession 注入真实 ctx,非测试通道);`SPECIALDEPART`/`SPECIALORG` 客户库零使用但引擎支持,本期已补构造验证全覆盖。
### 5.35 多维自举 bootstrap 清理须按精确 id 删属性,LIKE 'a1000000-%' 会误删 bootstrap-sys 的 SYS 自描述元数据 [NEW 2026-06-11]
- **现象**:`bootstrap-multidim.sql` 复用 `bootstrap-privilege` 的 SYS_FILTERRULE 自描述元数据 id(`a1000000-…-08xx/09xx`),清理时若写 `DELETE FROM sys_entityattribute WHERE sys_entityattribute_id LIKE 'a1000000-%'`,会**连带删掉 bootstrap-sys 为 SYS_ENTITY/SYS_USERGROUP/SYS_ENTITYATTRIBUTE 等系统表建的自描述属性**(它们 id 同前缀 `a1000000-…-01xx..07xx`)→ 引擎 `getSYSEntityByTableName` 的 `loadPOJO(…,"SYS_ENTITY",…)` 因 SYS_ENTITY 零属性 → `buildSelect` 产出字面 `null` → **任意实体 list 全盘 HTTP 500**(`PSQLException: syntax error at or near "null"`,Position 1)。
- **根因**:SYS 自描述元数据(SYS_ENTITY 自身的列定义)是引擎解析**所有**实体的前置依赖;bootstrap-sys 与权限/多维 bootstrap 的属性 id 共享 `a1000000-` 前缀,宽前缀 DELETE 跨界误删。
- **对策**:幂等清理**只删本脚本自建**的属性——精确到 `a1000000-…-0008%`/`-0009%`(SYS_FILTERRULE/中间表)+ 自定义前缀 `amd00000-`(多维实体),**绝不**用宽 `a1000000-%`。排错锚点:`SELECT e.tablename, count(a.*) FROM sys_entity e LEFT JOIN sys_entityattribute a … WHERE e.tablename='SYS_ENTITY'`——SYS_ENTITY 属性数为 0 即此坑。
- **影响范围**:所有复用 bootstrap-privilege/bootstrap-sys 固定 id 的增量 bootstrap 脚本;新增自举脚本的 DELETE 一律按**本脚本自有 id 段**收敛,不按共享前缀。
### 5.36 附件 FileService 原版后端=FTP(非本地盘),本地盘默认须经替换类落地;旧依赖 sun.misc.BASE64Decoder/ant zip 在 JDK17 不可用 [NEW 2026-06-11]
- **现象**:framework `FileServiceImpl` 看似「本地盘」,实则 `save` 经 `ZipUtil.ZipFileToDest`→`FTPClientTemplate.uploadFileAndZip` **上传到 FTP 服务器**(地址取自 DB `DBInfoConfigurer.getContextProperty("FTPServer/FTPPort/...")`),`getDocFile` 同样经 FTP 下载;且 `FileServiceImpl` 用 `sun.misc.BASE64Decoder`(JDK 17 已移除)、`ZipUtil` 用 `org.apache.tools.zip`(ant)、`FileUtil.getFileType` 用 `javax.swing.FileSystemView`。直接原样移植在 Boot 3 / JDK 17 既编译不过,也不满足「默认本地盘、不依赖外部服务」。
- **根因**:旧引擎附件层是「DB 元数据(SYS_DOC) + FTP 物理存储」二段式;存储后端被封装在 `FTPClientTemplate`(commons-net),正是 §3.1 可等价替换的耦合点。
- **对策**:按 §3.1「保包名/类名/对外签名」替换类策略——`FileServiceImpl`/`ZipUtil` 主体原样移植(仅 `BASE64Decoder`→`java.util.Base64`、ant zip→`java.util.zip`、`HashCalc` 的 commons-codec→JDK `MessageDigest`,摘要逐字节一致),把 `FTPClientTemplate` 整体换为**本地盘后端**(同包同名同签名 `uploadFileAndZip`/`downloadFile`/`delete`/`fileExists`)。根目录 = `MainApp.destPath`,默认 `./data/files`,经 `eip4.file.root`(application.yml,环境变量 `EIP4_FILE_ROOT` 可覆盖)由 `LegacyXmlWiring` 单向注入(保真层不反向依赖现代层,ArchUnit 约束)。上传仍按原语义把单附件 zip(单条目=文件名)落 `destPath+相对路径`,SYS_DOC 落库(FILEPATH/MD5/软删 ISACTIVE)语义不变。**安全第 1 层**:`resolveSafe` 用 canonical path 比对,拒绝 `../` 逃逸出根(WARN + IOException)。
- **影响范围**:凡涉及附件存储的路径;真实启用 MinIO/对象存储时,同样在 `FTPClientTemplate` 这一替换类处换后端,`FileServiceImpl` 及引擎调用方零改动。`MainApp` 原版写死 Windows 路径(`C:\\...`/`D:\\c\\baseDoc\\`),移植时默认值改为跨平台相对路径并加 setter。
### 5.37 系统/数据日志为异步队列+定时批量落库,bean 名 systemLogManager/dataOperatorLog/dataLogRecorder 三件齐;jdbcTemplate 须 XML 等价 setter 补齐;LOGLEVEL 未配置=整链静默 [NEW 2026-06-11]
- **现象**:`SystemLogManagerImpl.log(LogType,String)` 与 `DataOperatorLogger.insert/update/deleteData` **并不直接写库**,而是入 `ConcurrentLinkedQueue` 后由 `DataLogManager`(单例 Timer,1s 启动 30s 周期)经线程池分批(每批 100)调 `ProcessSysLogThread`/`ProcessLogThread`→ 真正落库的 `systemLogManager.log(List)` / `dataLogRecorder.recorderLogs(List)`。线程任务用 `SpringBeanOsgiServices.getInstance().getBeanByName(...)` 取 bean,故 `systemLogManager`/`dataLogRecorder` **bean 名必须精确**。`SystemLogManagerImpl.log(LogType,String)` 还有两道闸:`UserSession.get()==null` 直接返回,且 `LOGLEVEL` 配置(`com.dsasp.server.log.LOGLEVEL`,逗号分隔 `LogType.value`=Errors/Info/Debug/Warnings)未命中也返回——**未配置 LOGLEVEL = 系统日志整链静默**。
- **根因**:旧引擎日志为「写多读少、容忍延迟」设计,异步批量降数据库压力;`jdbcTemplate` 在 framework 经 service.xml `<property>` setter 注入(非 @Autowired)。
- **对策**:三个 impl(`SystemLogManagerImpl`/`DataOperatorLogger`/`DataLogRecorderImpl`)原样移植 + `DataLogManager`/`ProcessLogThread`/`ProcessSysLogThread` 原样移植;`jdbcTemplate` 经 `LegacyXmlWiring`(SmartInitializingSingleton)等价 setter 补齐(见 §4.1,本次新增 fileService/systemLogManager/dataLogRecorder 三处)。本地验证须在 `sys_application_config` 种 `com.dsasp.server.log.LOGLEVEL='Errors,Info,Debug,Warnings'`(见 bootstrap-xservice.sql),否则系统日志不落。`SYS_DATA_LOGITEM` 为 insert-only 无 UPDATETIME 列(§5.1),`DataLogRecorderImpl` 只走纯 INSERT,符合。数据日志仅当实体 `SYS_ENTITY.ischangelog=1` 才记(`po.get_poInfo().isChangeLog()`)。
- **影响范围**:凡需端到端验证日志落库,须备齐三表(SYS_LOG/SYS_DATA_LOG/SYS_DATA_LOGITEM)+ LOGLEVEL 配置 + changelog 实体 + 请求级 UserSession;异步链路落库有最长 ~30s 延迟,集成测试宜直接调 `log(List)`/`recorderLogs(List)` 同步路径断言。
### 5.38 邮件 SystemEmailServiceImpl 深度依赖外部 SMTP(javax.mail + freemarker + OSGi ConfigUtil),按「配置缺省降级 no-op + WARN」装配,不阻塞启动 [NEW 2026-06-11]
- **现象**:原版 `SystemEmailServiceImpl` 构造期即 `ConfigUtil.getValue("admin_mail")`(经 OSGi `com.dsasp.resource.Activator` 读 bundle 内 properties),发件走 Spring `JavaMailSender`(javax.mail,非 jakarta.mail)+ freemarker 模板 + `TaskExecutor` 异步;`ClientMailServiceImpl` 更是整套 POP3/IMAP 收发件客户端。直接原样移植在 Boot 3 需 javax→jakarta.mail 迁移 + 活的 SMTP/POP3 服务器,且 eip4 当前无任何调用方。
- **根因**:邮件是「深度依赖外部服务」的横切件,与文件/日志(纯本地盘/本地库)性质不同。
- **对策**:按 P2 任务约定——移植 `SystemEmailService` 接口 + `SystemEmail` bean(原样),提供 `SystemEmailServiceImpl`(bean `systemEmailService`)**降级实现**:`sendEmail` 读 SMTP 发件人配置(`SysConfig` 键 `com.dsasp.server.mail.admin_mail`),缺省(默认)时仅打 WARN 后 no-op 返回,**决不抛异常、决不阻塞调用方/启动**;配置就绪时 WARN 提示「真实 SMTP 投递待 JavaMailSender 装配后接通」留口。`ClientMailService`(POP3/IMAP 全客户端)非「横切消息服务」范畴且无调用方,本次不移植。真实启用时在此 impl 接 `JavaMailSender`(jakarta.mail)即可,接口/bean 名零改动。
- **影响范围**:工作流任务提醒、报表订阅等触达邮件的路径;启用前调用方得到的是「静默 no-op + 日志」,不影响主流程正确性。
### 5.OTP P2 organize 移植:OTP 库 jotpverify.jar 无公网坐标,经模块内私有仓库解析 [NEW 2026-06-11]
- **现象**:`UserOtpServiceImpl`(动态令牌认证)依赖 `ft.otp.verify.OTPVerify`(`framework/com.dsasp.server.organize/lib/jotpverify.jar`),Maven 中央仓库无此坐标,模块编译期 `package ft.otp.verify does not exist`。
- **根因**:旧系统私有第三方令牌库,无公网 Maven 坐标。
- **对策**:置 jar 于 `platform-legacy-core/local-libs/`(标准 Maven repo 布局 `ft/otp/jotpverify/1.0.0/jotpverify-1.0.0.{jar,pom}`),在 **platform-legacy-core 模块 pom** 加 `file://${project.basedir}/local-libs` 私有仓库 + 依赖坐标 `ft.otp:jotpverify:1.0.0`。**父 pom 不动**,模块自包含、构建可复现(随工程进版本库)。`UserOtpServiceImpl` 代码原样保留一行未改。**注意**:offline(`-o`)首次构建会拒绝 file:// 仓库(未缓存),需联网构建一次(无网络下载,仅解析本地 file 仓库)。
- **影响范围**:凡移植带私有 lib jar 的 framework 模块同此法(模块 local-libs 私有仓库),勿往父 pom 加 system-scope 或全局坐标。
### 5.39 P4 脚本迁移线三坑:spring-boot 离线打包不刷新上游 jar / FULL_AUTO 不等于零外部依赖 / bindField 须随 facade 动词表注入 [NEW 2026-06-11]
- **现象一(打包陷阱)**:改了 platform-metadata 后单独 `mvn -o -pl platform-app package`,boot jar 的 `BOOT-INF/lib/platform-metadata-*.jar` 时间戳仍停在改前,新增 facade 动词运行时执行报 `No signature of method: ...bindField()`。
- **根因**:spring-boot-maven-plugin 离线 repackage 解析上游模块用了 reactor/缓存的旧产物,单模块 package 不连带重建上游。
- **对策**:改上游模块后用反应堆 `mvn -o -pl platform-app -am package` 连带重建上游再起服务;或起服务前 `unzip -l` 核验 `BOOT-INF/lib` 内上游 jar 字节码已含新方法(`javap -p` grep)。
- **现象二(FULL_AUTO 语义边界)**:S3 改写器的 FULL_AUTO(497 条)仅指「无残留 S3 UI 动词」,但脚本可能并存 `GetServicesFunction`/`GetDefaultValueFunction`/`Console`/`CustomSearchConditional` 等平台 S2 函数库/领域类调用——这些需 WS3 回迁的 Java 函数库桩(第三章),**不在 31 动词 facade 覆盖内**。
- **对策**:facade 集成挑样须按「仅 facade 动词」筛选(本批 612 条 S3 中 296 条 facade-only);端到端全量跑通须先补齐函数库桩(GetServicesFunction 等,迁移手册 §111「WS3 回迁」)。
- **现象三(基础 facade 漏注)**:改写器不改 `bindField`(它本就是 S2 形态),但运行时若只注入 31 个「改写目标动词」会漏掉 `bindField`,含 bindField 的 FULL_AUTO 脚本报未定义方法。
- **对策**:facade 动词表须把 `bindField`/`getFieldValue`/`setFieldReadOnly`/`showConfirmDialog` 四个**基础辅助函数**(§161)与 31 改写目标动词一并注入,合计 ≥32 个动词闭包。
- **影响范围**:P4 脚本批量转换/运行时脚本加载;凡用 facade 闭包注入机制执行存量脚本的环节;改上游模块后的 boot 打包流程。
## 六、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 未移植则流程发起/审批全部无法运行 |
### 6.4 Maven 调用 exec:java 时 JDK 不走脚本 JAVA_HOME(工具链坑)[NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | 升级脚本通过 `bash lib/03_upgrade_v5.sh` 调用时,`mvn exec:java` 报 `NoClassDefFoundError: org/yaml/snakeyaml/constructor/BaseConstructor`(snakeyaml 版本冲突),但在 terminal 直接运行 `mvn exec:java` 成功 |
| **根因** | Homebrew Maven(3.9.x)在脚本子 shell 中用自身探测的 JDK(如 openjdk@26),而非脚本 `export PATH` 设置的 JDK;Java 26 + exec-maven-plugin 3.4.1 + snakeyaml 1.33(Flowable 6.8.1 传递依赖)存在 NoClassDefFoundError |
| **对策** | 在调用 `mvn exec:java` 前显式 `export JAVA_HOME=<jdk17-path>` 并在 mvn 调用行传 `JAVA_HOME="${JAVA_HOME}"`;Maven 3.x 优先读 `JAVA_HOME` 环境变量覆盖自身探测结果;工具链 `03_upgrade_v5.sh` / `04_upgrade_v6.sh` 已修复 |
| **影响范围** | 工具链在 macOS arm64 Homebrew 多 JDK 环境;生产 Linux 服务器通常只有一个 JDK,此坑概率低但须在生产前验证 `mvn -version` 显示的 Java 版本 = 目标 JDK |
**三坑汇总检查清单(写入升级 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,515 个定义可见 + 抽取运行中实例 engineVer=v5 + schema.version=6.8.1.0
□ flowable-service 已包含 3 个 handler bean + cfg.setBeans 注册(P3 落地:独立服务侧而非 gateway,见 6.5)
□ 工具链运行前确认 JAVA_HOME 指向 JDK17(export JAVA_HOME=/path/to/jdk17)
```
### 6.5 3 个 handler 落在独立服务而非 gateway;组织服务全闭包改直查 SQL [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | §6.3 原写「将 3 个 handler 移植到 `platform-flow-gateway`」;但架构第三节裁定交付为 4 进程,`flowable-service.jar` 是独立进程、引擎在独立服务,`platform-flow-gateway` 只做客户端。handler 须随引擎落在 **`flowable-service`** 模块,非 gateway |
| **根因** | 候选人表达式由 Flowable 引擎在 `cfg.setBeans` 注册的 bean 上求值,bean 必须与引擎同进程;gateway 是 REST 客户端、无引擎,注册无意义 |
| **对策** | handler 按原包名移植进 `flowable-service`(`com.dsasp.server.wf.*`),bean 名不变经 `cfg.setBeans` 注册。**关键裁剪**:原版 handler 经 `SpringBeanOsgiServices` 取 `AssignmentHandler`/`UserFindService`/`OrganizationService`,传递闭包是整个保真层元数据/CRUD 引擎(`POJOCRUDService`/`GeneralPOJO`);独立服务**不拖入该闭包**,改为 `OrgDirectory` 窄接口 + `OrgDirectoryJdbc` 直查业务组织库 SQL(逐条对齐 framework `AssignmentHandlerImpl`/`UserFindServiceImpl`/`OrganizationServiceImpl`)。OSGi 取 bean → `WfBeanRegistry`(§3.1/§5.17 替换类策略)。详见 `flowable-service/P3流程服务实测报告.md` 第二节 |
| **覆盖面(P3 基线)** | 实测配置类型分布 position 1949/user 1683/formSpecifiedDimension 601/depart 14/initiator 3 等占主导(~91%)已直查覆盖;scriptUser(JUEL 脚本)/initiatorDepartManager·fixedDimension(依赖 SYS_USER.MASTERDEPART 元数据虚拟列,客户库无物理列)/sameToTask(前序活动栈)/projectRoleType(项目定制扩展)当时 WARN 降级 |
| **覆盖面(P4 闭环后,2026-06-11 更新)** | 缺口表见下;**降级类型从 5 类收敛到 1 类,候选人覆盖率 91%→99.46%**,唯一剩余降级为 scriptUser(26 处,0.54%)。详见 `flowable-service/P4前置-projectRoleType闭环报告.md` |
| **影响范围** | P3 模块落点(flowable-service 而非 gateway);gateway 聚合实现是 P3-4 客户端任务 |
#### 6.5.1 候选人配置类型缺口表(P4 前置闭环后,2026-06-11)
| 类型 | 频次 | 占比 | 状态 | 解析链落点 |
|------|-----:|-----:|------|-----------|
| position | 1949 | 40.2% | ✅ P3 | `sys_positionuser` where positionid IN(...) |
| user | 1683 | 34.7% | ✅ P3 | content 即 userid,直返 |
| formSpecifiedDimension | 601 | 12.4% | ✅ P3 | 部门→岗位类别岗位→人员,部门内无则回退公司 |
| **projectRoleType** | 528 | 10.9% | ✅ **P4 闭环** | `pm_project_user` where pm_projectid=? and role IN(八大员 true 位序) and isactive=1;位序 1-based↔role 编号;客户私有 `ProjectRoleUser` 注入时优先委托 |
| **scriptUser** | **26** | **0.54%** | ⛔ **唯一剩余降级** | JUEL 脚本 `${var}`,需活的 ExecutionEntity + 反序列化变量(实测 serializable 15/null 14/string 7),超独立服务边界,WARN 降级;方案见 P4 报告 §5.1 |
| **initiatorDepartManager** | 24 | 0.50% | ✅ **P4 闭环** | `getMainDepart`(MASTERDEPART 经 `view_sys_user.masterdepart` 子查询:positionuser.ismaster=1→position.parentdepartid)→ `sys_depart.leader` |
| depart | 14 | 0.29% | ✅ P3 | 部门→岗位→人员 |
| **fixedDimension** | 12 | 0.25% | ✅ **P4 闭环** | content=维度,岗位类别...;经 `view_sys_dimensiondepart`(parentdepartids 祖先链)本部门命中或向上回溯 |
| **sameToTask** | 5 | 0.10% | ✅ **P4 闭环** | `historyService` 取流程实例下已结束 userTask 按结束时间倒序第一条 assignee(content 为指定活动 id),对齐 `ProcessCoreServiceImpl.getSpecialActivityProcessor` |
| initiator | 3 | 0.06% | ✅ P3 | 发起人本人(流程变量 WFINITIATORUSERID) |
> 总计 4845 处:覆盖 4819(99.46%),剩余降级 26(scriptUser,0.54%)。
### 6.6 Flowable 独立服务 Boot 自动装配两坑 [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象一** | flowable-service 启动抛 `IllegalStateException: Liquibase migration DataSource missing`,context 初始化失败 |
| **根因一** | `flowable-engine` 传递依赖带 liquibase-core,Boot `LiquibaseAutoConfiguration` 被激活,但本服务双数据源无 `@Primary`,liquibase 找不到迁移数据源 |
| **对策一** | `@SpringBootApplication(exclude={DataSourceAutoConfiguration, DataSourceTransactionManagerAutoConfiguration, LiquibaseAutoConfiguration})`;`databaseSchemaUpdate=false` 下本就严禁任何 schema 迁移,liquibase 不该跑 |
| **现象二** | Hikari 报 `jdbcUrl is required with driverClassName`,引擎构建失败 |
| **根因二** | `DataSourceBuilder.build()` 产出 `HikariDataSource`,`@ConfigurationProperties` 绑 `url` 属性时 Hikari 无 `setUrl` setter(其属性名是 `jdbcUrl`) |
| **对策二** | YAML 用 Hikari 原生属性名 `jdbc-url`(非 `url`) |
| **影响范围** | 凡手工装配 Flowable 引擎 + 多数据源的独立 Boot 服务(非 flowable-spring-boot-starter 路径) |
### 6.7 act_ru_task.assignee_ 的 bpchar padding(待办按 assignee 精确查询坑)[NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | 待办 REST 按 assignee 精确查询,用 trim 后的 userid 查不到记录,但库里确有该用户的待办 |
| **根因** | `act_ru_task.assignee_` 对短 id(如 32 字符 hex)补空格到 36 字符(bpchar padding),与客户库 `sys_*.userid` 的 padding 同源(§5.32);Flowable taskQuery `taskAssignee()` 走精确等值,padding 不一致则不匹配 |
| **对策** | 待办查询/聚合层须按 padding 后形态匹配 assignee;REST 调用方(P3-4 gateway/前端)须知此口径,或在聚合层统一 padding 规整 |
| **影响范围** | 所有按 assignee 精确查询的待办接口;实测 padded assignee(尾 4 空格)REST 待办数=act_ru_task 直查数=12,trim 形态=0 |
### 6.8 Flowable 6.8.1 Task 接口无 businessKey;待办聚合须由查询侧从实例补全 [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | P3-4 gateway 待办聚合需「任务 businessKey → 业务表数据摘要」,但 flowable-service 原 `TaskDto` 不含 businessKey,gateway 无从连接业务数据 |
| **根因** | Flowable 6.8.1 `org.flowable.task.api.TaskInfo`(Task/HistoricTaskInstance 共同父接口)**无 `getBusinessKey()`**(javap 核实,仅 `getProcessInstanceId()`);businessKey 在 process instance 上,不在 task 上 |
| **对策** | flowable-service 查询侧契约增强:`TaskDto` 加 `businessKey` 字段,`/tasks/todo` 用 `runtimeService`、`/tasks/done` 用 `historyService` 按 `processInstanceId` 反查实例 businessKey 补全;另加 `GET /api/flow/process/{id}` 查实例(运行中 ended=false / 已结束历史实例 ended=true / 不存在 404),供 gateway 办理后判定流程是否结束以回写业务状态。gateway 据 `businessKey` 经 `SYS_DATASTATUS.tablename` 映射 + `loadPOJO` 读业务摘要 |
| **影响范围** | 任何需要 task↔业务数据连接的聚合层;契约演进已记入 `flowable-service` REST(todo/done 出参多 businessKey 字段,新增 GET /process/{id});实测 8089 todo 返回 businessKey 与 act_ru_execution.business_key_ 一致 |
### 6.9 单体侧流程网关 503 熔断语义 + SYS_DATASTATUS 回写守卫 [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象一·熔断** | gateway(platform-app 内)是 flowable-service(8089)的 REST 客户端;引擎进程宕机/网络分区时,待办聚合若直接抛出 RestClient 的 `ResourceAccessException` → Spring 默认 500 + 堆栈,语义错误且暴露内部 |
| **对策一** | `FlowableClient` 三道纪律:超时(connect/read 配置化)、重试(仅连接级瞬时故障带退避重试 `eip4.flow.max-retries` 次,业务级 4xx/5xx 绝不重试)、熔断降级(重试耗尽 → `FlowServiceUnavailableException` → `@RestControllerAdvice` 映射 **503** `FLOW_SERVICE_UNAVAILABLE`;引擎在线但拒绝如挂起拒办 409 → `FlowRemoteException` 透传原状态码)。实测:kill 8089 后 `/api/todo` 返回 503 干净 JSON,platform-app 进程存活不崩 |
| **现象二·回写守卫** | 办理(complete)后须按老系统语义回写 `SYS_DATASTATUS.DATASTATUS`;若无守卫,会在无业务状态记录时凭空 INSERT、或把已「通过(3)」回退 |
| **根因/口径** | 逐条对齐 framework `WfChangeStatus`(upsert:先 UPDATE,0 行则 INSERT BUSINESSKEY/TABLENAME/DATASTATUS)+ `ProcessCoreServiceImpl.passProcess`:`status = 流程已结束 ? STATUS_PASS(3) : STATUS_PROCESSING(2)`,且**仅当 `oldstatus != null && oldstatus < status`** 才回写(单调递增,不回退、不在无记录时凭空插入)。DATASTATUS 值语义=`ProcessCoreService` 常量:1 未提交/2 处理中(在批)/3 通过(已归档)/4 未通过/5 重新提交/6 作废 |
| **对策二** | `StatusWriteback.afterComplete` 复刻该守卫;参数化占位收敛原版裸拼注入面(语义不变)。**本地库验证,客户库只读**:回写仅在连本地 eip4m0(可写)时执行,生产/客户库形态由最小权限只读连接约束。实测:本地构造 SYS_DATASTATUS 行 datastatus=1,经 8090 complete(流程结束 ended=true)回写为 3;守卫负向(已达 3 / 无记录)由单测覆盖 |
| **新坑·SYS_DATASTATUS 无主键** | SYS_DATASTATUS 客户库物理表无主键(§7.2 已登记);本地自举表对齐该口径(不建主键,businesskey 上建普通索引),`bootstrap-datastatus.sql`(platform-flow-gateway 模块)随 P3-4 提供 |
| **影响范围** | platform-flow-gateway 全模块;聚合 API `/api/todo`、`/api/done`、`/api/task/{id}/complete`、`/api/process/start`(经 platform-app 暴露,JWT 取 userId/roles) |
---
## 七、库内数据质量已知问题
> 来源: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 条 |
### 8.3 amis `picker` 表单项不在 6.13 schema 的表单项 oneOf 中(弹窗选择器映射坑)[NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | P4 批量转换把旧引擎 `uitype=SelectDialog` 弹窗选择器映射为 amis `picker` 控件后,**闸一 schema 校验大批失败**,错误为 `$.body.body: array found, object expected`(form 含 ≥3 表单项时爆发);但 picker 在浏览器实际能渲染 |
| **根因** | amis 6.13 官方 schema 中 `PickerControlSchema`(type const "picker")虽存在,但**未被纳入表单项的 oneOf 分支**;form.body 数组里出现 picker 时,校验器走不到 picker 分支、回落到把整个 form.body 当单对象(SchemaNode)的分支并报「array found, object expected」。这是 schema 枚举不全,非 schema 严格性问题 |
| **对策** | 弹窗选择器(SelectDialog/MultiSelectDialog)**映射为 `select` + 远程 `source`**(multiple 对应多选),而非 picker——select+source 双闸皆过且语义保真(弹窗本质是远程数据选择)。picker 需内嵌 pickerSchema(CRUD)、跨模板引用,本就无法在单模板转换内自洽。**实测此一项把闸一通过率从 94.7% → 98.2%** |
| **影响范围** | P4 转换器 uitype 映射表(已落 `UiTypeMapper`);任何把"弹窗选择"类旧控件转 amis 表单项的地方;AI 生成管线若生成 picker 表单项同样会被闸一拒,应优先用 select+source |
### 8.4 闸二渲染冒烟宿主:大 schema 不可经 URL query 注入(HTTP 431 坑)[NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | P4 闸二 playwright 渲染冒烟,个别大模板(字段多、schema 大)被误判「根组件未渲染出 DOM」;实为宿主 HTML 自身加载失败 |
| **根因** | 冒烟宿主把 schema JSON 经 `?schema=<urlencoded>` 塞进 URL,大 schema 撑爆 HTTP 请求头,Node 静态服务器返回 **431 Request Header Fields Too Large**,host.html 根本没加载 |
| **对策** | schema 经**独立端点**(`/schema?id=<模板id>` 后端读文件返回)拉取,URL 只传短 id;宿主 `fetch('/schema?id=…')` 后再 `amis.embed`。改后该类模板渲染恢复正常(form 抽样 4/5 → 5/5) |
| **影响范围** | P4 闸二冒烟宿主(已修,见 `platform-converter/gate2-smoke/{host.html,smoke.mjs}`);任何用 query 串传 schema 给 headless 宿主的渲染验证脚本 |
### 8.5 amis show/hidden/setValue/static 不是顶层注册动作,须经组件级路由(脚本挂回重放坑)[NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | P4-5 改写后脚本挂回 onEvent 重放:把 facade 返回的指令(`{actionType:"hidden",componentId:"BEGINDATE"}` 等)当成顶层 amis 动作直接派发时,担心 `registerAction` 列表里查不到 show/hidden/setValue/static/reload 而失效 |
| **根因** | amis 6.13 SDK `registerAction(...)` 注册的**顶层动作**仅 `ajax/dialog/toast/copy/broadcast/component/...` 等(实测 30 个,无 show/hidden/setValue/static/reload);显隐/赋值/只读/重载是**组件级动作**——动作对象带 `componentId` 时由 amis 路由到该组件实例的 `doAction`,actionType 名(show/hidden/static/nonstatic/setValue/reload)由组件自身识别。`toast` 是少数顶层动作之一(无 componentId,走 args.msg) |
| **对策** | 自定义重放动作 `replayScriptCommands` 里对每条指令调 amis-core `runActions(action, renderer, event)`:带 `componentId` 的自动走组件级路由(show/hidden/setValue/static/reload 生效),`toast` 走顶层。componentId 用改写器输出的大写列名,与 amis 字段 `name` 同源天然对齐,无需映射表。实测 inited 隐藏字段、change 回填字段值均生效(见 `tools/s3_rewriter/P4脚本挂回实测报告.md`) |
| **影响范围** | eip4-web `src/amis/{scriptCommands.ts,registerReplayAction.ts}`;任何把后端 UI 动词指令重放到 amis 的胶水层;setOptions/addOption 等「改组件 options」类动词在原生 amis 无对应组件动作,select 选项联动需后端 source 或 amis `setValue` 整体替换 options(非逐条 addOption),落 P4 中段后续 |
### 8.6 改写后脚本挂回走「改写产物按 templateId+seq 取数」而非「库内 XML 原始脚本」[NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | 报告第五章 §5.2 把衔接接口写成 `/api/script/execute`(带 `{script,item}`,前端直传脚本文本);端到端 §3.2 又用 `/api/script/execute-template?template=<名>`(按模板名从库 XML 取**原始** S3 脚本)。两者都不是「挂回改写后脚本」的正解 |
| **根因** | 挂回链路要挂的是**改写后脚本**(`output/rewritten/<tid>/<seq>.FULL_AUTO.groovy` 去头注释正文),不是库内原始 S3 脚本(含未改写的 Vaadin S3 动词);且前端直传脚本文本不安全(任意脚本注入面)。正确取数键是 `(templateId, seq)`——与改写产物落盘命名一致 |
| **对策** | P4-5 实装把 `/api/script/execute-template` 改为接受 `{templateId, seq, item}`(RequestBody),后端 `RewrittenScriptStore` 按 `(tid,seq)` 从改写产物取脚本正文执行;原「按模板名取库内 XML 脚本」端点路径区隔为 `/api/script/execute-template-by-name`(保留 P4-2 兼容)。转换器 `attachScriptOnEvent` 生成的 onEvent 即调前者,`item:${&}` 传当前全量表单数据作脚本上下文。出入点已回写报告第五章 |
| **影响范围** | `platform-metadata` ScriptExecuteController + RewrittenScriptStore;`platform-converter` TemplateToAmisConverter.attachScriptOnEvent;改写产物落盘根经 `eip4.script.rewritten-root` 配置(默认 `tools/s3_rewriter/output/rewritten`),部署须确保改写产物随应用可达 |
### 8.7 SelectDialog 的 dialogid = view_template_id(弹窗数据源解析口径坑,picker 端点契约)[NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | P4-4 实现 `/api/picker/{dialogid}/list` 选择窗数据源端点时,初判 `dialogid` 是 `SYS_REFERENCE_ID`(拟经 `DataDicServiceImpl.getReferenceEntityTableName` 反解实体表名)。侦察客户库实测:244 个真实 picker dialogid **全部在 `sys_reference` 反解失败(0 命中)** |
| **根因** | 旧引擎模板 XML 里 `SelectDialog`/`MultiSelectDialog` 字段的 `dialogid` 属性,取值是一个 **`view_template_id`**——即「弹窗用哪个列表模板渲染」,**不是** SYS_REFERENCE_ID。被引用模板的 XML 根元素(`<crud entityid="...">` 等)携带 `entityid`,那才是弹窗数据源实体。实测 5 个高频 dialogid 经此路径解析到 PM_PROJECT/SYS_ORG/VIEW_SYS_USER 等真实实体 |
| **对策** | picker 端点 `resolveTable` 按优先级解析:① `view_template_id` → 读其 `xml::text` 根 `@entityid` → `DataDicService.getSYSEntity(entityId).getPo().get_Value("TABLENAME")`(主路径,覆盖全部存量 source);② 退化 SYS_REFERENCE_ID 反解(兼容旧引用语义);③ 退化直接实体表名。三路任一解析出的表名都过 P1-3 白名单。**契约与转换器产物对得上靠此解析路径,转换器 source 生成(`/api/picker/{dialogid}/list`)零改动**(dialogid 即模板里原样的属性值) |
| **影响范围** | `platform-metadata` PickerController;任何按 SelectDialog 语义做数据源解析的地方;PG `xml` 列须 `xml::text` 取出再 dom4j 解析(见 §5.33);本地 M0 库 `view_template` 是裁剪 stub(无 `xml` 列),端点对 `DataAccessException` 兜底返回 null 走退化路径,不崩 |
### 8.8 引擎 GeneralPO 对 String 查询条件裸拼 `col like '%值%'`,picker 搜索须转义防注入 [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | picker/entity 列表端点把前端搜索值下推为引擎查询条件(`cond.put(列名, 值)`)时,String 列的值进了一个 **字符串拼接的 LIKE** 子句 |
| **根因** | `GeneralPO.get_searchWhereWithPrefix`(GeneralPO.java:1940-1941)对 `clazz==String.class` 的条件值直接 `sb.append(columnName + " like '%" + obj.toString().trim() + "%'")`——**裸拼,无参数绑定**。列名侧已由 P1-3 白名单守(元数据即白名单),但**值侧**是注入面:值含单引号即可闭合字符串字面量注入 |
| **对策** | picker 端点对搜索值 `q` 先过 `escapeLikeValue`:单引号双写(`''`,闭合引擎拼接的字面量防注入)、LIKE 通配符 `%`/`_` 与反斜杠剔除为空格(引擎 LIKE 无 ESCAPE 子句,无法转义,降级为「不可作通配」优先保安全)。实测 `?q=' OR 1=1--` 返回 200 空结果而非 500/注入。**列名仍走白名单,值走转义,双管**。注:EntityController 的 amis filter 值侧同样经此 sink,P5 可考虑统一在引擎外包一层值转义工具(本期 picker 先落地) |
| **影响范围** | `platform-metadata` PickerController.escapeLikeValue;EntityController 的 filter 值透传(同 sink,P5 统一);任何把用户输入下推为引擎 String 查询条件的端点 |
### 8.9 SYS_PAGE_SCHEMA 平台表本期 bootstrap+生产脚本落地,Flyway 引入列 P5 [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | P4-4 schema 服务化需建平台表 `SYS_PAGE_SCHEMA`(templateId/schema_json/etag/version/update_time)存 1489 个转换产物。架构条款(架构设计 §「平台表管理」):SYS_* 平台表由 Flyway 管。但本工程当前**尚未引入 Flyway** |
| **根因** | Flyway 引入是独立工程动作(依赖 + `db/migration` 目录 + baseline 策略),不应在单个功能 P4-4 内顺带引;强行引会与「业务表引擎动态建、不进 Flyway」的边界产生迁移基线划界问题,须单独决策 |
| **对策** | 本期按「bootstrap SQL(本地/CI 自举)+ 生产建表脚本落 docs」落地:①`platform-metadata/src/main/resources/bootstrap/bootstrap-page-schema.sql`(`CREATE TABLE IF NOT EXISTS`,幂等,本地/CI psql 灌);②`docs/sql/SYS_PAGE_SCHEMA.sql`(生产建表脚本,注释里写明 P5 引 Flyway 时原样改名 `V{n}__create_sys_page_schema.sql` 即可,DDL 无需改);③导入 CLI `SchemaImportCli` 启动时 `CREATE TABLE IF NOT EXISTS` 兜底。**Flyway 引入列 P5 待办** |
| **影响范围** | `platform-metadata`;P5 引 Flyway 时把 `docs/sql/*.sql` 收编为 migration;schema 接口 `GET /api/page/schema/{templateId}` 带 ETag/304(etag=schema_json 的 sha-256,入库时算),amis schema KB 级,304 省重复下发 |
### 8.10 保真层 GeneralPO 值位置裸拼 LIKE 注入:单引号转义堵注入面(真参数化列 P2 热点) [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | 承 §8.8——保真层 SQL 引擎 `GeneralPO.get_searchWhereWithPrefix` 对 String 列搜索值 `col like '%值%'`(GeneralPO.java:1940)及同形态 5 处(Object 等值 1982、Object IN 1978、全表模糊 ilike 2075/like 2145/2173)**裸拼无参数绑定**,值含单引号即可闭合字面量注入 |
| **根因** | 引擎值位置历史只在部分点经 `StringUtil.TO_STRING` 转义,但 LIKE 路径漏了——`TO_STRING` 会补外层 `'...'`,而 LIKE 需要值落在 `'%...%'` 内、通配符 `%` 在引号外,形态不匹配故当年未套用,遂成残余注入面 |
| **对策(本次落地)** | `StringUtil` 新增 `escapeSqlLiteral(txt)`:**只把 `'` 双写为 `''`(SQL 标准转义堵注入)、绝不转义通配符 `%`/`_`**(旧系统通配语义是既有行为,转义=改语义=破保真),且**不补外层引号**(拼接形态零变化,diff 最小)。`GeneralPO` 6 处值位置各包一层 `escapeSqlLiteral(...)`,SQL 字符串结构一字未改。**保真层最小改动**:合法值(含中文/空格/含 `%` 的通配搜索)逐字节零行为变化,注入载荷降级为字面量 |
| **关键区别** | 与 §8.8 picker 端 `escapeLikeValue`(**剔除** `%`/`_`/`\`,现代层产品决策「搜索框不可作通配」优先保安全)口径不同:保真层 `escapeSqlLiteral` **保留** `%`/`_`(保真硬约束)。二者不同层不同语义,最终汇到同一引擎 sink,本次修复让该 sink 对任何进来的值都堵单引号注入,双管不冲突 |
| **真参数化(后续)** | 本次仅值转义堵注入面,**未改 PreparedStatement `?` 占位**。架构 §四第 2 层「渐进参数化」+ §五「计划缓存抖动」的根子级修复(值位置改 `?`,一次还安全+性能两笔债)**列 P2 后续热点项**,优先级=C3 压测热点∩安全风险点,改造时仍须「每改一处过对拍」(本次对拍套件可复用) |
| **验证** | 单测 `StringUtilEscapeSqlLiteralTest` 7/7(`'`→`''`、`% _` 不变、中文/空格不变、null、拼接产物);ParityCli `--all` 21 实体全一致 + `--privilege` 9 正/3 负全过;REST 8091 实测 `' OR '1'='1` / `'; DROP TABLE x--` / UNION → 200 空结果不注入不报错(表未被 DROP),`a%b`/纯 `%` 仍按通配匹配(引擎实拼 SQL 留证:`like '%''; DROP TABLE x--%'` 单引号已双写、载荷落字面量内未闭合)。详见 `platform-legacy-core/P2-LIKE注入修复报告.md` |
| **影响范围** | `platform-legacy-core` `StringUtil.escapeSqlLiteral` + `GeneralPO` 6 处值位置;凡用户输入下推为引擎 String/Object 列搜索条件或 `FUZZY_QUERY` 模糊查询的入口(entity list / picker / 服务流查询)均经此 sink 受益 |
---
## 九、待补章节占位
> 以下章节在 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 动词表扩展(已交付 P4-2 2026-06-11)
当前已确认的 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……
**[已交付 2026-06-11 / P4-2]** 动词表已扩展并在引擎侧落地,详见 `tools/s3_rewriter/P4脚本迁移执行报告.md`:
- **改写器目标动词 31 个**(C4 报告 §2.2),运行时实现 `com.eip4.platform.metadata.script.ScriptFacade`,经 PoC 已建的 facade 闭包注入机制(`ScriptingEnginesManager.evaluateGroovy` 的 `Bindings`)注入,**com.dsasp 源码零改、无替换类登记**(ArchUnit「保真层禁止依赖现代层」复跑通过)。
- **动词分两类**:①服务端语义(`getFieldValue`/`getFieldDisplay`/`getFieldDataSource`,服务端求值返回);②UI 语义(其余 29 个,捕获为 amis 事件动作指令 JSON `{actionType, componentId, args}`,actionType 取 amis 标准动作名 show/hidden/enabled/disabled/static/setValue/setFilter/setOptions/addOption/toast/…)。连同 4 个基础辅助函数中的 `bindField`,合计 32 个动词闭包注入。
- **执行端点**:`POST /api/script/execute`(改写后脚本直接执行)、`POST /api/script/execute-template`(按模板名取客户库真实脚本执行)。
- **验证**:单测 17 方法逐动词覆盖(均经真实 Groovy 过保真层引擎,BUILD SUCCESS);集成 6 条真实 FULL_AUTO 改写脚本经 8086 执行产出 amis 指令、协议合规;回归 PoC script-test 通过。
剩余 `showConfirmDialog`(同步确认框)的异步回调链改造仍属 HARD 人工范畴(85 条),不在 facade 自动覆盖内。
---
---
## 十、本地开发库 eip4dev 坑位台账 [NEW 2026-06-11]
### 10.1 SYS_USER 表缺 MASTERDEPART 列
**现象**:dev profile 启动后调用 `/api/auth/login` 返回 500,日志报 `column "masterdepart" does not exist`。
**根因**:`SysUserService.java` 的 SQL 中查询了 `MASTERDEPART` 列,但侦察源库 5435 及本地 eip4dev 均无此列(sys_user 实际只有 14 列)。该列名来自早期代码中对 eip4m0 自举库的假设。
**对策**:已修复 `SysUserService.java`,SQL 去除 `MASTERDEPART`,RowMapper 中 `depart` 字段固定为 null。
**影响范围**:platform-auth 模块登录路径;`AuthPrincipal.depart()` 在实际库中始终为 null,下游若依赖此字段需注意。
---
### 10.2 sys_page_schema 表在 eip4dev 中不存在
**现象**:`GET /api/page/schema/{id}` 返回 `{"status":2,"msg":"schema 存储不可用"}`。
**根因**:`sys_page_schema` 是 eip4-platform 新增表(非客户库原有),在 eip4dev dump/restore 时不存在于源库,因此目标库也没有该表。
**对策**:需在 eip4dev(及所有目标库)中手动建表。建表 SQL 位于 `platform-metadata` 模块的 schema 迁移脚本(待补)。这是已知 gap,不影响引擎元数据/list/picker 等主路径验证。
**影响范围**:page schema 存储相关接口;其余接口不受影响。
---
### 10.3 build_devdb.sh 中变量名后紧跟中文字符导致 unbound variable
**现象**:早期版本脚本运行报 `unbound variable`,类似 `$PG_VER(` 被 bash 解析为含多字节字节的变量名。
**根因**:bash 不识别 UTF-8 多字节边界,中文全角括号 `(` 的首字节(0xEF)被当作变量名的一部分,导致 `$VAR(...)` 形式的 log 字符串在 `set -u` 下报错。
**对策**:所有 shell 脚本中,`$VAR` 后若紧跟中文,必须用 `${VAR}` 花括号保护,或将中文括号改为 ASCII `()`。已在 `build_devdb.sh` 中全面修复并用 Python 扫描验证无遗漏。
**影响范围**:所有含中文注释/log 的 shell 脚本;CI 环境若 LANG 不同可能提前暴露此问题。
---
**手册维护说明**:本手册随工程化进展持续更新;新坑位发现即追加,以 `[NEW yyyy-mm-dd]` 标记;章节完成后移除「待补」标记。任何对引擎行为契约的更改必须同步更新第五章并过 code review。