docs(parity): P1-1 全库对拍报告 + 二轮 discover 汇总 + 迁移手册 5.22-5.28

- platform-parity/P1-1 全库对拍报告.md:115 问题实体五类归因终表
  (48 豁免转 OK / 11 引擎真缺陷 / 55 库孤儿 / 1 夜批),豁免规则登记,
  真缺陷清单(PM_LABORTEAM/PM_SPIDER_JSBIDWIN 行集坍缩 + 9 HTTP-500),
  55 孤儿清单,与 PoC 计数级 99.1% 口径对比。终局 1099/1166=94.3%。
- 二轮 discover 汇总:43 问题实体重跑 42 转 OK,134422 行零 DIFF。
- 迁移手册新增 5.22-5.28:物理孤儿列 / xml 表示(SQLXML)/ 空值渲染 /
  视图多重集 / 大表抽样退全量 / 引擎行集错误 / HTTP-500 漂移与视图读路径缺陷。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 12:57:13 +08:00
parent 923cc72c66
commit 3ea1a5590c
5 changed files with 381 additions and 0 deletions

View File

@@ -324,6 +324,55 @@ com.dsasp.* com.eip4.*
- **诚实边界**:本地 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 计数级口径互证(本轮逐个落实根因)。
## 六、Flowable 升级三坑
> 来源:eip4-poc WS4 实测,flowable-poc / flowable5-poc 工程(2026-06-10)