GaoYiYuan_0626 037ce7edca docs(架构改进): 补齐 PRD/开发计划/TODO/交接文档，落地无密钥告警与 Redis 分布式锁 ...

一、流程文档（按 AIcoding 六步落地，供新会话从交接文档开工）
- 新增 docs/PRD/PRD-架构改进与稳定性加固.md：6 条 FR（文档勘误、非缺陷说明、
  无密钥启动告警、审计失败告警、Redis 分布式锁、中间件顺序测试）
- 新增 docs/项目框架设计/改进方案评审-问题清单与对比.md：24 项问题分档 A~G，
  经两轮独立 AI 评审，无阻断级错误
- 新增 docs/项目框架设计/开发计划-架构改进.md：HOW 层设计，含合并前只做低风险
  11 项的批次策略
- 新增 docs/项目框架设计/TODO-架构改进.md：T-101~T-109、T-201~T-202 可勾选项
- 新增 docs/交接文档-架构改进.md：自包含交接入口，hy3 新会话可直接开工
- 新增 docs/项目框架设计/架构设计说明书.md：按模块/分层逐一讲解的全量架构说明

二、代码改动（T-107/108/109、T-201.1、T-201.2）
- app/main.py：启动时 DEEPSEEK_API_KEY 缺失告警，明确告知将走降级回复
- 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 为主、进程内锁为备；
  Redis 超时沿用 fn(locked=False) 降级语义，Redis 不可用（含测试 Fake 缺方法的
  AttributeError）安全退回进程内锁，绝不抛异常

三、文档勘误（A1/A2/A3）
- MEMORY.md：文件数 42→45、Tools 4→5
- 02-mysql-agent专用.sql：会话表 5→6
- 架构设计-风控模块.md：同步更正

四、测试
- 新增 tests/test_locks_redis.py：覆盖抢锁成功、占用超时、Redis 故障降级、
  Fake 缺方法降级、只删自己锁、三处调用点 key 前缀
- tests/test_audit_middleware.py：补充告警字段断言
- 全量 pytest 510 passed（原基线 503）

2026-09-09 18:10:03 +08:00

..

_ddl.py

AL-05: suitability 服务重构换核对齐 main 基准——判定内核由 SUIT-001~008 纯函数矩阵改为 core_ro.check_suitability(C×R 数据驱动)；SuitabilityResult 扩 main 新字段(match_result 五值/mismatch_type 七值/requires_disclosure/needs_branch_confirm/block_response_code/rule_refs)并保留旧字段兼容层(rule_id=机器码别名/effective_level=customer_level/reasons=[reason])；check_core/cap_by_age/match_by_matrix/is_assessment_valid 删除(SUIT-006 被 FM-01 替换,SUIT-008 被 FM-03 expires_at 替换)；settings.risk_assessment_valid_days 退役(.env/.env.example 注释)；NotFoundError 不再抛(not_found 结构化,main 契约)；写库走 build_suitability_log_row + insert_suitability_log 升级 21 列(rule_refs JSON 序列化)；check_source 参数化(网关 r02_trade/risk.py manual)+actor_id 透传；网关阻断响应补 block_response_code；model 抽 compute_rule_refs 公共函数防两处漂移；测试配套：_ddl 加矩阵 25 行种子 helper、conftest fixture 灌种子+集成就位校验改 expires_at 口径、trade_gateway/risk_api fixture 补种子与 expires_at、404 两例改 200+blocked 新契约、repository 21 列断言、settings 退役断言、test_suitability 占位 skip 待 AL-07 重写。sqlite 端到端七语义+落库验证通过；剩 4 failed 均为 chat_tools/API 旧展示断言(AL-06 处理)

2026-09-07 17:34:32 +08:00

conftest.py

feat: C6 FR-10 代理人行为链 RISK-008

2026-09-07 19:53:39 +08:00

test_agent_behavior_service.py

feat: C6 FR-10 代理人行为链 RISK-008

2026-09-07 19:53:39 +08:00

test_agent_service.py

feat: T-07 LangGraph StateGraph 骨架——compose(system 四 Agent 边界 prompt)→llm(DeepSeek/langchain-openai, 无 key 降级)→guard(customer/risk 免责声明+has_disclaimer, 未知类型 fail-safe 最严口径) + chat() 入口 + 图/LLM 单例缓存与测试隔离出口 + tests/test_agent_service 8 例(mock LLM 不依赖外网)

