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

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

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

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

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

35 KiB
Raw Blame History

EIP4 迁移手册 v1

版本:v1.0(2026-06-10)| 性质:M0 强制交付物,老员工知识转移 + PoC 坑位整编 适用对象:所有参与 eip4-platform 工程化的开发人员,新成员上手必读 维护原则:每个坑位必须补全「现象/根因/对策/影响范围」四栏后方可关闭;新发现的坑位在 对应章节追加,打 [NEW] 标记并注明发现时间


一、移植总则

1.1 双层制架构纪律

eip4-platform 采用双层制:

保真层(platform-legacy-core)     现代层(platform-metadata 等)
com.dsasp.*                        com.eip4.*
──────────────────────────────     ──────────────────────────────
移植引擎原样保留                    REST API / DTO / 转换器 / MCP
包名不动、行为不动                  新代码、新范式
以对拍为完成定义                    以评审+单测为完成定义

纪律(ArchUnit 规则固化,编译期强制):

  • com.eip4.* 可调用 com.dsasp.*,反向绝对禁止
  • com.dsasp.* 与 framework 源码的 diff 保持最小——移植不是重构
  • 保真层代码改动必须附一份对拍测试通过截图,否则 PR 不得合入

1.2 保真层纪律

原则 含义 违规后果
不重写 610 行引擎、1,346 行 SQL 拼装,原样搬入,不"现代化" 破坏对拍基线,视同 P1 返工
不改包名 com.dsasp.server.dataDic 等包名不变 所有 import 和反射引用失效
不引 ORM JdbcTemplate 是引擎的血液,JPA/MyBatis 不得引入保真层 动态 DDL 与 ORM 范式相克
diff 最小化 每次修改记录为「必要改动」(API 断点修复)或「适配」(桩替换),不顺手改 下一次升级时无法 diff 溯源

1.3 对拍 = 完成定义

移植代码的唯一完成标准是逐行对拍通过,不接受人工目测。

  • 计数级对拍(已完成):tools/eip4_sweep.py,全量 1,166 实体,0 计数不一致,通过率 99.1%
  • 逐行对拍(C1,工程化第一周强制):在旧系统关键出口加 SQL 录制切面,新旧结果集逐行 diff。≥20 个代表性实体(含主子表/字典翻译/数据权限/深分页),一致率必须 100%
  • C1 前提:旧系统需有可运行环境供 SQL 录制。若旧系统不可得,需设计生产流量旁路录制方案并报批(决策会开放项,P1 第一周第一个问题)

对外口径:「计数级一致性 99.1%(0 计数不一致),逐行对拍待工程化阶段 C1 补全」 禁止在 C1 完成前使用「99.1% 一致」表述(决策会书面更正)


二、Spring 3.1 → Boot 3 API 断点台账

来源:eip4-poc Day 1 实测,framework/ 静态扫描 + 编译验证 结论:断点仅此一类,已全部修复;未发现其他不兼容 API

2.1 queryForInt / queryForLong(7 处)

栏目 内容
现象 编译期报错:The method queryForInt(String) is undefined for the type JdbcTemplate
根因 JdbcTemplate.queryForInt() 和 queryForLong() 在 Spring 4.2 已废弃,Spring 6(Boot 3 内置)彻底移除
对策 改为 queryForObject(sql, Integer.class) 或 queryForObject(sql, Long.class);另有 1 处 (String, Object[], Class) 重载参数顺序变更,须同步调整
影响范围 com.dsasp.server.dataDic.POJOServiceImpl(1,346 行内),共 7 处;已在 eip4-poc 全部修复

2.2 javax → jakarta(6 处)

栏目 内容
现象 编译期报错:javax.servlet 包找不到
根因 Spring Boot 3 对应 Jakarta EE 9+,javax.* 命名空间已迁移为 jakarta.*
对策 dataDic + common + core 三模块内 6 处 javax.servlet 机械替换为 jakarta.servlet;javax.script(JSR-223,共 17 处)不动,JDK 17 原样可用
影响范围 仅 6 处,半天内完成;已在 eip4-poc 全部修复

2.3 数据源与事务 XML 配置(1 处)

栏目 内容
现象 旧 META-INF/spring/db.xml 用 Spring XML 配置 commons-dbcp 连接池与事务管理器,Boot 3 不识别
根因 Spring Boot 3 推荐 Java Config;commons-dbcp 已被 HikariCP 替代
对策 com.dsasp.server.db/META-INF/spring/db.xml 事务配置转换为 @Configuration Java Config;连接池替换为 HikariCP(Boot 3 默认);已在 eip4-poc 实测通过
影响范围 单处配置文件;业务代码无感知

