## 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` 正确加载连接串