llm-quant/docs/architecture/code_review_checklist.md

架构与代码整洁治理计划

目标：支撑「全量代码审查｜TODO 标记治理｜业务逻辑体检」三项工作，持续缩减遗留债务。

1. 全量代码审查

• app/ui/streamlit_app.py：梳理启动流程、路径注入、自动更新逻辑。
• app/ui/views/*：关注重复组件、可拆分的横向导航、潜在的阻塞调用。
• app/backtest/*：确保引擎接口与决策环境的异常兜底一致。
• app/llm/*：重点检查 Provider 降级逻辑、缓存策略、成本控制开关。
• app/agents/*：核对部门权重、协议 Host、Telemetry 写入是否对齐。
• 每轮审查输出摘要（PR 注释或 issue），并将建议归档到 docs/architecture/。

2. TODO 标记治理

1. 使用 python scripts/todo_report.py --format table 生成待处理列表。
2. 按模块划分归类：
   • 无效 TODO → 删除。
   • 长期待办 → 转为 docs/TODO.md 列表。
   • 未描述清楚 → 补充上下文、负责人、预期结果。
3. 每周至少一次同步报告（截屏或粘贴 CLI 输出）到工作记录。

3. 业务逻辑体检

• 建立「关键链路」档案（数据采集 → 回测 → 调参 → UI 呈现）。
• 对每条链路列出：
  • 输入/输出契约
  • 依赖的配置项
  • 失败重试 & 降级逻辑
  • 观察指标（日志、Telemetry、Metrics）
• 体检发现的问题纳入 docs/TODO.md 或新 issue。

4. 工具支撑

• scripts/todo_report.py：归集 TODO/FIXME/HACK，支持 JSON 输出利于持续集成。
• 计划补充：
  • 模块耦合分析（import 依赖图）
  • 代码所有权（CODEOWNERS 草案）
  • 常见安全用法检查脚本

5. 推进节奏

周期	动作
每周	更新 TODO 报告、归档新增 TODO、关闭已完成项
每两周	聚焦一个子系统做深入代码审查
每月	汇总「体检 + TODO + 审查」结果，形成复盘

说明：本计划将根据治理结果滚动调整，欢迎在 PR 或 issue 中补充改进建议。