Fundamental_Analysis/docs/3_project_management/logs/20251106_[Archived]_log.md

2025-11-06 开发日志

今日概览

• 多市场“昨日快照”接口落地（CN/US/HK/JP）并在报告页新增快照卡片
• 美股数据链路增强：Finnhub 支持 SDK+HTTP 兜底与标准化映射，YFinance 兼容CN代码规则
• 财务报表聚合与 period 统一（YYYYMMDD），去重并按年限裁剪；日度行情/估值按报告期对齐
• 分析执行体验优化：顺序流式、可停止/继续、单模块重试、耗时/进度统计
• 配置与文档：Prisma 读取 config/config.json 数据库URL；补充“财务数据字典”和项目状态说明

---

后端（FastAPI）

DataManager 与数据源策略

• backend/app/data_manager.py
  • 只从 config/config.json 读取各 Provider 的 api_key（不再读取环境变量），初始化受控更清晰
  • 依据 config/data_sources.yaml 的市场优先级，按序尝试 tushare、yfinance、finnhub 等 Provider
  • 统一 get_data 成功判定与异常兜底，支持多返回类型（list/dict/标量）
  • get_financial_statements：将扁平报表数据规范化为 series 结构，确保数值可序列化

Finnhub Provider（美股重点）

• backend/app/data_providers/finnhub.py
  • 初始化增加 Token 掩码日志；SDK 失败时自动回退到 HTTP 接口（profile2、financials-reported）
  • get_stock_basic 标准化公司基本信息；get_daily_price 输出 {trade_date, open, high, low, close, vol}
  • get_financial_statements 将 financials-reported 年度数据映射为内部字段，计算派生比率：grossprofit_margin、netprofit_margin、roa、roe，并直接输出 series

YFinance Provider（兼容与映射）

• backend/app/data_providers/yfinance.py
  • 适配中国代码：.SH -> .SS，.SZ 优先尝试无后缀
  • 规范化 stock_basic、日线行情与年度财务（合并利润表/资产负债表/现金流），提供基础字段重命名

财务与分析路由

• backend/app/routers/financial.py
  • 新增“昨日快照”接口：
    • GET /api/financials/china/{ts_code}/snapshot：优先 daily_basic，兜底 daily
    • GET /api/financials/{market}/{stock_code}/snapshot：CN 复用上式；其他市场用日线在近10日内回看最近交易日
  • GET /api/financials/{market}/{stock_code}：
    • 一次性拉取并聚合年度财报 series；识别当年最新报告期，将估值/股价按报告期映射
    • 统一 period（优先 YYYYMMDD，缺失则由 year 映射为 YYYY1231），去重、排序并按 years 裁剪
  • 保持分析编排/单模块/流式接口与分析配置读写接口，便于前端顺序流式展示

---

前端（Next.js 15 / React 19）

报告页体验

• frontend/src/app/report/[symbol]/page.tsx
  • 新增“昨日快照”卡片：日期、股价、PE、PB、股息率、总市值（亿元）
  • 分析执行：顺序流式、可停止/继续、总进度与耗时、单模块“重新生成分析”
  • 财务表格：统一 period，扩充指标（人均效率、费用率、资产占比、周转能力、市场表现等）并突出关键阈值

数据获取 Hooks

• frontend/src/hooks/useApi.ts
  • 新增 useChinaSnapshot、useSnapshot；统一市场参数（china/us/hk/jp）与 SWR 策略
  • fetcher 强化：兼容非标准 JSON 的错误返回，统一抛出可读错误

Prisma 适配

• frontend/src/lib/prisma.ts
  • 从 config/config.json 动态解析数据库URL；将 postgresql+asyncpg:// 转换为 Prisma 需要的 postgresql://，默认追加 schema=public
  • 开发环境下复用单例，减少连接开销

---

文档

• 新增：docs/financial_data_dictionary.md（统一字段口径与来源映射）
• 更新：docs/project-status.md（现状、限制与后续计划）；docs/user-guide.md（报告页、快照与分析流程）
• 清理：删除 docs/tasks.md

---

风险与注意事项

• Provider 密钥现仅从 config/config.json 读取；未配置将跳过需密钥的数据源（日志有警告）
• 美股字段映射存在口径差异，个别指标为近似计算，需结合“财务数据字典”持续校验
• 单模块分析尝试附带最近年度财报上下文，边界与稳定性需结合真实数据回归

---

验收建议

• 快照：
  • CN: GET /api/financials/china/600519.SH/snapshot
  • US: GET /api/financials/us/AAPL/snapshot
• 报告页：访问 /report/600519?market=china 验证快照卡片、顺序流式与保存按钮
• 多源融合：调整 config/data_sources.yaml 优先级，观察回退与成功率日志
• 数据库：在无 .env 的场景下，确认 Prisma 能从 config/config.json 正确加载连接串