# 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 按主键排序配对 → 逐行逐列归一比较 │ │ 产出 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` 无序,比较走列名集合并集, 列在表里的物理顺序对结果零影响。 - **冗余列由 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 旧系统」的录制重放对拍仍待旧系统环境(录制切面交付物已就绪)。