2026-09-07 02:34:57 +08:00

test_alert_service.py

test: B8 收敛——sqlite 测试 DDL 单一事实源 _ddl.py(10 文件 45 处手写 DDL 清零)+localtime 时区收敛(B5 评审 P3-4, utcnow 边界修复)+测试内遗留建表清理, 196 绿; docs 同步 B8 完成状态

2026-09-06 23:37:03 +08:00

test_aml_service.py

fix: B9b 复审闭环——P2-1 SOP 交互重灌补 DROP jinrong_agent(reset.ps1 只重建 core+裸 CREATE TABLE 会 1050 中止); P2-2 补做 T-31 名下 P2-8 手工 SQL 对照收口(4 组合真库 SQL 推导与函数判定一致, 登记 SOP 核查单附行); P2-3 SOP 走查范围与 11/11 口径统一(A-6 归 M3/A-8 映射交代); P3: A-4/A-9 COUNT 当日窗+已处置单幂等用例+suitability/check 阻断响应补 G-08 两要素(advice/notice)+记忆文档数字同步; 留痕 scan_all 幂等读后写无锁取舍; 209 绿

2026-09-07 01:59:15 +08:00

test_audit_middleware.py

docs(架构改进): 补齐 PRD/开发计划/TODO/交接文档，落地无密钥告警与 Redis 分布式锁

2026-09-09 18:10:03 +08:00

test_auth_adapter.py

chore: 风控Agent模块自治边界标注 + AL-09 合并预处置

2026-09-07 18:28:18 +08:00

test_auth_jwt.py

fix: Wave 0 独立 AI 评审闭环(有条件通过→闭环, 273 绿)——P2-1 python-jose>=3.5.0(防 CVE-2024-33663/33664) P2-2 audit 降级+OPTIONS 测试 P2-3 JWT 通道 chat 3 例 P2-4 debug 兜底双闸门(dev+无 RS256 公钥) P2-5 留痕失败降级显式化(401/403 拒绝语义不漂移, _safe_unauth_audit 保护 repo 构造); P3 顺手: 401 归 platform/值域外 400 补留痕/Bearer 大小写不敏感/jti 加 uuid/CLI permissions+exp 上限/dev 默认密钥 warning/LLM 单例加锁/chat 主角色优先序+message strip+guard 日志脱敏/必填 claims 参数化+none 算法固化; P3 登记项(会话枚举/seq_no 锁/trace_id 口径/文档同步)归 M4 文档

2026-09-07 03:03:12 +08:00

test_build_kb.py

feat: T21-3 知识库首批数据+入库脚本——data/kb 6 只种子产品手册(每只 prospectus/fee/rule/risk 四节 24 块, 费率与 core_product seed 对齐)+build_kb.py(front-matter+节标题切块/doc_type 白名单/Core 权威元数据缺省即中止/一次批量 embedding/upsert 幂等/--dry-run); 脚本单测 10 例, 404 绿

2026-09-07 11:55:24 +08:00

test_chat_stream.py

feat(chat): 新增 SSE 流式对话端点 POST /api/chat/stream（方案 C）

2026-09-08 14:23:33 +08:00

test_chat_tools.py

feat: C5 FR-9 预警处置时效升级（RISK-007，P0）

2026-09-07 19:28:04 +08:00

test_chat.py

feat(chat): 新增前端拉侧三端点（会话列表/历史消息/关闭会话）

2026-09-08 14:07:38 +08:00

test_concentration_c4.py

feat: C4 FR-8 持仓集中度预警（RISK-006）

2026-09-07 19:05:02 +08:00

test_core_ro_sum.py

test: B8 收敛——sqlite 测试 DDL 单一事实源 _ddl.py(10 文件 45 处手写 DDL 清零)+localtime 时区收敛(B5 评审 P3-4, utcnow 边界修复)+测试内遗留建表清理, 196 绿; docs 同步 B8 完成状态

2026-09-06 23:37:03 +08:00

test_db.py

fix: B7 复审 P1-1——dispose_engines 显式 Engine.dispose()(手写单例字典替代 lru_cache, test_db 3 例, 独立评审有条件通过→闭环)

2026-09-06 23:06:32 +08:00

test_demo_scripts.py

