feat(parity): P1-1 全库归因——5 条元数据感知豁免 + 多重集兜底 + SQLXML 物化

全库 115 问题实体逐个归因,harness 修正(保真层零改动):

- 物理孤儿列豁免(RowDiff.physicalOrphanColumns):MISSING_RIGHT 且列无活跃
  元数据 → 引擎元数据驱动 SELECT 永不读,登记不判负;反向守门保留。
- XML 表示归一(Normalizer.xmlEqual + JdbcResultReader SQLXML.getString 物化):
  xml 物理列剥 <?xml?> 声明 + trim 首尾空白;根治 PgSQLXML 比对/序列化问题。
- 引擎空值渲染豁免(engineEmptyForNullColumns + Normalizer.nullVsEngineEmpty):
  物理 null 引擎渲染为空数组/空串,左 null+右空串语义等值。
- 多重集兜底(RowDiff.diffMultiset + Normalizer.groupingKey):视图无稳定唯一
  行键(两侧坍缩/合成)时按行多重集比较,时间/数值同口径归一。
- 抽样退全量:checkSample 无 {表名}_ID / IN 回查失败 / 合成键签名 → full check。

单测 23 → 30 全绿(每条新规则配正反例 + 守门用例)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 12:56:44 +08:00
parent ca2a6db0ab
commit 923cc72c66
6 changed files with 464 additions and 14 deletions

View File

