转换器扩展(platform-converter,PoC crud 三段种子上): - 按 XML 根元素分派 crud/form/tree/report/group;ConversionResult+Grade 三级分级 - EDITFORM:form pageid 解析 view_page 取字段;主子表 EditGrid/FormEditGrid→input-table(子列取自 editgridtemplate) - 树:type=3 声明式→input-tree、type=4 引用式→flex(tree+crud) - 选择窗 SelectDialog/MultiSelectDialog→select+source(非 amis picker:picker 不在 6.13 schema 表单项 oneOf,闸一会拒) - <report> A 类:crud+合计行(issummer→summaryFields)+金额列(ismoney→number);selectservice→/api/flow;JOR/图表降级标注 - UiTypeMapper 统一 uitype 映射;每决策登记映射台账(全量约 1.6 万条) - 孤儿模板(entityid 非法/空 xml)旁路标记不崩(手册 §7.4) 批量+双闸(BatchConvertCli,可独立 CLI 跑批,只读连库+5435 ceshi 库硬守门): - 闸一 SchemaGate(宽松语义预处理抽出,与 AmisSchemaController 共享):通过 98.2%(1489/1516) - 闸二 playwright+本地 amis SDK 渲染冒烟,每类型抽≥5:25/25 全过 - 产物 转换产物/(schema/*.json + 分级清单.csv + 闸二结果.json) - 失败 27 个全为空 xml 孤儿模板(库内数据问题,非转换器缺陷) 新坑进手册 §8.3(picker 不在表单项 oneOf,用 select+source) §8.4(闸二大 schema 经端点拉避 HTTP 431) 单测 24 个;全 reactor mvn test+ArchUnit 绿 报告 platform-converter/P4批量转换报告.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
716 lines
82 KiB
Markdown
716 lines
82 KiB
Markdown
# 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 宿主的渲染验证脚本 |
|
||
|
||
---
|
||
|
||
## 九、待补章节占位
|
||
|
||
> 以下章节在 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 自动覆盖内。
|
||
|
||
---
|
||
|
||
**手册维护说明**:本手册随工程化进展持续更新;新坑位发现即追加,以 `[NEW yyyy-mm-dd]` 标记;章节完成后移除「待补」标记。任何对引擎行为契约的更改必须同步更新第五章并过 code review。
|