feat: main 集成(路由挂载/trace 中间件/lifespan) + B7 挂账收口(引擎工厂/统一错误体/锁公共化/L3 缓存 DEL/死代码清理/处置原子事务/启动期 debug 校验, B7)

2026-09-06 20:48:50 +08:00
parent a78e9d4d31
commit 6195349dd6
27 changed files with 608 additions and 234 deletions
@@ -38,7 +38,7 @@
 RBAC 联调账号：scripts/dev/rbac-seed-reference.md
 ```

-**尚未自动化：** agent 专用表 SQL、Milvus 建 Collection、JWT 中间件 — 见 `TODO.md`。
+**尚未自动化：** Milvus 建 Collection、JWT 中间件（现 `api/deps.py` debug 头过渡，T-01 就绪换工厂内部）— 见 `TODO.md`；agent 专用表已有 `02-mysql-agent专用.sql`（手工执行，含 risk_aml_list）。

 ------

@@ -48,7 +48,7 @@ RBAC 联调账号：scripts/dev/rbac-seed-reference.md
 Client → Gateway(JWT/RBAC) → api/chat → agent_service(LangGraph) → Tools → 存储 → 响应 + audit_log
 ```

-当前：`main.py` 仅 health；全链路待 Wave 0 起逐步挂载。
+当前：**风控事件线已集成**（交易网关 → 规则引擎 → 预警/AML/L3 → 4 API，`main.py` 路由挂载 + trace 中间件 + lifespan 完成，B1~B7，180 测试绿）；对话链路待 T-01/T-07。

 ------

@@ -34,13 +34,13 @@

 | 模块 | 职责 | 依赖 | 代码状态 |
 | --- | --- | --- | --- |
-| Agent Gateway / Auth SDK | JWT、RBAC、归属校验 | Redis、MySQL customer_advisor_rel | **未做**（见 JWT 手册） |
+| Agent Gateway / Auth SDK | JWT、RBAC、归属校验 | Redis、MySQL customer_advisor_rel | **过渡版已实现**（`api/deps.py` debug 头 AuthContext + 归属断言 + 越权审计，B6；JWT 解析归 T-01，仅换工厂内部） |
 | 客户财富 Agent | L1 画像、事实查询、阈值提醒 | Core RO、Milvus 产品库 | 空壳 service |
 | 代理人助手 Agent | L2 画像、RAG、草稿 | L1 只读、Milvus | 空壳 service |
 | 数据分析 Agent | NL→SQL→解读 | Core RO、画像只读 | 空壳 service |
-| 风控监测 Agent | 预警、L3、R-02 适当性 | 交易事件、AML 名单 | 空壳 service |
-| Core 只读层 | L0 事实查询 | `jinrong_core` | **core_ro.py 已实现** |
-| 共用底座 | 会话、审计、输入防护 | MySQL 11 表 + Redis | SQL 已定；代码未接 |
+| 风控监测 Agent | 预警、L3、R-02 适当性 | 交易事件、AML 名单 | **已实现**（B1~B7：rules/alert_service/profile_l3/aml_service/engine/scoring 占位 + 4 API + suitability + main 集成与挂账①~⑦） |
+| Core 只读层 | L0 事实查询 | `jinrong_core` | **core_ro.py 已实现**（含风控扩展查询） |
+| 共用底座 | 会话、审计、输入防护 | MySQL 11 表 + Redis | **部分接入**（风控审计落库 / Redis 推送已接；会话、全量审计中间件、输入防护待 T-02/T-03） |
 | 同步脚本 | 归属、Neo4j | Core → agent / 图库 | **sync_*.py 已实现** |

 ------