@@ -53,6 +53,21 @@ public class DiffReport {
/** COLUMNSQL 计算列(元数据配子查询,引擎以计算值覆盖物理列;新旧行为一致):不参与值比对,整列登记。 */
public final Set<String> engineComputedSqlColumns = new TreeSet<>();
/**
* 物理孤儿列:物理表/视图有此列、引擎不返回(MISSING_RIGHT),且该列在 SYS_ENTITYATTRIBUTE
* 无活跃元数据 —— 引擎元数据驱动 SELECT 永不读它(物理冗余列,新旧系统行为一致)。整列登记不判负。
*/
public final Set<String> physicalOrphanColumns = new TreeSet<>();
/** xml 物理类型列:JDBC {@code xml::text} 带 {@code <?xml..?>} 声明头/首尾空白,引擎读路径剥离;XML 归一后等值。 */
public final Set<String> xmlRepresentationColumns = new TreeSet<>();
/** 引擎对 JSON 类型列的物理 null 渲染为空数组/空串(如 DETAILS):左 null + 右空 = 语义等值,整列登记。 */
public final Set<String> engineEmptyForNullColumns = new TreeSet<>();
/** 多重集兜底模式:视图无稳定唯一行键,放弃逐行配对、按行多重集比较(行集语义一致即判一致)。 */
public boolean multisetMode;
public DiffReport(String label) {
this.label = label;
}
@@ -136,6 +151,10 @@ public class DiffReport {
m.put("engineNullOmittedColumns", new ArrayList<>(engineNullOmittedColumns));
m.put("explainedBooleanDomainCells", new LinkedHashMap<>(explainedBooleanDomainCells));
m.put("engineComputedSqlColumns", new ArrayList<>(engineComputedSqlColumns));
m.put("physicalOrphanColumns", new ArrayList<>(physicalOrphanColumns));
m.put("xmlRepresentationColumns", new ArrayList<>(xmlRepresentationColumns));
m.put("engineEmptyForNullColumns", new ArrayList<>(engineEmptyForNullColumns));
m.put("multisetMode", multisetMode);
m.put("clean", isClean());
m.put("consistencyRate", consistencyRate());
List<Map<String, Object>> ms = new ArrayList<>();
@@ -170,6 +189,21 @@ public class DiffReport {
sb.append("- COLUMNSQL 计算列(引擎子查询覆盖物理列,不参与值比对): `")
.append(String.join(", ", engineComputedSqlColumns)).append("`\n");
}
if (!physicalOrphanColumns.isEmpty()) {
sb.append("- 物理孤儿列(物理有列、无活跃元数据,引擎不读 → 不判负): `")
.append(String.join(", ", physicalOrphanColumns)).append("`\n");
}
if (!xmlRepresentationColumns.isEmpty()) {
sb.append("- XML 表示差异列(声明头/首尾空白,XML 归一后等值): `")
.append(String.join(", ", xmlRepresentationColumns)).append("`\n");
}
if (!engineEmptyForNullColumns.isEmpty()) {
sb.append("- 引擎空值渲染列(物理 null 渲染为空数组/空串,语义等值): `")
.append(String.join(", ", engineEmptyForNullColumns)).append("`\n");
}
if (multisetMode) {
sb.append("- 对拍模式:多重集兜底(视图无稳定唯一行键,按行多重集比较)\n");
}
if (!explainedBooleanDomainCells.isEmpty()) {
sb.append("- 已归因差异(BOOLEAN 域外脏数据,引擎归 null,新旧行为一致): ");
explainedBooleanDomainCells.forEach((c, n) -> sb.append('`').append(c).append("`x").append(n).append(' '));

View File

@@ -142,6 +142,71 @@ public final class Normalizer {
return Kind.OTHER;
}
/**
* xml 物理类型列归一比较:PG {@code xml::text}(JDBC 直连侧)会保留入库时的 {@code <?xml..?>}
* 声明头(XML prolog)与首尾空白/空行;引擎读路径(REST 出口)把它们剥离。二者语义同一份 XML。
* 归一做法:剥去开头的 XML 声明 {@code <?xml ...?>},再 trim 全部首尾空白后比较剩余正文。
*
* <p>只做"声明头 + 首尾空白"两类表示差异的吸收;正文任何实质字符差异仍判不等(守门:不吞真差异)。
*/
public static boolean xmlEqual(Object a, Object b) {
if (a == null || b == null) {
return a == null && b == null;
}
String sa = stripXmlProlog(a.toString());
String sb = stripXmlProlog(b.toString());
return sa.equals(sb);
}
private static String stripXmlProlog(String s) {
String t = s.strip();
if (t.startsWith("<?xml")) {
int end = t.indexOf("?>");
if (end >= 0) {
t = t.substring(end + 2).strip();
}
}
return t;
}
/**
* 引擎对 JSON/数组类型列的物理 null 渲染为空表示(空数组 {@code []} → {@code ""}、空串)的等值判定:
* 左(物理基线)为 null,右(引擎)为空串 {@code ""} → 语义等值(同一份"无值",新旧引擎渲染一致)。
* 仅此一个方向(左 null / 右空串)成立;两侧都有内容或都 null 由常规 {@link #equal} 处理。
*/
public static boolean nullVsEngineEmpty(Object left, Object right) {
return left == null && right instanceof CharSequence cs && cs.length() == 0;
}
/**
* 多重集分组键:把单值归一为「与 {@link #equal} 同口径可比」的稳定字符串,
* 供 {@link RowDiff#diffMultiset} 给无稳定主键的视图按行多重集配对。
*
* <p>关键:必须吸收 {@link #equal} 里跨族等值的两类——(a) 整数↔等值小数(2 vs 2.000000)、
* (b) DATE/TIME 的 epoch(Long) ↔ ISO 串。否则同一行在两侧因表示不同被分到不同桶,假阳性。
* 分别归一:数值统一到去尾零 BigDecimal 的 plain 串;时间统一到 epoch 毫秒串;其余按规范字符串。
*/
public static String groupingKey(Object v) {
Object c = canonical(v);
if (c == null) {
return "NULL";
}
// 时间:Long 或 ISO instant 串都归一到 epoch 毫秒(与 equal 的 epochOf 同口径)
Long e = epochOf(c);
// Long 既可能是时间也可能是普通整数;但普通整数与"等值小数"也要统一 → 一律走数值归一,
// 只有当对端是 ISO 串时 equal 才按时间比;分组键无对端,故:ISO 串 → epoch,Long/数值 → 数值串。
if (c instanceof String s && looksLikeIsoInstant(s) && e != null) {
return "N:" + e;
}
if (c instanceof Long l) {
return "N:" + new BigDecimal(l).toPlainString();
}
if (c instanceof BigDecimal bd) {
return "N:" + bd.toPlainString();
}
return "S:" + c;
}
/** char(n) 定长列尾部空格归一(只去尾部,保留中间与前导)。 */
public static String stripTrailing(String s) {
if (s == null) {

View File

@@ -67,6 +67,31 @@ public final class RowDiff {
return this;
}
/** 实体活跃元数据列集(大写);为空表示"未知/不启用物理孤儿列豁免"(规则失效,照旧判负)。 */
private java.util.Set<String> metadataColumns = java.util.Set.of();
private boolean metadataColumnsKnown = false;
/**
* 注入实体的「活跃元数据列集」,启用物理孤儿列豁免:某列在物理基线(左)存在、引擎(右)缺,
* 且该列不在元数据列集 → 引擎元数据驱动 SELECT 永不读它(物理冗余列,新旧行为一致),
* 登记 {@link DiffReport#physicalOrphanColumns} 不判负。仅自对拍模式生效。
*
* <p>传 null 视为"元数据未知",规则不启用(保守:照旧报 MISSING_RIGHT,不误豁免)。
*/
public RowDiff metadataColumns(java.util.Set<String> cols) {
this.metadataColumnsKnown = cols != null;
this.metadataColumns = cols == null ? java.util.Set.of() : cols;
return this;
}
/** xml 物理类型列集(大写):JDBC {@code xml::text} 带声明头/首尾空白,引擎读路径剥离 —— XML 归一后比较。 */
private java.util.Set<String> xmlColumns = java.util.Set.of();
public RowDiff xmlColumns(java.util.Set<String> cols) {
this.xmlColumns = cols == null ? java.util.Set.of() : cols;
return this;
}
public DiffReport diff(String label, List<Map<String, Object>> left, List<Map<String, Object>> right) {
DiffReport report = new DiffReport(label);
report.keyColumns.addAll(keyColumns);
@@ -102,6 +127,94 @@ public final class RowDiff {
return report;
}
/**
* 多重集对拍兜底:SQL 视图无稳定唯一行键({表名}_ID 在两侧坍缩/不唯一,如 VIEW_OA_MEETING
* 两侧仅 5 distinct/83 行)时,逐行配对必然错位、报满 onlyLeft/onlyRight 假阳性。
* 此路径放弃配对,把两侧规范化为「行多重集」直接比较:行集语义一致(内容相同、仅顺序/键不可配对)
* 即判一致,否则报为剩余的多重集差异(净增/净缺行数登记到 onlyInLeft/onlyInRight 计数)。
*
* <p>比对域 = 左侧物理列集减去 {物理孤儿列、COLUMNSQL 计算列、不稳定主键列},
* 与逐行模式同口径(引擎计算列/null 省略列不参与);每列值经 {@link Normalizer} 规范化。
* 仅自对拍模式({@code rightOnlyColumnsAsInfo}=true)使用。
*
* @param excludeColumns 额外排除的列(通常是不稳定的 {表名}_ID;视图生成的 _ID 两侧表示不同)
*/
public DiffReport diffMultiset(String label, List<Map<String, Object>> left,
List<Map<String, Object>> right, java.util.Set<String> excludeColumns) {
DiffReport report = new DiffReport(label);
report.multisetMode = true;
report.leftRowCount = left == null ? 0 : left.size();
report.rightRowCount = right == null ? 0 : right.size();
// 比对域:左侧物理列,去掉孤儿/计算/显式排除列(引擎不返回或不可比的列)
java.util.LinkedHashSet<String> domain = new java.util.LinkedHashSet<>();
if (left != null) {
for (Map<String, Object> row : left) {
for (String c : row.keySet()) {
String cu = c == null ? null : c.toUpperCase();
if (cu == null || computedSqlColumns.contains(cu)) {
continue;
}
if (excludeColumns != null && excludeColumns.contains(cu)) {
continue;
}
if (metadataColumnsKnown && !metadataColumns.contains(cu)) {
report.physicalOrphanColumns.add(cu);
continue;
}
domain.add(cu);
}
}
}
report.keyColumns.add("(multiset:" + String.join("+", domain) + ")");
Map<String, Integer> leftBag = rowBag(left, domain);
Map<String, Integer> rightBag = rowBag(right, domain);
// 多重集差:两侧抵消后剩余即净差异行
int onlyLeft = 0;
int onlyRight = 0;
int matched = 0;
java.util.Set<String> allRowKeys = new java.util.TreeSet<>();
allRowKeys.addAll(leftBag.keySet());
allRowKeys.addAll(rightBag.keySet());
for (String rk : allRowKeys) {
int lc = leftBag.getOrDefault(rk, 0);
int rc = rightBag.getOrDefault(rk, 0);
matched += Math.min(lc, rc);
if (lc > rc) {
onlyLeft += lc - rc;
} else if (rc > lc) {
onlyRight += rc - lc;
}
}
report.matchedRows = matched;
for (int i = 0; i < onlyLeft; i++) {
report.onlyInLeft.add("(multiset-net-left)");
}
for (int i = 0; i < onlyRight; i++) {
report.onlyInRight.add("(multiset-net-right)");
}
return report;
}
/** 把结果集规范化为「行→出现次数」多重集;行键 = 域内各列规范值的拼接串。 */
private Map<String, Integer> rowBag(List<Map<String, Object>> rows, java.util.Set<String> domain) {
Map<String, Integer> bag = new java.util.HashMap<>();
if (rows == null) {
return bag;
}
for (Map<String, Object> row : rows) {
Map<String, Object> upper = upperKeys(row);
StringBuilder sb = new StringBuilder();
for (String col : domain) {
// groupingKey 与逐行 equal 同口径:吸收整数↔等值小数、epoch↔ISO 时间表示差异
sb.append(Normalizer.groupingKey(upper.get(col))).append(SEP);
}
bag.merge(sb.toString(), 1, Integer::sum);
}
return bag;
}
/** 逐列比较一行(主键已匹配);列集 = 两侧并集。 */
private DiffReport.RowMismatch diffRow(String key, Map<String, Object> l, Map<String, Object> r,
DiffReport report) {
@@ -128,6 +241,10 @@ public final class RowDiff {
if (rightOnlyColumnsAsInfo && lu.get(col) == null) {
// 引擎 JSON 对 null 值列整列省略:左 null + 右缺列 = 语义等值
report.engineNullOmittedColumns.add(col);
} else if (rightOnlyColumnsAsInfo && metadataColumnsKnown && !metadataColumns.contains(col)) {
// 物理孤儿列:物理表有此列(左)、引擎不返回(右),且该列无活跃元数据 ——
// 引擎元数据驱动 SELECT 永不读它(新旧系统行为相同),登记不判负
report.physicalOrphanColumns.add(col);
} else {
mm.cells.add(new DiffReport.CellDiff(col, lu.get(col), null, "MISSING_RIGHT"));
}
@@ -144,7 +261,21 @@ public final class RowDiff {
// 两侧都有该列(可能值为 null)
Object lv = lu.get(col);
Object rv = ru.get(col);
if (!Normalizer.equal(lv, rv)) {
boolean equal = Normalizer.equal(lv, rv);
if (!equal && xmlColumns.contains(col)) {
// xml 物理列:JDBC xml::text 带 <?xml..?> 声明头/首尾空白,引擎读路径剥离 —— XML 归一后比
equal = Normalizer.xmlEqual(lv, rv);
if (equal) {
report.xmlRepresentationColumns.add(col);
}
}
if (!equal && rightOnlyColumnsAsInfo && Normalizer.nullVsEngineEmpty(lv, rv)) {
// 引擎对 JSON 类型列(如 PM_CALCBASICSCONFIG.DETAILS)的物理 null 渲染为空数组/空串:
// 左 null + 右空(""/[]) = 语义等值(新旧引擎渲染一致),登记不判负
equal = true;
report.engineEmptyForNullColumns.add(col);
}
if (!equal) {
if (rv == null && lv != null && booleanDomainColumns.contains(col)
&& !isZeroOrOne(lv)) {
// BOOLEAN 列域外脏数据(如 2/-1):引擎(新旧一致)归 null,已归因不判负

View File

@@ -47,10 +47,26 @@ public class JdbcResultReader {
for (Map<String, Object> r : rows) {
Map<String, Object> m = new LinkedHashMap<>();
for (Map.Entry<String, Object> e : r.entrySet()) {
m.put(e.getKey() == null ? null : e.getKey().toUpperCase(), e.getValue());
m.put(e.getKey() == null ? null : e.getKey().toUpperCase(), materialize(e.getValue()));
}
out.add(m);
}
return out;
}
/**
* 物化 JDBC 惰性/流式类型为可比可序列化的标量:
* {@code xml} 列经 PG 驱动返回 {@link java.sql.SQLXML}(PgSQLXML),其 {@code toString()} 非 XML 正文、
* 且 Jackson 无法序列化(内含 binaryStream)。统一取 {@code getString()} 得 XML 文本,与引擎侧对齐。
*/
private static Object materialize(Object v) {
if (v instanceof java.sql.SQLXML xml) {
try {
return xml.getString();
} catch (java.sql.SQLException ex) {
return null;
}
}
return v;
}
}

View File

@@ -59,15 +59,35 @@ public class SelfCheckRunner {
List<String> keys = (!left.isEmpty() && left.get(0).containsKey(pk))
? List.of(pk)
: RowDiff.inferKeyColumns(t, left.isEmpty() ? right : left);
if (!left.isEmpty() && !RowDiff.keyIsUnique(keys, left)) {
boolean keyUniqueLeft = !left.isEmpty() && RowDiff.keyIsUnique(keys, left);
if (!left.isEmpty() && !keyUniqueLeft) {
List<String> composite = RowDiff.allIdColumns(left);
keys = RowDiff.keyIsUnique(composite, left) ? composite : List.of();
if (RowDiff.keyIsUnique(composite, left)) {
keys = composite;
keyUniqueLeft = true;
} else {
keys = List.of();
}
}
// 自对拍模式:引擎计算列(右独有)登记不判负;BOOLEAN 域外脏数据归 null 为已归因差异
return new RowDiff(keys, true)
// 自对拍模式:引擎计算列(右独有)登记不判负;BOOLEAN 域外脏数据归 null 为已归因差异;
// 物理孤儿列(无活跃元数据)/xml 表示差异/JSON 空值渲染均按元数据感知豁免
RowDiff rd = new RowDiff(keys, true)
.booleanDomainColumns(booleanColumns(t))
.computedSqlColumns(computedSqlColumns(t))
.diff(t, left, right);
.metadataColumns(metadataColumns(t))
.xmlColumns(xmlColumns(t));
// 主键在两侧均唯一才走逐行配对;否则(SQL 视图无稳定唯一行键,如 VIEW_OA_MEETING
// {表名}_ID 两侧坍缩)退多重集兜底 —— 排除不稳定的 {表名}_ID 列
if (keyUniqueLeft && RowDiff.keyIsUnique(keys, right)) {
DiffReport rowwise = rd.diff(t, left, right);
// 逐行配对退化检测:两侧均非空却零配对(SQL 视图 {表名}_ID 两侧各自唯一但取值不相交——
// 视图按行生成 _ID,两端表示不同)→ 主键不可跨端配对,退多重集兜底
if (rowwise.matchedRows == 0 && !left.isEmpty() && !right.isEmpty()) {
return rd.diffMultiset(t, left, right, java.util.Set.of(pk));
}
return rowwise;
}
return rd.diffMultiset(t, left, right, java.util.Set.of(pk));
}
/**
@@ -84,8 +104,10 @@ public class SelfCheckRunner {
return error(t, "引擎读路径失败(抽样): " + e.getMessage());
}
String pk = t + "_ID";
// 关联/视图表无 {表名}_ID 主键(如 SYS_ROLE_ROLE / OA_*RELATION):抽样按 IN(pk) 回查不成立,
// 退全量 check() —— 其复合键/多重集兜底能正确处理无稳定主键的大表
if (right.isEmpty() || !upper(right.get(0)).containsKey(pk)) {
return error(t, "抽样模式需 {表名}_ID 主键且结果非空");
return check(t);
}
List<String> pks = new java.util.ArrayList<>(right.size());
for (Map<String, Object> r : right) {
@@ -95,16 +117,28 @@ public class SelfCheckRunner {
}
}
List<Map<String, Object>> left = new java.util.ArrayList<>(pks.size());
for (int i = 0; i < pks.size(); i += 1000) {
List<String> chunk = pks.subList(i, Math.min(i + 1000, pks.size()));
String in = String.join(",", java.util.Collections.nCopies(chunk.size(), "?"));
left.addAll(jdbc.query(
"SELECT * FROM " + t + " WHERE " + pk + " IN (" + in + ")",
chunk.toArray()));
try {
for (int i = 0; i < pks.size(); i += 1000) {
List<String> chunk = pks.subList(i, Math.min(i + 1000, pks.size()));
String in = String.join(",", java.util.Collections.nCopies(chunk.size(), "?"));
left.addAll(jdbc.query(
"SELECT * FROM " + t + " WHERE " + pk + " IN (" + in + ")",
chunk.toArray()));
}
} catch (Exception inErr) {
// IN(pk) 回查失败(如 SQL 视图 {表名}_ID 是引擎合成列,JDBC 侧不可过滤)→ 退全量 check()
return check(t);
}
// 合成主键签名:引擎 {表名}_ID 在物理侧大面积查不到(回查行数远小于抽样行数)——
// 引擎按行生成 _ID(如 VIEW_HR_CHECKINOUTSELECT 的 md5 合成键),抽样不可信,退全量多重集
if (left.size() * 2 < pks.size()) {
return check(t);
}
return new RowDiff(List.of(pk), true)
.booleanDomainColumns(booleanColumns(t))
.computedSqlColumns(computedSqlColumns(t))
.metadataColumns(metadataColumns(t))
.xmlColumns(xmlColumns(t))
.diff(t + "[抽样" + right.size() + "行]", left, right);
}
@@ -157,6 +191,51 @@ public class SelfCheckRunner {
}
}
/**
* 实体的「活跃元数据列集」(大写):SYS_ENTITYATTRIBUTE 中 isactive=1 的 columnname。
* 用于物理孤儿列豁免——MISSING_RIGHT 且列不在此集 → 引擎元数据驱动 SELECT 永不读它。
* 查询失败/空集返回 null(规则不启用,保守判负,绝不误豁免)。
*/
private java.util.Set<String> metadataColumns(String table) {
try {
var rows = jdbc.query(
"SELECT a.columnname FROM sys_entityattribute a "
+ "JOIN sys_entity e ON a.entityid = e.sys_entity_id "
+ "WHERE upper(trim(e.tablename)) = ? AND a.isactive = 1",
table.toUpperCase());
java.util.Set<String> cols = new java.util.HashSet<>();
for (var r : rows) {
Object c = r.values().iterator().next();
if (c != null) {
cols.add(c.toString().trim().toUpperCase());
}
}
return cols.isEmpty() ? null : cols;
} catch (Exception e) {
return null;
}
}
/** 实体的 xml 物理类型列集(大写):JDBC xml::text 带声明头/空白,引擎读路径剥离 → XML 归一比较。 */
private java.util.Set<String> xmlColumns(String table) {
try {
var rows = jdbc.query(
"SELECT upper(column_name) c FROM information_schema.columns "
+ "WHERE upper(table_name) = ? AND data_type = 'xml'",
table.toUpperCase());
java.util.Set<String> cols = new java.util.HashSet<>();
for (var r : rows) {
Object c = r.values().iterator().next();
if (c != null) {
cols.add(c.toString().trim().toUpperCase());
}
}
return cols;
} catch (Exception e) {
return java.util.Set.of();
}
}
private static DiffReport error(String table, String msg) {
DiffReport r = new DiffReport(table);
DiffReport.RowMismatch mm = new DiffReport.RowMismatch("RUNNER_ERROR");