FA3-Datafetch/DOC/implementation_plan.md

实施计划：财务数据获取与分析系统

目标描述

开发一个后端工具，用于获取中国、香港、美国及日本股市的10年财务报表，保存到本地，计算财务指标，并输出带有样式的 Markdown 报告。

用户需确认事项

• API Keys: 需要 Tushare 和 Alpha Vantage 的 API Key。
• 日本市场数据: Alpha Vantage 对日股财务数据的支持情况待验证。
• 财务指标: 需确认具体的计算指标列表。

拟定变更

1. 项目初始化

• 创建项目目录结构。
• 初始化依赖管理 requirements.txt (pandas, requests, tushare, alpha_vantage)。
• 创建 .env 文件用于存放 API Keys。

2. 模块：数据获取器 (src/fetchers)

• 定义抽象基类 DataFetcher。
• TushareFetcher (CN & HK):
  • 实现与 Tushare 的连接。
  • 方法：获取利润表、资产负债表、现金流量表。
  • 适配 A 股和港股代码后缀。
• AlphaVantageFetcher (US & JP):
  • 实现与 Alpha Vantage 的连接。
  • 方法：同上。
  • 针对日本市场进行适配测试。
• 工厂模式: get_fetcher(market, api_keys) 根据市场返回对应的获取器实例。

3. 模块：数据存储 (src/storage)

• 实现将 DataFrame 保存为 CSV 的功能。
• 目录结构：data/{market}/{stock_code}/{statement_type}.csv。

4. 模块：分析器 (src/analysis)

• 加载本地 CSV 数据。
• 计算指标 (初步规划):
  • 盈利能力: ROE (净资产收益率), Net Profit Margin (净利率), Gross Margin (毛利率)。
  • 偿债能力: Debt-to-Equity (产权比率/负债权益比), Current Ratio (流动比率)。
  • 成长能力: Revenue Growth (营收增长率), Net Income Growth (净利增长率)。
• 返回汇总的 DataFrame。

5. 模块：报告生成器 (src/reporting)

• 类 MarkdownReporter.
• 方法 generate_table(indicator_data).
• 样式实现:
  • 使用 HTML <table> 标签嵌入 Markdown，通过 style="background-color: ..." 实现背景色。

验证计划

自动化测试

• 编写单元测试，Mock API 响应，测试数据解析逻辑。
• 测试指标计算公式的准确性。

人工验证

1. 中国/香港股票: 获取茅台 (600519.SH) 和 腾讯 (00700.HK)，检查文件是否生成，内容是否正确。
2. 美国/日本股票: 获取 Apple (AAPL) 和 Sony (6758.T)，检查数据获取情况。
3. 报告检查: 打开生成的 report.md，确认颜色样式能否正确渲染。