fix: B9a 复审闭环——P2-1 skipped 分支 has_engine_error_audit 中间态警示(input_summary LIKE)+docstring 局限声明; P2-2 非首笔 trade 幂等用例; P3 顺手: 双脚本连接自检/ImportError 分支/非 dict payload raw 兜底/get_trade_by_id confirmed 过滤/勿并行声明, 8 例 204 绿, warning 路径真库复验后清理; docs 同步复审结论

2026-09-07 01:02:12 +08:00

test_desensitize.py

feat: trace 贯通与脱敏工具 + risk 阈值配置(A1)

2026-09-06 15:09:14 +08:00

test_embedding.py

feat: T21-1 embedding 服务——Ollama bge-m3 批量 /api/embed(1024 维), 连接/模型/结构/维度四类失败一律 EmbeddingError 不静默降级(拍板口径), 空输入短路; settings 增 embed_dim/embed_timeout; 单测 10 例 mock HTTP 不依赖 Ollama, 386 绿

2026-09-07 11:46:24 +08:00

test_escalation_service.py

feat: C5 FR-9 预警处置时效升级（RISK-007，P0）

2026-09-07 19:28:04 +08:00

test_input_guard_api.py

test: T-03 评审闭环(PASS, P0=0)——P2-1 词表规范化断言修正/P2-2 补 7 条同构变体(你现在是管理员/ignore the above instructions 等)+变体单测/P2-3 窗口 TTL 断言+EXPIRE 失败取舍锁定; P3 session_id 落库截断+trace 兜底注释, 378 绿

2026-09-07 11:16:15 +08:00

test_input_guard.py

test: T-03 评审闭环(PASS, P0=0)——P2-1 词表规范化断言修正/P2-2 补 7 条同构变体(你现在是管理员/ignore the above instructions 等)+变体单测/P2-3 窗口 TTL 断言+EXPIRE 失败取舍锁定; P3 session_id 落库截断+trace 兜底注释, 378 绿

2026-09-07 11:16:15 +08:00

test_integration_risk.py

AL-08: 演示库重灌与种子核对对齐 main 基准——prepare_risk_demo.sql 改写 expires_at 口径(演示客户刷新为测评 90 天前/剩余 275 天,CUST-1004 保持过期演示 FM-03,替代 SUIT-008 evaluated_at+365 旧写法)；演示 SOP 同步(§2 完成标志 33 客户口径+expires_at 剩余天数,A-1 预期改 SUIT_RISK_MISMATCH,A-2 改 FM-01 SUIT_AGE_CONFIRM 网点确认)；网关阻断响应补全 main 契约字段(match_result/mismatch_type/requires_disclosure/needs_branch_confirm/rule_refs)+audit detail 加 block_response_code；集成测试 4 例旧口径断言更新(A-1 trace 一致性断机器码/A-1 audit JSON 断机器码/A-2 重写为 FM-01 语义/settings 退役断言)。SOP §2 脚本化全量重灌双库验证通过(AML 8 条/演示 7 行/sync 33 rows)；全量 406 passed 0 failed 0 skipped(集成测试真库走 21 列新表+expires_at 数据恢复执行)

2026-09-07 17:49:39 +08:00

test_kb_tools.py

feat: T21-5 知识库 Tool 接入对话——kb_tools(search_knowledge)挂统一注册表第三层; ToolSpec 新增 skip_access_check(公开知识无归属语义, advisor 无绑定客户可查, 意图层限定 customer/advisor); 意图关键词 customer/advisor 组尾挂 kb 词(Core 词优先, risk 不开放); tool_node 按 spec 白名单注入 query; summarize 溯源口径; 单测 13 例, 425 绿

2026-09-07 12:05:36 +08:00

test_locks_redis.py

docs(架构改进): 补齐 PRD/开发计划/TODO/交接文档，落地无密钥告警与 Redis 分布式锁

2026-09-09 18:10:03 +08:00

test_main.py

feat(chat): 新增 SSE 流式对话端点 POST /api/chat/stream（方案 C）

2026-09-08 14:23:33 +08:00

test_milvus_service.py

feat: T21-2 Milvus 接入层——kb_product_rules 幂等建集合(冻结 11 字段+AUTOINDEX COSINE)+upsert 入库+search_kb(溯源字段必带+effective_date 合规过滤+标量过滤); 规避 pymilvus 3.x import 阶段读 .env 文件 URI 炸 import 的坑(setdefault 预置合法 MILVUS_URI); 单测 8 例真 Lite 临时库, 394 绿

