db-normalization

db-normalization (M1)

规范化是关系设计的核心：它通过让每条事实都有唯一归属，消除更新、插入和删除异常。本模块审查 1NF→3NF，以及经过审慎决策并有文档说明的例外（针对读取路径的反规范化）。它仅属于设计轴。对于文档/KV 范式，本模块会由配置中的 Access-pattern&embedding 取代——不要因为 Mongo 集合“缺少 3NF”而扣分。

检查内容

• 1NF — 原子性：存储列表的列（用逗号分隔值的 tags VARCHAR、phone_numbers TEXT）、重复组列（addr1, addr2, addr3、item_1, item_2），或用作连接表替代方案的数组。静态信号：列名模式，以及示例 DDL/注释中承载分隔数据的 text/varchar 类型。
• 2NF — 部分依赖：对于复合 PK，某个非键列仅依赖于键的一部分（例如，order_items(order_id, product_id, product_name) 中的 product_name 仅依赖于 product_id）。
• 3NF — 传递依赖：某个非键列在函数上由另一个非键列决定（例如，employees(id, dept_id, dept_name) 中的 dept_name 应属于 departments）。
• 反规范化规范性：重复/派生列（total、full_name、缓存计数）没有生成列定义、触发器或有文档说明的刷新路径——这些值会悄无声息地偏离。与 db-defaults-generated（M6）交叉检查。

轴与严重性

• 轴：设计。影响范围分为 high|medium|low，绝不捏造异常率。
• 高写入表中的重复组/列内 CSV：严重性 3–4，warn/fail，置信度 directional（静态）。
• 导致冗余可更新数据的传递依赖：严重性 3，warn。
• 可能偏离且未记录的反规范化重复数据：严重性 3，warn，fixable: proposed。
• M1 绝不设置严重性 5 上限；它会影响 Modelado 类别值。

Tier-0 静态检查

通过 scripts/parse-schema.mjs 解析 DDL 并检查列清单：标记使用分隔列表的列名、重复编号列，以及名称与其他表实体匹配的非键列（与 *_id 并列的 *_name、*_label）。对程序源代码的解析结果保持 directional，绝不设置上限。

Tier-1 验证查询

确认疑似列内 CSV 实际包含多个值：

-- $DATABASE_URL, read-only; does the column hold delimited lists?
SELECT count(*) AS rows_with_delimiter
FROM <table>
WHERE position(',' IN <column>::text) > 0;   -- >0 confirms 1NF violation

对于传递依赖，确认函数决定关系在各行间成立：

SELECT dept_id, count(DISTINCT dept_name) AS distinct_names
FROM employees GROUP BY dept_id HAVING count(DISTINCT dept_name) = 1;

没有可用的实时 DB 时，对于计数断言，该发现保持 needs_api——绝不悄然通过。

发现

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

• M1.users.tags_csv_in_column — tags VARCHAR(255) 存储逗号分隔的值（严重性 4，fail，fixable: proposed，轴 design，置信度 directional）。
• M1.order_items.partial_dependency_product_name — 非键列 product_name 依赖于复合 PK 的一部分（严重性 3，warn，轴 design）。
• M1.invoices.total_denormalized_undocumented — 派生列 total 没有生成列/触发器刷新机制（严重性 3，warn，fixable: proposed）。 每项发现：evidence.observed 原样引用实际 DDL 行（已脱敏）；verification.reproduce 是上述可运行命令（静态检查使用 method: ddl_parse，Tier-1 使用 query_stat/schema_introspect）；expected_impact 按影响范围分级并标注置信度，且附有理由。

诚实性

• 反规范化是合理且有时正确的选择——只标记不规范的反规范化（没有刷新路径、没有文档说明），绝不把反规范化本身视为问题。
• 1NF/2NF/3NF 适用于关系模型。文档存储中的嵌入式文档不属于规范化缺陷；这项判断由文档配置负责。
• 没有 Tier-1 查询作为依据时，绝不捏造异常频率或行数。