2.4 SimpleJdbcTemplate(0 处)

栏目 内容
现象 预核查前担心此 API 大量使用(Spring 4.x 已删除)
根因 N/A
对策 源码实测零使用,此风险解除;无需任何改动
影响范围 无

完整结论:Spring 3.1/JDK 6 → Boot 3/JDK 17 的移植,全部 API 断点仅 8 处(7 处 queryForInt/Long + 1 处重载顺序),已在 eip4-poc 全部修复,WS1 通过。


三、OSGi 解耦做法

来源:framework/ 源码实测(源码预核查报告核查 2) 结论:OSGi 耦合面高度集中,等价替换成本极低

3.1 替换类清单(6 个)

类名 原版(OSGi) 替换实现 原版行数 替换行数 替换要点
SpringBeanOsgiServices OSGi BundleListener 服务定位器 ApplicationContext.getBean(name) 72 行 43 行 注入 ApplicationContext,按名取 bean;删除 BundleListener 逻辑
ScanServiceBeanXml OSGi bundle 启动期 SAX 扫描 service XML no-op(保留 classList 契约) 待查 极简 业务调用方只用 classList 返回值
CCache Adempiere 缓存(GPL 头 + CacheMgt 注册) 极简 HashMap 版 待查 极简 调用方只用 Map API,实现可直接换
Console Vaadin 浏览器控制台推送 slf4j 待查 极简 日志语义等价
InstallOrUpdate 启动期按版本跑 install SQL isDevDB()=false 桩 待查 极简 生产环境不触发
GetServicesFunction 等 3 个 Groovy 脚本函数库(约 2,600 行) Java 桩(仅实现 findCount);WS3 回迁 约 2,600 行 最小桩 P1/P3 阶段补全真实现

注意:替换时必须保持包名/类名/方法签名完全一致,旧引擎代码对这些类的引用不做任何修改——「旧代码零感知」是双层制的核心约定。

3.2 横切服务桩清单(P2 换真实现)

桩 包路径 当前行为 P2 真实现要点
dataPrivilegeService com.eip4.poc.stub 已由 M0/C2 真实现接管 桩已删除;保真层 com.dsasp.server.privilege.service.DataPrivilegeServiceImpl(原样移植)提供行级过滤原版语义;P2 在此之上接组织数据源 + 管理 UI(见 §5.8 / platform-auth/C2实测报告.md)
fileService com.eip4.poc.stub no-op 本地盘 / MinIO 接口
projectSwitchService com.eip4.poc.stub no-op 项目上下文切换
systemLogManager com.eip4.poc.stub slf4j 业务操作日志入库

四、XML 装配补齐

来源:eip4-poc 移植台账,Day 1 实测发现

4.1 LegacyXmlWiring(setter 注入补齐)

栏目 内容
现象 旧 service.xml 用 <property> setter 注入 systemLogManager / dataOperatorLog(非 @Autowired 字段),Boot 3 注解驱动容器不会自动装配这些 setter
根因 引擎代码是旧 Spring XML 编程模型,没有 @Autowired 注解;直接移植后 setter 未被调用,引用为 null
对策 新增 LegacyXmlWiring(实现 SmartInitializingSingleton),在容器启动后手动将这些 bean 注入到引擎的对应 setter,等价于 XML <property> 注入行为
影响范围 systemLogManager、dataOperatorLog 两个依赖;已在 eip4-poc 实测通过;转换器和新模块不受影响

4.2 JodaModule(Jackson 序列化)

栏目 内容
现象 引擎内部日期值为 joda.time.DateTime 对象,REST 层序列化时 Jackson 抛 InvalidDefinitionException: No serializer found 或输出异常 JSON
根因 Spring Boot 3 不再自动注册 JodaModule(Boot 2.x 会自动注册)
对策 显式在 ObjectMapper 配置中 registerModule(new JodaModule());jackson-datatype-joda 依赖加入 pom.xml
影响范围 所有包含 DATE 显示类型字段的实体查询响应;已在 eip4-poc 实测通过

五、引擎行为契约清单

来源:eip4-poc Day 2 移植对拍记录(README.md 坑位章节) 性质:这些是引擎内部已经确认的行为,不是 bug,移植工具和转换器必须遵守

5.1 updatePO 审计列强制追加

栏目 内容
现象 对某些表执行 update 路径时,引擎抛 SQL 错误:column UPDATETIME does not exist
根因 引擎 updatePO 无条件追加 UPDATETIME / UPDATEBY 两个审计列到 UPDATE 语句,不判断目标表是否存在这两列
对策 insert-only 设计的表(如 SYS_DATA_LOGITEM,物理表无这两列)不可走 update 路径,必须走 insert-only 路径;新建实体时审计列存在与否须与设计意图对齐;老系统行为一致(非新引入缺陷)
影响范围 所有无 UPDATETIME/UPDATEBY 列的表;P2 数据权限迁移时需排查;write-test 已验证