2026-09-07 11:49:43 +08:00

test_module_boundary.py

chore: 风控Agent模块自治边界标注 + AL-09 合并预处置

2026-09-07 18:28:18 +08:00

test_profile_l3.py

test: B8 收敛——sqlite 测试 DDL 单一事实源 _ddl.py(10 文件 45 处手写 DDL 清零)+localtime 时区收敛(B5 评审 P3-4, utcnow 边界修复)+测试内遗留建表清理, 196 绿; docs 同步 B8 完成状态

2026-09-06 23:37:03 +08:00

test_rag_service.py

feat: T21-4 RAG 检索编排——rag_service.search_knowledge(query→bge-m3 向量→Milvus 检索→chunks+source_refs 溯源去重), 异常原样上抛不吞(防 LLM 编造回答), 空白 query 短路, ensure_collection 幂等防御; 单测 8 例注入 mock, 412 绿

2026-09-07 12:01:45 +08:00

test_risk_api.py

feat: C5 FR-9 预警处置时效升级（RISK-007，P0）

2026-09-07 19:28:04 +08:00

test_risk_chat_tools.py

AL-06: 对话 Tool 与 API 响应对齐 main 基准——chat_tools.suitability_check 返回体扩展 match_result/mismatch_type/requires_disclosure/needs_branch_confirm/block_response_code/rule_refs(替代 rule_id/reasons/effective_level 展示)，check_source='r02_chat'，not_found 转结构化 found=False(NotFoundError except 死代码清除)；tool_service.summarize suitability 分支按新枚举重写文案(网点当面确认 FM-01/签署风险揭示书/测评过期 FM-03/专业豁免,附 rule_refs 依据)；risk_api 断言改 block_response_code。全量 373 passed 0 failed(1 skip=test_suitability 占位待 AL-07)。遗留：chat 链路 risk_suitability_log.actor_id 暂落 SYSTEM(run_tool 统一透传需动 core_tools/kb_tools 冻结 func 契约,发起者留痕已由 agent_tool_call 覆盖)

2026-09-07 17:39:04 +08:00

test_risk_engine.py

test: B8 收敛——sqlite 测试 DDL 单一事实源 _ddl.py(10 文件 45 处手写 DDL 清零)+localtime 时区收敛(B5 评审 P3-4, utcnow 边界修复)+测试内遗留建表清理, 196 绿; docs 同步 B8 完成状态

2026-09-06 23:37:03 +08:00

test_risk_repository.py

AL-05: suitability 服务重构换核对齐 main 基准——判定内核由 SUIT-001~008 纯函数矩阵改为 core_ro.check_suitability(C×R 数据驱动)；SuitabilityResult 扩 main 新字段(match_result 五值/mismatch_type 七值/requires_disclosure/needs_branch_confirm/block_response_code/rule_refs)并保留旧字段兼容层(rule_id=机器码别名/effective_level=customer_level/reasons=[reason])；check_core/cap_by_age/match_by_matrix/is_assessment_valid 删除(SUIT-006 被 FM-01 替换,SUIT-008 被 FM-03 expires_at 替换)；settings.risk_assessment_valid_days 退役(.env/.env.example 注释)；NotFoundError 不再抛(not_found 结构化,main 契约)；写库走 build_suitability_log_row + insert_suitability_log 升级 21 列(rule_refs JSON 序列化)；check_source 参数化(网关 r02_trade/risk.py manual)+actor_id 透传；网关阻断响应补 block_response_code；model 抽 compute_rule_refs 公共函数防两处漂移；测试配套：_ddl 加矩阵 25 行种子 helper、conftest fixture 灌种子+集成就位校验改 expires_at 口径、trade_gateway/risk_api fixture 补种子与 expires_at、404 两例改 200+blocked 新契约、repository 21 列断言、settings 退役断言、test_suitability 占位 skip 待 AL-07 重写。sqlite 端到端七语义+落库验证通过；剩 4 failed 均为 chat_tools/API 旧展示断言(AL-06 处理)

2026-09-07 17:34:32 +08:00

test_risk_rules.py

feat: C4 FR-8 持仓集中度预警（RISK-006）

2026-09-07 19:05:02 +08:00

test_settings.py

