db-referential-integrity

db-referential-integrity（M3）

外键由数据库负责确保引用指向真实存在的对象，是防止产生孤儿数据成本最低、最持久的保障。缺少外键会将完整性检查推给应用代码，而应用代码中的检查会悄然失效。本模块同时关注两个维度：设计层面的完整性，以及性能层面的联接和规划行为。它仅适用于支持外键的关系型数据库引擎；文档型和 KV 型配置文件完全不包含此项（避免造成误报）。

检查内容

• 缺少外键：列的名称或类型表明它是一个引用（*_id 与另一张表的主键匹配），但没有 FOREIGN KEY 约束。对于财务或身份验证表（订单、付款、会话、成员关系），缺少外键导致可能产生孤儿数据的情况属于严重性 5 的上限情形。
• ON DELETE / ON UPDATE 操作：外键未明确指定引用操作，而默认操作（NO ACTION/RESTRICT）不适用于该关系；或者存在可能导致大规模删除的危险 CASCADE（例如删除用户时级联删除发票）。每项操作都必须经过有意选择。
• 引用循环：外键形成循环（A→B→C→A），导致无法按顺序插入或删除，并增加迁移复杂度——严重性 4。
• 复合外键不匹配：多列外键的列集合或顺序与所引用的唯一键不匹配，或仅引用复合键的部分列。
• 未受信任/NOT VALID 外键：回填后仍未验证的外键（Postgres NOT VALID）。

维度与严重性

• 缺少外键，导致财务/身份验证数据行可能成为孤儿：严重性 5，fail，维度 both，置信度 established（触发上限）。
• 外键循环：严重性 4，warn，维度 both。
• 缺少或范围过宽的 ON DELETE（静默的 RESTRICT 阻止操作，或非预期的 CASCADE）：严重性 3–4，warn，维度 design。
• 复合外键顺序不匹配：严重性 3，warn。
• 注意：缺少支持索引的外键列归 M11（索引）检查，不在此处处理——请交叉引用，不要重复计数。

Tier-0 静态检查

通过 scripts/parse-schema.mjs 解析 DDL：对于每个 *_id 风格的列，检查是否存在匹配的 FOREIGN KEY/REFERENCES 子句；枚举已声明的外键，并标记未明确指定 ON DELETE/ON UPDATE 操作的外键；构建外键图并检测循环。方向性的 ORM 源码解析绝不会触发严重性 5 的孤儿数据上限。

Tier-1 验证查询

列出外键约束及其操作（确认是否缺少危险操作）：

-- $DATABASE_URL, read-only
SELECT conrelid::regclass AS child, confrelid::regclass AS parent,
       confdeltype AS on_delete, confupdtype AS on_update, convalidated AS validated
FROM pg_constraint WHERE contype = 'f';

确认疑似缺少外键时是否确实存在孤儿数据：

SELECT count(*) AS orphans FROM child c
LEFT JOIN parent p ON c.parent_id = p.id WHERE p.id IS NULL AND c.parent_id IS NOT NULL;

没有连接到实时数据库时，孤儿数据计数应标记为 needs_api，绝不能静默通过。

发现项

按 schema/finding.schema.json 输出。示例：

• M3.payments.user_id_no_fk — user_id 未引用任何表；可能产生孤儿付款记录（严重性 5，fail，维度 both，置信度 established）。
• M3.invoices.fk_cascade_deletes_financial — 从用户开始的 ON DELETE CASCADE 会大规模删除发票（严重性 4，warn，维度 design，fixable: proposed）。
• M3.graph.fk_cycle_a_b_c — 引用循环会阻止按顺序加载（严重性 4，warn，维度 both）。 每个发现项：evidence.observed 按原样引用外键/列 DDL 或目录行；verification.reproduce 使用上方可运行的查询（method: ddl_parse / constraint_check / query_stat）；expected_impact 按等级划分并标注置信度。

诚实原则

• 只有在孤儿数据风险确实存在（财务/身份验证完整性）时，缺少外键才会触发上限；低风险查找表缺少外键最多标记为 warn。
• 应用层完整性检查（验证、软外键）是缓解措施，不是替代方案——应注明，但数据库层面的保障仍然缺失。不要声称应用代码“修复”了这一问题。
• 没有 Tier-1 计数时，绝不要断言存在孤儿数据；静态检查的结论属于 directional。