# AgomTradePro 项目整改清单（2026-04-30）

> **整理日期**: 2026-04-30
> **适用版本**: AgomTradePro 0.7.0
> **文档目标**: 将原评估结果改写为面向研发与外包执行团队的两周整改清单

## 背景说明

本清单基于 2026-04-30 的架构评估结果整理而成。
原报告中的静态扫描结果可作为线索，但其中包含部分优先级失真和个别自相矛盾的结论。
本次文档仅保留值得投入的整改项，并统一改写为可执行任务，不再以评分、排名和代码量统计为主体。
本清单用于指导未来两周的整改顺序与验收口径，不等同于一次性清偿全部技术债。

## 本次整改结论摘要

### 值得改

- `dashboard` 已出现跨模块 infrastructure 直连，应优先治理，避免仪表盘继续演化为跨 App ORM 聚合器。
- Application 层直接调用 `call_command` 的做法应尽快收口，避免命令入口和用例层反向耦合。
- `apps/dashboard/interface/views.py` 已同时承载页面、HTMX、API 和辅助逻辑，且存在较多宽泛异常捕获，适合本轮拆分。
- `account` 的边界问题真实存在，但应先做 bounded context 梳理，不在本轮直接发起大规模迁移。

### 暂不建议投入

- 不发起全仓 `repository_provider.py` 统一依赖注入改造。
- 不发起全仓 Django import 清洗运动。
- 不单独以类型标注覆盖率为本轮目标。
- 不优先处理 `import *` 清理、迁移文件 squash、全量大文件排名对应的拆分任务。

## P0 本周必须做

### 事项 1：治理 `dashboard` 跨模块 infrastructure 直连

- 现状
  - `apps/dashboard/infrastructure/repositories.py` 直接导入其他模块的 ORM Model 与 Repository。
  - 当前问题不是单点违规，而是 `dashboard` 正在承担跨模块读模型拼装职责，后续会持续放大耦合。
- 整改动作
  - 为 `dashboard` 引入明确的查询聚合边界，优先通过对方 App 已公开的 application service、query service 或 facade 获取数据。
  - 将 `dashboard` 内部必须保留的读模型逻辑收敛到少量可替换接口，不再继续增加新的跨模块 infrastructure import。
  - 先治理最常用、最容易继续扩散的读路径，不要求本周一次性清零历史依赖。
- 不要做的事
  - 不要把更多跨模块 ORM 查询继续塞进 `apps/dashboard/infrastructure/repositories.py`。
  - 不要为了“快速解耦”把业务规则挪回 interface 层。
- 验收标准
  - 本轮涉及的 `dashboard` 新增代码不再新增跨模块 infrastructure 直连。
  - 已识别的高频查询路径改为通过稳定查询入口获取数据。
  - 相关查询有回归测试，至少覆盖 query 或 use case 层。

### 事项 2：收口 Application 层 `call_command` 入口

- 现状
  - `apps/pulse/application/use_cases.py` 中直接调用 `call_command` 刷新上游数据。
  - `apps/task_monitor/application/tasks.py` 中直接调用 `call_command` 执行数据库备份。
  - 这种做法会让管理命令入口反向侵入用例层，增加测试和替换成本。
- 整改动作
  - 将管理命令中的核心行为下沉到可复用服务或应用服务，由 management command 和 Celery/task/use case 共同调用。
  - 保留命令行作为入口壳层，不再让 application 直接依赖 `call_command`。
  - 若短期无法完全抽离，至少先引入单一封装点，避免继续在其他 application 文件复制该模式。
- 不要做的事
  - 不要把 `call_command` 从一个 application 文件挪到另一个 application 文件后视为完成。
  - 不要在函数内部新增延迟 import 继续绕开架构边界。
- 验收标准
  - `pulse` 与 `task_monitor` 本轮涉及路径不再直接依赖 `call_command`。
  - 核心逻辑可被单元测试或应用层测试直接调用，无需通过 management command 间接触发。
  - 新增代码符合 AGENTS.md 中的四层架构边界要求。

### 事项 3：拆分 `dashboard/interface/views.py` 并收窄宽泛异常

- 现状
  - `apps/dashboard/interface/views.py` 同时承载页面视图、HTMX 局部渲染、API 端点和大量辅助函数。
  - 文件内存在多处 `except Exception`，会掩盖真实错误并增加维护成本。
- 整改动作
  - 按页面视图、HTMX、API、辅助函数四类职责拆分文件。
  - 优先把高频访问和近期还在继续变动的部分拆出去，减少单文件持续膨胀。
  - 将宽泛异常替换为明确异常类型；确需兜底时，必须附带清晰日志和稳定返回契约。
- 不要做的事
  - 不要只做机械移动文件而不处理异常边界。
  - 不要把业务编排逻辑从 application 拉回 interface。
