# 实施计划：财务数据获取与分析系统 (V3.0) - Refactored

## 1. 目标描述
开发一个可扩展的后端工具，通过策略模式（Strategy Pattern）支持多市场（当前为中国A股、美股、港股）的财务数据分析。工具能够为每个市场定制数据获取、分析和报告生成的全过程，同时保持核心流程的统一和代码的清晰。

## 2. 核心架构：策略模式
系统采用策略模式，将每个市场的完整业务流程（“获取-存储-分析-报告”）封装在独立的策略类中。`main.py` 作为上下文，根据用户指定的市场，选择并执行相应的策略。

- **基础策略 (Base Strategy)**: 定义在 `src/strategies/base_strategy.py`，提供了一个所有具体策略都必须遵循的通用接口，如 `execute()` 方法，该方法依次调用 `fetch_data()`、`analyze_data()` 和 `generate_report()`。
- **中国市场策略 (CN_Strategy)**: `src/strategies/cn_strategy.py`，封装了针对A股的完整处理流程。
- **美国市场策略 (US_Strategy)**: `src/strategies/us_strategy.py`，封装了针对美股的完整处理流程。
- **香港市场策略 (HK_Strategy)**: `src/strategies/hk_strategy.py`，封装了针对港股的完整处理流程。

## 3. 核心执行流程 (通过策略)

### 步骤 1: 初始化与策略选择
- **目的**: 准备环境并根据市场选择合适的策略。
- **动作**:
    - 加载 `.env` 文件中的 `TUSHARE_TOKEN` 和 `ALPHA_VANTAGE_KEY`。
    - `main.py` 根据用户输入的 `market` 参数，通过一个简单的工厂函数 `get_strategy`，实例化 `CN_Strategy`、`US_Strategy` 或 `HK_Strategy`。

### 步骤 2: 策略执行流程
`main.py` 调用所选策略实例的 `execute` 方法，触发完整的分析流程。根据市场选择，执行路径如下：

---

#### **场景 A: 中国市场 (market='CN')**
选择中国市场时，`CN_Strategy` 的 `execute` 方法会按顺序执行以下操作：

1.  **数据获取 (`fetch_data`)**:
    - **执行**: `CN_Strategy` 实例化并调用 `CnFetcher` 来获取数据。
    - **API调用序列 (共7次)**:
        1. **获取利润表**: 调用 Tushare 的 `income` 接口 (1次)。
        2. **获取资产负债表**: 调用 Tushare 的 `balancesheet` 接口 (1次)。
        3. **获取现金流量表**: 调用 Tushare 的 `cashflow` 接口 (1次)。
        4. **获取市场指标 (PE/PB等)**: 调用 Tushare 的 `daily_basic` 接口 (1次)。
        5. **获取基本信息 (名称/日期)**: 调用 Tushare 的 `stock_basic` 接口 (1次)。
        6. **获取公司信息 (员工数)**: 调用 Tushare 的 `stock_company` 接口 (1次)。
        7. **获取股东信息**: 调用 Tushare 的 `stk_holdernumber` 接口 (1次)。
    - **数据存储 (两阶段缓存)**:
        - **1. 原始数据缓存**: `CnFetcher` 将API返回的原始数据保存为 `raw_*.csv`。
        - **2. 处理后数据缓存**: `CN_Strategy` 将初步处理过的数据保存为 `income_statement.csv` 等文件。

2.  **数据分析 (`analyze_data`)**:
    - **执行**: `CN_Strategy` 实例化 `CN_Analyzer`。
    - **动作**: `CN_Analyzer` 对获取的数据进行合并、列名映射 (`_map_columns`) 和A股特定的财务指标计算。

3.  **报告生成 (`generate_report`)**:
    - **调用**: `CN_Strategy` 调用 `CN_ReportGenerator` 实例的 `generate_report` 方法，传递分析数据和输出路径。
    - **核心动作**: `CN_ReportGenerator` 全权负责报告的生成与保存：
        1. **生成Markdown**: 调用继承自 `BaseReporter` 的 `_generate_markdown_content` 方法创建报告内容。
        2. **保存Markdown**: 将内容写入 `data/CN/{symbol}/report.md`。
        3. **生成HTML**: 使用 `markdown` 库将内容转换为 HTML，并嵌入预设的 CSS 样式。
        4. **保存HTML**: 将最终的 HTML 内容写入 `data/CN/{symbol}/report.html`。

---

#### **场景 B: 香港市场 (market='HK')**
选择香港市场时，`HK_Strategy` 的 `execute` 方法会按顺序执行以下操作：