@@ -48,15 +48,16 @@
 ## 3. 后端分层（app/）

 ```text
-api/          → 路由（chat、knowledge、admin）；薄，不含业务          【空壳】
-service/      → agent_service、rag_service、memory_service、risk/*   【空壳】
-tool/         → document_parser、embedding_tool、milvus_tool          【空壳】
-repository/   → core_ro（Core 只读）；后续 agent 库 Repository       【core_ro 已实现】
-gateway/      → 模拟交易网关（外部 Core 交易系统替身，非 Agent 分层）【PRD v1.0 新增】
-model/        → schemas（Pydantic）、entities（ORM）                  【占位】
-config/       → settings、database                                     【settings 已实现】
-utils/        → response、exceptions、logger                           【占位】
-main.py       → FastAPI 入口；当前仅 /health                          【部分】
+api/          → 风控 risk / simulate / deps 已实现（main 已挂载）；chat、knowledge、admin 空壳【部分】
+service/      → risk/*（rules/alert/aml/engine/l3/scoring/locks/redis_gateway）+ suitability 已实现；
+                agent_service、rag_service、memory_service 空壳                          【部分】
+tool/         → document_parser、embedding_tool、milvus_tool                              【空壳】
+repository/   → core_ro（Core 只读）+ risk_repository（风控四表）                         【已实现】
+gateway/      → 模拟交易网关（trade_gateway + gateway_repository 仅 INSERT core_trade）   【已实现 B5】
+model/        → schemas（Pydantic）、entities（ORM）                                      【占位】（风控暂用 dict，收敛待后续）
+config/       → settings（双库 + risk_* 阈值）、database                                  【settings 已实现】
+utils/        → trace / desensitize / db（引擎工厂）/ response（统一错误体）/ exceptions   【基本就绪；logger 占位】
+main.py       → 路由挂载 + trace 中间件 + lifespan（B7）                                  【已集成】

 允许：api → service → tool / repository / model / config
 禁止：api 直连 Milvus/MySQL 写复杂逻辑；tool 写业务流程；repository 写 Core
@@ -9,20 +9,28 @@

 **项目是什么：** 金融四 Agent（客户财富 / 代理人 / 数据分析 / 风控）共用数据层与合规底座；**不**互调 LLM，跨 Agent 走 L1/L2/L3 画像与预警表。

-**当前进度：** 需求与表设计已定 · 后端 **脚手架 + Core 模拟库脚本** 已落地 · **业务 API / JWT / LangGraph 图尚未实现**（多为空壳模块）。
+**当前进度：** 需求与表设计已定 · **风控模块已落地 B1~B7**（规则/预警聚合/L3/AML/引擎/交易网关/鉴权+4 API/适当性校验/**main 集成+挂账①~⑦**，**180 测试绿**）· 剩 **B8 conftest+集成测试 → B9a 脚本 → B9b 演示走查** · **JWT(T-01) / 审计中间件(T-02) / LangGraph 对话线(T-07) 未做**（chat/knowledge/admin 仍空壳）。

 **仓库地图：**

 | 路径 | 状态 | 说明 |
 | --- | --- | --- |
-| `app/main.py` | 可跑 | 仅 `/health`；路由未挂载 |
-| `app/api/*.py` | 空壳 | chat / knowledge / admin 待实现 |
-| `app/service/*.py` | 空壳 | agent / rag / memory 待实现 |
-| `app/repository/core_ro.py` | **已实现** | Core 只读 SELECT（jinrong_core） |
-| `app/config/settings.py` | **已实现** | 双库 `jinrong_agent` + `jinrong_core` |
+| `app/main.py` | **已集成** | 路由挂载 + trace 中间件（X-Trace-Id 贯通）+ lifespan（启动期 debug 校验 · Redis 网关注册 · 引擎 dispose，B7） |
+| `app/api/risk.py` `simulate.py` `deps.py` | **已实现** | 风控 4 API + 模拟网关路由 + debug 头 AuthContext（T-01 过渡版，JWT 就绪只换工厂内部） |
+| `app/api/chat.py` `knowledge.py` `admin.py` | 空壳 | 待 T-06 / T-07 |
+| `app/service/risk/*` + `service/suitability.py` | **已实现** | RISK-001~005 规则 / 预警聚合 / L3 写入 / AML / 引擎编排 / SUIT-001~008 / locks+redis_gateway 公共原语（B7） |
+| `app/service/agent_service.py` 等 | 空壳 | LangGraph 对话线待 T-07 |
+| `app/gateway/` | **已实现** | 模拟交易网关（仅 gateway_repository 可 INSERT core_trade，B5） |
+| `app/repository/core_ro.py` | **已实现** | Core 只读 SELECT（含风控扩展 sum_trades_on_date / list_trades_range / list_active_customers） |
+| `app/repository/risk_repository.py` | **已实现** | risk_alert / risk_suitability_log / L3 / risk_aml_list 读写 |
+| `app/utils/` | **基本就绪** | trace / desensitize / db（引擎工厂）/ response（统一错误体）/ exceptions（含 ApiError）已实现；logger 占位 |
+| `app/config/settings.py` | **已实现** | 双库 `jinrong_agent` + `jinrong_core` + risk_* 阈值 |
 | `scripts/core/*.sql` + `reset.ps1` | **已实现** | Core 模拟库 DDL + 种子 |
+| `scripts/agent/` `scripts/demo/` | **已实现** | AML 名单种子 + 风控演示数据 |
 | `scripts/sync/*.py` | **已实现** | 归属同步 + Neo4j 全图 |
+| `tests/` | **已实现** | 13 个测试文件 173 用例（sqlite 隔离） |
 | `docs/需求拆解/` | 已定 | 场景 P0、矩阵、合规原文 |
+| `docs/PRD/PRD-风控监测Agent.md` | **已冻结** | 风控 PRD v1.0 + 规则表附录 |
 | `docs/项目框架设计/表设计/` | 已定 | Agent 共用 11 表 + agent 专用 SQL |
 | `docs/项目框架设计/Core模拟底座/` | 已定 | 无真实 Core 时的 L0 方案 |
 | `web/` | **不存在** | 前端 React 待 init |
@@ -39,7 +47,7 @@
 7. uvicorn app.main:app --reload     # GET /health
 ```

-**下一步开发（见 TODO）：** T-01 JWT 中间件 → 挂载 api → LangGraph agent_service → Wave 0 验收。
+**下一步开发（见 TODO）：** 风控 B8 conftest+集成测试（A-1~A-5/A-7~A-9 + trace 一致性 + sqlite DDL 收敛）→ B9a 演示/运维脚本 → B9b 演示走查；随后 Wave 0 T-01 JWT / T-02 审计中间件 / T-06 / T-07 LangGraph。

 **禁止（改代码前必记）：** Core 正式 C1~C5 不可被画像覆盖 · 审计表只 INSERT · 代理人草稿不外发 · 仅 R-02 可阻断交易 · 四 Agent 不互调 LLM。

@@ -48,8 +56,8 @@
 ## 1. 项目简介

 - **名称：** JinRong 金融四 Agent 智能管家
- **当前阶段：** MVP 脚手架期（设计已定，Wave 0 开发中）
- **当前优先级：** Wave 0 共用底座 → Wave 1 代理人/分析闭环
+- **当前阶段：** 风控模块（Wave 2 提前开发）B7~B9 收尾中；Wave 0 底座被风控借道部分落地
+- **当前优先级：** 风控 B7/B8/B9 → Wave 0（T-01/T-02/T-06/T-07）→ Wave 1

 ------

@@ -107,10 +115,12 @@ audit_log 等审计表（只 INSERT）

 ```text
 后端入口：app/main.py · 配置 app/config/settings.py · Core 只读 app/repository/core_ro.py
-Agent 库 SQL：docs/项目框架设计/表设计/01-mysql-共用底座.sql
+Agent 库 SQL：docs/项目框架设计/表设计/01-mysql-共用底座.sql · 02-mysql-agent专用.sql（含 risk_aml_list）
 Core 模拟：scripts/core/reset.ps1 · 文档 docs/项目框架设计/Core模拟底座/
+种子：scripts/agent/seed-aml-list.sql（AML 名单）· scripts/demo/prepare_risk_demo.sql（reset 后重跑）
 依赖：requirements.txt（LangGraph + langchain-core/openai + FastAPI + SQLAlchemy）
 启动：uvicorn app.main:app --reload → GET /health
+测试：python -m pytest（173 用例，sqlite 隔离）
 配置：.env（见 .env.example）
 RBAC 联调账号：scripts/dev/rbac-seed-reference.md
 ```
@@ -17,14 +17,16 @@

 | ID | 需求 | 验收对照 | 状态 | TODO |
 | --- | --- | --- | --- | --- |
-| F-01 | JWT + RBAC + 数据归属 | 越权 403 + audit；JWT 手册 §13 | 未做 | T-01 |
-| F-02 | 全量审计留痕 | trace_id 可还原 | 未做 | T-02 |
-| F-03 | 输入防护 | input_guard_log | 未做 | T-03 |
-| F-04 | Core 只读层 | 不改 Core 账；Repository 只 SELECT | **部分** | T-04 |
+| F-01 | JWT + RBAC + 数据归属 | 越权 403 + audit；JWT 手册 §13 | **部分**（deps.py debug 头 AuthContext + 归属断言 + 越权审计已落地，B6；JWT 解析待 T-01） | T-01 |
+| F-02 | 全量审计留痕 | trace_id 可还原 | **部分**（utils/trace 贯通 + 风控审计 INSERT 已接；全量审计中间件待 T-02） | T-02 |
+| F-03 | 输入防护 | input_guard_log | 未做（双写缺口挂账 B7 接 T-02 时统一补） | T-03 |
+| F-04 | Core 只读层 | 不改 Core 账；Repository 只 SELECT | **部分**（core_ro 已扩展风控查询；接入 api/service Tool 与归属校验待 T-04） | T-04 |
 | R0-DB | MySQL 共用 11 表 + Redis | 01-mysql-共用底座.sql | SQL 已定；灌库待验 | T-05 |
 | R0-CORE | Core 模拟 + 同步 | reset.ps1 + sync 脚本 | **脚本已落地** | T-05 |

-**F-04 部分完成说明：** `app/repository/core_ro.py` + `scripts/core/*` + `settings.mysql_core_database` 已有；尚未接入 api/service Tool 与归属校验。
+**F-01 部分完成说明：** B6 已落地 `app/api/deps.py`（AuthContext Pydantic + `get_auth_context()` 工厂，dev 从 `X-Debug-Role`/`X-Debug-Actor` 头构造；T-01 就绪后仅替换工厂内部为 JWT 解析）。
+
+**F-04 部分完成说明：** `app/repository/core_ro.py`（含风控扩展 sum_trades_on_date / list_trades_range / list_active_customers）+ `scripts/core/*` + `settings.mysql_core_database` 已有；尚未接入对话 Tool 与归属校验。

 ## Wave 1 · 内部 Agent P0

@@ -39,11 +41,11 @@

 | ID | 需求 | 验收对照 | 状态 | TODO |
 | --- | --- | --- | --- | --- |
-| R-01 | 大额预警 | risk_alert pending_review | 未做 | T-30 |
-| R-02 | 适当性阻断请求 | 唯一阻断场景 | 未做 | T-31 |
-| R-03 | AML 命中通知 | 不自动冻户 | 未做 | T-32 |
-| R-04 | 频繁/试探模式预警 | 聚合出单 + 去重 | 未做 | T-30 |
-| R-05 | L3 画像写入 | 最小写入（最高档合并） | 未做 | T-30 |
+| R-01 | 大额预警 | risk_alert pending_review | **已实现**（B1~B6，A-1/A-2 用例绿） | T-30 |
+| R-02 | 适当性阻断请求 | 唯一阻断场景 | **已实现**（suitability SUIT-001~008 + check API 带鉴权 + 网关阻断，B5/B6；MySQL 手工 SQL 对照挂账 B9b） | T-31 |
+| R-03 | AML 命中通知 | 不自动冻户 | **已实现**（aml_service + scan API + L3 联动；对话通知线待 T-32 阶段 C） | T-32 |
+| R-04 | 频繁/试探模式预警 | 聚合出单 + 去重 | **已实现**（B1 规则 + B2 聚合去重） | T-30 |
+| R-05 | L3 画像写入 | 最小写入（最高档合并） | **已实现**（profile_l3 防降级；`risk_score` 一期保持 NULL 归评分模型首写） | T-30 |

 ## Wave 3 · 客户 P0

@@ -20,7 +20,7 @@

 ### 风控模块（PRD v1.0 已冻结 · `docs/PRD/PRD-风控监测Agent.md`，事件驱动线不依赖 T-07 可先行）

- [ ] T-30 风控事件线：`app/gateway/` 交易网关 + `service/risk/` 规则引擎（RISK-001~005）+ 预警单聚合 + L3 最小写入 + `risk:pub:alert` 推送 + AML（含 `risk_aml_list` 种子）+ 演示数据脚本验收 A-1~A-5/A-9 —— **进度（2026-09-06）：B1 规则纯函数 / B2 预警服务 / B3 L3 写入（risk_score 一期不写）/ B4 AML+引擎编排 / B5 交易网关 / B6 鉴权+4 API+处置编排（含独立 AI 复审通过：P0/P1=0，P2 测试隔离已修，agent_type 口径等 P3 已修或挂账 B7/B9b，173 测试绿）均已完成并经独立 AI 评审闭环；剩 B7 main 集成、B8 conftest+集成测试、B9a 脚本、B9b 演示走查**
+- [ ] T-30 风控事件线：`app/gateway/` 交易网关 + `service/risk/` 规则引擎（RISK-001~005）+ 预警单聚合 + L3 最小写入 + `risk:pub:alert` 推送 + AML（含 `risk_aml_list` 种子）+ 演示数据脚本验收 A-1~A-5/A-9 —— **进度（2026-09-06）：B1 规则纯函数 / B2 预警服务 / B3 L3 写入（risk_score 一期不写）/ B4 AML+引擎编排 / B5 交易网关 / B6 鉴权+4 API+处置编排 / B7 main 集成（路由挂载 + trace 中间件 + lifespan 启动期 debug 校验；挂账①锁公共化 ②L3 缓存 DEL ③死代码 ④统一错误体 ⑤启动校验 ⑥引擎工厂 ⑦处置原子事务均落地；⑧ input_guard_log 双写仍随 T-02）均完成并经独立 AI 评审闭环（180 测试绿）；剩 B8 conftest+集成测试、B9a 脚本、B9b 演示走查**
 - [ ] T-31 `service/suitability.py` 公共校验（SUIT-001~008）+ `POST /api/risk/suitability/check` + 单测验收 A-8 —— **代码已完成（A1~A4 · 77 测试绿；B6 起该 API 带鉴权+直调审计）；MySQL 手工 SQL 对照挂账至 B9b 执行（阶段 A 评审 P2-8）**
 - [ ] T-32 预警台账与人工处置 API（`GET /alerts`、`POST /handle`，risk_officer/compliance 权限）+ 对话线（依赖 T-01/T-03/T-07）验收 A-6/A-7 —— **API 部分已由 B6 覆盖并复审通过（A-7/A-9 用例绿）；对话线仍依赖 T-01/T-03/T-07**