MomentumLab/app/docs/04-API接口文档.md

# A股智投分析平台 - API接口文档

## 基础信息

```
Base URL: https://api.aguzhitou.com/v1
WebSocket: wss://ws.aguzhitou.com

请求头:
Content-Type: application/json
Authorization: Bearer {access_token}
```

---

## 一、市场数据接口

### 1.1 获取市场指数

**请求**
```http
GET /market/indices
```

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "name": "上证指数",
            "code": "000001",
            "current": 3050.32,
            "change": 15.23,
            "changePercent": 0.50,
            "volume": 450000000,
            "turnover": 4200000000
        },
        {
            "name": "深证成指",
            "code": "399001",
            "current": 9850.15,
            "change": -25.60,
            "changePercent": -0.26,
            "volume": 520000000,
            "turnover": 5100000000
        }
    ]
}
```

### 1.2 获取涨跌家数统计

**请求**
```http
GET /market/updown-stats
```

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "up": 2850,
        "down": 1950,
        "flat": 200
    }
}
```

### 1.3 获取涨跌幅分布

**请求**
```http
GET /market/price-distribution
```

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        { "range": "<-7%", "min": -999, "max": -7, "count": 45 },
        { "range": "-7~-5%", "min": -7, "max": -5, "count": 128 },
        { "range": "-5~-3%", "min": -5, "max": -3, "count": 356 },
        { "range": "-3~0%", "min": -3, "max": 0, "count": 1421 },
        { "range": "0~3%", "min": 0, "max": 3, "count": 1856 },
        { "range": "3~5%", "min": 3, "max": 5, "count": 623 },
        { "range": "5~7%", "min": 5, "max": 7, "count": 312 },
        { "range": ">7%", "min": 7, "max": 999, "count": 259 }
    ]
}
```

---

## 二、版块数据接口

### 2.1 获取版块列表

**请求**
```http
GET /sectors
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| sort | string | 否 | 排序方式: momentum/rank/change |
| order | string | 否 | 排序: asc/desc |

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "name": "半导体",
            "code": "880491",
            "change": 3.25,
            "changePercent": 3.25,
            "volume": 25000000,
            "turnover": 850000000,
            "leadingStock": "中芯国际",
            "momentumScore": 85.5,
            "rank": 1,
            "previousRank": 3,
            "rankChange": 2
        }
    ]
}
```

### 2.2 获取版块详情

**请求**
```http
GET /sectors/{sector_code}
```

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "name": "半导体",
        "code": "880491",
        "change": 3.25,
        "changePercent": 3.25,
        "volume": 25000000,
        "turnover": 850000000,
        "leadingStock": "中芯国际",
        "momentumScore": 85.5,
        "rank": 1,
        "previousRank": 3,
        "rankChange": 2
    }
}
```

### 2.3 获取版块历史排名

**请求**
```http
GET /sectors/{sector_code}/rank-history
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| days | number | 否 | 天数，默认30 |

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "date": "2024-01-15",
            "rank": 5,
            "momentumScore": 72.5,
            "topStock": "中芯国际"
        },
        {
            "date": "2024-01-16",
            "rank": 3,
            "momentumScore": 78.2,
            "topStock": "韦尔股份"
        }
    ]
}
```

### 2.4 获取版块内股票

**请求**
```http
GET /sectors/{sector_code}/stocks
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| sort | string | 否 | 排序: momentum/change/volume |
| limit | number | 否 | 数量限制，默认20 |

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "code": "688981",
            "name": "中芯国际",
            "price": 52.35,
            "change": 2.15,
            "changePercent": 4.28,
            "volume": 12500000,
            "turnover": 654000000,
            "marketCap": 415000000000,
            "pe": 45.2,
            "pb": 3.8,
            "industry": "半导体"
        }
    ]
}
```

### 2.5 获取版块内动量股票