5.2 DATE 类型 = joda DateTime(非 java.util.Date)

栏目 内容
现象 REST 入参传 Long 型时间戳给 DATE 类型字段,引擎抛 ClassCastException
根因 引擎内部 DATE 显示类型存储为 org.joda.time.DateTime 对象,不接受 Long;引擎从未把这个内部约定暴露为接口文档
对策 REST 层适配器必须将前端传入的时间戳(Long)或 ISO 字符串转换为 joda.time.DateTime 后再传给引擎;反向序列化(引擎 → REST 响应)见 4.2 JodaModule
影响范围 所有 DATE 显示类型字段的写入接口;P1 REST 层实现时必须加适配,P4 转换器生成 amis 日期组件时需对齐格式

5.3 dom4j 取脚本必须用 getText(),不得用 getTextTrim()

栏目 内容
现象 取出的 Groovy 脚本源码缩进/换行消失,执行时 GroovyShell 报语法错误
根因 getTextTrim() 会压扁所有前后空白和换行符;Groovy 是换行敏感语言,多行脚本的换行是语法的一部分,压扁后源码损坏
对策 所有从 XML/dom4j 节点取脚本文本的地方一律改用 getText();转换器(P4)和运行时的脚本读取处都须核对,已有问题处一并修复
影响范围 TemplateToAmisConverter 的脚本提取逻辑;运行时 ScriptingEnginesManager 的脚本加载路径;全量 1,427 条脚本转换质量

5.4 PK 列名 = {表名}_ID 约定

栏目 内容
现象 克隆实体或用转换工具新建实体后,PK 列名与引擎预期不符,查询报 column not found
根因 引擎的 DDL 生成器在创建 PK 属性时,列名硬编码为 {表名}_ID(例如 SYS_USERGROUP 的主键列为 SYS_USERGROUP_ID);这是设计器创建时的约定,但未在文档中明示
对策 克隆工具、批量转换工具、P4 的迁移脚本在新建或克隆实体元数据时必须同步按此约定命名 PK 列;引擎不接受其他命名的主键列
影响范围 P4 批量转换 1,516 个模板;P1 对拍测试中克隆实体场景;所有新建实体的 DDL 生成

5.5 MIDTABLE 类型无主键子句

栏目 内容
现象 MIDTABLE(中间表/关联表)类型实体的 DDL 中没有 PRIMARY KEY 子句,但调用了 CRUD 路径
根因 引擎设计:MIDTABLE 是多对多中间表,无业务主键,DDL 生成时故意不加 PRIMARY KEY
对策 对 MIDTABLE 类型实体不走引擎的 updatePO 路径(见 5.1),只走 insert/delete;P2 数据权限中涉及关联表的场景需特别处理
影响范围 所有 MIDTABLE 类型实体(数量待 P1 统计);P4 转换器需识别并生成对应的 amis 组件

5.6 REFERENCES 外键自动生成

栏目 内容
现象 动态建表后,发现某些列带有外键约束,但元数据 XML 中并未显式声明
根因 引擎 DDL 生成器:引用类型(REFERENCE 属性)的列自动生成 REFERENCES 外键约束;这是引擎的内置行为
对策 P0' PG 升级演练时需检查外键约束在 PG 15 下的行为;P4 转换器处理引用列时不需要额外指定外键,引擎自动处理;批量删除/清理测试数据时须注意外键级联
影响范围 所有引用类型属性;对拍测试中的数据清理逻辑;P0' PG 升级兼容性扫描

5.7 listSelect(String sql) 混合大小写表名在 PG 取值异常

栏目 内容
现象 DataDicServiceImpl.getEntityAttributes 使用混合大小写表名(如 "SYS_EntityAttribute")调用 listSelect(sql,...) 时,PG 返回空集或查询结果字段映射异常;使用条件 Map 的规范路径(全大写表名)正常
根因 PostgreSQL 默认将未加双引号的标识符折叠为小写;混合大小写表名在未加引号时匹配不到实际的大写物理表名(EIP3 在 PG 下所有表名均大写);listSelect(String sql) 直接传 SQL 字符串时绕过了引擎的标准化处理
对策 正式移植时核查所有 listSelect(String sql, ...) 调用点,确认表名大小写;所有直接 SQL 路径中的表名统一用双引号包裹("SYS_EntityAttribute")或改用全大写;优先改用条件 Map 路径,让引擎统一处理标识符
影响范围 DataDicServiceImpl 中的直接 SQL 调用路径;P1 全量移植时的回归扫描重点;P4 转换器生成 SQL 片段时的命名规范

