给 trigger_rule_codes 加 JSON 多值索引；登记 P3 处理结果（docs/25 P3 #21）

实测确认 #21 描述准确：fin_risk_alert 只有 11 个普通 BTREE 索引 + 主键 + alert_no 唯一键，规则命中的 JSON_CONTAINS 查询 EXPLAIN 为 type=ALL、possible_keys=NULL，即全表扫。MySQL 8.0.27 支持多值索引，故新增迁移 20260911_risk_rule_index： ADD INDEX idx_fin_risk_alert_trigger_rule_codes ((CAST(`trigger_rule_codes` AS CHAR(16) ARRAY))) 迁移幂等（先查 information_schema.STATISTICS），upgrade/downgrade 往返已验证。生效后 EXPLAIN 变为 access_type=range 且 key 命中该索引，原始证据留档在 docs/evidence/risk-index-probe.json（由 tools/probe_risk_index.py 生成，只读探查）。只解决一半，另一半如实记为限制：若干 like(f"%{keyword}%") 全表扫无法用 B-tree 索引，根治需全文索引 + 中文分词组件（部署依赖），本轮不做。 revision 名刻意压到 32 字符以内 —— alembic_version.version_num 是 VARCHAR(32)，超长会在写版本号时报 1406，而 DDL 是非事务的，那时索引已经建好了。 docs/25 追加"P3 处理结果"表，逐条登记 17-25 的状态：#19 是协议级重做（keyset 分页）不单方面改，#21 部分修复，#25 前半段不成立，其余已修。
2026-09-11 14:19:05 +08:00
parent 661b17c244
commit df96275ab5
4 changed files with 386 additions and 0 deletions
@@ -0,0 +1,80 @@
+"""给 `fin_risk_alert.trigger_rule_codes` 补 JSON 多值索引（docs/25 P3 #21）。
+
+修订原因：规则命中查询走的是 `JSON_CONTAINS(trigger_rule_codes, '"RW-018"')`
+（`risk_repository.py` 的 `contains`），而 `docs/25` 第 21 条实测该表**没有**任何可用于
+该表达式的索引 —— `information_schema.STATISTICS` 里 `fin_risk_alert` 只有 11 个普通
+BTREE 索引（`status`、`customer_id`、`created_at` 等）+ 主键 + `alert_no` 唯一键，
+`EXPLAIN` 显示 `type=ALL`、`possible_keys=NULL`，即每次按规则码筛选都是全表扫描。
+
+为什么用**多值索引**而不是普通索引：`trigger_rule_codes` 是 `json` 列，存的是数组
+（实测取值形如 `["RW-007", "RW-002", "RW-012"]`）。MySQL 8.0.17 起支持在 JSON 数组上
+建多值索引，且优化器在 `JSON_CONTAINS` / `MEMBER OF` / `JSON_OVERLAPS` 上可以使用它 ——
+这正是本条要解决的那个谓词。当前实例版本 8.0.27，满足条件。
+
+`CAST(... AS CHAR(16) ARRAY)` 中的 16：规则码是 `RW-###`（5 字符），留足余量而不至于让
+索引项过大。**注意**这不是"截断匹配"—— 多值索引要求列上所有取值都能装进声明长度，
+否则 `ALTER` 会直接失败（报 3903），而不是悄悄少索引几行。
+
+前置条件已在 `tools/probe_risk_index.py` 里验证并留档
+（`docs/evidence/risk-index-probe.json`）：3 行数据全部是 JSON 数组，
+`non_array_rows = 0`。
+
+**本条只解决一半**：另一处索引失效是若干 `like(f"%{keyword}%")` 全表扫 —— 前后都有
+通配符的模糊匹配在 B-tree 上无法索引，唯一出路是全文索引（中文需要分词组件，属于部署
+依赖）。因此这里**不**假装解决它，只把它记为已知限制，见迁移提交说明与 `docs/25`。
+
+基线合规（`AGENTS.md` 第 2/3/4 条）：本迁移只**新增一个索引**，不建表、不加列、不改列，
+不重命名、不删除任何已有表或字段，也不改变任何已有字段的类型、可空性与业务含义。
+`docs/00-新数据库基线设计.md` 未修改。
+
+幂等性：先查 `information_schema.STATISTICS` 再决定是否 `ALTER`，重复执行不会报 1061。
+`downgrade` 与之对称，回退后结构与迁移前完全一致。
+"""
+
+from sqlalchemy import text
+from sqlalchemy.engine import Connection
+
+from alembic import op
+
+# revision 名必须 ≤ 32 字符：`alembic_version.version_num` 是 VARCHAR(32)，
+# 超长会在写版本号时报 1406 Data too long —— 而 DDL 是非事务的，那时索引已经建好了。
+revision = "20260911_risk_rule_index"
+down_revision = "20260910_drop_review_separation"
+branch_labels = None
+depends_on = None
+
+TABLE = "fin_risk_alert"
+INDEX = "idx_fin_risk_alert_trigger_rule_codes"
+EXPRESSION = "CAST(`trigger_rule_codes` AS CHAR(16) ARRAY)"
+
+
+def _index_exists(bind: Connection) -> bool:
+    found = bind.execute(
+        text(
+            """
+            SELECT 1
+            FROM information_schema.STATISTICS
+            WHERE TABLE_SCHEMA = DATABASE()
+              AND TABLE_NAME = :table
+              AND INDEX_NAME = :name
+            LIMIT 1
+            """
+        ),
+        {"table": TABLE, "name": INDEX},
+    ).first()
+    return found is not None
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    if _index_exists(bind):
+        return
+    # 表名/索引名/表达式都是本模块常量，不含外部输入。
+    op.execute(f"ALTER TABLE `{TABLE}` ADD INDEX `{INDEX}` (({EXPRESSION}))")
+
+
+def downgrade() -> None:
+    bind = op.get_bind()
+    if not _index_exists(bind):
+        return
+    op.execute(f"ALTER TABLE `{TABLE}` DROP INDEX `{INDEX}`")
@@ -240,6 +240,20 @@ Asia/Shanghai 展示。北京 08:00 前生成时，统计窗口是"前一日 08:
 | 24 | SSE 未校验 `Accept`（`SseNotAcceptableError`/406 已定义但未被使用） | `api/controllers/risk.py:182-204` |
 | 25 | 接口未登记 `docs/05`：§19 目录里一条风控接口都没有，而 §20 明确要求"新增接口必须同步更新 §19"；且 §12 约定的前缀是 `/risk-scans/**`、`/risk-alerts/**`，实现是 `/api/v1/risk` | `docs/05-接口文档.md` §12/§19/§20 |

