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

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

## 任务列表

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

- [x] **后端：按市场分段的 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`）。
  - **关键点**：
    - [x] 去除硬编码的 `china`，新增路径参数 `market`，并对取值做校验（`cn/us/hk/jp`）。
    - [x] 使用单一处理函数，根据 `market` 分派到相应的数据提供方与代码格式规范。

- [x] **前端：更新 API 调用**
  - **目标**：修改前端调用，基于用户选择的市场与股票代码，请求新的按市场分段路由。
  - **关键点**：
    - [x] 替换 `useChinaFinancials`，新增通用 `useFinancials(market, stockCode, years)`。
    - [x] 将请求路径改为 `/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`；空值以 `-` 展示。