From e80f5a1b8c28f4d2b628ff114da87616ed92726f Mon Sep 17 00:00:00 2001 From: YUAN Date: Wed, 9 Sep 2026 18:15:08 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E6=9E=B6=E6=9E=84=E6=94=B9=E8=BF=9B):=20?= =?UTF-8?q?=E5=9B=9E=E5=86=99=E6=89=A7=E8=A1=8C=E7=8A=B6=E6=80=81=EF=BC=8C?= =?UTF-8?q?=E7=BA=A0=E6=AD=A3=E6=B5=8B=E8=AF=95=E6=95=B0=E4=B8=BA=E5=AE=9E?= =?UTF-8?q?=E6=B5=8B=20510?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - TODO-架构改进.md：T-101~T-202 全部勾选；用例数由 hy3 记录的 511 纠正为 实测 510（503 基线 + 6 条锁测试 + 1 条中间件顺序守卫）；手工冒烟项保持 未勾选并标注待执行，避免被误读为已验证 - 交接文档-架构改进.md：升 v1.1，新增「当前状态」块（已完成/遗留/改动文件 清单）、§2 状态列、§7.3 勾选、§10 收尾动作；注明《架构设计说明书》存在 两个文件并存（架构设计-风控模块.md 与全量版 架构设计说明书.md），避免改错 - docs/memory/2026-09-09.md：追加 commit 037ce7e 的提交与复核记录 --- docs/memory/2026-09-09.md | 17 +++++++ docs/交接文档-架构改进.md | 81 +++++++++++++++++++++++------- docs/项目框架设计/TODO-架构改进.md | 2 +- 3 files changed, 82 insertions(+), 18 deletions(-) diff --git a/docs/memory/2026-09-09.md b/docs/memory/2026-09-09.md index b0c1390..2edf20d 100644 --- a/docs/memory/2026-09-09.md +++ b/docs/memory/2026-09-09.md @@ -31,3 +31,20 @@ ## 未做（合并后，按约定） - 第 3/4 批（agent_message 唯一索引、限流 EXPIRE、core_ro 只读账号、convert、意图识别、日志基建、权限收拢、model 层、注入词表配置化、R-05 动态评分等）一律未动 + +--- + +## 提交与复核（2026-09-09 21:10） + +**commit `037ce7e`**（分支 `risk-control-agent`，**未 push**）：16 files changed, 2607 insertions(+) + +提交内容：全部流程文档（PRD / 问题清单 / 开发计划 / TODO / 交接文档 / 架构设计说明书）+ 上述代码改动 + 测试。 + +**复核结果**： +- 全量 pytest **510 passed**（实测，系统 Python 3.13.14）。hy3 日志写的 511 有误 —— 实际新增 6 条锁测试 + 1 条守卫 = 7 条，503 + 7 = 510。已回写 TODO 与交接文档 +- 采用 `from app.service.agent_service import _DEGRADED_PREFIX` **函数内延迟导入**，无循环导入 +- `locks.py` 双层实现与开发计划 §4.1.3 冻结设计一致：超时沿用 `fn(locked=False)`、不可用退回进程内锁、绝不抛异常 + +**遗留（需下一个会话做）**： +1. §7.2 七项手工冒烟：清空/恢复 DEEPSEEK_API_KEY 各启动一次、交易阻断+放行、预警聚合、停/启 Redis、**调换装饰器验证守卫变红后恢复** +2. 冒烟完成后报告用户 → 浏览器目视确认 UI → 才允许 push → 打里程碑 tag diff --git a/docs/交接文档-架构改进.md b/docs/交接文档-架构改进.md index c019e48..b9ce948 100644 --- a/docs/交接文档-架构改进.md +++ b/docs/交接文档-架构改进.md @@ -1,9 +1,46 @@ # 交接文档 · 架构改进与稳定性加固（给执行 AI） -> **版本**：2026-09-09 v1.0 +> **版本**：2026-09-09 **v1.1（执行后回写）** > **用途**：**给执行代码改动的 AI（hy3）**。读完本文即可开工，**不需要重读全部代码**。 > **代码基线**：分支 `risk-control-agent`，HEAD `2d0e2fa`，pytest **503 绿** > **本轮已完成的规划**：PRD + 架构设计说明书 + 开发计划 + TODO + 两轮独立审核，**全部已通过审核**。 + +--- + +## ⚡ 当前状态（v1.1，2026-09-09 21:10 更新） + +**第 1、2 批代码已全部落地并提交 `037ce7e`，pytest 实测 510 绿。未 push。** + +| 项 | 状态 | +| --- | --- | +| T-101~T-109（文档勘误 + 标注 + 告警） | ✅ 已完成 | +| T-201.1 / .2 / .3（Redis 双层锁 + 测试） | ✅ 已完成 | +| T-202（中间件顺序守卫） | ✅ 已完成 | +| 全量 pytest | ✅ **510 passed**（503 基线 + 6 锁测试 + 1 守卫） | +| commit | ✅ `037ce7e`（**未 push**） | +| **手工冒烟（§7.2 七项）** | ❌ **未执行** ← 下一个会话优先做 | +| 第 3、4 批（合并后） | ⏸ 按原计划不动 | + +**下一个会话开工三件事**：① 跑 `python -m pytest -q` 复核 510；② 做 §7.2 七项手工冒烟（尤其"停 Redis"和"调换装饰器验证守卫变红"）；③ 补齐后报告用户，由用户浏览器目视确认再 push。 + +**已改动文件（本次提交）**： + +```text +app/main.py # DEEPSEEK_API_KEY 缺失告警（函数内延迟 import，无循环导入） +app/utils/authz.py # 越权审计失败日志补 trace_id +app/api/audit_middleware.py # 审计失败日志补 status/path/request_id +app/service/risk/redis_gateway.py # +acquire_lock(SET NX EX) / +release_lock(Lua) +app/service/risk/locks.py # run_locked 改双层（Redis 为主、进程内为备） +tests/test_locks_redis.py # 新增 6 条（monkeypatch 假网关，不依赖本机 Redis） +tests/test_audit_middleware.py # +1 条顺序守卫；_http_access 查询加 trace_id 列 +docs/memory/MEMORY.md # A1 42→45 / A2 4→5 +docs/项目框架设计/表设计/02-mysql-agent专用.sql # A3 5→6 +docs/项目框架设计/架构设计-风控模块.md # A4/A5 标注 + §5.8 G1/G2/G3 +``` + +> ⚠️ **注意文件名**：《架构设计说明书》实际落盘为 `docs/项目框架设计/架构设计-风控模块.md`（本次 A4/A5/G1~G3 标注写在这里）；另有全量版 `docs/项目框架设计/架构设计说明书.md`（新增，9 章，40KB）。**两者并存，改标注时别改错文件。** + +--- > **你的任务**：按 TODO 执行代码改动。**只做清单内的事，不做范围外改动。** --- @@ -38,14 +75,14 @@ XingHuo 智能财富管家：金融四 Agent（客户财富 / 代理人 / 数据 ## 2. 你要做的事（范围，严格按此执行） -| 批次 | 原子项 | 内容 | 风险 | -| --- | --- | --- | --- | -| **第 1 批** | A1~A5 | 修 5 处文档口径错误 | 极低（纯文档） | -| | G1~G3 | 补 3 项"非缺陷"设计标注 | 极低（纯文档） | -| | C4 | 无 key 启动告警（加一行日志） | 低 | -| | C3 相关 | 审计降级日志补 trace_id（2 处） | 低 | -| **第 2 批** | **B6** | **Redis 分布式锁（核心改动）** | 中 | -| | B2 | 中间件顺序测试守卫（新增测试） | 低 | +| 批次 | 原子项 | 内容 | 风险 | 状态 | +| --- | --- | --- | --- | --- | +| **第 1 批** | A1~A5 | 修 5 处文档口径错误 | 极低（纯文档） | ✅ | +| | G1~G3 | 补 3 项"非缺陷"设计标注 | 极低（纯文档） | ✅ | +| | C4 | 无 key 启动告警（加一行日志） | 低 | ✅ | +| | C3 相关 | 审计降级日志补 trace_id（2 处） | 低 | ✅ | +| **第 2 批** | **B6** | **Redis 分布式锁（核心改动）** | 中 | ✅ | +| | B2 | 中间件顺序测试守卫（新增测试） | 低 | ✅ | **详细验收标准**：《docs/项目框架设计/TODO-架构改进.md》（逐项可勾选，照着做即可） @@ -185,10 +222,11 @@ python -m pytest -q # 必须全绿，用例数 ≥ 503 ### 7.3 完成判定 -- [ ] FR-01~FR-06 验收标准逐条通过（见 PRD §3） -- [ ] pytest 全绿且 ≥ 503 -- [ ] 未新增配置项、未新增依赖、未改路由 -- [ ] **commit 但不 push**，等用户在浏览器目视确认 +- [x] FR-01~FR-06 验收标准逐条通过（见 PRD §3） +- [x] pytest 全绿且 ≥ 503（**实测 510**） +- [x] 未新增配置项、未新增依赖、未改路由 +- [x] **commit 但不 push**（`037ce7e`），等用户在浏览器目视确认 +- [ ] **§7.2 七项手工冒烟（未执行）** —— 这是目前唯一缺口 --- @@ -227,10 +265,19 @@ python -m pytest -q # 必须全绿，用例数 ≥ 503 ## 10. 完成后 -1. 更新 `docs/项目框架设计/TODO-架构改进.md`：勾选已完成项，标注实际用例数 -2. 更新本交接文档 §2 表格状态（若范围有变） -3. 在 `docs/memory/2026-09-09.md` 追加实施记录（改了哪些文件、测试结果、遇到的问题） -4. **不要 push**，报告给用户等目视确认 +**已完成的回写（v1.1）**： + +1. [x] 更新 `docs/项目框架设计/TODO-架构改进.md`：T-101~T-202 全部勾选，实测用例数改为 **510**（原记录写 511 有误，实际新增 6 锁 + 1 守卫 = 7 条） +2. [x] 更新本交接文档：新增"当前状态"块、§2 状态列、§7.3 勾选 +3. [ ] 在 `docs/memory/2026-09-09.md` 追加实施记录 —— **待补** +4. [x] **未 push**（`037ce7e`），等用户目视确认 + +**下一个会话的收尾动作**： + +1. 跑 `python -m pytest -q` 复核 510 绿 +2. 做 §7.2 七项手工冒烟，逐条在 TODO 里勾选 +3. 把冒烟结果写进 `docs/memory/2026-09-09.md` +4. 报告用户 → **用户在浏览器目视确认 UI 后**才允许 push；push 后打里程碑 tag --- diff --git a/docs/项目框架设计/TODO-架构改进.md b/docs/项目框架设计/TODO-架构改进.md index 5ccbd92..c7b8b40 100644 --- a/docs/项目框架设计/TODO-架构改进.md +++ b/docs/项目框架设计/TODO-架构改进.md @@ -199,7 +199,7 @@ def test_audit_middleware_runs_inside_trace_middleware(client, captured_audit): **验收**： - [x] 正常顺序下测试通过（pytest 510 绿） -- [ ] **临时调换 `main.py` 两个装饰器顺序 → 测试变红**（确认有效，**需手工，未执行**） +- [ ] **临时调换 `main.py` 两个装饰器顺序 → 测试变红**（hy3 日志称已验证变红并恢复；**本次会话未复核**，建议重跑一次确认） - [ ] 恢复顺序 → 转绿 - [x] **不**加 `ensure_trace()` 兜底（未加，顺序错误不会被掩盖）