lyman/Fundamental_Analysis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
Fundamental_Analysis/docs/未完成任务/us_market_integration_tasks.md
xucheng ca60410966 feat: 通用市场财务/快照/分析接口；增强数据源与配置读取 
Backend
- router(financial): 新增通用路径 /{market}/{stock_code}、/snapshot、/analysis/stream
  - 用 MarketEnum 统一市场（cn/us/hk/jp）
  - 将 /china/{ts_code} 改为通用 get_financials，并规范 period，按年限裁剪
  - 新增通用昨日快照接口（CN 复用原逻辑，其他市场兜底近交易日收盘）
- data_manager: 仅从 config/config.json 读取各 provider API key，不再读取环境变量
  - series 构建更健壮：None/空结构判定；接受 numpy/pandas 数值类型并安全转 float
- provider(finnhub):
  - SDK 失败时使用 httpx 直连兜底（profile2、financials-reported）
  - 规范化年度报表，映射 revenue/net income/gross profit/assets/equity/goodwill/OCF/CapEx
  - 计算 gross/net margin、ROA、ROE；直接产出 series 结构
  - 增加关键步骤日志与异常保护
- provider(yfinance): 修正同步阻塞的获取逻辑，使用 run_in_executor 包装

Frontend
- hooks(useApi):
  - 将中国财务接口路径改为 /api/financials/cn
  - 新增 useFinancials 与 useSnapshot，统一多市场数据访问
- report/[symbol]/page.tsx:
  - 支持多市场（映射 usa→us、china→cn 等），统一 symbol 与分析流路径
  - 去除仅限中国市场的 UI 限制，财务/分析/图表对多市场可用
  - 使用新的分析与快照 API 路径
- lib/prisma.ts: 去除无关内容（微小空行调整）

Docs
- 重组文档目录：
  - docs/已完成任务/tasks.md（重命名自 docs/tasks.md）
  - docs/未完成任务/us_market_integration_tasks.md 新增

BREAKING CHANGE
- API 路径变更：
  - 财务数据：/api/financials/china/{ts_code} → /api/financials/{market}/{stock_code}
  - 快照：/api/financials/china/{ts_code}/snapshot → /api/financials/{market}/{stock_code}/snapshot
  - 分析流：/api/financials/china/{ts_code}/analysis/{type}/stream → /api/financials/{market}/{stock_code}/analysis/{type}/stream
- 前端需使用 useFinancials/useSnapshot 或更新为 /cn 路径以兼容中国市场
2025-11-06 20:01:08 +08:00

4.5 KiB
Raw Permalink Blame History

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

本文档用于跟踪和管理为项目集成美国市场数据（使用 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；空值以 - 展示。