# AgomTradePro 模块分级表

> **版本**: V1.2
> **基线日期**: 2026-03-28
> **文档性质**: 模块治理规范
> **依赖来源**: `docs/architecture/MODULE_DEPENDENCIES.md`

---

## 1. 分级原则

模块分级基于以下维度：

1. **被依赖次数**: 越多依赖，越核心
2. **稳定性要求**: 接口变更影响面
3. **测试覆盖**: 测试完整度
4. **功能成熟度**: 生产使用情况

---

## 2. 三级分类

### 🔴 核心内核（Tier 1）- 不能乱动

**定义**: 被大量模块依赖，接口变更影响面极大

**数量**: 4 个

**变更规则**:
- ❌ 禁止破坏性接口变更
- ✅ 只允许向后兼容的扩展
- ✅ 变更必须经过架构评审
- ✅ 变更前必须通知所有依赖方

| 模块 | 职责 | 被依赖次数 | 关键性 |
|------|------|-----------|--------|
| **regime** | 宏观象限判定引擎 | 10 | 🔴 极高 |
| **ai_provider** | AI 服务商管理 | 5 | 🔴 极高 |
| **events** | 事件发布与订阅 | 4 | 🔴 高 |
| **macro** | 宏观数据采集 | 4 | 🔴 高 |

**依赖图**:

```
regime (10)
    ↓ 被依赖
account, asset_analysis, audit, dashboard, decision_rhythm, 
prompt, realtime, simulated_trading, signal, strategy

ai_provider (5)
    ↓ 被依赖
policy, prompt, sentiment, simulated_trading, strategy

events (4)
    ↓ 被依赖
account, alpha_trigger, beta_gate, decision_rhythm

macro (4)
    ↓ 被依赖
account, audit, filter, prompt
```

---

### 🟡 成熟外围（Tier 2）- 可小改

**定义**: 功能稳定，有完整测试覆盖，可进行小规模优化

**数量**: 20 个

**变更规则**:
- ✅ 允许小规模重构
- ✅ 允许新增功能（向后兼容）
- ⚠️ 重大变更需评审
- ✅ 必须补充测试

| 模块 | 职责 | 依赖数 | 被依赖数 | 测试覆盖 |
|------|------|--------|----------|----------|
| **signal** | 投资信号管理 | 1 | 3 | ✅ 完整 |
| **policy** | 政策事件管理 | 1 | 2 | ✅ 完整 |
| **sentiment** | 舆情分析 | 1 | 1 | ✅ 完整 |
| **asset_analysis** | 资产分析框架 | 4 | 3 | ✅ 完整 |
| **equity** | 个股分析 | 1 | 2 | ✅ 完整 |
| **fund** | 基金分析 | 1 | 0 | ✅ 完整 |
| **backtest** | 回测引擎 | 1 | 2 | ✅ 完整 |
| **audit** | 事后审计 | 3 | 0 | ✅ 完整 |
| **dashboard** | 仪表盘 | 13 | 0 | ✅ 完整 |
| **prompt** | AI Prompt 模板 | 3 | 2 | ✅ 完整 |
| **realtime** | 实时价格监控 | 2 | 1 | ✅ 完整 |
| **data_center** | 数据中台 | 4 | 12 | ✅ 完整 |
| **terminal** | 终端 CLI | 1 | 0 | ✅ 完整 |
| **strategy** | 策略系统 | 3 | 1 | ✅ 完整 |
| **decision_rhythm** | 决策频率约束 | 3 | 2 | ✅ 完整 |
| **share** | 分享功能 | 2 | 0 | ✅ 完整 |
| **simulated_trading** | 模拟盘交易 | 7 | 2 | ✅ 完整 |
| **account** | 账户管理 | 14 | 1 | ✅ 完整 |
| **alpha_trigger** | Alpha 离散触发 | 1 | 1 | ✅ 完整 |
| **beta_gate** | Beta 闸门 | 1 | 0 | ✅ 完整 |

**说明**:
- `dashboard` 依赖 13 个模块（聚合查询），但无被依赖，属于展示层
- `account` 依赖 14 个模块，职责较重，建议后续拆分（见开发禁令）
- `simulated_trading` 依赖 7 个模块，已通过 Facade 模式解耦

---

### 🟢 试验模块（Tier 3）- 允许迭代

**定义**: 新增或持续优化中，允许较大改动

**数量**: 11 个

**变更规则**:
- ✅ 允许大规模重构
- ✅ 允许接口变更
- ⚠️ 变更后必须更新文档
- ✅ 变更后必须补充测试

| 模块 | 职责 | 状态 | 备注 |
|------|------|------|------|
| **alpha** | AI 选股 (Qlib) | 🟢 迭代中 | 4 层降级机制 |
| **factor** | 因子管理 | 🟢 迭代中 | IC/ICIR 评估 |
| **hedge** | 对冲策略 | 🟢 迭代中 | 期货对冲计算 |
| **rotation** | 板块轮动 | 🟢 迭代中 | Regime 驱动 |
| **sector** | 板块分析 | 🟢 迭代中 | 独立模块 |
| **agent_runtime** | Agent 运行时 | 🟢 新增 | Terminal AI 后端 |
| **task_monitor** | 任务监控 | 🟢 新增 | Celery 监控 |
| **filter** | HP/Kalman 滤波 | 🟢 迭代中 | 算法优化 |
| **ai_capability** | AI 能力目录 | 🟢 新增 | 统一路由 |
| **setup_wizard** | 系统初始化向导 | 🟢 新增 | 首次安装引导 |
| **pulse** | Pulse 脉搏层 | 🟢 新增 | 战术指标聚合与转折预警 |

