# 计划：策略 tab 历史持仓展示（显示/隐藏已清仓持仓 + 清仓时间范围筛选）（阶段航点）

> 编号：PLAN-015 ｜ 粒度：阶段航点 ｜ 创建：2026-09-07 ｜ 状态：**已实施（待验收）**
> 派生自终极目标：目标-003（按策略监控市场）、目标-008（真实交易系统接入）
> 依据需求：**R-016（已定稿，2026-09-07，Q1-Q7 老师拍板）** —— 符合入范围门槛
> 设计约束：新增 技术约束-019（历史持仓查询走本地库，当前持仓快照语义不掺历史）

## 目标

两个策略 tab（做T / 网格超市）title 旁提供「历史持仓」开关 + 清仓时间范围筛选（默认近一周，另有近 1 个月 / 近 3 个月 / 近半年 / 近 1 年）；历史持仓行可展开查看关联交易记录（复用 R-010），补上「清仓即失联」的操作追溯缺口。

## 范围

**做**：
1. **存储层**（SqliteStore）：新增 getHoldingsHistory(strategyId, { sinceMs }) —— closed_at 非空 + closed_at ≥ sinceMs 过滤 + 按 closed_at DESC 排序（读只读，零写路径变更，不改 closeHolding 语义）；
2. **门面层**（DataStore）：getHoldingsHistory 透传（await _ensure 后委托）；
3. **API**：新增 strategy-holdings/history 端点（args: strategyId 必填 + range ∈ week|month|quarter|halfYear|year，服务端换算 sinceMs；缺失/非法参数报参数错误）；strategy-positions 等现有端点零改动；
4. **前端 StrategyTab**：
   - 头部按钮区（+ 添加持仓 / 列设置 旁）新增「历史持仓」开关按钮 + 范围下拉（仅开关开启时显示；默认 week）；
   - 开启时懒加载历史数据（切换范围重新拉取；关闭即隐藏不销毁缓存）；进 tab 默认关（会话级，不持久化）；
   - 历史行渲染在当前持仓行之后：代码 / 名称（关联委托 name 兜底，无则 —）/ 份额（显示 DB 原值 0，Q2）/ 清仓时间 / 持有天数；实时行情列（现价/涨幅/涨停跌停/今开/最高）显示 —；
   - 历史行灰显 + 「已清仓」徽标（含清仓日期）；标题计数（N 只）只数当前持仓；
   - 历史行行展开复用 R-010（trades/by-holding，按 holdingId 懒加载）；
   - 自定义字段列历史行只读展示（values 随行返回，无编辑入口）；
5. **回归脚本** scripts/test-r016-history.mjs（独立临时数据目录，技术约束-011）。

**不做**：全部持仓 tab；盈亏统计；清仓方式标记；历史行实时行情；成本价/收益推导；closeHolding 语义与任何存储写入路径变更；范围偏好持久化；「全部历史」档位。

## 涉及文件

- 修改：src/storage/SqliteStore.js、src/storage/DataStore.js、src/api/strategies.js、src/client/views/StrategyTab.jsx
- 新增：scripts/test-r016-history.mjs

## 实现步骤

1. 本文档链（PLAN + 迭代三件套 + 技术约束-019）；2. SqliteStore.getHoldingsHistory + DataStore 门面；3. API 端点；4. StrategyTab 开关/范围/历史行渲染/展开复用；5. 回归脚本 + typecheck + build + 存量回归（test-position-sync / test-r013 / test-quote-sync）；6. 复盘。

## 验收要点

见 `docs/04-迭代记录/14-策略tab历史持仓展示/验收标准.md`。

## 二轮补充（2026-09-07 Q8-Q9 老师拍板：今日已清仓默认层）

- **补充范围**：已清仓行分两层——L1「今日已清仓」（range='today'，本地自然日 00:00 起）默认恒显示、不受「历史持仓」开关控制；L2「历史范围层」（今天之前的 week/month/quarter/halfYear/year）仍由开关控制（默认关）。前端按 holdingId 去重两层（开启范围不重复出两行）；标题计数不含已清仓行维持；零写路径变更维持。
- **不做（维持首轮）**：不做统计 / 不改 closeHolding / 范围偏好不持久化 / 全部持仓 tab 不加 / 不新增「全部历史」档。

## 验收要点（二轮）

见验收标准「二轮补充验收线 7-10」；自动化已复跑：test-r016 24/24 + 存量回归全绿。