# AgomTradePro 教学模块实施文档

> **实施日期**: 2026-02-01
> **实施内容**: 宏观经济教学指南模块
> **状态**: 已完成

---

## 一、模块概述

教学模块是一个悬浮窗（Modal）形式的教学指南，帮助用户理解宏观经济基础、Regime 判定系统、Policy 档位系统、资产配置策略和历史案例。

### 功能定位

- **入口位置**: 仪表盘左侧边栏底部，"📚 教学指南"按钮
- **呈现形式**: 全屏模态窗 + 侧边栏导航 + 手风琴内容
- **交互功能**: Regime计算器、Policy模拟器、历史案例浏览

---

## 二、文件清单

### 新建文件

| 文件路径 | 说明 | 行数 |
|---------|------|------|
| `core/static/css/teaching.css` | 教学模块样式文件 | ~850 |
| `core/templates/dashboard/teaching_modal.html` | 教学模态窗模板 | ~600 |
| `core/static/js/teaching/teaching-modal.js` | 模态窗逻辑（导航、手风琴、案例） | ~300 |
| `core/static/js/teaching/regime-calculator.js` | Regime 计算器 | ~250 |
| `core/static/js/teaching/policy-simulator.js` | Policy 模拟器 | ~300 |

### 修改文件

| 文件路径 | 修改内容 |
|---------|----------|
| `core/templates/dashboard/index.html` | 添加教学入口按钮、引入CSS/JS、包含模态窗模板 |

---

## 三、内容架构

### 教学章节

```
📚 AgomTradePro 教学指南
├── 1️⃣ 宏观经济基础
│   ├── 什么是 PMI？
│   ├── 什么是 CPI？
│   ├── 经济周期四阶段
│   └── V2 水平判定法简介
├── 2️⃣ Regime 判定系统
│   ├── Regime 四象限划分
│   ├── V2 水平判定方法
│   ├── 置信度的含义
│   └── 🎮 Regime 计算器
├── 3️⃣ Policy 档位系统
│   ├── P0-P3 档位说明
│   ├── 政策事件分类
│   ├── 档位响应规则
│   └── 🎮 Policy 模拟器
├── 4️⃣ 资产配置策略
│   ├── Regime × Policy 准入矩阵
│   ├── 资产类别特性
│   └── 风险控制原则
└── 5️⃣ 历史案例库
    ├── 2020年疫情危机
    ├── 2022年通胀压力
    └── 2023年中国经济
```

---

## 四、交互功能

### Regime 计算器

- **输入**: PMI (40-60)、CPI (-2% - 10%)
- **输出**: 当前所处象限 + 投资建议
- **V2 水平判定**:
  - PMI >= 50 且 CPI <= 2% → Recovery (复苏)
  - PMI >= 50 且 CPI > 2% → Overheat (过热)
  - PMI < 50 且 CPI <= 2% → Deflation (通缩)
  - PMI < 50 且 CPI > 2% → Stagflation (滞胀)
- **算法说明**: 使用 V2 水平法，基于 PMI/CPI 的绝对水平判定，更符合经济直觉

### Policy 模拟器

- **事件选择**: 6种预设政策事件（宽松/收紧）
- **档位计算**:
  - 总分 >= 3 → P0（强力支持）
  - 总分 1-2 → P1（温和支持）
  - 总分 -1 至 0 → P2（政策收紧）
  - 总分 <= -2 → P3（强力收紧）
- **输出**: 档位显示 + 投资建议

### 历史案例

- **案例列表**: 3个历史案例卡片
- **案例详情**: 时间线 + 经验教训
- **支持返回**: 点击"返回案例列表"

---

## 五、使用方式

### 开发环境

```bash
# 启动开发服务器
python manage.py runserver

# 访问仪表盘
http://localhost:8000/dashboard/

# 点击左侧边栏底部的 "📚 教学指南" 按钮
```

### 功能验证清单

- [ ] 模态窗正常打开/关闭
- [ ] ESC 键关闭模态窗
- [ ] 点击背景关闭模态窗
- [ ] 5个教学章节切换正常
- [ ] 手风琴展开/折叠正常
- [ ] Regime 计算器计算正确
- [ ] Policy 模拟器档位更新正确
- [ ] 历史案例详情显示正常
- [ ] 移动端响应式正常

---

## 六、技术细节

### 依赖

- **无新增依赖**：纯前端实现
- **CSS变量复用**：使用项目现有的颜色系统变量
- **兼容性**：ES5+ JavaScript，现代浏览器

### 样式规范

- 使用 CSS 变量保持一致性
- 响应式断点：1200px、768px
- 动画：fadeIn（0.3s ease）

### JavaScript 特性

- 全局函数导出（window.xxx）供 HTML 调用
- localStorage 学习进度追踪
- 事件委托优化性能

---

## 七、后续扩展方向

### Phase 2 (可选)

1. **Policy 模拟器增强**
   - 添加更多政策事件类型
   - 显示档位变化的时间线
   - 支持自定义事件场景

2. **历史案例库扩展**
   - 添加更多历史案例 (2015股灾、2008金融危机)
   - 添加案例筛选和搜索功能
   - 添加案例对比功能

