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

CONTEXT.md

@@ -0,0 +1,28 @@
+# 知行量化研究上下文
+
+本上下文描述 A 股市场数据同步与选股策略分析中的业务语言，重点保证历史结果可以被可靠复现。
+
+## 分析语义
+
+**历史可复现分析**：给定一个历史交易日，在当前目标股票池范围内重建该日的行情与估值状态；价格采用数据库中当前最新修订的前复权行情，不要求还原某次同步时的价格版本。
+_Avoid_: 用当前市值回填历史、把当前目标股票池当作无幸存者偏差的长期回测宇宙
+
+## 市场数据
+
+**股票主数据**：描述证券标识及其在市场中的基础状态，例如代码、名称、交易所和上市状态。
+
+**当前目标股票池**：同步时仍处于上市状态的沪深 A 股集合，排除 ST/风险警示股和北交所股票，也不包含退市股票的长期历史成员资格。
+
+**有效选股股票池**：当前目标股票池中，行情和所需估值数据均已同步到目标交易日的股票集合；数据仍停留在更早交易日的股票不参与当天选股。
+
+**日线行情**：以证券和交易日为粒度记录的开盘价、最高价、最低价、收盘价和成交量等交易结果。
+
+**前复权行情**：按 `qfq` 口径整理的日线价格序列，作为当前选股策略分析的唯一价格口径。
+
+**估值快照**：在某个交易日可见的证券估值与交易活跃度指标，例如总市值、流通市值和换手率。
+
+**行情落地快照**：一次同步从数据源取得的完整行情集合，用于核对和传递数据，不承担策略查询职责。
+
+**同步批次**：一次面向当前目标股票池的市场数据同步运行；批次可以全部成功、部分成功或失败，并保留每只股票的处理结果。
+
+**数据覆盖率**：目标交易日内，有效选股股票数占当前目标股票池目标数的比例，用于判断选股结果是否具备足够完整性。

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 都只承诺滚动保留最近六年；如果未来需要更长周期回测，应重新评估数据范围并回补历史数据。