文档分层:随代码演进的技术文档入 git(团队 clone 可得、有版本与评审); 决策档案与含商务内容的治理文档留工作区 docs/(不随仓库分发,外包 clone 不携带)。 全部交叉引用已更新(README×2/实测报告×2/登记表/pom/ArchUnit 注释) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
17 KiB
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 内核 + 归一化规则 + 报告产物正确;距「与客户库全量逐行对拍」还差:
- 基线侧换真流量(网络恢复后):
- 在旧系统部署
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())。
- 在旧系统部署
- 旧系统侧切面部署步骤(报批后):见
recorder/集成说明.md第五节 「生产流量旁路录制方案」——方案 A(进程内异步旁路 + 采样,可热关)/ 方案 B(镜像库重放,零生产侵入); 验收期建议 B 跑全量 + A 采样补热点,切流灰度期 A 低采样常开作线上对拍探针。 - 安全负例进对拍(架构第四节第 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 内核/归一化规则/报告产物全部实证就位,降低网络恢复后的集成风险。
七、复现步骤
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 |
结论与边界
- 引擎移植保真度在客户库真实数据上成立:44 万+行逐行逐列零未解释差异。
- 三类元数据感知豁免(布尔域/null 省略/COLUMNSQL)都有引擎语义证据,且在报告中可见(整列登记+计数),不是吞差异。
- PM_PAYMENTAPPLY 用抽样口径(2,000/38,138 行):全量约 78 分钟(每页 ≈61s 的 O(N) 重算,见迁移手册 §5.14),完整全量列入夜间批跑待办。
- 本自对拍验证的是「引擎 vs 物理数据」;「新引擎 vs 旧系统」的录制重放对拍仍待旧系统环境(录制切面交付物已就绪)。