# 股票池基本面数据准备

财务因子目录描述计算能力；策略需要的财报、市值等观测值保存在
`qd_fundamental_snapshots`。AI 投研页面临时获取的数据，不等同于策略已经拥有完整的历史基本面。

## 管理员操作

1. 在系统设置的市场数据管理区域，确认股票池及其成员已同步。
2. 打开“基本面数据准备”，选择股票池。标普500策略选择 `sp500`。
3. 选择所需字段。盈利、市值筛选至少需要 `market_cap` 和 `net_income`；这里的净利润为最近报告期，非自动 TTM。
4. 美股选择“历史财报”，点击“同步股票池基本面”。港股、A股当前支持“当前快照”。
5. 查看任务进度和失败股票。失败项自动最多尝试三次，之后可以单独重试失败股票。
6. 按策略最近一根已完成行情的日期检查覆盖。日期默认上一个工作日，遇到交易所节假日需要调整。
7. 可勾选每日检查。调度使用启用时选定的模式和字段；修改字段后需重新设置每日检查。

## 首次补齐与增量检查

手动同步和定时任务默认都先查本地数据库，仅为需要采集的股票创建任务项。
首次没有数据时会采集全池；已有可复用的历史数据时直接复用。每次检查都会重新读取股票池成员，新增成员缺少数据时自动补采。
页面显示本次采集数量和跳过数量；跳过也可能是失败后的冷却等待，不等于该股票数据已经齐全，实际完整性仍看覆盖表。

- 美股历史财报：所需字段缺失或财报过期时补采；字段齐全且财报期结束不足100天时，每7天复查一次；满100天后每24小时复查一次。
- 这是按报告期推算的轮询策略，没有接入准确的财报发布事件流。非密集检查期，新披露数据可能延迟约一周发现；数据源异常时更久。
- 当前快照：保持每24小时更新，避免把当前估值字段长期当作新鲜数据。
- 一轮三次尝试均失败后，等待24小时再进入下一批自动任务。新增字段要求不受旧要求的失败冷却限制。
- “重试失败股票”立即重试；“强制全量刷新”只作用于本次手动同步，不会把每日调度改回全量。
- 当前快照不会替代首次历史财报导入；历史检查只复用历史导入来源。
- 股价变化不触发历史财报重拉：策略面板已有的市值计算使用行情收盘价乘以已知股数。股数仍依赖财报更新，并非实时股本事件订阅。

增量粒度为股票。选中股票后仍使用原有历史导入器检查其可获取的财报期，按唯一键更新，非新增一套逐财报事件采集服务。

“字段齐全”只表示当前成员在指定日期存在要求的字段且财报期未超过200天。
它不代表行情完整、历史成分股准确、整个回测区间可用或跨币种估值口径一致。
负数或零净利润是有效数据，不应当作数据缺失；盈利条件由策略另行判断。

## 部署要求

同时更新前端、API、Celery Worker 和 Celery Beat。启动迁移会从 `migrations/init.sql`
创建任务、任务股票、调度三张表；独立 SQL 为
`backend_api_python/migrations/20260913_fundamental_sync.sql`。

Worker 必须消费 `maintenance` 队列。Beat 每分钟触发检查，任务逐只处理股票，
成功处理后继续排队。每日检查为约24小时间隔，并非固定交易所收盘时刻。
任务与重试状态保存在 PostgreSQL，服务重启后可以继续；失联任务租约为5分钟。
外部数据请求不占用数据库连接。重复提交同一股票池返回已有活动任务。

管理员接口：

- `GET /api/factors/fundamentals/universe/{id}`：最新任务、调度和指定日期覆盖。
- `POST /api/factors/fundamentals/universe/{id}/sync`：批量同步或重试失败股票。
- `POST /api/factors/fundamentals/universe/{id}/schedule`：启用或关闭每日更新。

排队超过一分钟时，先检查 Beat、maintenance Worker 和 Redis。
失败原因显示为缺失/过期或采集/写入失败；详细异常可按股票和任务号查询后端日志。

## 数据和因子口径

- 当前快照不会回填到过去，不能用今天采集的数据伪造过去已知的信息。
- 美股历史导入使用数据源提供的财报披露日期，并保守地从次日生效；无法确定披露时间的记录跳过。
- 当前历史源为 yfinance 季度财报，历史长度和字段覆盖受数据源限制，也不能保证是未重述的原始披露版本。
- 账面市值比使用股东权益总额除以总市值，修正每股账面值与公司总市值混用的问题。
- 营收增长读取报告字段，历史导入按去年同季计算，修正按相邻交易日比较导致的零增长。
- 财务字段缺失时不再悄悄使用更早的非空值。净利润、权益回报和现金流收益口径不自动年化。

## 本地验收（2026-09-13）

在独立 Docker PostgreSQL、Redis、API、Celery Worker/Beat 环境中：

- 真实数据源对 AAPL 导入5期财报；AAPL、MSFT、ABBV 三股经真实任务队列全部落库，指定日期覆盖3/3。
- 实际挂载的管理面板完成同步、进度、覆盖展示；每日更新保存后由 Beat 再次执行，3/3成功。
- Docker 集成测试验证权限、落库后供策略读取、失败重试、并发领取、中断恢复、日期隔离和调度持久化。
- 前端行为测试验证股票池切换时旧响应不会覆盖新结果、清空字段不会卡住加载状态、非美股使用快照模式。
- 增量集成测试验证二次检查不再采集已更新股票、新成员只补采新增项、快照与历史隔离、失败冷却及手动强制刷新。
- 对已采集真实数据的三股股票池再次执行增量检查：任务41直接完成，跳过3只、采集0只。
- 增量版本后端回归2338项、Docker集成9项、前端247项通过；生产构建及后端质量检查通过。

浏览器测试使用隔离账号的组件测试页；完整应用登录因测试环境验证码配置未通过，本次不声称完整登录导航已验收。
测试没有提交真实证券订单，也未同步验收整个标普500。云端更新后仍需运行全股票池同步并检查实际覆盖。