5.8 ROLES 多值列经 LIST + 中间表落地(数据权限规则装载)

来源:eip4-platform M0 任务 C2 实测(2026-06-11),详见 platform-auth/C2实测报告.md

栏目 内容
现象 SYS_FILTERRULE.ROLES 是「一条规则关联多个角色」的多值列,DataFilterHelper.converToDataFilterRule 直接 po.get_Value("ROLES") 期望拿到 List<String>;但物理表上并无 ROLES 列,值如何加载不直观
根因 引擎对 DisplayType.List(REFERENCEID='LIST')列的多值加载走「中间表(MIDTABLE)」路径:ROLES 列的 REFERENCEVALUE 指向一条 SYS_REFERENCEVALUE,其 ENTITYID→中间表实体(SYS_FILTERRULEROLE,tabletype=2,恰 2 列),ENTITYATTRIBUTEID→回引列(FILTERRULEID)。POJOServiceImpl.loadPOJO(isHierarchical=true) 的 hierarchicalQuery 对 LIST 列查 SELECT * FROM 中间表 WHERE 回引列=规则id,收集「另一列」(ROLEID)全部值组成 List<String> 设回 ROLES(见 POInfo.getReferenceValueTable/ColumnName + POJOServiceImpl.java:1256-1262)
对策 自举建模需三件齐备:①中间表 SYS_FILTERRULEROLE(恰 2 列 FILTERRULEID+ROLEID,tabletype=2,元数据 seq 决定 getColumnName(0/1) 次序,第 0 列必须是回引列);②ROLES 列 REFERENCEID='LIST' + REFERENCEVALUE 指向一条 SYS_REFERENCEVALUE(ENTITYID=中间表实体、ENTITYATTRIBUTEID=回引列属性);③配套一条 SYS_REFERENCE(ENTITYID=中间表实体)。读路径必须走 loadPOJO(...,isHierarchical=true)(getEntityDataFilterRule 已如此),否则 LIST 列不展开。本地用 bootstrap-privilege.sql 直插中间表行种规则角色
影响范围 所有 LIST(多值/子表)显示类型列的自举与对拍;P1 客户库副本不可达期间,凡需种多值列数据都按此三件套建模;P2 数据权限管理 UI 写规则时引擎自身的写路径(saveOrUpdateDataPrivilege)会按同口径落中间表

5.9 行级过滤仅在非 ADMIN 上下文触发

栏目 内容
现象 即便实体配了 SYS_FILTERRULE 规则,用默认(ADMIN)上下文 listSelect 仍返回全量,过滤「不生效」
根因 POJOCRUDServiceImpl.listSelectSpecialCol 显式判断 ctx.get(CURRENTUSER) != LoggedInUser.ADMIN 才调 dataPrivilegeService.getWhereClause;ADMIN 视角天然不过滤(管理员看全量)。这是引擎设计而非缺陷
对策 对拍/验证行级过滤必须构造非 ADMIN 的 ctx(CURRENTUSER=具体用户 + ROLES=List)。C2 通过 EntityController 增 asUser/roles 查询参可选项构造该上下文驱动引擎过滤路径;不传则沿用 ADMIN(不过滤),向后兼容
影响范围 所有行级数据权限验证与对拍场景;P2 管理 UI / 网关须在请求上下文正确填充 CURRENTUSER + ROLES;LoggedInUser.ADMIN 是补足 36 位的 'ADMIN'(char(36) 比较口径)

5.10 DataFilterHelper 用 Jackson 1.x(org.codehaus.jackson)

栏目 内容
现象 移植 DataFilterHelper 时其 import org.codehaus.jackson.*(Jackson 1.x,ObjectMapper/JsonNode/ArrayNode),与现代层用的 com.fasterxml.jackson(Jackson 2)是两套不兼容 API
根因 framework 原版即用 Jackson 1.x 做 FILTERRULE(Conditional[])的 JSON 互转;保真层纪律「com.dsasp 旧代码一行不改」,不得改写为 Jackson 2
对策 platform-legacy-core pom 显式引入 org.codehaus.jackson:jackson-mapper-asl:1.9.13(传递带 jackson-core-asl),与 Jackson 2 共存(包名不同不冲突);代码原样保留 1.x API
影响范围 platform-legacy-core 依赖树(多一条 1.x 链);P1 全量移植中凡用 Jackson 1.x 的旧类同此处理;现代层序列化仍用 Jackson 2,互不干扰

