# 数据缓存功能 - 快速参考卡

## 📋 文件变更清单

### 前端文件
- `src/pages/admin/AdminConfig.jsx` - 主要修改文件

### 后端文件
- `backend/src/api/market.ts` - 新增3个API
- `backend/src/services/cacheService.ts` - 新增2个方法

---

## 🚀 快速启动

### 编译后端
```bash
cd backend && npm run build
```

### 验证API
```bash
# 批量缓存
curl -X POST http://localhost:3007/api/market/cache-all

# 单合约缓存
curl -X POST http://localhost:3007/api/market/cache/AU

# 缓存统计
curl http://localhost:3007/api/market/cache-stats
```

---

## 📡 API 速查

| 操作 | 方法 | 端点 | 说明 |
|------|------|------|------|
| 批量缓存 | POST | `/market/cache-all` | 缓存所有合约 |
| 单合约缓存 | POST | `/market/cache/:symbol` | 强制刷新指定合约 |
| 缓存统计 | GET | `/market/cache-stats` | 获取数据库统计 |
| 市场概览 | GET | `/market/overview` | 获取合约列表 |
| 合约详情 | GET | `/market/detail/:symbol` | 获取单个合约详情 |
| K线数据 | GET | `/market/klines/:symbol?period=1D` | 获取K线数据 |

---

## 🗄️ 缓存键命名规范

### LocalStorage
```
cached_overview           - 市场概览
cached_alerts            - 风险预警
cached_detail_{code}     - 合约详情
cached_kline_{code}_{period}  - K线数据
```

### Redis
```
market:overview              - 市场概览
market:detail:{symbol}       - 合约详情
market:kline:{symbol}:{period}  - K线数据
```

### MySQL
```sql
-- market_data 表
symbol | type        | data
-------|-------------|--------
AU     | detail      | {...}
AU     | kline:1D    | {...}
CU     | detail      | {...}
```

---

## ⏱️ 缓存有效期

| 数据类型 | LocalStorage | Redis | MySQL |
|---------|-------------|-------|-------|
| 市场概览 | 5分钟 | 5分钟 | 永久 |
| 风险预警 | 3分钟 | 3分钟 | 永久 |
| 合约详情 | 10分钟 | 5分钟 | 永久 |
| K线数据 | 30分钟 | 10分钟 | 永久 |

---

## 🔧 常用操作

### 查看 MySQL 缓存
```sql
-- 查看所有缓存
SELECT symbol, type, updated_at FROM market_data ORDER BY updated_at DESC;

-- 按类型统计
SELECT type, COUNT(*) FROM market_data GROUP BY type;

-- 查看特定合约
SELECT * FROM market_data WHERE symbol = 'AU';
```

### 查看 Redis 缓存
```bash
# 查看所有 key
KEYS market:*

# 查看过期时间
TTL market:detail:AU

# 删除特定 key
DEL market:detail:AU

# 清空所有
FLUSHDB
```

### 清除 LocalStorage
```javascript
// 清除所有缓存
Object.keys(localStorage).forEach(key => {
  if (key.startsWith('cached_')) {
    localStorage.removeItem(key);
  }
});
```

---

## 🐛 快速排错

| 问题 | 解决方案 |
|------|---------|
| 页面加载失败 | 清除 vite 缓存 `rm -rf node_modules/.vite` |
| API 返回 500 | 检查数据源配置和数据源服务状态 |
| 缓存未写入 DB | 检查 MySQL 连接和 market_data 表 |
| Redis 未命中 | 检查 Redis 连接 `redis-cli ping` |
| 批量缓存超时 | 查看后端日志，减少并发或分批处理 |

---

## 📊 监控命令

```bash
# 实时监控后端日志
tail -f backend/logs/app.log | grep -E "cache|Cache|缓存"

# 监控 MySQL 查询
mysql -u root -p -e "SELECT COUNT(*), type FROM market_data GROUP BY type;"

# 监控 Redis 内存
redis-cli INFO memory | grep used_memory_human

# 查看当前连接的合约数
curl -s http://localhost:3007/api/market/overview | jq '.data | length'
```

---

## 📝 代码片段

### 前端调用批量缓存
```javascript
const cacheAll = async () => {
  const res = await fetch('/api/market/cache-all', { method: 'POST' });
  const data = await res.json();
  console.log(`成功: ${data.data.success}/${data.data.total}`);
};
```

### 前端调用单合约缓存
```javascript
const cacheSymbol = async (symbol) => {
  const res = await fetch(`/api/market/cache/${symbol}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ periods: ['1H', '4H', '1D'] })
  });
  return await res.json();
};
```

### 后端直接保存缓存
```typescript
await cacheService.saveDirect('AU', 'detail', data, { expireTime: 300 });
```

---

## 🔗 相关文档

- 完整开发文档: `docs/data-cache-feature.md`
- API 参考文档: `docs/api-reference.md`
- 部署指南: `docs/cache-deployment-guide.md`

---

**最后更新**: 2026-03-02