FA3-Datafetch/DOC/implementation_plan.md

实施计划：财务数据获取与分析系统 (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 文件，确认内容与旧版报告基本一致，数据完整，格式正确。