5.11 引擎 JSON 对 null 值列整列省略 [NEW 2026-06-11]

  • 现象:对拍中物理列值为 NULL 的列(如 WF_HI_TASKINST.DUEDATE 全表 null),引擎 REST 输出的行 JSON 里整列缺失,被误判 MISSING_RIGHT。
  • 根因:GeneralPOJO.toRow / JSON 序列化跳过 null 值键。
  • 对策:对拍 harness 规则「右缺列 + 左值 NULL = 语义等值」(platform-parity RowDiff 自对拍模式);前端/AI 消费 API 时不可假设所有元数据列必出现。
  • 影响范围:所有 list/load REST 输出消费方。

5.12 BOOLEAN 列域外脏数据引擎归 null [NEW 2026-06-11]

  • 现象:BOOLEAN 元数据列物理值存在 2、-1 等域外值(旧库脏数据,如 PM_BUDGETRCJ.ISTURNOVERMATERIALS=2 共 1,094 行、PM_BUDGETLIST.ISLIST=-1),引擎读出为 null。
  • 根因:引擎布尔解析只认 0/1,域外值归 null;旧系统行为相同,非移植缺陷。
  • 对策:对拍按「已归因差异」处理(可见不判负);数据治理时这批脏值应与客户确认语义后清洗。
  • 影响范围:全库 BOOLEAN 列;涉及行数见 C1 客户库对拍报告。

5.13 "胖列"实体大结果集不可单次取全 [NEW 2026-06-11]

  • 现象:GB_PRJ_WORKER(15,814 行,含工人照片类大文本列)单次全量 REST 响应达 1.7GB,超 Jackson 1GB 字符串上限,解析失败。
  • 根因:引擎 SqlRowSet 全量物化 + 大文本列;消费端单响应承载有上限。
  • 对策:此类实体必须分页消费;对拍 harness 已做"单次抓取失败自动回退翻页"。架构第五节「大结果集流式导出」改造时此类实体优先。
  • 影响范围:含 BLOB/大文本列的实体;P4 导出功能设计。

5.14 复杂视图实体的分页查询是 O(N) 重算 [NEW 2026-06-11]

  • 现象:PM_PAYMENTAPPLY(38,138 行)引擎 SQL 为 DISTINCT + 4 个 LATERAL 子查询,每页 500 行耗时 ≈61 秒,深页更慢;全量遍历约 78 分钟。
  • 根因:每页请求都重新执行完整 DISTINCT/JOIN 再 OFFSET,计划缓存不可复用叠加显示列翻译子查询。
  • 对策:C3 压测已把此类实体列为热点;P2「渐进参数化 + Caffeine」与「DDL 索引增强」改造的优先验证对象;对拍用抽样模式(--sampleRows)。
  • 影响范围:带多引用显示列的大表;真实用户的列表页延迟(决策会风险 R2 直接证据)。

5.15 服务流脚本默认导入含 Vaadin UI 类,缺失则每个脚本编译失败 [NEW 2026-06-11]

  • 现象:服务流引擎移植后,任何带 groovy 脚本的服务流经 REST 执行报 HTTP 500,日志为 MultipleCompilationErrorsException: unable to resolve class client.groovy.TestService / com.dsasp.client.viewframework.component.MainComponent。
  • 根因:SecureGroovyScriptEngineFactory.DEFAULTIMPORTSLIST 经 imports.addImport(it) 把这两条 Vaadin 客户端 UI 类作为默认导入逐脚本注入;它们属已淘汰 Vaadin 表现层,eip4-platform 保真层不含,classpath 缺失令编译期解析失败。IMPORTSWHITELIST/STARIMPORTSWHITELIST 里的 Vaadin 类是 AST 白名单字符串(不加载),无害;只有 DEFAULTIMPORTSLIST 真加载。
  • 对策:SecureGroovyScriptEngineFactory.groovy 的 DEFAULTIMPORTSLIST 移除这两条 Vaadin 默认导入(原值在源码注释登记供 diff 溯源),保留 8 条服务端导入(GeneralPOJO/POJOCRUDService/StringUtil/三个 Get*Function/Console 等,均已就位)。属「确需替换的类按保包名/类名/签名纪律」适配。
  • 影响范围:所有含脚本的服务流(D 类 79 个全部含脚本);P4 脚本批量转换/运行时脚本加载;凡移植 SecureGroovy 工厂的环境必做此适配。