**请求**
```http
GET /sectors/{sector_code}/momentum-stocks
```

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "code": "688981",
            "name": "中芯国际",
            "price": 52.35,
            "change": 2.15,
            "changePercent": 4.28,
            "volume": 12500000,
            "turnover": 654000000,
            "industry": "半导体",
            "momentumScore": 92,
            "tags": ["强势突破", "量价齐升"],
            "volumeRatio": 3.5,
            "breakThrough": true
        }
    ]
}
```

### 2.6 获取版块K线数据

**请求**
```http
GET /sectors/{sector_code}/kline
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| period | string | 否 | 周期: day/week/month，默认day |
| days | number | 否 | 天数，默认60 |

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "date": "2024-01-15",
            "open": 2850.25,
            "high": 2895.60,
            "low": 2835.15,
            "close": 2880.35,
            "volume": 45000000,
            "ma5": 2865.20,
            "ma10": 2850.80,
            "ma20": 2835.50
        }
    ]
}
```

---

## 三、股票数据接口

### 3.1 搜索股票

**请求**
```http
GET /stocks/search
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| keyword | string | 是 | 搜索关键词 |
| type | string | 否 | 类型: stock/sector/all，默认all |

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "sectors": [
            {
                "name": "半导体",
                "code": "880491",
                "changePercent": 3.25,
                "rank": 1,
                "momentumScore": 85.5
            }
        ],
        "stocks": [
            {
                "code": "688981",
                "name": "中芯国际",
                "price": 52.35,
                "changePercent": 4.28,
                "industry": "半导体"
            }
        ]
    }
}
```

### 3.2 获取股票详情

**请求**
```http
GET /stocks/{stock_code}
```

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "code": "688981",
        "name": "中芯国际",
        "price": 52.35,
        "change": 2.15,
        "changePercent": 4.28,
        "volume": 12500000,
        "turnover": 654000000,
        "marketCap": 415000000000,
        "pe": 45.2,
        "pb": 3.8,
        "industry": "半导体",
        "open": 50.50,
        "high": 53.20,
        "low": 50.20,
        "preClose": 50.20,
        "amplitude": 5.98,
        "turnoverRate": 2.35,
        "macd": {
            "dif": 0.85,
            "dea": 0.62,
            "macd": 0.46
        },
        "kdj": {
            "k": 75.2,
            "d": 68.5,
            "j": 88.6
        },
        "rsi": {
            "rsi6": 72.5,
            "rsi12": 68.3,
            "rsi24": 65.1
        }
    }
}
```

### 3.3 获取股票K线数据

**请求**
```http
GET /stocks/{stock_code}/kline
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| period | string | 否 | 周期: day/week/month，默认day |
| days | number | 否 | 天数，默认60 |

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "date": "2024-01-15",
            "open": 50.50,
            "high": 53.20,
            "low": 50.20,
            "close": 52.35,
            "volume": 12500000,
            "ma5": 51.20,
            "ma10": 50.80,
            "ma20": 49.50,
            "ma30": 48.90,
            "ma60": 47.20
        }
    ]
}
```

### 3.4 获取新高股票

**请求**
```http
GET /stocks/new-high
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| days | number | 否 | 近N天，默认20 |
| limit | number | 否 | 数量限制，默认20 |

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "code": "688981",
            "name": "中芯国际",
            "price": 52.35,
            "change": 2.15,
            "changePercent": 4.28,
            "volume": 12500000,
            "turnover": 654000000,
            "industry": "半导体",
            "highLowPrice": 52.35,
            "date": "2024-01-15",
            "daysToHighLow": 15
        }
    ]
}
```

### 3.5 获取新低股票

**请求**
```http
GET /stocks/new-low
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| days | number | 否 | 近N天，默认20 |
| limit | number | 否 | 数量限制，默认20 |

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "code": "600519",
            "name": "贵州茅台",
            "price": 1650.00,
            "change": -25.00,
            "changePercent": -1.49,
            "volume": 850000,
            "turnover": 1402500000,
            "industry": "白酒",
            "highLowPrice": 1650.00,
            "date": "2024-01-15",
            "daysToHighLow": 8
        }
    ]
}
```

### 3.6 获取动量股票推荐

**请求**
```http
GET /stocks/momentum-recommendation
```