1.  **数据获取 (`fetch_data`)**:
    - **执行**: `HK_Strategy` 实例化并调用 `HkFetcher` 来获取数据。
    - **API调用序列 (共7次)**:
        1. **获取利润表**: 调用 Tushare 的 `hk_income` 接口 (1次)。
        2. **获取资产负债表**: 调用 Tushare 的 `hk_balancesheet` 接口 (1次)。
        3. **获取现金流量表**: 调用 Tushare 的 `hk_cashflow` 接口 (1次)。
        4. **获取市场指标 (PE/PB等)**: 调用 Tushare 的 `daily_basic` 接口 (1次)。
        5. **获取基本信息 (名称/日期)**: 调用 Tushare 的 `stock_basic` 接口 (1次)。
        6. **获取公司信息 (员工数)**: 调用 Tushare 的 `stock_company` 接口 (1次)。
        7. **获取股东信息**: 调用 Tushare 的 `stk_holdernumber` 接口 (1次)。
    - **数据存储 (两阶段缓存)**:
        - **1. 原始数据缓存**: `HkFetcher` 将API返回的原始数据保存为 `raw_*.csv`。
        - **2. 处理后数据缓存**: `HK_Strategy` 将初步处理过的数据保存为 `income_statement.csv` 等文件。

2.  **数据分析 (`analyze_data`)**:
    - **执行**: `HK_Strategy` 实例化 `HK_Analyzer`。
    - **动作**: `HK_Analyzer` 对获取的数据进行合并、列名映射和港股特定的财务指标计算。

3.  **报告生成 (`generate_report`)**:
    - **调用**: `HK_Strategy` 调用 `HK_ReportGenerator` 实例的 `generate_report` 方法，传递分析数据和输出路径。
    - **核心动作**: `HK_ReportGenerator` 全权负责报告的生成与保存：
        1. **生成Markdown**: 调用继承自 `BaseReporter` 的 `_generate_markdown_content` 方法创建报告内容。
        2. **保存Markdown**: 将内容写入 `data/HK/{symbol}/report.md`。
        3. **生成HTML**: 使用 `markdown` 库将内容转换为 HTML，并嵌入预设的 CSS 样式。
        4. **保存HTML**: 将最终的 HTML 内容写入 `data/HK/{symbol}/report.html`。

---

#### **场景 C: 美国市场 (market='US')**
选择美国市场时，`US_Strategy` 的 `execute` 方法会按顺序执行以下操作：

1.  **数据获取 (`fetch_data`)**:
    - **执行**: `US_Strategy` 实例化并调用 `UsFetcher`。
    - **API调用序列 (共4次, 每次调用前有15秒延迟)**:
        1. **获取利润表**: 调用 Alpha Vantage 的 `INCOME_STATEMENT` 功能 (1次)。
        2. **获取资产负债表**: 调用 Alpha Vantage 的 `BALANCE_SHEET` 功能 (1次)。
        3. **获取现金流量表**: 调用 Alpha Vantage 的 `CASH_FLOW` 功能 (1次)。
        4. **获取公司概览**: 调用 Alpha Vantage 的 `OVERVIEW` 功能 (1次)，用于计算市值、PE、PB等核心指标。
    - **数据存储 (两阶段缓存)**:
        - **1. 原始数据缓存**: `UsFetcher` 将API返回的原始数据保存为 `raw_*.csv`。
        - **2. 处理后数据缓存**: `US_Strategy` 将初步处理过的数据保存为 `income_statement.csv` 等文件。

2.  **数据分析 (`analyze_data`)**:
    - **执行**: `US_Strategy` 实例化 `US_Analyzer`。
    - **动作**: `US_Analyzer` 对获取的数据进行合并、列名映射和美股特定的计算逻辑。

3.  **报告生成 (`generate_report`)**:
    - **调用**: `US_Strategy` 调用 `US_ReportGenerator` 实例的 `generate_report` 方法，传递分析数据和输出路径。
    - **核心动作**: `US_ReportGenerator` 全权负责报告的生成与保存：
        1. **生成Markdown**: 调用继承自 `BaseReporter` 的 `_generate_markdown_content` 方法创建报告内容。
        2. **保存Markdown**: 将内容写入 `data/US/{symbol}/report.md`。
        3. **生成HTML**: 使用 `markdown` 库将内容转换为 HTML，并嵌入预设的 CSS 样式。
        4. **保存HTML**: 将最终的 HTML 内容写入 `data/US/{symbol}/report.html`。

## 4. 验证计划
- **核心逻辑不变**: 由于核心的数据获取和指标计算逻辑是从旧代码平移而来，其准确性得以保留。
- **结构验证**: 
    1. **中国股票**: 运行 `python main.py CN 600519.SH`。检查程序是否无报错执行完毕，并生成 `data/CN/600519.SH/report.md` 文件。
    2. **香港股票**: 运行 `python main.py HK 00700.HK`。检查程序是否无报错执行完毕，并生成 `data/HK/00700.HK/report.md` 文件。
    3. **美国股票**: 运行 `python main.py US AAPL`。检查程序是否无报错执行完毕，并生成 `data/US/AAPL/report.md` 文件。
    4. **报告内容**: 打开生成的 `.md` 文件，确认内容与旧版报告基本一致，数据完整，格式正确。