# 需求：R-014 持仓内存快照（服务端 10s 定时同步，请求不再穿透 QMT）

> 登记：2026-09-02 ｜ 来源：架构梳理讨论 + 老师指令 ｜ 状态：**已定稿（老师逐项拍板 4 问）**
> 归属：迭代 12 ｜ 计划：PLAN-013


> **归档头（2026-09-08）** ｜ 需求状态：已完成 ｜ 归档日期：2026-09-08 ｜ 实现迭代：12-持仓内存快照（持仓内存快照）
> 讨论记录索引：R-014.md 正文；实现细节见 04-迭代记录/12-持仓内存快照/
> 归档路径：05-需求池/已完成/R-014.md
> 迭代状态标记：已实现（迭代 12，回归 34/34 + typecheck + build 通过）→ 已归档（2026-09-08 老师归档指令确认验收）

## 需求描述

原实盘持仓数据在**每次请求时穿透 QMT**（`PositionManager.getAllPositions()` 实时拉 `/trade/positions`），带来两个问题：

1. **QMT 一抖（超时/掉线），策略持仓 / 全部持仓 / 未分配三个页面当场空白**——因为拼装以 QMT 返回行为驱动表，QMT 返回空则整页无行；
2. **每次进 tab 都打一次 QMT HTTP**，且部分实盘字段（volume/available/frozenVolume/price/marketValue/profit/profitPct 七个）该页面根本不消费，属搭车字段。

老师拍板优化：**服务端建缓存（内存快照），以快照为准，每 10 秒与 QMT 同步一次；策略持仓等接口相信快照，去掉请求时穿透 QMT 的逻辑。**

## 讨论记录（2026-09-02，三问拍板）

| # | 问题 | 结论（老师拍板） |
|---|---|---|
| 1 | 落库还是内存？（AI 初版方案建 SQLite 缓存表，老师质疑） | **纯内存管理，不落库**。理由（老师追问后 AI 论证修正）：持仓快照随时可用一次调用重拿全，不满足落库任一正当条件（不可再生历史 / 重启首屏依赖）；落库反引入「过期快照冒充实时的说谎风险」；不复用 strategy_holdings（账本 ≠ 对账单，holding_id 是交易归属锚点，不可掺易变快照） |
| 2 | 首启缓存未预热 / QMT 从未连上时，前端请求怎么办？ | **读穿透兜底**：缓存为空当场拉一次 QMT 并回填；QMT 也挂才报错（前端既有 LoadState 重试 UI 兜住） |
| 3 | QMT 里卖光的票，本地持仓记录（幽灵条目）怎么办？ | **同步时自动清仓**：QMT 快照连续 3 轮（约 30s）消失的 code，本地全部策略当前持仓自动转历史（不物理删除）；加防抖护栏（账户身份守卫）防误清 |
| 4 | 前端要不要显示同步时间（数据最多滞后 10s）？ | **本轮不加**，前端零改动；10s 级滞后对持仓场景够用 |

## 边界

**做**：内存快照同步服务（PositionSync）、getAllPositions 改读快照 + 读穿透兜底、空快照双重确认、幽灵持仓自动清仓（防抖 + 账户守卫）、回归脚本。

**不做**：不落库（无新表、无 schema 变更）；不同步时间前端显示；部分减持（QMT 仍有但变少 → 负数未分配）的自动修正（维持 UI 暴露现状，后续可另立需求）；策略份额账本（strategy_holdings）的任何改动。

## 验收

见 `docs/04-迭代记录/12-持仓内存快照/验收标准.md`。