AL-05: suitability 服务重构换核对齐 main 基准——判定内核由 SUIT-001~008 纯函数矩阵改为 core_ro.check_suitability(C×R 数据驱动)；SuitabilityResult 扩 main 新字段(match_result 五值/mismatch_type 七值/requires_disclosure/needs_branch_confirm/block_response_code/rule_refs)并保留旧字段兼容层(rule_id=机器码别名/effective_level=customer_level/reasons=[reason])；check_core/cap_by_age/match_by_matrix/is_assessment_valid 删除(SUIT-006 被 FM-01 替换,SUIT-008 被 FM-03 expires_at 替换)；settings.risk_assessment_valid_days 退役(.env/.env.example 注释)；NotFoundError 不再抛(not_found 结构化,main 契约)；写库走 build_suitability_log_row + insert_suitability_log 升级 21 列(rule_refs JSON 序列化)；check_source 参数化(网关 r02_trade/risk.py manual)+actor_id 透传；网关阻断响应补 block_response_code；model 抽 compute_rule_refs 公共函数防两处漂移；测试配套：_ddl 加矩阵 25 行种子 helper、conftest fixture 灌种子+集成就位校验改 expires_at 口径、trade_gateway/risk_api fixture 补种子与 expires_at、404 两例改 200+blocked 新契约、repository 21 列断言、settings 退役断言、test_suitability 占位 skip 待 AL-07 重写。sqlite 端到端七语义+落库验证通过；剩 4 failed 均为 chat_tools/API 旧展示断言(AL-06 处理)

2026-09-07 17:34:32 +08:00

test_suitability.py

AL-07: test_suitability 按 main 契约重写——七判定路径正反例(not_found 客户/产品两向/FM-03 过期/JR-AST-PRO 专业豁免优先于矩阵 forbidden/JR-AST-012 矩阵 forbidden/矩阵缺行 fail-closed/allowed/矩阵披露与产品 requires_disclosure 两源/FM-01 age70+R5 阻断+69岁与R2 两边界)；compute_rule_refs 四类组合(含报告样例 过期+不匹配→['JR-AST-012','FM-03'])；build_suitability_log_row 逐字段 21 列映射断言+bool→int 转换；服务集成端到端(21 列落库/check_source r02_trade 与 r02_chat/actor_id/request_ref 透传/兼容字段 rule_id=机器码 映射/NotFound 结构化不抛)；MySQL 方言冒烟(真库连通时验 SQL 可执行性,未灌库自动 skip)。可控日期用远未来/远过去 expires_at 种子。全量 395 passed 0 failed；1 skip=集成模块待 AL-08 重灌演示 SQL expires_at

2026-09-07 17:42:55 +08:00

test_trace.py

feat: trace 贯通与脱敏工具 + risk 阈值配置(A1)

2026-09-06 15:09:14 +08:00

test_trade_gateway.py

AL-05: suitability 服务重构换核对齐 main 基准——判定内核由 SUIT-001~008 纯函数矩阵改为 core_ro.check_suitability(C×R 数据驱动)；SuitabilityResult 扩 main 新字段(match_result 五值/mismatch_type 七值/requires_disclosure/needs_branch_confirm/block_response_code/rule_refs)并保留旧字段兼容层(rule_id=机器码别名/effective_level=customer_level/reasons=[reason])；check_core/cap_by_age/match_by_matrix/is_assessment_valid 删除(SUIT-006 被 FM-01 替换,SUIT-008 被 FM-03 expires_at 替换)；settings.risk_assessment_valid_days 退役(.env/.env.example 注释)；NotFoundError 不再抛(not_found 结构化,main 契约)；写库走 build_suitability_log_row + insert_suitability_log 升级 21 列(rule_refs JSON 序列化)；check_source 参数化(网关 r02_trade/risk.py manual)+actor_id 透传；网关阻断响应补 block_response_code；model 抽 compute_rule_refs 公共函数防两处漂移；测试配套：_ddl 加矩阵 25 行种子 helper、conftest fixture 灌种子+集成就位校验改 expires_at 口径、trade_gateway/risk_api fixture 补种子与 expires_at、404 两例改 200+blocked 新契约、repository 21 列断言、settings 退役断言、test_suitability 占位 skip 待 AL-07 重写。sqlite 端到端七语义+落库验证通过；剩 4 failed 均为 chat_tools/API 旧展示断言(AL-06 处理)

2026-09-07 17:34:32 +08:00