# 架构与代码整洁治理计划

> 目标：支撑「全量代码审查｜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 中补充改进建议。