+**P3 处理结果（2026-09-11）**
+
+| # | 状态 | 处理 |
+|---|---|---|
+| 17 | ✅ 已修 | 列表信封改为 `{data: [...], meta: {trace_id, next_cursor, has_more}}`，对齐 §3.3；五个列表端点统一走 `_list_envelope` |
+| 18 | ✅ 已修 | 游标内嵌 SHA-256 指纹（`user_id` + `data_scope`/`customer_ids` + 查询条件；`/evidence/{source}` 的 `source` 一并绑定，否则 customers 的游标能直接翻 products）。指纹不符一律 `400 INVALID_CURSOR`。**刻意排除 `limit`**：它是分页参数不是查询条件 |
+| 19 | ⚠️ 已知限制 | offset 游标无法根治跳行/重复，要根治得改 keyset 分页（游标携带"上一页最后一条的排序键"）。这会**改动分页协议本身**，且当前排序首列是 `case(alert_level=HIGH…)` 这种计算列，需要连排序一起去掉 —— 属于协议级重做，不在本轮单方面改 |
+| 20 | ✅ 已修 | 详情证据每类封顶 200 条、日报每组封顶 5000 条，用 `limit + 1` 判定截断，并在响应里暴露 `evidence_truncated` / `data_truncated`。**不静默截断**：日报计数直接来自行数，静默截断等于给出一份看起来正常、实际少统计的日报 |
+| 21 | 🟡 部分修复 | `trigger_rule_codes` 已加 JSON 多值索引（迁移 `20260911_risk_rule_index`）；`EXPLAIN` 由 `type=ALL`、`possible_keys=NULL` 变为 `type=range` 并命中 `idx_fin_risk_alert_trigger_rule_codes`，实测证据留档在 `docs/evidence/risk-index-probe.json`。**`like(f"%{keyword}%")` 依然全表扫**：前后通配符在 B-tree 上无解，根治需全文索引 + 中文分词组件（部署依赖），本轮不做，如实记为限制 |
+| 22 | ✅ 已修 | 6 个写接口接入平台 `api_request_receipt` 幂等。新增 `ApiTransactionService.execute_in`：原 `execute` 自开 `SessionFactory()` 与 `session.begin()`，而 `RiskActionService._finish` 内部会 commit，套进去就是"内层提交外层事务"，故改为在调用方事务内读写幂等记录 |
+| 23 | ✅ 已修 | **不把 413 降成 422**：413 是上传超限的标准语义，前端文档也已按 413 做提示映射，改为在 `docs/05` §3.5 状态码表**补登** 413，契约以"补齐"而非"改动"方式对齐 |
+| 24 | ✅ 已修 | SSE 端点补 `Accept` 协商（抽到 `app/api/dependencies/negotiation.py` 与 `/agent-runs/{run_id}/events` 共用）。顺带发现一个更隐蔽的问题：鉴权原本在 async generator 内部，403 只能在响应头发出**之后**抛出，表现为"200 + 半截流"，现改为构造 `StreamingResponse` 前完成 |
+| 25 | 🟡 部分成立 | "§19 一条风控接口都没有"**不成立**：§19 末尾写明业务域接口由各自业务文档登记，15 条端点已在 `docs/风控业务演示文档/06-模块接口与字段映射.md` 逐条登记。真问题是 §12 写的 `/risk-scans/**`、`/risk-alerts/**` 与实际实现 `/api/v1/risk/**` 不符，已按实现更新 §12 并加说明 |
+
 ---

 ## 六、做得好、建议保持 ✅