5.16 服务流脚本引擎的 juel 来自 activiti,保真层不引 activiti [NEW 2026-06-11]

  • 现象:core.service.script.ScriptingEnginesManager 原版 new org.activiti.engine.impl.scripting.JuelScriptEngineFactory() 注册 juel(${...})引擎;保真层无 activiti 依赖,编译失败。
  • 根因:framework 的流脚本引擎复用了 activiti-engine-5.14 的 juel 工厂;架构设计第二节裁定 activiti/Flowable 仅存在于独立工作流服务,禁止进入保真层运行时(EOL 工件 + 私有化部署中间件最小化)。
  • 对策:适配为 JSR-223 名称惰性注册(classpath 提供 juel 引擎则注册其 factory,否则跳过),groovy 路径与类签名逐字不变。juel 仅服务流带条件转移(${...} transition / initExpression)时触发;D 类查询/报表为线性流(start→service→end)不走 juel,不受影响。带分支流的 juel 支持随 P3 工作流(Flowable)落地补。
  • 影响范围:带条件分支的服务流(如 DefaultFlowHelper 的 SAVE_AND_SUBMIT);P3 工作流;不引入 activiti 是保真层依赖纪律(对照 §5.10 Jackson 1.x 是「引入共存」,此处是「不引入」)。

5.17 OSGi Activator 不移植,流引擎 bean 靠组件扫描 + SpringBeanOsgiServices 注册 [NEW 2026-06-11]

  • 现象:framework com.dsasp.server.core.Activator 是 OSGi BundleActivator(org.osgi.* + sun.awt.ComponentFactory + ServiceTracker),JDK17 不可用且无 OSGi 容器。
  • 根因:OSGi 生命周期类,服务注册/发现走 bundle 机制;Boot 3 用 Spring 容器替代。
  • 对策:不移植 Activator(PoC 全模块零 Activator 先例)。流引擎三 bean(flowExcuteService/flowService/flowPrivilegeService/originServiceManager)靠 @Service(value=...) + 组件扫描(scanBasePackages 含 com.dsasp)自动注册;运行期按名取 bean 走 SpringBeanOsgiServices.getBeanByName(已是 @Component 替换实现,§3.1)。FlowServiceImpl.jdbcTemplate 非 @Autowired 字段,在 LegacyXmlWiring 补 setter 注入(等价原 XML ,§4.1)。
  • 影响范围:凡移植带 Activator 的 framework 模块;bean 注册改由 @Service 名 + LegacyXmlWiring setter 补齐。

5.18 REST 服务流入口不区分读写,需流定义审阅 + P2 防护 [NEW 2026-06-11]

  • 现象:/api/flow/{id} 把任意服务流交给引擎 excute;引擎一个流既可挂 listSelect(读)也可挂 save/update/delete(写)service 节点,门面无法仅凭 flowId 区分读写。
  • 根因:服务流引擎设计为通用执行器(读写同入口 excute);读写语义在流定义 XML 的 service 节点 method 里,门面层不解析。
  • 对策:P1 不在门面做引擎级读写闸(避免误判);调用方/运维按流定义 XML 审阅确认查询/报表类后放行,客户库只读纪律下只执行已审阅无写动作的流。P2 补三层防护:①流定义静态扫描(service method 读白名单);②最小权限只读连接;③statement_timeout。
  • 影响范围:所有经 REST 执行的服务流;客户库只读期的流挑选;P2 安全加固(对齐架构第四节安全第 1/3/4 层)。

六、Flowable 升级三坑

来源:eip4-poc WS4 实测,flowable-poc / flowable5-poc 工程(2026-06-10) 背景:客户库引擎版本 5.13-SNAPSHOT(非评估报告所写 5.14); 全量 1,509 个 BPMN 定义,零 activiti:class 自定义扩展, 但有 3 个表达式 bean(见 6.3)

6.1 版本串 5.13-SNAPSHOT 不被升级链识别

栏目 内容
现象 将 ACT_* 表指给 Flowable 5.23 时报错 "unknown version from database",升级脚本终止
根因 Flowable 5.x 升级链通过 act_ge_property 表中 schema.version 字段识别当前版本,5.13-SNAPSHOT 不是正式版本号,升级链无法匹配版本范围
对策 升级前必须执行:UPDATE act_ge_property SET value_='5.13' WHERE name_='schema.version';执行完成后再启动 Flowable 5.23 升级
影响范围 每一个客户库升级前的必执行步骤,写入《Flowable 升级 Runbook》变更四要素前置;漏做则整个升级链中断

6.2 5.13 不能直接跳 6.x(两步升级强制)

