Fundamental_Analysis/docs/未完成任务/us_market_integration_tasks.md

美国市场数据集成任务清单

本文档用于跟踪和管理为项目集成美国市场数据（使用 Finnhub 作为数据源）所需的各项开发任务。

任务列表

• 后端：实现 FinnhubProvider 数据映射

  • 目标：根据 docs/financial_data_dictionary.md 中的定义，在 backend/app/data_providers/finnhub.py 文件中，完成从 Finnhub API 原始数据到系统标准字段的完整映射。
  • 关键点：
    • 处理直接映射的字段。
    • 实现所有需要通过计算得出的衍生指标。
    • 确保处理 null 或空值，避免计算错误。
    • 验证返回的数据结构符合 DataManager 的预期。

• 后端：按市场分段的 API 路由

  • 目标：在 backend/app/routers/financial.py 中，将现有的 /api/v1/financials/china/{ts_code} 改为按市场分段：/api/v1/financials/{market}/{stock_code}（示例：/api/v1/financials/us/AAPL，/api/v1/financials/cn/600519.SH）。
  • 关键点：
    • 去除硬编码的 china，新增路径参数 market，并对取值做校验（cn/us/hk/jp）。
    • 使用单一处理函数，根据 market 分派到相应的数据提供方与代码格式规范。

• 前端：更新 API 调用

  • 目标：修改前端调用，基于用户选择的市场与股票代码，请求新的按市场分段路由。
  • 关键点：
    • 替换 useChinaFinancials，新增通用 useFinancials(market, stockCode, years)。
    • 将请求路径改为 /api/financials/{market}/{stock_code}?years=...（代理到后端对应的 /api/v1/financials/{market}/{stock_code}）。
    • 确保展示与错误处理兼容美国、香港、日本等市场。

• 测试与验证

  • 目标：对整个流程进行端到端测试，确保两个市场的功能都稳定可靠。

  • 关键点：

    • 中国市场回归测试：使用多个中国 A 股代码测试，确保原有功能不受影响。
    • 美国市场功能测试：使用多个美国股票代码（如 AAPL, MSFT）测试，验证报告能否成功生成。
    • 数据一致性验证：抽样对比 Finnhub 返回的数据和前端展示的数据，确保映射和计算的准确性。
    • 错误处理测试：测试无效的股票代码，检查系统是否能给出清晰的错误提示。

  • 前置条件：

    • 在 config/config.json 或环境变量中配置 FINNHUB_API_KEY。
    • 后端已启动（默认 http://127.0.0.1:8000/api），前端已启动（默认 http://127.0.0.1:3000）。

  • 接口用例（后端）：

    • GET /api/v1/financials/cn/600519.SH?years=10
      • 期望：200；返回 ts_code、name、series（含 revenue、n_income 等关键指标，period/年序列齐全）。
    • GET /api/v1/financials/cn/000001.SZ?years=5
      • 期望：200；返回与上同，近 5 年序列。
    • GET /api/v1/financials/us/AAPL?years=10
      • 期望：200；series 至少包含：revenue、n_income、total_assets、total_hldr_eqy_exc_min_int、__free_cash_flow、grossprofit_margin、netprofit_margin、roe、roa。
    • GET /api/v1/financials/us/MSFT?years=10
      • 期望：200；字段与口径同 AAPL。
    • GET /api/v1/financials/us/INVALID?years=10
      • 期望：4xx/5xx；detail.message 含可读错误。

  • 页面用例（前端）：

    • 打开 /report/600519.SH?market=cn
      • 期望：基本信息与“昨日快照”显示；“财务数据（来自 Tushare）”表格展示 10 期内主要指标。
    • 打开 /report/000001.SZ?market=cn
      • 期望：与上同；代码规范化逻辑（无后缀时自动补 .SZ/.SH）正常。
    • 打开 /report/AAPL?market=us
      • 期望：“股价图表”正常；“财务数据”表格展示主要指标（含自由现金流、毛利率、净利率、ROA、ROE）。
    • 打开 /report/MSFT?market=us
      • 期望：与上同。
    • 打开 /report/INVALID?market=us
      • 期望：顶部状态为“读取失败”并有错误提示文案。

  • 验收标准：

    • 中国市场功能无回归；美国市场关键指标齐全、值域合理（百分比类 ∈ [-1000%, 1000%]，金额类为有限数）。
    • 报错信息清晰可读；网络/密钥缺失时提示明确。
    • 页内主要表格不出现 NaN/Infinity；空值以 - 展示。