@@ -0,0 +1,154 @@
+{
+  "mysql_version": "8.0.27",
+  "column": [
+    {
+      "COLUMN_NAME": "trigger_rule_codes",
+      "COLUMN_TYPE": "json",
+      "DATA_TYPE": "json",
+      "IS_NULLABLE": "NO"
+    }
+  ],
+  "indexes": [
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_alert_level",
+      "COLUMN_NAME": "alert_level",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_alert_type",
+      "COLUMN_NAME": "alert_type",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_created_at",
+      "COLUMN_NAME": "created_at",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_customer_id",
+      "COLUMN_NAME": "customer_id",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_due_at",
+      "COLUMN_NAME": "due_at",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_handler_id",
+      "COLUMN_NAME": "handler_id",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_primary_risk_work_order_id",
+      "COLUMN_NAME": "primary_risk_work_order_id",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_priority_score",
+      "COLUMN_NAME": "priority_score",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_related_order_id",
+      "COLUMN_NAME": "related_order_id",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_related_transaction_id",
+      "COLUMN_NAME": "related_transaction_id",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_related_work_order_id",
+      "COLUMN_NAME": "related_work_order_id",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_status",
+      "COLUMN_NAME": "status",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "idx_fin_risk_alert_trigger_rule_codes",
+      "COLUMN_NAME": null,
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": "cast(`trigger_rule_codes` as char(16) array)"
+    },
+    {
+      "INDEX_NAME": "PRIMARY",
+      "COLUMN_NAME": "id",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    },
+    {
+      "INDEX_NAME": "uk_fin_risk_alert_alert_no",
+      "COLUMN_NAME": "alert_no",
+      "INDEX_TYPE": "BTREE",
+      "EXPRESSION": null
+    }
+  ],
+  "row_count": 3,
+  "non_array_rows": 0,
+  "distinct_rule_codes": [
+    {
+      "raw_codes": "[\"RW-007\", \"RW-002\", \"RW-012\"]",
+      "rows_count": 1
+    },
+    {
+      "raw_codes": "[\"RW-015\", \"RW-003\"]",
+      "rows_count": 1
+    },
+    {
+      "raw_codes": "[\"RW-018\"]",
+      "rows_count": 1
+    }
+  ],
+  "explain_json_contains": {
+    "query_block": {
+      "select_id": 1,
+      "cost_info": {
+        "query_cost": "0.71"
+      },
+      "table": {
+        "table_name": "fin_risk_alert",
+        "access_type": "range",
+        "possible_keys": [
+          "idx_fin_risk_alert_trigger_rule_codes"
+        ],
+        "key": "idx_fin_risk_alert_trigger_rule_codes",
+        "used_key_parts": [
+          "cast(`trigger_rule_codes` as char(16) array)"
+        ],
+        "key_length": "67",
+        "rows_examined_per_scan": 1,
+        "rows_produced_per_join": 1,
+        "filtered": "100.00",
+        "cost_info": {
+          "read_cost": "0.61",
+          "eval_cost": "0.10",
+          "prefix_cost": "0.71",
+          "data_read_per_join": "936"
+        },
+        "used_columns": [
+          "id",
+          "trigger_rule_codes",
+          "cast(`trigger_rule_codes` as char(16) array)"
+        ],
+        "attached_condition": "json_contains(cast(`trigger_rule_codes` as char(16) array),json'[\"RW-018\"]')"
+      }
+    }
+  }
+}
@@ -0,0 +1,138 @@
+"""只读探查：`fin_risk_alert.trigger_rule_codes` 能否用 JSON 多值索引（docs/25 P3 #21）。
+
+只做 SELECT / EXPLAIN，不做任何写入。结果写成 JSON 便于在 GBK 控制台下查看：
+
+    python tools/probe_risk_index.py
+
+排查点：
+1. MySQL 版本是否 ≥ 8.0.17（多值索引的下限）；
+2. 列是否确实是 JSON、是否已存在同类索引；
+3. 是否存在**非数组**取值 —— 有的话 `CAST(... AS CHAR ARRAY)` 建索引会直接失败；
+4. 当前 `JSON_CONTAINS` 查询走的是什么访问路径（有没有可用的 key）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import text
+
+from app.infrastructure.db import SessionFactory
+
+OUTPUT = Path("docs/evidence/risk-index-probe.json")
+
+
+async def collect() -> dict[str, Any]:
+    report: dict[str, Any] = {}
+    async with SessionFactory() as session:
+        report["mysql_version"] = (
+            await session.execute(text("SELECT VERSION()"))
+        ).scalar_one()
+
+        report["column"] = [
+            dict(row)
+            for row in (
+                (
+                    await session.execute(
+                        text(
+                            """
+                            SELECT COLUMN_NAME, COLUMN_TYPE, DATA_TYPE, IS_NULLABLE
+                            FROM information_schema.COLUMNS
+                            WHERE TABLE_SCHEMA = DATABASE()
+                              AND TABLE_NAME = 'fin_risk_alert'
+                              AND COLUMN_NAME = 'trigger_rule_codes'
+                            """
+                        )
+                    )
+                )
+                .mappings()
+                .all()
+            )
+        ]
+
+        report["indexes"] = [
+            dict(row)
+            for row in (
+                (
+                    await session.execute(
+                        text(
+                            """
+                            SELECT INDEX_NAME, COLUMN_NAME, INDEX_TYPE, EXPRESSION
+                            FROM information_schema.STATISTICS
+                            WHERE TABLE_SCHEMA = DATABASE()
+                              AND TABLE_NAME = 'fin_risk_alert'
+                            ORDER BY INDEX_NAME, SEQ_IN_INDEX
+                            """
+                        )
+                    )
+                )
+                .mappings()
+                .all()
+            )
+        ]
+
+        report["row_count"] = (
+            await session.execute(text("SELECT COUNT(*) FROM fin_risk_alert"))
+        ).scalar_one()
+        report["non_array_rows"] = (
+            await session.execute(
+                text(
+                    "SELECT COUNT(*) FROM fin_risk_alert "
+                    "WHERE trigger_rule_codes IS NULL "
+                    "   OR JSON_TYPE(trigger_rule_codes) <> 'ARRAY'"
+                )
+            )
+        ).scalar_one()
+        report["distinct_rule_codes"] = [
+            dict(row)
+            for row in (
+                (
+                    await session.execute(
+                        text(
+                            """
+                            SELECT CAST(trigger_rule_codes AS CHAR) AS raw_codes,
+                                   COUNT(*) AS rows_count
+                            FROM fin_risk_alert
+                            GROUP BY 1
+                            """
+                        )
+                    )
+                )
+                .mappings()
+                .all()
+            )
+        ]
+
+        # 用 FORMAT=JSON：传统 EXPLAIN 会把"该查询无法被缓存"写成 warning 打到 stderr，
+        # 让脚本在 CI 里看起来是失败的，而它其实成功了。
+        raw_explain = (
+            await session.execute(
+                text(
+                    """
+                    EXPLAIN FORMAT=JSON
+                    SELECT id FROM fin_risk_alert
+                    WHERE JSON_CONTAINS(trigger_rule_codes, '"RW-018"')
+                    """
+                )
+            )
+        ).scalar_one()
+        report["explain_json_contains"] = json.loads(raw_explain)
+
+    return report
+
+
+async def main() -> None:
+    report = await collect()
+    OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    OUTPUT.write_text(
+        json.dumps(report, ensure_ascii=False, indent=2, default=str),
+        encoding="utf-8",
+    )
+    print(f"wrote {OUTPUT}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())