group_xinghuo_jinrong/docs/memory/2026-09-09.md

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