栏目 内容
现象 尝试直接用 Flowable 6.8.1 连接 5.13 版本数据库时,迁移脚本因缺少 TENANT_ID_ 列而报错并回滚
根因 v5→v6 的 DDL 迁移脚本假设数据库已达到 Flowable 5.15 引入的 TENANT_ID_ 列;5.13 没有该列,跳版直升会触发 DDL 错误
对策 强制两步升级路径:① 先用 Flowable 5.23(v5 末版)引擎升级数据库到 v5 最终 schema;② 再换 Flowable 6.8.1(启用 flowable5-compatibility)升级到 v6;两步均需全量备份回退点
影响范围 生产升级 Runbook 中必须明确两步窗口(决策会已拍板 PG 升级与 Flowable 升级分两个独立停机窗口);PoC 已完整实测,1,509 定义 / 9,383 执行 / 9,321 待办 / 26,749 历史全部就地保留

6.3 表达式 handler bean 移植面(3 个类)

栏目 内容
现象 Flowable 独立服务启动后,BPMN 流程中的候选人表达式 ${candidateUsersHandler.getUsers(...)} 解析失败,抛 FlowableException: Unknown property used in expression
根因 这 3 个 bean 定义在 com.dsasp.server.wf 模块中,Flowable 独立服务(flowable-service.jar)需要显式注册;PoC 扫描时遗漏了表达式 bean 层(仅扫描了 activiti:class,零结果),表达式层是独立入口
对策 将 3 个 handler 类从 com.dsasp.server.wf 移植到 platform-flow-gateway 模块;通过 ProcessEngineConfiguration.setBeans(Map) 注册(PoC 已验证注册机制有效);P3 阶段优先级最高
影响范围 引用量:candidateUsersHandler × 4,761 处(全量 1,509 个 BPMN)、wfContextService × 175 处、multiInstanceUsersHandler × 33 处;这 3 个 bean 未移植则流程发起/审批全部无法运行

三坑汇总检查清单(写入升级 Runbook):

□ 升级前:UPDATE act_ge_property SET value_='5.13' WHERE name_='schema.version'
□ 第一步:Flowable 5.23 完整升级 + 验证 schema.version 达到 5.x 末版
□ 第二步:Flowable 6.8.1 启用 flowable5-compatibility 升级
□ 升级后:验证 1,509 个定义可见 + 抽取 3 个运行中实例续跑 + 候选人表达式解析正常
□ platform-flow-gateway 已包含 3 个 handler bean + cfg.setBeans 注册

七、库内数据质量已知问题

来源:eip4-poc Day 2 全量扫描结果(tools/eip4_sweep.py)+ 移植台账 性质:旧系统库内存量问题,非移植缺陷;工程化前必须定性处置(决策会切流红线 3)

7.1 55 个孤儿元数据

栏目 内容
现象 eip4_sweep.py 对拍时,55 个实体的 listSelect 返回 0 条但引擎无错——但直接查 count(*) 也返回 0(物理表不存在)
根因 SYS_ENTITY 中存在元数据定义,但对应的物理表已不存在于数据库——元数据孤儿,可能是历史删表未清元数据
对策 逐条定性:① 已废弃(可归档元数据);② 需要重建物理表;③ 业务仍在使用(严重问题,需客户确认);定性结果需客户书面确认后方可进切流(决策会红线 3)
影响范围 55 个实体从全量 1,166 中排除后,有效对拍范围为 1,111 个;P1 对拍框架建立时需排除或单独标记这 55 个

7.2 9 个元数据漂移

栏目 内容
现象 引擎查询返回 500 错误,但旧系统行为一致(老系统同样报错);全量扫描中 9 个 500 实体排除在通过率计算之外
根因 元数据声明与物理表结构不一致:典型案例 SYS_DATASTATUS,元数据声明为普通表但物理表无主键列;引擎拼出的 SQL 在 PG 下执行失败
对策 逐条排查漂移原因(元数据错误 vs 物理表被手工改过 vs 历史 bug);修复方向:对齐元数据或对齐物理表;需客户书面确认后处理(决策会红线 3)
影响范围 9 个实体;SYS_DATASTATUS 已知 1 例;P1 对拍框架需将这 9 个标记为「已知漂移,人工定性中」

7.3 HR_ATTENDLOGDETAIL.UNITNAME 物理列缺失

栏目 内容
现象 主子表级联测试中,HR_ATTENDLOGDETAIL 的 UNITNAME 属性读取返回 null;写入时无报错但值丢失
根因 SYS_ENTITYATTRIBUTE 中存在 UNITNAME 属性定义,但 HR_ATTENDLOGDETAIL 物理表中该列不存在——属于 7.2 元数据漂移的又一具体案例
对策 与 7.2 同:客户确认是否需要补列还是废弃该属性定义;在客户确认前,涉及 UNITNAME 的查询/写入不得进切流
影响范围 HR_ATTENDLOGDETAIL 相关的考勤详情功能;如有其他 HR 表存在类似问题需一并排查

