db-indexing

db-indexing（M11）

索引是 性能与规模（轴 performance）中影响最大的杠杆（关系型权重 20，索引）。此模块会检查现有索引是否符合数据查询方式——缺失、顺序错误或类型不当的索引，可能会让亚毫秒级查找变成顺序扫描。

检查内容

1. 复合索引顺序（ESR）——多列索引的列顺序应为 等值 → 排序 → 范围。将范围列或低选择性列放在首位会浪费索引。
2. 覆盖索引／部分索引——频繁执行的 SELECT a,b WHERE c 可从包含 INCLUDE 的覆盖索引中受益；若查询始终会根据某个谓词进行筛选（WHERE deleted_at IS NULL），则可从部分索引中受益。
3. 专用类型——对 jsonb／数组／全文搜索（FTS）包含查询使用 GIN；对几何数据／范围使用 GiST／SP-GiST；对自然有序的只追加列（时间戳）使用 BRIN。标记由普通 B-tree（或无索引）处理的全文搜索／地理数据／JSONB 筛选条件。
4. 外键无索引——每个外键列都应有覆盖索引；没有索引的外键会在 ON DELETE／ON UPDATE 时强制对被引用端执行顺序扫描，也会影响联接。这是收益最高、风险最低的索引问题。

分数／轴

仅影响 performance（关系型 索引 w20；每个 NoSQL 配置中的 索引类别）。

Tier-0（静态）

解析 DDL／迁移文件，识别已声明的索引和外键；将可见的查询模式（ORM where／orderBy、原始 SQL）与索引列进行交叉比对。检测没有匹配索引前缀的外键列、首列非等值条件的复合索引，以及没有专用索引的 JSONB／数组／全文搜索／地理数据谓词。索引是否实际被使用属于运行时事实 → Tier-0 阶段标记为 needs_api。

Tier-1（验证查询）——外键无索引（Postgres）

SELECT conrelid::regclass AS tbl, conname,
       pg_get_constraintdef(c.oid) AS fk
FROM pg_constraint c
WHERE c.contype = 'f'
  AND NOT EXISTS (
    SELECT 1 FROM pg_index i
    WHERE i.indrelid = c.conrelid
      AND (c.conkey[1]) = i.indkey[0]   -- leading index column == first FK column
  );

方法 index_check。每个返回的行都表示一个已确认未建立索引的外键（established）。对于 ESR／覆盖索引，使用真实查询执行 EXPLAIN (ANALYZE, BUFFERS)（方法 explain_plan，Tier-2）可确认扫描类型。

发现项

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

• M11.orders.customer_id_fk_unindexed——外键列没有覆盖索引（severity:3，warn， 轴 performance，静态检测置信度为 directional／Tier-1 检测置信度为 established，fixable: auto—— CREATE INDEX CONCURRENTLY）。
• M11.events.composite_order_esr——复合索引以范围列开头（severity:2，warn， directional，fixable: proposed）。
• M11.posts.jsonb_no_gin——jsonb 包含筛选条件没有 GIN 索引（severity:3，warn， directional，fixable: proposed）。

每个发现项：evidence.observed 原样引用外键／索引 DDL 或查询；verification.reproduce 为上文的目录查询（针对外键无索引）或引用 $DATABASE_URL 的 EXPLAIN；expected_impact 需标注影响范围并附置信度（不可只给出百分比）。

如实表述

• 缺少索引不一定就是缺陷——对于很小的查找表或写入密集型表，添加索引反而可能降低性能。应结合表大小／访问频率确定严重程度；缺少统计信息时，默认置信度为 directional。
• 绝不引用延迟或行数的具体改善数值；影响幅度只能标为 high|medium|low。
• 对外键索引缺失，CREATE INDEX CONCURRENTLY 可自动修复（仅新增、不阻塞、可验证）；复合索引重排和部分索引应标为 proposed，因为实际意图可能不同。