Files
eip4-platform/platform-parity/C1实测报告.md
zhengwr c2b3c5004f docs: 技术文档随仓库——架构设计/迁移手册/C3基线/C5报告迁入 docs/
文档分层:随代码演进的技术文档入 git(团队 clone 可得、有版本与评审);
决策档案与含商务内容的治理文档留工作区 docs/(不随仓库分发,外包 clone 不携带)。
全部交叉引用已更新(README×2/实测报告×2/登记表/pom/ArchUnit 注释)

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

232 lines
17 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.
# C1「逐行对拍框架」实测报告
> 模块:`platform-parity` | 阶段:M0 | 日期:2026-06-10
> 上承《架构设计》(docs/架构设计.md)第四节「检测兜底」层与 eip4-poc 决策口径更正
> (PoC 仅做到「计数级一致 99.1%」,逐行对拍列为工程化第一周 C1 强制补验项)。
> 本报告固化 C1 框架的架构、归一化规则、本地实证数字、与客户库全量对拍的差距与待办、风险论证。
---
## 一、定位与结论
PoC 阶段对全库 1,166 个实体只做到**计数级**一致性(`引擎 listSelect total` vs `count(*)`),
非「结果集逐行逐列一致」。C1 补齐**逐行逐列对拍框架**并在本地自举环境上完成实证:
> **结论:框架四件(录制 / 重放 / RowDiff 内核 / 自对拍)全部跑通;
> 本地 21 个代表性实体、1,108 行,逐行逐列一致率 100%,差异数 0。
> RowDiff 单测 17 例全绿。**
客户库副本(192.168.20.68:5435)当前网络不可达,故本阶段用**自对拍模式**
(引擎读路径 vs 直连 JDBC)作为 diff 内核与归一化规则的等价实证;网络恢复后把基线侧
换成旧系统录制 JSONL 即可,内核零改动(见第五节)。
---
## 二、架构:四件套
```
旧系统(Spring3.1/JDK6) 新引擎(Spring Boot 3/JDK17 + eip4m0)
┌─────────────────────────┐ ┌──────────────────────────────────┐
│ ① recorder 录制切面 │ JSONL 流量 │ ② replay 重放器 │
│ SqlRecordingAspect │ ───────────────▶ │ ReplayRunner:同 SQL 复跑 │
│ (AOP 拦 JdbcTemplate) │ │ │
└─────────────────────────┘ └───────────────┬──────────────────┘
▼
┌──────────────────────────────────────────────────┐
│ ③ diff 内核 RowDiff + Normalizer(本模块心脏) │
│ 两个结果集 List<Map> 按主键排序配对 → 逐行逐列归一比较 │
│ 产出 DiffReport(JSON + Markdown) │
└──────────────────────────────────────────────────┘
▲
┌──────────────────────────────────────────────────────────┴──────────────────┐
│ ④ selfcheck 自对拍(本地实证替身):引擎 REST /api/entity/{t}/list vs 直连 JDBC │
│ ParityCli --seed --all → parity-reports/ │
└────────────────────────────────────────────────────────────────────────────┘
```
| 件 | 包 | 关键类 | 职责 |
|----|----|--------|------|
| ① 录制 | `recorder`(资源交付) | `SqlRecordingAspect.java.txt` + `SqlRecord/JsonOut` + 集成说明.md | 旧系统侧 AOP 切面源码(Spring 3.1 XML 装配),拦 `JdbcTemplate.query*/update/execute`,SQL+参数+结果集 → JSONL。含「生产流量旁路录制方案」报批备选 |
| ② 重放 | `replay` | `ReplayRunner` / `SqlRecord` | 读录制 JSONL,对新引擎数据源执行同 SQL,逐行 diff;写操作默认 dry-run |
| ③ diff | `diff` | `RowDiff` / `Normalizer` / `DiffReport` | 核心:结果集规范化对比,输出结构化差异报告 |
| ④ 自对拍 | `selfcheck` | `ParityCli` / `SelfCheckRunner` / `ParitySeeder` / `EngineHttpClient` / `JdbcResultReader` | 本地实证:建实体灌数据 + 引擎读路径 vs JDBC 逐行 diff,CLI 跑批 |
录制端(旧系统)与重放端(新引擎)的 `SqlRecord` 字段完全一致
(`op/sql/params/columns/rows/affectedRows/ts/entity`),保证 JSONL 无损往返。
---
## 三、归一化规则表(RowDiff 心脏)
两侧「语义等值但表示不同」的值由 `Normalizer` 归一后比较。每条规则对应一类真实表示差异,
全部出自保真层引擎与 PG 物理类型口径(`Entity.createTableSql`/`processAttribute` 已逐一核对),
每条都有单测覆盖(`RowDiffTest`,17 例)。
| # | 规则 | 场景(旧/新两侧差异) | 归一做法 | 单测 |
|---|------|---------------------|----------|------|
| 1 | char(36) 尾部空格 | PG `character(n)` 定长列读出补空格(id/外键/CREATEBY 等)。引擎 REST 与 JDBC 都补 36 位 | 去**尾部**空格(保留前导/中间) | `charTrailingSpace` |
| 2 | numeric scale | `numeric(18,6)` 读出 `2.000000` vs `2` | `BigDecimal.compareTo`(忽略 scale) | `decimalScale` |
| 3 | 整数跨类型 | 同列在两侧可能 Integer/Long/Short/BigInteger | 统一比较 `long` 值 | `integralCrossType` |
| 3b | 整数↔等值小数 | `2`(整型) vs `2.000000`(numeric) | Long 与 BigDecimal 互转后 compareTo | `integralVsDecimal` |
| 4 | 布尔/整型混用 | BOOLEAN 物理列是 integer(0/1);引擎 REST 序列化为 `true/false`,JDBC 读 `1/0` | Boolean 归一到 0/1(long) | `booleanAsInt` / `booleanRowLevel` |
| 5 | bigint 时间戳原样 | DATE/TIME 物理列是 epoch 毫秒 bigint | 按整数原样比 | `bigintTimestamp` |
| 5b | ISO 串 ↔ epoch | 引擎 REST 经 JodaModule 把 epoch 序列化为 ISO-8601(`...Z`),JDBC 直连返回 bigint | ISO instant 解析为 epoch 毫秒后比较 | `isoInstantVsEpoch` |
| 6 | NULL 区分缺列 | 「键存在值 NULL」≠「键不存在(缺列)」 | 行级分别报 `VALUE` / `MISSING_LEFT` / `MISSING_RIGHT`;两侧都 NULL 或都缺列视为一致 | `nullSemantics` / `nullVsMissingColumn` |
| — | 行序无关 | 两侧 ORDER BY 差异 | 按主键(可多列)规范化排序后配对 | `orderIndependent` |
| — | 主键配对/缺行检出 | 一侧多行/少行 | `onlyInLeft` / `onlyInRight` | `rowPresenceMismatch` |
> 规则 1/4/5b 三条正是本地实证一次跑通的关键:引擎 REST 出口与 JDBC 出口对同一物理行的
> char 填充、布尔表示、时间表示**系统性不同**,RowDiff 把它们全部正确吸收为「一致」,
> 同时仍能检出真实的值差异(`valueMismatchDetected` 用例守门)。
---
## 四、本地实证数字
### 4.1 环境
- 本地 PG 15.18(`localhost:5433`,数据目录 `/Users/zhengwr/eip4-pgdata`),新建库 **eip4m0**(eip4flow 未动)。
- 自举 schema:`platform-parity/src/main/resources/bootstrap/bootstrap-sys.sql`(可重复执行,DROP IF EXISTS 开头),
建 7 个自描述系统实体(SYS_ENTITY / SYS_ENTITYATTRIBUTE / SYS_USERGROUP / SYS_REFERENCE /
SYS_REFERENCEVALUE / SYS_RULE / SYS_ENUMERATE)+ 物理基表 + SYS_USERGROUP 业务种子 1 行。
- 服务:platform-app,profile=**local**(`application-local.yml` → eip4m0,端口 8084),后台 nohup,日志落 `/tmp/eip4m0/app.log`。
### 4.2 跑批结果(`ParityCli --seed --all`)
| 指标 | 值 |
|------|----|
| 测试实体数 | **21** |
| 总比对行数(JDBC 基线侧) | **1,108** |
| 内容差异行 | **0** |
| 仅 JDBC / 仅引擎 行 | **0 / 0** |
| 逐行逐列一致率 | **100%** |
| 实体级一致率 | **21/21 = 100%** |
报告产物:`platform-parity/parity-reports/parity-20260610-233738.{json,md}`。
### 4.3 类型与约束覆盖
21 实体覆盖全部显示类型与约束:
- 类型:NVARCHAR(字符串)、INTEGER、DECIMAL、MONEY、DATE、BOOLEAN、CODE(`EIP4PT_ALLTYPE` 单实体八列全覆盖)。
- 必填(mandatory)、唯一(identifier,如 `EIP4PT_ALLTYPE.CODE`)、组合唯一(combidentifier,
`EIP4PT_COMBO` 的 USERID+BIZDATE)、外键引用(`EIP4PT_REFER.ALLTYPE_REF` → EIP4PT_ALLTYPE)、
主子表(`EIP4PT_ORDER` 主 / `EIP4PT_ORDERLINE` 子,108 子行外键回填到主)。
- 数据用固定种子 `SEED=20260610` 灌注,可复现。
### 4.4 单测
`RowDiffTest`:**17 例全绿**(0 失败 0 错误),覆盖第三节全部归一化规则与差异检出路径
(含注入负例式的"应检出差异"反向断言)。
---
## 五、与客户库全量对拍的差距与待办
本地自对拍证明了 **diff 内核 + 归一化规则 + 报告产物**正确;距「与客户库全量逐行对拍」还差:
1. **基线侧换真流量**(网络恢复后):
- 在旧系统部署 `recorder/SqlRecordingAspect`(见集成说明.md,推荐挂在 `POJOService.listSelect`
出口,与新引擎 `EntityController.toRow()` 平面 map 语义逐字节对齐)。
- 录制产出 `sql-record.jsonl` → 新环境 `ReplayRunner` 复跑 → `RowDiff` 比对。
- 替换升级 `eip4-poc/tools/eip4_sweep.py`:把现有「计数级对比」整列替换为**本框架的逐行对拍**
(sweep 的实体遍历/分页骨架保留,比较函数从 `count==total` 升级为 `RowDiff.diff(...).isClean()`)。
2. **旧系统侧切面部署步骤**(报批后):见 `recorder/集成说明.md` 第五节
「生产流量旁路录制方案」——方案 A(进程内异步旁路 + 采样,可热关)/ 方案 B(镜像库重放,零生产侵入);
验收期建议 B 跑全量 + A 采样补热点,切流灰度期 A 低采样常开作线上对拍探针。
3. **安全负例进对拍**(架构第四节第 4 层「检测兜底」):对拍套件加注入负例
(`' OR 1=1--`、`'; DROP` 等)断言「被转义/被白名单拒绝」,把"不可注入"变可回归断言。本阶段框架已就位,负例用例随 P1 标识符白名单实现一并补。
---
## 六、风险与论证
### 6.1 本地自举 schema 为「重建口径」,与真实库的差异是否影响 diff 语义?——**不影响**
本地 schema 由 `bootstrap-sys.sql` 按引擎权威口径重建,真实客户库的物理表存在
**列序差异、历史冗余列、额外索引**等。论证 diff 语义不受影响:
- **RowDiff 按列名(大写归一)配对,不依赖列序**:`Map<String,Object>` 无序,比较走列名集合并集,
列在表里的物理顺序对结果零影响。
- **冗余列由 MISSING_* 显式区分**:真实库若多出 diff 关心之外的列,会被报为 `MISSING_*` 而非静默,
口径透明可裁决(对拍时可按元数据列集投影,只比引擎认知的列)。
- **diff 的真值锚点是引擎元数据而非物理 schema**:引擎读路径只 SELECT 元数据声明的列;
自对拍的 JDBC 侧用 `SELECT *`,两侧列集差异(物理冗余列)会被 MISSING 标出而不污染"值一致"判定。
- **本地实证已覆盖最易出错的表示差异**(char 填充 / 布尔 / 时间 ISO↔epoch),这些与列序/冗余列正交。
### 6.2 引擎适配坑(已遇,进迁移手册)
| # | 坑 | 现象 | 处置 |
|---|----|------|------|
| 1 | **空库下 BOOLEAN/ENUMERATE 列触发 SYS_ENUMERATE 查询** | `GeneralPO.load` 对 YesNo/ENUMERATE/STATUS 列每行回调 `getEnumerateItems` → `SELECT SYS_ENUMERATE`;若该表无自描述元数据,`buildSelect` 返回 null → NPE | bootstrap 必须为 **SYS_ENUMERATE 建自描述元数据**(CODEVALUE 须 INTEGER)。已固化进 bootstrap-sys.sql |
| 2 | **外键 REFERENCEID 必须是 SYS_REFERENCE_ID(36 位 uuid),不能直写表名** | 引擎 `POInfo.getReferenceTable` 仅当 `displayType.length()==36` 或 ColumnClass=Object 时,拿 REFERENCEID 当 SYS_REFERENCE_ID 查 `getReferenceEntityTableName`;直写表名落空 → JOIN `null` → `syntax error at or near "null"` | FK 列先建 SYS_REFERENCE 行(entityid=被引实体),列 REFERENCEID=该 reference uuid。已固化进 ParitySeeder |
| 3 | **POInfo 缓存跨请求不失效** | 实体元数据变更(如补 SYS_REFERENCE 行)后,已被缓存的 POInfo 仍是旧的 → 仍报错;须重启服务或清缓存才生效 | 自举/重建元数据后**重启服务**再对拍;工程化需补元数据变更触发的 POInfo/CCache 失效(对应架构第五节 Caffeine 缓存改造,留缓存清理钩子) |
| 4 | **MetaController `POST /api/meta/entity` 在空 bootstrap 库上建表失败** | 克隆 SYS_USERGROUP 属性后 `getSYSEntity(id).getAttributes()` 取不到新属性 → 生成无列 DDL(`CREATE TABLE x ( primary key (x_ID) )`)→ `column x_id named in key does not exist` | 疑同坑 3(POInfo 缓存)或克隆时序问题。**非 C1 框架问题**;本地实证改用 ParitySeeder 直建元数据+物理表(口径同引擎 createTableSql)。REST 创建路径修复列入 P1 元数据 REST 层待办 |
| 5 | **本地 PG postmaster 易停** | 会话期间 5433 postmaster 停过一次,且 brew 默认数据目录(`/opt/homebrew/var/postgresql@15`)与实际数据目录(`/Users/zhengwr/eip4-pgdata`)不同 | 起服务前确认 `pg_ctl -D /Users/zhengwr/eip4-pgdata -o "-p 5433" start` |
### 6.3 自对拍的诚实边界
自对拍证明的是「引擎读路径 vs 物理事实逐行一致」(WS1 读路径保真),
**不能替代**「新引擎 vs 旧系统」的端到端对拍——后者必须靠 recorder 真流量(第五节待办)。
本阶段定位是:在客户库不可达期间,把 diff 内核/归一化规则/报告产物全部实证就位,降低网络恢复后的集成风险。
---
## 七、复现步骤
```bash
export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
# 0) 确保本地 PG 在 5433
pg_ctl -D /Users/zhengwr/eip4-pgdata -o "-p 5433" start # 若未起
# 1) 建库 + 自举 schema(可重复执行)
psql -h localhost -p 5433 -U zhengwr -d postgres -c "CREATE DATABASE eip4m0;" # 首次
psql -h localhost -p 5433 -U zhengwr -d eip4m0 -f platform-parity/src/main/resources/bootstrap/bootstrap-sys.sql
# 2) 起服务(profile=local,后台)
cd platform-app && mvn spring-boot:run -Dspring-boot.run.profiles=local &
# 3) RowDiff 单测
mvn test -pl platform-parity
# 4) 自对拍跑批(建 21 实体 + 灌数据 + 逐行 diff)
CP="platform-parity/target/classes:$(mvn -q org.apache.maven.plugins:maven-dependency-plugin:build-classpath \
-pl platform-parity -Dmdep.outputFile=/dev/stdout -o | tail -1)"
java -cp "$CP" com.eip4.platform.parity.selfcheck.ParityCli --seed --all
# → parity-reports/parity-*.{json,md},退出码 0=全一致
```
> 注:`--seed` 后引擎首次 list 才加载新实体 POInfo;若服务在 seed 前已缓存过同名实体(失败轮次),
> 需重启服务再 `--all`(见坑 3)。
---
## 【2026-06-11 增补】客户库口径实测(5435 网络恢复后)
### 最终结果:24/24 实体通过
| 口径 | 实体数 | 行数 | 结果 |
|------|-------:|-----:|------|
| 全量逐行 | 23 | **442,529** | 100% 一致 |
| 抽样逐行(PM_PAYMENTAPPLY,重查询实体) | 1 | 2,000(抽样,总 38,138) | 100% 一致 |
样本:跨 HR/WF/GB/OA/PM/SYS 六域 24 个真实实体,行数 57~49,938;含引用显示列、状态联查、
COLUMNSQL 计算列、布尔脏数据、关联表(无自有主键)、胖列(照片)等真实形态。
报告档:`parity-reports/parity-20260611-091808.*`(22 全量)+ `parity-20260611-095348.*`(GB_PRJ_WORKER 翻页回退)
+ `parity-20260611-110342.*`(PM_PAYMENTAPPLY 抽样)。
### 归因迭代台账(首轮 6/24 → 终轮 24/24,harness 修正,保真层零改动)
| 类 | 现象 | 根因 | 修正 | 涉及实体 |
|----|------|------|------|---------|
| A 计算列 | 引擎输出 UNITNAME/XXX_DISPLAY__/STATUS 等,物理表无此列,全行 MISSING_LEFT | 引擎对引用列做显示翻译(lateral 子查询) | 比对域限定左侧物理列;右独有列整列登记 engineExtraColumns | 13 个实体 |
| A2 null 省略 | DUEDATE/RCJTYPE 等全 null 列右侧整列缺失 | 引擎 JSON 省略 null 值键 | 右缺列+左 NULL=语义等值,登记 engineNullOmittedColumns | WF_HI_TASKINST、PM_MATERIALREPOSITORY |
| B 取数失败 | 行=0 报错 | ①单页 500 行 ≈61s 超时(DISTINCT+4 LATERAL);②单次全量 1.7GB 超 Jackson 上限(照片列) | 超时 60→300s;单次抓取失败自动回退翻页;--perPage/--sampleRows | PM_PAYMENTAPPLY、GB_PRJ_WORKER |
| C 行集错位 | onlyLeft=onlyRight 成对(929/1234) | 推断主键命中不唯一外键列(关联表无自有 PK);翻页幻影 | 主键唯一性校验→全部 *ID 复合键升级;单次全量抓取 | PM_TASKQUOTA、OA_SEALUSEAPPLYANDSEALRRELATION |
| D 已归因值差异 | BOOLEAN 列 L=2/-1 R=null(1,149+579 行);CONTRACTNUMBER L=null R=合同号(742/2000 行) | ①布尔域外脏数据引擎归 null;②COLUMNSQL 计算列覆盖物理列——**均为新旧一致的引擎语义,经元数据验证** | 元数据感知豁免:booleanDomainColumns / computedSqlColumns,可见不判负 | PM_BUDGETRCJ、PM_BUDGETLIST、PM_PAYMENTAPPLY |
### 结论与边界
1. **引擎移植保真度在客户库真实数据上成立**:44 万+行逐行逐列零未解释差异。
2. 三类元数据感知豁免(布尔域/null 省略/COLUMNSQL)都有引擎语义证据,且在报告中**可见**(整列登记+计数),不是吞差异。
3. PM_PAYMENTAPPLY 用抽样口径(2,000/38,138 行):全量约 78 分钟(每页 ≈61s 的 O(N) 重算,见迁移手册 §5.14),完整全量列入夜间批跑待办。
4. 本自对拍验证的是「引擎 vs 物理数据」;「新引擎 vs 旧系统」的录制重放对拍仍待旧系统环境(录制切面交付物已就绪)。