**说明**:
- 这些模块功能尚在演进，接口可能变化
- 优先级低于核心模块，但测试仍需完整
- 迭代完成后可升级为 Tier 2

---

## 3. 分层架构映射

### 3.1 依赖层级图

```
┌─────────────────────────────────────────────────────────┐
│  Tier 1: 核心内核 (4个)                                  │
│  regime, ai_provider, events, macro                     │
│  🔴 不能乱动                                             │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Tier 2: 成熟外围 (20个)                                 │
│  signal, policy, asset_analysis, equity, fund, ...      │
│  🟡 可小改                                               │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Tier 3: 试验模块 (11个)                                 │
│  alpha, factor, hedge, rotation, ai_capability, ...     │
│  🟢 允许迭代                                             │
└─────────────────────────────────────────────────────────┘
```

### 3.2 依赖方向规则

```
✅ 允许: Tier 3 → Tier 2 → Tier 1
✅ 允许: 同 Tier 内依赖
❌ 禁止: Tier 1 → Tier 2/3
❌ 禁止: 循环依赖
```

---

## 4. 模块依赖统计

### 4.1 依赖数 TOP 5

| 模块 | 依赖数 | 分级 | 风险 |
|------|--------|------|------|
| **account** | 14 | Tier 2 | 🔴 过重，建议拆分 |
| **dashboard** | 13 | Tier 2 | 🟡 聚合查询，正常 |
| **decision_rhythm** | 3 | Tier 2 | 🟢 正常 |
| **simulated_trading** | 7 | Tier 2 | 🟡 较多，已解耦 |
| **asset_analysis** | 4 | Tier 2 | 🟢 正常 |

### 4.2 被依赖数 TOP 5

| 模块 | 被依赖数 | 分级 | 关键性 |
|------|----------|------|--------|
| **regime** | 10 | Tier 1 | 🔴 极高 |
| **ai_provider** | 5 | Tier 1 | 🔴 极高 |
| **events** | 4 | Tier 1 | 🔴 高 |
| **macro** | 4 | Tier 1 | 🔴 高 |
| **signal** | 3 | Tier 2 | 🟡 高 |

---

## 5. 变更影响评估

### 5.1 变更影响矩阵

| 变更模块 | 影响范围 | 必须通知 | 评审级别 |
|----------|----------|----------|----------|
| **Tier 1** | 全局 | 所有依赖方 | 架构评审 |
| **Tier 2** | 局部 | 直接依赖方 | 技术评审 |
| **Tier 3** | 自身 | 无 | 代码评审 |

### 5.2 破坏性变更定义

以下变更视为**破坏性变更**：

- ❌ 删除公开 API 端点
- ❌ 修改 API 参数签名（删除/重命名必填参数）
- ❌ 修改返回值结构（删除字段）
- ❌ 修改 Domain 层实体定义
- ❌ 修改数据库 Schema（非加列）

---

## 6. 升级/降级规则

### 6.1 升级到 Tier 2

**条件**（需同时满足）：

1. ✅ 被依赖次数 ≥ 2
2. ✅ 测试覆盖率 ≥ 85%
3. ✅ 生产环境使用 ≥ 3 个月
4. ✅ 接口稳定 ≥ 2 个月无破坏性变更

### 6.2 升级到 Tier 1

**条件**（需同时满足）：

1. ✅ 被依赖次数 ≥ 5
2. ✅ 测试覆盖率 ≥ 90%
3. ✅ 生产环境使用 ≥ 6 个月
4. ✅ 接口稳定 ≥ 6 个月无破坏性变更
5. ✅ 架构评审通过

### 6.3 降级

**触发条件**：

- ⚠️ 连续 3 次破坏性变更
- ⚠️ 测试覆盖率 < 80%
- ⚠️ 生产环境重大故障

---

## 7. 监控与告警

### 7.1 依赖监控

- **监控指标**: 模块依赖数、被依赖数
- **告警阈值**: 依赖数 > 10 或被依赖数 > 5 时告警
- **检查频率**: 每次发布前

### 7.2 测试监控

- **监控指标**: 测试覆盖率、测试通过率
- **告警阈值**: Domain 层覆盖率 < 90%
- **检查频率**: 每次 PR

---

## 8. 变更记录

| 日期 | 版本 | 变更内容 |
|------|------|----------|
| 2026-03-28 | V1.2 | 新增 pulse 模块（Tier 3），更新 Tier 3 数量(10→11) |
| 2026-03-22 | V1.1 | 新增 ai_capability 模块（Tier 3），更新模块数量(8→9) |
| 2026-03-18 | V1.0 | 初始版本，建立三级分类体系 |

---

**维护者**: AgomTradePro Team
**最后更新**: 2026-03-28
**参考文档**: `docs/architecture/MODULE_DEPENDENCIES.md`
