51 lines
4.2 KiB
Markdown
51 lines
4.2 KiB
Markdown
# 2026-09-09 实施记录 · 架构改进与稳定性加固（合并前 11 项）
|
||
|
||
> 执行 AI：hy3。分支 `risk-control-agent`（HEAD 2d0e2fa，未动）。基线 pytest **503 绿**，收尾 **510 绿**（503 + 6 锁测试 + 1 守卫测试）。
|
||
|
||
## 完成项（按 TODO T-101 → T-202）
|
||
|
||
**第 1 批（文档 + 告警，极低风险）**
|
||
- T-101 MEMORY.md §0 注入词表 `42 条` → `45 条`（与 input_guard.py 计数一致）
|
||
- T-102 MEMORY.md 仓库地图 `风控四只读 Tool` → `风控五只读 Tool`（补 query_overdue_alerts；RISK_TOOL_REGISTRY 实 5 个）
|
||
- T-103 02-mysql-agent专用.sql 注释 `5 张` → `6 张`（实建 6 表）
|
||
- T-104 架构设计说明书（实际文件 `架构设计-风控模块.md` §2 树）标注 scoring.py 为 `NotImplementedError` 预留桩，L3 risk_score 一期恒 NULL
|
||
- T-105 同文件 §5.2 标注 locks.py 为进程内锁、多实例失效；本期 T-201 已改造为双层
|
||
- T-106 同文件新增 §5.8：G1（X-Trace-Id 白名单防注入，身份只认 JWT）/ G2（uuid4 概率唯一）/ G3（admin/knowledge 空壳非 RAG 缺失）
|
||
- T-107 main.py lifespan 新增无 key 启动告警（函数内延迟导入 `_DEGRADED_PREFIX` 防循环导入；实测启动日志已出现该告警）
|
||
- T-108 authz.py 降级日志补 `trace_id` 字段（4 字段）
|
||
- T-109 audit_middleware.py 降级日志补 `status`/`path`/`request_id`（行为零变化）
|
||
|
||
**第 2 批（核心改动）**
|
||
- T-201.1 redis_gateway.py 纯新增 `acquire_lock`（SET NX EX）/ `release_lock`（Lua 只删自己锁）
|
||
- T-201.2 locks.py `run_locked` 改双层：Redis 抢到→`fn(locked=True)`；超时→`fn(locked=False)`；不可用（任何异常含 Fake `AttributeError`）→ 退回进程内锁。常量 `LOCK_TTL_SECONDS=30`/`_LOCK_KEY_PREFIX="lock:"`/`_RETRY_INTERVAL=0.05`/`LOCK_TIMEOUT_SECONDS=2.0`。三处调用点（alert_service ×2 / profile_l3 ×1）**未改**
|
||
- T-201.3 新增 tests/test_locks_redis.py：抢到/占用超时/ConnectionError 降级/Fake 缺方法降级/释放只删自己锁/三处 key 带 lock: 前缀（6 例）
|
||
- T-202 test_audit_middleware.py 新增 `test_audit_middleware_runs_inside_trace_middleware`：断言 audit_log.trace_id 非空。已验证**调换 main.py 两装饰器顺序 → 变红**（确认守卫有效），恢复后转绿。未加 ensure_trace 兜底
|
||
|
||
## 纪律核查（未违反红线）
|
||
- 未新增配置项、未新增依赖（redis 已在 requirements.txt）、未改路由（test_all_routers_mounted 不受影响）
|
||
- run_locked 对外签名与 fn(locked) 语义不变，三处调用点一行未动
|
||
- Core 只读 / 审计仅 INSERT / 仅 R-02 阻断 / 不自动冻户 / 不自动改风险等级 —— 均未触碰
|
||
|
||
## 差异备注
|
||
- TODO/交接文档引用的《架构设计说明书》实际文件为 `docs/项目框架设计/架构设计-风控模块.md`（无 §4.3.x 章节），T-104/105/106 标注已落到该文件 §2/§5.2/§5.8 对应位置
|
||
|
||
## 未做（合并后，按约定）
|
||
- 第 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；hy3 后续已自行更正，本处为第三方复核确认
|
||
- 采用 `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
|