# API 接口文档 - 数据缓存模块

## 基础信息

- **Base URL**: `http://localhost:3007/api`
- **Content-Type**: `application/json`

---

## 数据缓存接口

### 1. 批量缓存所有合约

批量获取所有合约的详情和K线数据，并持久化存储到数据库。

```http
POST /market/cache-all
```

**请求参数**: 无

**响应示例**:
```json
{
  "success": true,
  "message": "批量缓存完成，成功: 25/30",
  "data": {
    "total": 30,
    "success": 25,
    "failed": 5,
    "details": [
      { "code": "AU", "status": "success" },
      { "code": "CU", "status": "success" },
      { "code": "XX", "status": "error", "error": "合约不存在" }
    ],
    "klineCached": 50
  }
}
```

**说明**:
- 自动获取市场概览中的所有合约
- 逐个缓存合约详情到 MySQL 和 Redis
- 缓存前10个热门合约的1H和1D周期K线数据
- 每10个合约延迟100ms避免请求过快

---

### 2. 缓存指定合约

针对单个合约进行强制刷新缓存。

```http
POST /market/cache/:symbol
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbol | string | 是 | 合约代码，如 AU、CU、RB |

**请求体**:
```json
{
  "periods": ["1H", "4H", "1D"]
}
```

**请求体参数**:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| periods | string[] | 否 | ["1H", "4H", "1D"] | 要缓存的K线周期 |

**响应示例**:
```json
{
  "success": true,
  "message": "合约 AU 缓存成功",
  "data": {
    "symbol": "AU",
    "detail": true,
    "klines": [
      { "period": "1H", "success": true },
      { "period": "4H", "success": true },
      { "period": "1D", "success": false, "error": "数据获取失败" }
    ]
  }
}
```

**说明**:
- 会先清除该合约的现有缓存（强制刷新）
- 缓存合约详情和指定周期的K线数据
- 各周期K线缓存相互独立，单个失败不影响其他

---

### 3. 获取缓存统计

获取数据库中的缓存统计信息。

```http
GET /market/cache-stats
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "total": 150,
    "byType": {
      "detail": 50,
      "kline:1H": 30,
      "kline:1D": 30,
      "kline:4H": 20,
      "overview": 1,
      "alerts": 1
    }
  }
}
```

---

### 4. 获取市场概览

获取所有期货合约的市场概览数据。

```http
GET /market/overview
```

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "code": "AU",
      "name": "黄金",
      "currentPrice": 485.32,
      "changePercent": 1.25,
      "winRate": 65,
      "atr": 2.34,
      "adx": 35,
      "trends": {
        "5MIN": { "direction": "看多", "status": "多头趋势", "rsi": 58 },
        "1DAY": { "direction": "看多", "status": "多头趋势", "rsi": 62 }
      }
    }
  ]
}
```

**缓存策略**: 
- Redis: 5分钟
- MySQL: 永久

---

### 5. 获取品种详情

获取指定合约的详细信息。

```http
GET /market/detail/:symbol
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbol | string | 是 | 合约代码 |

**响应示例**:
```json
{
  "success": true,
  "data": {
    "code": "AU",
    "name": "黄金",
    "currentPrice": 485.32,
    "changePercent": 1.25,
    "winRate": 65,
    "indicators": {
      "macd": "金叉向上",
      "rsi": "58(中性)"
    },
    "tradingAdvice": {
      "entry": 485.0,
      "stopLoss": 475.0,
      "target": 500.0
    }
  }
}
```

**缓存策略**:
- Redis: 5分钟
- MySQL: 永久

---

### 6. 获取K线数据

获取指定合约的K线数据。

```http
GET /market/klines/:symbol?period=1D
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbol | string | 是 | 合约代码 |

**查询参数**:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| period | string | 否 | "1H" | K线周期: 1M, 5M, 15M, 30M, 1H, 4H, 1D, 1W |

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "timestamp": 1704067200,
      "open": 480.5,
      "high": 485.2,
      "low": 479.8,
      "close": 485.0,
      "volume": 15234
    }
  ]
}
```

**缓存策略**:
- Redis: 10分钟
- MySQL: 永久

---

## 错误处理

### 错误响应格式

```json
{
  "success": false,
  "message": "错误描述信息"
}
```

### 常见错误码

| HTTP 状态码 | 说明 | 场景 |
|------------|------|------|
| 200 | 成功 | 请求处理成功 |
| 500 | 服务器内部错误 | 数据源连接失败、数据库错误 |
| 404 | 未找到 | 合约不存在 |

### 常见错误消息

| 错误消息 | 说明 | 解决方案 |
|---------|------|---------|
| 无可用数据源 | 未配置或启用数据源 | 在 AdminConfig 中启用至少一个数据源 |
| 合约不存在 | 指定的合约代码无效 | 检查合约代码是否正确 |
| 获取市场概览失败 | 数据源连接问题 | 检查数据源配置和网络连接 |
| 批量缓存失败 | 批量处理过程中出错 | 查看服务器日志获取详细错误 |

---

## 调用示例

### JavaScript/Fetch

```javascript
// 批量缓存所有合约
const cacheAllContracts = async () => {
  const response = await fetch('http://localhost:3007/api/market/cache-all', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    }
  });
  return await response.json();
};

// 缓存指定合约
const cacheSymbol = async (symbol) => {
  const response = await fetch(`http://localhost:3007/api/market/cache/${symbol}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      periods: ['1H', '4H', '1D']
    })
  });
  return await response.json();
};

// 获取缓存统计
const getCacheStats = async () => {
  const response = await fetch('http://localhost:3007/api/market/cache-stats');
  return await response.json();
};
```

---

## 数据类型定义

### ContractDetail

```typescript
interface ContractDetail {
  code: string;                    // 合约代码
  name: string;                    // 合约名称
  currentPrice: number;            // 当前价格
  changePercent: number;           // 涨跌幅百分比
  winRate: number;                 // 胜率
  atr: number;                     // 平均真实波幅
  adx: number;                     // ADX指标值
  trends: {                        // 各周期趋势
    [period: string]: {
      direction: string;           // 方向：看多/看空/观望
      status: string;              // 状态：多头趋势/空头趋势/震荡
      rsi: number;                 // RSI值
    }
  };
  indicators: {                    // 技术指标
    macd: string;
    rsi: string;
    bollinger: string;
    kdj: string;
  };
  tradingAdvice: {                 // 交易建议
    entry: number;                 // 入场价
    stopLoss: number;              // 止损价
    target: number;                // 目标价
    resistance: number;            // 阻力位
    support: number;               // 支撑位
  };
}
```

### KlineData

```typescript
interface KlineData {
  timestamp: number;   // 时间戳（秒）
  open: number;        // 开盘价
  high: number;        // 最高价
  low: number;         // 最低价
  close: number;       // 收盘价
  volume: number;      // 成交量
}
```

### CacheStats

```typescript
interface CacheStats {
  total: number;                    // 缓存总数
  byType: Record<string, number>;   // 按类型统计
}
```

---

**文档版本**: 1.0  
**最后更新**: 2026-03-02