- 验收标准
  - `dashboard` 视图入口按职责拆分，不再维持单文件承载全部接口。
  - 本轮改动覆盖到的视图逻辑，不再保留无说明的 `except Exception`。
  - 页面、HTMX、API 的现有关键行为有回归测试，至少覆盖成功路径和主要失败路径。

## P1 两周内完成

### 事项 4：梳理 `account` 的 bounded context 边界

- 现状
  - `account` 同时承载账户身份、组合、持仓、交易、配置、货币、文档等多类模型，职责边界不清。
  - 该问题真实存在，但直接拆模块会牵涉迁移、引用路径和跨模块契约，风险高于本轮 P0 项。
- 整改动作
  - 先完成模块边界梳理，明确哪些模型未来归 `portfolio`，哪些配置应迁往独立配置中心。
  - 输出拆分顺序、依赖切割点和兼容过渡方案，作为后续实施依据。
- 验收标准
  - 形成书面边界方案，明确第一批拆分对象和迁移前置条件。
  - 不在本轮直接发起大规模 model 迁移或跨模块重命名。

### 事项 5：将 `decision_rhythm` 的大文件拆分降级为“结合业务改动顺手拆”

- 现状
  - `decision_rhythm` 存在超大文件，尤其是 application use case 聚集明显。
  - 该问题影响可维护性，但当前并非最紧急的架构风险。
- 整改动作
  - 后续凡涉及 `decision_rhythm` 功能开发或缺陷修复，优先顺手拆分对应 use case、entity 或 repository 片段。
  - 本轮不单独立项做“纯拆分而不改行为”的大手术。
- 验收标准
  - 后续改动不再继续向原大文件堆积新职责。
  - 新增或重构部分按领域职责落入更小的模块单元。

### 事项 6：仅针对热点文件收窄 `except Exception`

- 现状
  - 宽泛异常捕获在项目中数量较多，但并非所有位置都值得同一轮集中处理。
- 整改动作
  - 仅处理近期高频变更、用户入口明显、排障成本高的热点文件。
  - 优先替换为领域异常、基础设施异常或输入校验异常，并统一日志语义。
- 验收标准
  - 本轮热点文件中的关键入口不再依赖宽泛异常吞错。
  - 失败路径能区分“预期业务失败”和“真实程序错误”。

### 事项 7：测试补强聚焦关键路径，不做目录形式治理

- 现状
  - 原评估以“是否存在独立测试目录”判断测试缺口，口径偏表面。
  - 当前更重要的是关键流程是否有可靠回归保护，而不是测试文件放在哪个目录。
- 整改动作
  - 优先补 `dashboard` 查询/视图、`pulse` 刷新链路、`task_monitor` 备份链路等关键路径测试。
  - 优先覆盖 contract、query、use case 层，再决定是否补更重的集成测试。
- 验收标准
  - P0 涉及的每条关键路径都有可执行测试覆盖。
  - 新增测试能够验证主要成功路径和至少一个失败路径。

## 暂缓项 / 长期观察

### 事项 8：全仓 `repository_provider.py` 统一 DI 改造

- 现状
  - Service Locator 模式在项目中已广泛存在，整体替换成本高。
- 整改动作
  - 本轮不发起全仓改造。
  - 后续新增代码不再扩大该模式的使用范围，热点模块逐步收口。
- 验收标准
  - 本轮无全仓替换动作。
  - 新增代码优先使用更明确的依赖边界。

### 事项 9：全仓 Django import 清洗

- 现状
  - 原评估将多类 Django import 统一归为“泄漏”，但其中一部分与仓库当前实践并不完全冲突。
- 整改动作
  - 本轮仅处理真正影响边界的 `call_command`、事务入口和直接 infrastructure 绑定。
  - 不以“消灭所有 Django import”为目标。
- 验收标准
  - 无全仓机械式清洗任务。
  - 架构整改聚焦真实边界问题而非数字好看。

### 事项 10：类型标注覆盖率、`import *` 清理、迁移 squash

- 现状
  - 这些问题存在，但短期收益低于当前架构热点问题。
- 整改动作
  - 不单独立项冲覆盖率指标。
  - 不优先发起 `import *` 全量替换。
  - 不优先处理 migration squash。
- 验收标准
  - 仅在相关文件发生业务改动时顺手改善，不作为两周主线任务。

## 统一验收标准

- 不破坏 AgomTradePro 四层架构边界，尤其不得新增跨模块 infrastructure 直连。
- P0 与 P1 中涉及的新增或重构代码必须补测试，优先覆盖 contract、query、use case 层。
- 每个整改项必须能回答“是否完成”，不得仅停留在“建议优化”“建议关注”。
- 本轮整改以降低真实耦合、提升可替换性和排障效率为目标，不以报表指标美化为目标。
- 若某项整改需要跨模块大迁移，必须先补边界方案与兼容方案，再进入实施。

## 备注

本文件是整改清单，不再承担原始扫描结果的统计归档职责。
若后续需要保留完整静态扫描结果，应单独归档为原始分析附件，不应再混入执行清单。
