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

17 KiB
Raw Permalink Blame History

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 内核/归一化规则/报告产物全部实证就位,降低网络恢复后的集成风险。


七、复现步骤

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 旧系统」的录制重放对拍仍待旧系统环境(录制切面交付物已就绪)。