# 缓存指南

emst 使用本地缓存系统存储 K线数据，减少 API 调用并提升性能。

## 概述

缓存数据存储在 `.emst/cache/` 目录中，按股票代码、市场、时间周期和复权类型组织：

```
.emst/cache/
  ├── 688005_1_daily_fqt1.json   # 上海 688005 日线前复权
  ├── 688005_1_weekly_fqt1.json  # 上海 688005 周线前复权
  ├── 688005_1_daily_fqt0.json   # 上海 688005 日线不复权
  ├── 688005_1_daily_fqt2.json   # 上海 688005 日线后复权
  ├── 000001_0_daily_fqt1.json   # 深圳 000001 日线前复权
  └── ...
```

**文件命名格式**：`{symbol}_{market}_{timeframe}_fqt{fqt}.json`

**复权类型（fqt）**：
- `fqt0`: 不复权
- `fqt1`: 前复权（默认）
- `fqt2`: 后复权

不同复权类型的数据分开缓存，互不影响。

## 缓存文件格式

每个缓存文件包含：

```json
{
  "data": [
    {
      "date": "2024-01-01",
      "open": 100.0,
      "close": 105.0,
      "high": 106.0,
      "low": 99.0,
      "volume": 1000000,
      "amount": 105000000
    }
  ],
  "lastSync": 1704067200000,
  "metadata": {
    "symbol": "688005",
    "market": 1,
    "timeframe": "daily",
    "fqt": 1
  }
}
```

### 字段说明

- `data`: K线记录数组
- `lastSync`: 最后同步时间戳（自纪元以来的毫秒数）
- `metadata`: 缓存元数据（股票代码、市场、时间周期、复权类型）
  - `symbol`: 股票代码
  - `market`: 市场代码
  - `timeframe`: 时间周期
  - `fqt`: 复权类型（0=不复权，1=前复权，2=后复权）

## 缓存机制

### 自动缓存

获取数据时自动执行：
1. **检查缓存**：先检查是否存在有效缓存
2. **验证有效性**：缓存存在、未过期且覆盖请求范围
3. **使用或更新**：有效则使用缓存，无效则获取新数据并更新缓存

### 缓存有效性

缓存被认为有效需满足：
- ✅ 缓存文件存在
- ✅ 缓存未过期（默认 24 小时）
- ✅ 缓存覆盖请求的日期范围

### 增量更新

同步时智能更新：
1. **检查日期范围**：查找现有缓存的日期范围
2. **获取新数据**：仅获取上次缓存日期之后的数据
3. **智能合并**：新数据与现有缓存合并，自动去重
4. **更新缓存**：保存合并后的完整数据

## 缓存管理

### 使用缓存

默认启用缓存，无需额外配置：

```bash
# 自动使用缓存（如果有效）
emst stock fetch --symbol 688005

# 绕过缓存，强制获取新数据
emst stock fetch --symbol 688005 --no-cache
```

### 获取流程

不使用 `--no-cache` 时的完整流程：
1. **检查缓存**：查找对应的缓存文件
2. **验证有效性**：检查缓存是否过期、是否覆盖日期范围
3. **使用或获取**：有效则直接返回缓存，无效则获取新数据
4. **更新缓存**：获取的新数据自动保存到缓存
5. **返回数据**：返回完整数据（来自缓存或新获取）

### 手动缓存管理

您可以手动管理缓存文件：

```bash
# 查看缓存文件
ls .emst/cache/

# 查看特定缓存文件（前复权，默认）
cat .emst/cache/688005_1_daily_fqt1.json

# 查看不复权缓存文件
cat .emst/cache/688005_1_daily_fqt0.json

# 查看后复权缓存文件
cat .emst/cache/688005_1_daily_fqt2.json

# 删除特定复权类型的缓存文件
rm .emst/cache/688005_1_daily_fqt1.json

# 清除所有缓存
rm -rf .emst/cache/*
```

## 缓存策略

### 日线数据

日线数据缓存有效期 24 小时，适合每日同步：

```bash
# 同步日线数据
emst stock watchlist sync --timeframe daily
```

### 日内数据

日内数据（5分钟、15分钟等）建议更频繁更新，可使用 `--force`：

```bash
# 强制刷新 5 分钟数据
emst stock watchlist sync --timeframe 5min --force
```

### 历史数据

历史数据缓存可长期保存，无需频繁更新：

```bash
# 同步历史数据（一次性获取，缓存长期有效）
emst stock watchlist sync --start 20200101 --end 20231231
```

## 性能优化

### 缓存大小

- 每个缓存文件存储单个股票/市场/时间周期的数据
- 大日期范围会产生较大的缓存文件
- 建议定期清理不再需要的缓存文件

### 缓存效率

- **首次获取**：完整 API 调用，数据保存到缓存
- **后续获取**：直接使用缓存，无需网络请求
- **增量同步**：仅获取新数据，智能合并到缓存

### 网络优化

- 缓存显著减少 API 调用次数
- 增量同步最小化数据传输量
- 谨慎使用 `--force`，避免不必要的网络请求

## 故障排除

### 过期缓存

如果您怀疑数据过期：

```bash
# 强制刷新
emst stock watchlist sync --force
```

### 缓存损坏

如果缓存文件损坏：

```bash
# 删除特定缓存文件（需要指定复权类型）
rm .emst/cache/{symbol}_{market}_{timeframe}_fqt{fqt}.json
# 例如：
rm .emst/cache/688005_1_daily_fqt1.json

# 或清除所有缓存
rm -rf .emst/cache/*
```

### 缓存不工作

如果缓存似乎不工作：
1. 检查 `.emst/cache/` 目录是否存在
2. 验证文件权限
3. 检查磁盘空间
4. 尝试清除缓存并重新获取

## 高级用法

### 自定义缓存位置

目前，缓存存储在项目目录的相对路径 `.emst/cache/` 中。要更改位置，需要修改缓存模块。

### 缓存过期

默认缓存过期时间为24小时。这是硬编码的，但可以在缓存模块中修改。

### 缓存合并

获取新数据时，会与现有缓存合并：
- 避免重复（按日期）
- 数据按日期排序
- 新数据优先于旧数据