docs(market-data): 补充同步架构上下文

docs/adr/0003-postgresql-as-market-data-store.md

@@ -0,0 +1,25 @@
+---
+status: accepted
+---
+
+# 市场数据以 PostgreSQL 为主存储
+
+为支持历史可复现分析、按交易日查询、增量同步和跨标的策略分析，标准化的股票池、日线行情与估值数据统一落入 PostgreSQL。CSV 不作为运行时事实源，仅作为 Tushare 落地快照、导出和故障恢复介质；策略层通过仓储接口读取 DataFrame，以隔离分析逻辑与存储技术。
+
+第一阶段同步范围包含股票主数据、日线行情和每日估值/交易指标；只迁移 K 线会无法重建当前股票池内的历史走势及市值/流动性条件。股票范围保持当前上市的沪深非 ST A 股，不包含北交所，也不维护退市股票的长期历史成员资格。价格数据只保留 Tushare `qfq` 前复权口径，不将未复权或 `hfq` 作为运行时事实。历史分析按交易日复现当前股票池内的行情与估值状态，但使用数据库中最新修订的 qfq，不承诺恢复某次同步时的 qfq 版本。
+
+第一阶段只同步日线收盘数据，不覆盖分钟级或实时行情。
+
+## Considered Options
+
+- **按股票拆分 CSV 作为主存储**：保留旧项目的低门槛结构，但难以保证跨标的一致性、时点查询和增量修订。
+- **SQLite 作为主存储**：适合单机原型，但与后续服务化、多进程同步和并发分析的目标不匹配。
+
+## Consequences
+
+- 需要设计 PostgreSQL schema、索引、迁移和备份策略。
+- 同步任务必须具备批次记录、幂等 upsert 和失败重试能力。
+- CSV 导出格式属于交付/快照契约，不再承担在线查询职责。
+- 若未来需要未复权或 `hfq` 分析，必须重新回补数据，不能从当前主表无损推导。
+- “历史可复现”不等同于恢复历史抓取版本；qfq 的供应商修订会改变历史价格，但不改变股票池和估值的交易日时点约束。
+- 当前方案不覆盖长期回测所需的退市股票、历史上市状态和无幸存者偏差股票池；若需求改变，应另立数据范围决策。

docs/adr/0004-tushare-six-year-snapshot-sync.md

@@ -0,0 +1,33 @@
+---
+status: accepted
+---
+
+# Tushare 同步采用六年落地快照与重叠区间指纹
+
+每日同步由外部调度器触发；应用对当前目标股票池逐只获取最近六年的 Tushare qfq 日线，形成 CSV 落地快照。新旧快照先比较完整历史重叠区间：指纹相同时只向 PostgreSQL 插入新交易日，指纹不同时对该股票最近六年执行幂等 upsert；一只股票的数据变化不会触发全市场回写。
+
+单只股票按“生成临时 CSV → 校验并比较重叠区间 → 提交 PostgreSQL 事务 → 原子替换正式 CSV”的顺序同步。PostgreSQL 提交失败时不替换正式 CSV，保证运行时事实源和已发布落地快照不会出现新旧倒置。
+
+单只股票也是事务和重试边界。部分股票失败时，批次标记为 `partial_success`，已成功股票不回滚；失败股票保留旧 PostgreSQL 数据和旧 CSV，并在后续只重试失败集合。
+
+`partial_success` 可以触发后续选股，但只能使用行情和所需估值数据均已到达目标交易日的有效股票；失败股票不得使用旧数据冒充当天行情，选股结果必须携带覆盖率和失败列表。
+
+自动选股的默认最低数据覆盖率为 `99%`，并允许通过配置调整。低于阈值时只报告同步结果并优先重试失败股票；人工强制运行必须把选股结果标记为不完整。
+
+六年窗口按目标交易日滚动。单只股票同步事务成功时删除窗口起点之前的 PostgreSQL 日线，并以只包含当前窗口的新文件原子替换正式 CSV；每日估值/交易指标及其日期快照采用相同的滚动保留边界。失败对象不发布新 CSV，也不因本次失败提前丢失其原有数据。该边界符合当前系统关注近期走势而非长期回测的定位。
+
+## Considered Options
+
+- **仅请求最新增量日期**：请求次数没有明显减少，却无法自然发现历史 qfq 修订。
+- **只比较最近一周**：能发现常见的近期除权变化，但可能漏掉供应商对更早历史数据的修正。
+
+## Consequences
+
+- CSV 是同步落地快照，PostgreSQL 仍是策略查询的事实源。
+- 指纹必须基于规范化、排序后的共同日期区间和固定字段集合，避免浮点文本差异造成误判。
+- PostgreSQL 写入以 Tushare `(ts_code, trade_date)` 为唯一键；未变化时只写新日期，变化时仅回写发生变化的股票。
+- 批量修复应通过 staging 表与批量装载完成，避免逐行 ORM 写入。
+- 临时 CSV 只有在对应 PostgreSQL 事务提交成功后才能晋升为正式落地快照；重复执行同一批次必须保持幂等。
+- 同步批次需要记录每只股票的成功、失败、插入、更新和未变化结果，以支持部分成功与定向重试。
+- 选股批次需要关联对应同步批次，并记录实际参与股票数、目标股票数和数据覆盖率。
+- PostgreSQL 与 CSV 都只承诺滚动保留最近六年；如果未来需要更长周期回测，应重新评估数据范围并回补历史数据。