xinghuo/group_xinghuo_jinrong
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs: 记录架构改进 T-101~T-202 完成（pytest 510 绿，待合并）

Browse Source 
- README 新增「架构改进与稳定性加固」小节 + 503→510 计数
- MEMORY §0/§1/§4/§7 同步 510 绿与分支状态 + locks 双层锁说明
- TODO 已完成区补 T-101~T-202 合并提示（零接口/表变更）
This commit is contained in:
GaoYiYuan_0626
2026-09-09 18:30:44 +08:00
parent 7230d80477
commit f733fc2305
3 changed files with 30 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+22 -2
View File
@@ -15,7 +15,7 @@
## 模块交付状态（截至 2026-09-08）
**后端功能全部完成，全量 pytest 503 passed 0 failed（sqlite + 真 MySQL 集成），核心接口实调验收通过。**
**后端功能全部完成，全量 pytest 510 passed 0 failed（sqlite + 真 MySQL 集成），核心接口实调验收通过。**
| 里程碑 tag | 内容 |
| --- | --- |
@@ -30,6 +30,26 @@
**架构定位**：风控 Agent 为**独立封装模块**——模块内自带鉴权（`app/api/deps.py` + `app/service/auth_service.py`）、防护、trace、引擎工厂；与宿主的耦合只走 4 个接缝（挂载点 / AuthContext / settings / 引擎工厂），由 `tests/test_module_boundary.py` 防呆锁定。详见《[风控Agent模块边界与合并接缝标注.md](docs/项目框架设计/风控Agent模块边界与合并接缝标注.md)》。
## 架构改进与稳定性加固（合并前已完成，待合并）
> **执行于 2026-09-09，分支 `risk-control-agent` 本地已完成、待用户目视验收后 push。** 全量 pytest **510 passed 0 failed**（较 503 基线 +7：T-201.3 双层锁 6 例 + T-202 trace 顺序守卫 1 例）。所有改动均为**文档与告警/锁原语修正，未动业务接口契约与表结构**，合并 main 时无冲突面新增。
| 任务 | 内容 | 落点 |
| --- | --- | --- |
| T-101 | 输入防护注入词表补齐至 **45 条** | `app/service/input_guard.py`（纯函数检测） |
| T-102 | 风控只读 Tool 补 `query_overdue_alerts`，共 **5 个只读 Tool**（RISK_TOOL_REGISTRY） | `app/service/risk/chat_tools.py` |
| T-103 | agent 专用 SQL 注释表数 5→**6 张** | `docs/项目框架设计/表设计/02-mysql-agent专用.sql` |
| T-104 | 架构设计补 `scoring.py` 桩说明（一期 `NotImplementedError`、L3 risk_score 恒 NULL） | `docs/项目框架设计/架构设计-风控模块.md` §2 |
| T-105 | 架构设计补 `locks.py` 进程内锁说明（多实例失效，T-201 已升级双层） | `docs/项目框架设计/架构设计-风控模块.md` §5.2 |
| T-106 | 架构设计新增 §5.8 三项设计遗留（G1 X-Trace-Id 白名单 / G2 uuid4 概率唯一 / G3 admin·knowledge 空壳非 RAG 缺失） | `docs/项目框架设计/架构设计-风控模块.md` §5.8 |
| T-107 | 启动期缺 `DEEPSEEK_API_KEY` 显式告警（对话走降级前缀） | `app/main.py` lifespan |
| T-108 | 鉴权拒绝留痕补 4 字段（code/agent/actor/trace_id） | `app/utils/authz.py` |
| T-109 | 审计中间件降级日志补 status/path/request_id | `app/api/audit_middleware.py` |
| T-201 | **Redis 双层分布式锁**：`acquire_lock` / `release_lock`（Lua 仅删己锁）+ `run_locked` 三降级（获取→持锁执行；超时→无锁执行；不可用/异常→进程内锁兜底，永不抛） | `app/service/risk/redis_gateway.py` + `app/service/risk/locks.py` |
| T-202 | 审计中间件运行于 trace 中间件**内层**的顺序守卫测试（交换顺序即红） | `tests/test_audit_middleware.py` |
**接手合并须知**：本批改动已在分支 `risk-control-agent` 本地提交（HEAD 领先 origin/risk-control-agent 4 个提交，推送被中断、尚未 push）。合并 main 前**无需**处理新冲突——仅文档与告警/锁原语，接口契约与表结构零变更。详见《docs/项目框架设计/合并注意事项-风控模块并入main.md》与本页「模块交付状态」里程碑表。
## 铁律（改码前必记）
- Core 正式 C1~C5 不可被画像覆盖；Core 库只读（仅模拟交易网关可 INSERT core_trade）
@@ -72,7 +92,7 @@ cp .env.example .env # 填 MYSQL_PASSWORD / NEO4J_PASSWORD / DEEPSEEK_A
pip install -r requirements.txt
# 首次灌库与同步：见 docs/memory/FLOW.md §0（权威步骤）
uvicorn app.main:app --reload # → GET http://127.0.0.1:8000/health
python -m pytest # 基线 503 用例（系统 Python）
python -m pytest # 基线 510 用例（系统 Python）
```
**演示库重灌（走查/集成测试前必做，两步缺一不可）**：
docs/memory/MEMORY.md
+7 -7
View File
@@ -9,7 +9,7 @@
**项目是什么：** 金融四 Agent（客户财富 / 代理人 / 数据分析 / 风控）共用数据层与合规底座；**不**互调 LLM，跨 Agent 走 L1/L2/L3 画像与预警表。
**当前进度：** 需求与表设计已定 · **风控模块 B1~B9b 全部完成（M2 tag risk-m2），M4 复核已闭环（2026-09-07），风控阶段 B 正式完结** · **Wave 0 已完成（2026-09-07，经独立 AI 评审闭环）**：T-01 JWT 鉴权（auth_service Auth SDK + deps 工厂替换 + X-Agent-Type 准入矩阵）/ T-02 审计中间件（http_access + 独立 request_id + 4xx/500 统一错误体 + input_guard_log 双写）/ T-06 chat 最小闭环（POST /api/chat + 会话落库 + Redis 窗口）/ T-07 LangGraph StateGraph 骨架 + DeepSeek（无 key 降级）· **T-04 Core RO Tool 节点已完成（2026-09-07）**：app/tool/core_tools.py 三只读 Tool + tool_service（意图/归属校验/run_tool）+ 图 tool 节点 + agent_tool_call 落库 + `utils/authz.py` 公共鉴权留痕，**321 测试绿（首评+复审双闭环）**。风控阶段 C 已完成（2026-09-07，345 绿，tag `risk-m3`，A-6 对话线验收通过，独立 AI 评审 PASS P0=0）。T-03 输入防护已完成（2026-09-07，378 绿，独立 AI 评审 PASS with findings P0=0）：app/service/input_guard.py 注入词表 45 条纯函数检测 + oversize 4000 + actor 级 Redis 固定窗口限流 30 次/分（fail-open）；chat 链路顺序 = 鉴权→准入→空白→限流 429→注入/超长 400→归属→会话，被拒 fail-fast 不建会话，blocked 落 input_guard_log（ENUM 四值已用满）。**阶段一「对齐 main 基准」AL-01~AL-08 已完成（2026-09-07，逐项独立 commit bb244f4~b5fd52e）：适当性判定换核为 main 的 core_ro.check_suitability（C×R 矩阵表数据驱动，match_result 五值/JR-AST-012/FM-01/FM-03/JR-AST-PRO 契约，SUIT-001~008 退役）；risk_suitability_log 重建 21 列；Core 表加 is_hnw/风评七新列（expires_at）；种子 33 客户/14 产品；全量 406 passed 0 failed 0 skipped + uvicorn 冒烟三端点通过；risk-m1 已补打（指向 3c07de6）**。**下一步：阶段一验收门（**合并 main 前的最终交付检查点，非分支开发阻塞**；用户浏览器目视确认 UI）→ AL-09 合并 main → AL-10 PRD v1.2 → AL-11 docx 登记 → 阶段二 C4~C6（**已完成并打 `risk-m4` tag**）/ 前端 React 多 Agent 入口（HashRouter `web/` init）。****开发在分支 `risk-control-agent`（与 origin/main 已分叉：领先 84 提交 / 落后 0，origin/main 为分支祖先；**分支已推送远程，origin/risk-control-agent 同步于 `1d00e53`，本地跟踪已建立**；旧文档中的 `feature/risk` 为过时口径）。**
**当前进度：** 需求与表设计已定 · **风控模块 B1~B9b 全部完成（M2 tag risk-m2），M4 复核已闭环（2026-09-07），风控阶段 B 正式完结** · **Wave 0 已完成（2026-09-07，经独立 AI 评审闭环）**：T-01 JWT 鉴权（auth_service Auth SDK + deps 工厂替换 + X-Agent-Type 准入矩阵）/ T-02 审计中间件（http_access + 独立 request_id + 4xx/500 统一错误体 + input_guard_log 双写）/ T-06 chat 最小闭环（POST /api/chat + 会话落库 + Redis 窗口）/ T-07 LangGraph StateGraph 骨架 + DeepSeek（无 key 降级）· **T-04 Core RO Tool 节点已完成（2026-09-07）**：app/tool/core_tools.py 三只读 Tool + tool_service（意图/归属校验/run_tool）+ 图 tool 节点 + agent_tool_call 落库 + `utils/authz.py` 公共鉴权留痕，**321 测试绿（首评+复审双闭环）**。风控阶段 C 已完成（2026-09-07，345 绿，tag `risk-m3`，A-6 对话线验收通过，独立 AI 评审 PASS P0=0）。T-03 输入防护已完成（2026-09-07，378 绿，独立 AI 评审 PASS with findings P0=0）：app/service/input_guard.py 注入词表 45 条纯函数检测 + oversize 4000 + actor 级 Redis 固定窗口限流 30 次/分（fail-open）；chat 链路顺序 = 鉴权→准入→空白→限流 429→注入/超长 400→归属→会话，被拒 fail-fast 不建会话，blocked 落 input_guard_log（ENUM 四值已用满）。**阶段一「对齐 main 基准」AL-01~AL-08 已完成（2026-09-07，逐项独立 commit bb244f4~b5fd52e）：适当性判定换核为 main 的 core_ro.check_suitability（C×R 矩阵表数据驱动，match_result 五值/JR-AST-012/FM-01/FM-03/JR-AST-PRO 契约，SUIT-001~008 退役）；risk_suitability_log 重建 21 列；Core 表加 is_hnw/风评七新列（expires_at）；种子 33 客户/14 产品；全量 406 passed 0 failed 0 skipped + uvicorn 冒烟三端点通过；risk-m1 已补打（指向 3c07de6）**。**下一步：阶段一验收门（**合并 main 前的最终交付检查点，非分支开发阻塞**；用户浏览器目视确认 UI）→ AL-09 合并 main → AL-10 PRD v1.2 → AL-11 docx 登记 → 阶段二 C4~C6（**已完成并打 `risk-m4` tag**）/ 前端 React 多 Agent 入口（HashRouter `web/` init）。****开发在分支 `risk-control-agent`（与 origin/main 已分叉：领先 84 提交 / 落后 0，origin/main 为分支祖先；**分支已推送远程，origin/risk-control-agent 同步于 `1d00e53`，本地跟踪已建立**；**架构改进与稳定性加固 T-101~T-202 已于 2026-09-09 在本分支本地完成（pytest 510 绿，较 503 基线 +7 例：T-201.3 双层锁 6 例 + T-202 trace 顺序守卫 1 例），含 Redis 双层分布式锁 T-201 与审计中间件 trace 顺序守卫 T-202，均为文档/告警/锁原语修正、接口契约与表结构零变更，待用户目视验收后 push（当前本地 HEAD 领先 origin 4 个提交）。** 旧文档中的 `feature/risk` 为过时口径）。**
**仓库地图：**
@@ -22,7 +22,7 @@
| `app/service/embedding.py` `milvus_service.py` `rag_service.py` | **已实现（T21-1/2/4）** | Ollama bge-m3 1024 维（失败不静默降级）/ kb_product_rules 建集合+upsert+合规过滤检索 / search_knowledge→chunks+source_refs 溯源 |
| `app/tool/kb_tools.py` | **已实现（T21-5）** | search_knowledge 对话 Tool（skip_access_check 公开知识；仅 customer/advisor 意图开放，risk 不开放）；kb_product_rules 首批 24 块已入库（data/kb 6 产品手册，scripts/kb/build_kb.py 可重灌） |
| `app/service/auth_service.py` | **已实现（T-01）** | Auth SDK：JWT 验签（HS256 dev/RS256 生产）、必填 claims、jti 吊销（Redis fail-open）；签发 CLI `scripts/dev/issue_dev_token.py` |
| `app/service/risk/*` + `service/suitability.py` | **已实现** | RISK-001~005 规则 / 预警聚合 / L3 写入 / AML / 引擎编排 / suitability（**阶段一换核：内核改调 core_ro.check_suitability，SUIT-001~008 已退役**）/ locks+redis_gateway 公共原语（B7） |
| `app/service/risk/*` + `service/suitability.py` | **已实现** | RISK-001~005 规则 / 预警聚合 / L3 写入 / AML / 引擎编排 / suitability（**阶段一换核：内核改调 core_ro.check_suitability，SUIT-001~008 已退役**）/ locks+redis_gateway 公共原语（B7；**T-201 升级为 Redis 双层分布式锁：acquire_lock/release_lock（Lua 仅删己锁）+ run_locked 三降级，多实例安全**） |
| `app/service/agent_service.py` `memory_service.py` | **已实现（T-07/T-06/T-04/C2 + 方案 C）** | LangGraph StateGraph（tool→llm→guard）+ DeepSeek（无 key 降级）；T-04 tool 节点（关键词意图 customer/advisor/risk 分组 + tool_service.run_tool）；C2 tool_node 守卫放宽（requires_customer=False 允许无绑定客户，支撑 A-6 全量待审）；Redis 会话窗口 + MySQL 回源。**方案 C：`stream_chat` 生成器（Tool 同步跑完→逐块推 LLM 文本）+ `needs_disclaimer`（首帧 meta 与落库尾部共用口径）** |
| `app/service/tool_service.py` `app/tool/core_tools.py` `service/risk/chat_tools.py` | **已实现（T-04/C1）** | 对话 Tool 编排（统一注册表 get_registered_tool：core+risk / 归属校验 / agent_tool_call 落库）+ Core RO 三只读 Tool（L0/持仓/流水）+ C1 风控五只读 Tool（query_overdue_alerts/alert_query/customer_context/suitability_check/aml_lookup，RISK_TOOL_REGISTRY） |
| `app/repository/session_repository.py` | **已实现（T-06/T-04 + 前端接入 B/C）** | agent_session / agent_message / agent_tool_call 读写；**方案 B 增 `list_sessions`（分页+total）/ `list_messages_page`（seq 升序分页，勿与 LLM 窗口的 `list_messages` 混用）/ `close_session`（条件更新防并发）**；**方案 C 增 `insert_turn`（user+assistant 同事务落库 + 事务内取 seq，修评审 P0/P1）** |
@@ -34,7 +34,7 @@
| `scripts/core/*.sql` + `reset.ps1` | **已实现** | Core 模拟库 DDL + 种子 |
| `scripts/agent/` `scripts/demo/` `scripts/dev/` | **已实现** | AML 名单种子 + 风控演示数据 + subscribe_alerts/rebuild_alerts + issue_dev_token（JWT 签发） |
| `scripts/sync/*.py` | **已实现** | 归属同步 + Neo4j 全图 |
| `tests/` | **已实现** | 36 个测试模块 503 用例（sqlite 隔离；DDL 单一事实源 `_ddl.py`；`test_integration_risk.py` 走真 MySQL + TRD-TEST- 前缀隔离；pytest 依赖装在系统 Python 3.13.14；阶段一基线 425→406，前端接入 B/C 后 **482→503**）。**改路由必同步 `tests/test_main.py::test_all_routers_mounted` 的路径清单，否则必红** |
| `tests/` | **已实现** | 36 个测试模块 510 用例（sqlite 隔离；DDL 单一事实源 `_ddl.py`；`test_integration_risk.py` 走真 MySQL + TRD-TEST- 前缀隔离；pytest 依赖装在系统 Python 3.13.14；阶段一基线 425→406，前端接入 B/C 后 **482→503**，架构改进 T-201.3+T-202 后 **503→510**）。**改路由必同步 `tests/test_main.py::test_all_routers_mounted` 的路径清单，否则必红** |
| `docs/需求拆解/` | 已定 | 场景 P0、矩阵、合规原文 |
| `docs/PRD/PRD-风控监测Agent.md` | **已冻结（v1.1）** | 风控 PRD v1.0 + v1.1 追加 FR-8/9/10（§4A）+ 规则表附录 |
| `docs/项目框架设计/实现方案-风控追加需求v1.1-C4C6.md` | **已定稿** | C4~C6 编码依据（经独立 AI 评审修订闭环）；分支/进度速览另见项目根 `交接文档.md` |
@@ -60,7 +60,7 @@
> **本机 ①~⑤已执行、`.env` 已配置，勿重做**；本机状态与已知坑（mysql.exe 路径 / reset.ps1 交互式 -p / `redis`、`python-jose` 包漏装已补）见 `FLOW.md` §0 尾注。
> **演示库状态（2026-09-07）**：已按演示 SOP §2 重灌并清理冒烟数据（alerts 0 / AML 8 / 会话 0），pytest 全量可直接跑；**下次演示/走查后再按 SOP §2 重灌**（核查单⑥前置断言会对走查残留显式 fail，属防护行为）。
**前端接入面已交付（2026-09-08，503 绿）**：**方案 B** 会话管理三端点（`GET /api/chat/sessions`、`GET /api/chat/sessions/{id}/messages`、`POST /api/chat/sessions/{id}/close`，commit `8328c24`）+ **方案 C** SSE 流式对话 `POST /api/chat/stream`（OpenAI 兼容 chunk：首帧 meta 带 disclaimer → delta → finish_reason=stop → `[DONE]`，commit `01ec5fc`）。三条硬约束：① 守卫全在返回 StreamingResponse 之前（SSE 一开改不了状态码，401/403/404/409/429/400 仍普通 JSON）；② 整轮一次性落库（`insert_turn` 同事务），断连/异常不落消息；③ risk_manager 在对话线数据面一律 403（PRD 4A.1）。遗留 P2：无心跳帧、断连留空会话、流式 429 未单测。
**前端接入面已交付（2026-09-08，当时 503 绿；现总 510，含 2026-09-09 架构改进 T-201.3+T-202 +7 例）**：**方案 B** 会话管理三端点（`GET /api/chat/sessions`、`GET /api/chat/sessions/{id}/messages`、`POST /api/chat/sessions/{id}/close`，commit `8328c24`）+ **方案 C** SSE 流式对话 `POST /api/chat/stream`（OpenAI 兼容 chunk：首帧 meta 带 disclaimer → delta → finish_reason=stop → `[DONE]`，commit `01ec5fc`）。三条硬约束：① 守卫全在返回 StreamingResponse 之前（SSE 一开改不了状态码，401/403/404/409/429/400 仍普通 JSON）；② 整轮一次性落库（`insert_turn` 同事务），断连/异常不落消息；③ risk_manager 在对话线数据面一律 403（PRD 4A.1）。遗留 P2：无心跳帧、断连留空会话、流式 429 未单测。
**下一步开发（见 TODO）：** **模块侧交付完毕（2026-09-07：全量 pytest 482 绿 + 接口实调验收通过——suitability/check 阻断+放行、simulate/trade 阻断、三条鉴权边界 401/403/403 契约零偏差；`risk-m1~m4` tag 齐）。合并 main 已移交合并执行人，操作手册《docs/项目框架设计/合并注意事项-风控模块并入main.md》（含基底锁定/20 冲突裁决/14 静默文件/三硬伤/合并后必测，实测数据编制）。模块侧开放项：chat 链路 risk_suitability_log.actor_id 落 SYSTEM 待评估 / 前端 React 多 Agent 入口（`web/` 未 init，归属待拍板）。**演示走查按 `docs/项目框架设计/演示SOP-风控模块.md`（debug 头通道仍有效；JWT 通道签发用 `scripts/dev/issue_dev_token.py`；演示库已按 AL-08 expires_at 新口径重灌）。知识库入库：`python scripts/kb/build_kb.py`（先启 Ollama；**Milvus 数据路径必须纯英文**——faiss 不支持中文路径，本机 .env 已配 C:/Users/YUAN/.jinrong/milvus/）。
@@ -81,7 +81,7 @@
## 1. 项目简介
- **名称：** JinRong 金融四 Agent 智能管家
- **当前阶段：** **模块交付完毕（2026-09-07）+ 前端接入面交付（2026-09-08）**——阶段一 AL-01~08 + 阶段二 C4~C6 + 前端接入 B/C 全部完成，**503 绿**，接口实调验收通过（AI 代验），`risk-m1~m4` tag 齐；合并 main 已移交合并执行人（手册：《合并注意事项-风控模块并入main.md》）
- **当前阶段：** **模块交付完毕（2026-09-07）+ 前端接入面交付（2026-09-08）+ 架构改进与稳定性加固（2026-09-09，T-101~T-202）**——阶段一 AL-01~08 + 阶段二 C4~C6 + 前端接入 B/C 全部完成，**510 绿**（较 503 +7 例），接口实调验收通过（AI 代验），`risk-m1~m4` tag 齐；架构改进含 Redis 双层锁 T-201 / trace 顺序守卫 T-202，均为文档·告警·锁原语修正（接口契约与表结构零变更），待用户目视验收后 push；合并 main 已移交合并执行人（手册：《合并注意事项-风控模块并入main.md》）
- **当前优先级：** 前端 React 入口（`web/` init，后端接入面已就绪）/ 模块侧开放项（actor_id 透传评估）；合并进度由合并执行人负责，模块侧不阻塞
------
@@ -145,7 +145,7 @@ 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（503 用例；集成测试需本机演示数据，未灌库时自动 skip）
测试：python -m pytest（510 用例；集成测试需本机演示数据，未灌库时自动 skip）
运维/演示脚本：scripts/demo/subscribe_alerts.py（订阅推送演示）· rebuild_alerts.py TRD-xxx（引擎异常补偿重放）
JWT 联调：python scripts/dev/issue_dev_token.py --sub STAFF-30001 --roles risk_officer（+ Authorization: Bearer + X-Agent-Type）
配置：.env（见 .env.example）
@@ -189,6 +189,6 @@ RBAC 联调账号：scripts/dev/rbac-seed-reference.md
2. 改动属于 api / service / tool / repository 哪一层？
3. 是否需 customer_id 归属与 JWT RBAC？
4. Core 是模拟库只读还是 agent 库读写？
5. 如何验证？（`python -m pytest` 全量（当前 **503 绿**）· uvicorn 启动 + /health · SQL / sync 脚本 · 对照 REQUIREMENTS 验收列）
5. 如何验证？（`python -m pytest` 全量（当前 **510 绿**）· uvicorn 启动 + /health · SQL / sync 脚本 · 对照 REQUIREMENTS 验收列）
大任务：FRAMEWORK/FLOW 与实现状态不符时先更新 memory 再编码（用户确认跳过除外）。
docs/memory/TODO.md
+1
View File
@@ -57,6 +57,7 @@
## 已完成
- [x] 2026-09-07 风控 M2 收尾（M4 复核）：MEMORY/TODO 状态与边界文字对齐（任务映射 T-30/T-31/T-32 口径确认；B7 复审留痕「成功响应不包裹外壳」演进口径维持并登记开发计划 M4 节）——风控阶段 B 正式完结
- [x] 2026-09-09 架构改进与稳定性加固 T-101~T-202（分支 `risk-control-agent` 本地完成、待用户目视验收后 push）：明细见 `docs/项目框架设计/TODO-架构改进.md`（全勾 ✓）；pytest **510 绿**（503+7：T-201.3 双层锁 6 + T-202 trace 顺序守卫 1）。含 Redis 双层分布式锁 T-201（acquire_lock/release_lock + run_locked 三降级，多实例安全）/ 审计中间件 trace 顺序守卫 T-202 / 注入词表 42→45 / 风控只读 Tool 加 query_overdue_alerts 共 5 个 / 架构设计补 §5.8 三项设计遗留（G1 X-Trace-Id 白名单 / G2 uuid4 概率唯一 / G3 admin·knowledge 空壳非 RAG 缺失）。**全部为文档·告警·锁原语修正，接口契约与表结构零变更，合并 main 无新增冲突面**。
- [x] 2026-09-07 T-01 JWT 鉴权（commit 36f476f + 评审闭环 61711cb）：`app/service/auth_service.py` Auth SDK（HS256 dev/RS256 生产、必填 claims 显式校验、jti 吊销 fail-open、RS256/HS256 算法白名单互斥）+ `deps.get_auth_context` 工厂替换（Bearer 全环境优先；debug 头降级 dev 兜底，双闸门=APP_ENV+无 RS256 公钥）+ X-Agent-Type 交叉校验（手册 §4.6/§5.4 AGENT_ACCESS_MATRIX）+ `scripts/dev/issue_dev_token.py` 签发 CLI + lifespan 改验 jwt_ready
- [x] 2026-09-07 T-02 审计中间件（commit 3cec034）：`app/api/audit_middleware.py` http_access 全量访问审计（actor 经 request.state.auth，排障路径/OPTIONS 跳过，写库失败降级）+ 独立 request_id（X-Request-Id 贯通，B7 复审 P3-4）+ 422/404/405/500 统一错误体（500 由 trace 中间件兜底回写 trace 头，B7 复审 P2-2）+ input_guard_log 双写（挂账⑧收口；401 归 platform、四 Agent 入口写 guard）
- [x] 2026-09-07 T-07 LangGraph 骨架（commit fb18c04）：`agent_service` StateGraph（llm→guard）+ DeepSeek/langchain-openai（无 key 降级明确标注）+ 四 Agent 边界 system prompt + customer/risk 免责声明（has_disclaimer）+ 单测 mock LLM 不依赖外网