**查询参数**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| limit | number | 否 | 数量限制，默认15 |

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "code": "688981",
            "name": "中芯国际",
            "price": 52.35,
            "change": 2.15,
            "changePercent": 4.28,
            "volume": 12500000,
            "turnover": 654000000,
            "industry": "半导体",
            "momentumScore": 92,
            "tags": ["强势突破", "量价齐升"],
            "volumeRatio": 3.5,
            "breakThrough": true
        }
    ]
}
```

---

## 四、用户接口

### 4.1 用户注册

**请求**
```http
POST /users/register
```

**请求体**
```json
{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
}
```

**响应**
```json
{
    "code": 200,
    "message": "注册成功",
    "data": {
        "id": 1,
        "username": "testuser",
        "email": "test@example.com",
        "token": "eyJhbGciOiJIUzI1NiIs..."
    }
}
```

### 4.2 用户登录

**请求**
```http
POST /users/login
```

**请求体**
```json
{
    "email": "test@example.com",
    "password": "password123"
}
```

**响应**
```json
{
    "code": 200,
    "message": "登录成功",
    "data": {
        "id": 1,
        "username": "testuser",
        "email": "test@example.com",
        "token": "eyJhbGciOiJIUzI1NiIs..."
    }
}
```

### 4.3 获取用户信息

**请求**
```http
GET /users/profile
Authorization: Bearer {token}
```

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "id": 1,
        "username": "testuser",
        "email": "test@example.com",
        "createdAt": "2024-01-15T10:00:00Z"
    }
}
```

### 4.4 获取自选股

**请求**
```http
GET /users/favorites
Authorization: Bearer {token}
```

**响应**
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {
            "code": "688981",
            "name": "中芯国际",
            "price": 52.35,
            "changePercent": 4.28,
            "industry": "半导体"
        }
    ]
}
```

### 4.5 添加自选股

**请求**
```http
POST /users/favorites
Authorization: Bearer {token}
```

**请求体**
```json
{
    "stockCode": "688981"
}
```

**响应**
```json
{
    "code": 200,
    "message": "添加成功",
    "data": null
}
```

### 4.6 删除自选股

**请求**
```http
DELETE /users/favorites/{stock_code}
Authorization: Bearer {token}
```

**响应**
```json
{
    "code": 200,
    "message": "删除成功",
    "data": null
}
```

---

## 五、WebSocket 实时数据

### 5.1 连接

```javascript
const ws = new WebSocket('wss://ws.aguzhitou.com');

ws.onopen = () => {
    // 订阅股票行情
    ws.send(JSON.stringify({
        action: 'subscribe',
        channels: ['stock:688981', 'stock:600519']
    }));
    
    // 订阅版块行情
    ws.send(JSON.stringify({
        action: 'subscribe',
        channels: ['sector:880491']
    }));
};

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log(data);
};
```

### 5.2 订阅消息格式

**订阅请求**
```json
{
    "action": "subscribe",
    "channels": ["stock:688981", "stock:600519"]
}
```

**取消订阅**
```json
{
    "action": "unsubscribe",
    "channels": ["stock:688981"]
}
```

### 5.3 推送数据格式

**股票行情推送**
```json
{
    "channel": "stock:688981",
    "type": "quote",
    "data": {
        "code": "688981",
        "name": "中芯国际",
        "price": 52.35,
        "change": 2.15,
        "changePercent": 4.28,
        "volume": 12500000,
        "turnover": 654000000,
        "time": "2024-01-15T14:30:00Z"
    }
}
```

**版块行情推送**
```json
{
    "channel": "sector:880491",
    "type": "quote",
    "data": {
        "code": "880491",
        "name": "半导体",
        "changePercent": 3.25,
        "momentumScore": 85.5,
        "rank": 1,
        "time": "2024-01-15T14:30:00Z"
    }
}
```

---

## 六、错误码

| 错误码 | 说明 |
|-------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权，需要登录 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |
| 503 | 服务暂时不可用 |

---

## 七、限流策略

| 接口类型 | 限流策略 |
|---------|---------|
| 公开接口 | 100次/分钟/IP |
| 需要登录 | 1000次/分钟/用户 |
| WebSocket | 10个连接/IP |

---

## 八、数据更新频率

| 数据类型 | 更新频率 |
|---------|---------|
| 实时行情 | 3秒 |
| K线数据 | 1分钟 |
| 版块排名 | 1分钟 |
| 涨跌幅分布 | 1分钟 |
| 历史数据 | 每日收盘后 |