7.4 entityid 非法字符孤儿模板

栏目 内容
现象 WS2 转换器处理某些模板(如「信息价管理」)时,entityid 字段值包含非法字符,无法在 SYS_ENTITY 中找到对应实体
根因 部分老模板的 entityid 值使用了历史 ID 格式(含特殊字符或已被删除的实体 ID),指向已不存在的实体
对策 P4 批量转换前需先跑一轮盘点 SQL,识别所有 entityid 异常的模板并单独标记;转换器需要 null-safe 处理(entityid 解析失败时输出错误日志而非抛异常终止批量任务)
影响范围 全量 1,516 模板中的孤儿模板数量待 P1 盘点确认;P4 转换器需增加异常模板的旁路处理流程

八、amis 侧已知坑

来源:eip4-poc WS2 实测(2026-06-10) amis 版本:6.13.0(锁定,本地化部署,不依赖 CDN)

8.1 官方 schema.json 宽松语义与 additionalProperties 预处理

栏目 内容
现象 直接用 ajv(draft-07)加载官方 schema.json 进行校验时,大量结构上合法的 amis schema 被报错为「额外属性不被允许」,与实际浏览器渲染结果矛盾
根因 官方 schema.json 中大量位置存在 {"$ref":..., "additionalProperties":true} 的兄弟键覆盖写法;在 draft-07 严格语义下,兄弟键被忽略,引用定义的 additionalProperties:false 生效,拒绝一切额外属性;但 amis 官方编辑器(VS Code 插件等)使用更宽松的 JSON Schema 实现,会合并引用 schema 与兄弟键
对策 校验前做预处理:递归剥除所有含 $ref 节点的兄弟 additionalProperties:false;已在 GET /api/poc/amis-validate 实现,3 个真实模板转换后校验通过(0 错误)
影响范围 P4 双闸中的「官方 schema 校验」闸;MCP Server 的 validate-schema 工具;AI 生成管线的校验-重试环节;所有使用 ajv 校验 amis schema 的地方都需要这个预处理步骤

8.2 双闸必要性(校验闸 + 渲染冒烟闸)

栏目 内容
现象 schema 校验通过(0 错误)的页面,在浏览器 amis 渲染时出现组件类型未识别或渲染为空
根因 schema.json 含 loose 宽松分支,「未知渲染器类型」会通过校验(schema 设计内)但运行时 amis 渲染器不识别;schema 校验只能抓结构错误/已知属性类型错误/必填缺失,无法保证可渲染性
对策 双闸缺一不可:第一闸(schema 校验)抓结构问题;第二闸(headless 渲染冒烟,如 Puppeteer/Playwright 执行 amis.embed)抓渲染问题;P4 批量转换流水线必须两闸串联,两闸都过才入库
影响范围 P4 全量 1,516 模板转换流水线;AI 生成管线;MCP Server validate-schema(需升级为双闸);决策会已将「双闸」作为质量门禁第 2 条

九、待补章节占位

以下章节在 M0 期间需要补充,当前为占位。责任人需在 M0 出口前完成。

9.1 知识 backup 人选(待定)

事项 状态 责任人 期限
熟引擎老员工 backup 人选确定 待定 项目负责人 M0 出口
backup 人员与老员工 1:1 交接会(≥2 次) 待定 老员工 + backup P1 第一周
backup 人员能独立运行 eip4-poc + 解释对拍结果 待定 backup P1 结束

背景:决策会将熟引擎老员工列为单点风险(R3),backup + 本手册是降险硬要求;立项决议含「backup 人选确定」为 M0 出口条件之一。

9.2 手册过评审记录(待补)

评审项 评审人 日期 结论
第二至八章坑位完整性 待定 待定 待定
对拍框架设计(C1)评审 CTO + 老员工 待定 待定
Flowable 升级三坑与 Runbook 对应 P3 责任人 待定 待定

9.3 WS3 facade 动词表扩展(待补 P1)

当前已确认的 4 个基础辅助函数(getFieldValue / bindField / setFieldReadOnly / showConfirmDialog)之外,盘点报告 Top S3 API 调用显示需扩展至 ~20 个:

已知待补:addButton×100、getValue×68、getContainerDataSource×61、setFilter×56、removeAllItems×29、group.setReadOnly×27、getDisplay×27、setVisible×21、setCaption×16……

P1/P4 阶段由老员工与后端架构逐条补全,补全后回填本节。


手册维护说明:本手册随工程化进展持续更新;新坑位发现即追加,以 [NEW yyyy-mm-dd] 标记;章节完成后移除「待补」标记。任何对引擎行为契约的更改必须同步更新第五章并过 code review。