3. **学习进度追踪**
   - 记录用户已读章节
   - 添加学习进度条
   - 添加学习统计

### Phase 3 (可选)

1. **视频教程嵌入**
   - 录制核心概念讲解视频
   - 嵌入到相应章节
   - 添加视频进度控制

2. **互动式图表**
   - 动态展示经济周期变化
   - 可交互的资产配置矩阵
   - 历史数据可视化

3. **多语言支持**
   - 添加英文翻译
   - 支持中英文切换

---

## 八、注意事项

1. **算法版本**: 教学模块使用 V2 水平判定法（PMI=50, CPI=2%），与系统实际算法一致。Regime 判定基于绝对水平，更符合经济直觉。

2. **数据时效性**: 历史案例数据基于 2020-2023 年真实情况，后续可能需要更新。

3. **兼容性**: 模态窗使用 fixed 定位和 z-index 9999，确保在最上层显示。

4. **性能**: 所有 JavaScript 延迟 500ms 初始化，确保 DOM 加载完成。

---

## 九、成功标准

### 必须达成 (P0) ✅

- [x] 教学模态窗正常打开/关闭
- [x] 5个教学章节内容完整
- [x] Regime 计算器功能正确
- [x] 手风琴展开/折叠正常
- [x] 样式与现有 UI 一致

### 建议达成 (P1) ✅

- [x] Policy 模拟器可用
- [x] 历史案例库包含 3 个案例
- [x] 移动端响应式正常

### 可选达成 (P2) ✅

- [x] 学习进度追踪（localStorage）✅ Phase 2
- [x] 互动式图表（ECharts）✅ Phase 3
- [x] 双语支持（中英文）✅ Phase 3

---

## 十一、Phase 2 & 3 增强功能 ✅

**完成日期**: 2026-02-01

### Phase 2 已完成 ✅

| 功能 | 说明 | 新增文件 |
|------|------|----------|
| **Policy 模拟器增强** | 时间线可视化、5种预设场景、自定义事件添加 | `policy-simulator-enhanced.js` (~450行) |
| **历史案例库扩展** | 9个历史案例(2008-2024)、搜索筛选、案例对比 | `cases-library.js` (~650行) |
| **学习进度追踪** | 进度条、8个成就系统、学习统计、导入导出 | `learning-progress.js` (~550行) |

### Phase 3 已完成 ✅

| 功能 | 说明 | 新增文件 |
|------|------|----------|
| **互动式图表** | Regime四象限、配置矩阵、时间线图表、饼图 | `interactive-charts.js` (~350行) |
| **双语支持** | 中英文切换、本地化翻译、数字日期格式化 | `bilingual-support.js` (~400行) |

### 新增文件总计

| 阶段 | 文件数 | 总行数 |
|------|--------|--------|
| Phase 1 (基础) | 5 | ~2,300 |
| Phase 2 (增强) | 3 | ~1,650 |
| Phase 3 (进阶) | 2 | ~750 |
| **合计** | **10** | **~4,700** |

### Phase 2/3 新增功能清单

#### Policy 模拟器增强
- ✅ 时间线可视化（政策事件时间轴）
- ✅ 5种预设场景（危机应对、常规支持、抗通胀、结构调整、收紧周期）
- ✅ 自定义事件添加
- ✅ 事件高亮和动画

#### 历史案例库扩展
- ✅ 新增6个历史案例（2008金融危机、2015股灾、2017去杠杆、2018贸易摩擦、2019科创板、2024新质生产力）
- ✅ 案例分类筛选（9种分类）
- ✅ 难度级别标记（入门/进阶/高级）
- ✅ 关键词搜索
- ✅ 多案例对比功能

#### 学习进度追踪
- ✅ 总体学习进度条
- ✅ 分章节进度显示
- ✅ 8个成就系统（初学者、基础专家、Regime大师等）
- ✅ 学习统计面板
- ✅ 进度导入/导出

#### 互动式图表
- ✅ Regime 四象限交互图
- ✅ 资产配置矩阵热力图
- ✅ Regime 历史时间线图
- ✅ 资产配置饼图
- ✅ 互动式 Regime 计算器图

#### 双语支持
- ✅ 中英文界面切换
- ✅ 所有教学内容翻译
- ✅ 本地化数字/日期格式
- ✅ 语言切换器组件

### 详细文档

Phase 2/3 详细实施文档请参阅：[PHASE2_3_IMPLEMENTATION.md](./PHASE2_3_IMPLEMENTATION.md)

---

## 十、维护说明

### 内容更新

- 教学内容硬编码在 HTML 模板中
- 修改内容需编辑 `teaching_modal.html`
- 建议保留 HTML 结构，只修改文本内容

### 样式调整

- 主题色在 `teaching.css` 开头定义
- 可通过修改 CSS 变量快速调整主题

### 功能扩展

- 新增章节需同步修改：
  - `teaching_modal.html` (内容)
  - `teaching-modal.js` (导航)
  - `teaching.css` (样式)

---

*文档结束*
