# VIP交易接口对接文档

## 一、用户端接口

### 1. 获取VIP交易列表

**接口地址：** `/api/stock/getVipList.do`

**请求方式：** POST

**请求参数：** 无

**返回数据：**
```json
{
  "status": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "stockName": "股票名称",
      "stockCode": "000001",
      "price": 10.50,
      "stockType": "股票类型",
      "stockGid": "sh000001",
      "stockPlate": "股票板块",
      "isLock": 0,
      "stockNum": 100,
      "startTime": "2024-01-01 09:00:00",
      "endTime": "2024-01-01 15:00:00",
      "discount": 0.95,
      "residualShare": 1000
    }
  ]
}
```

**字段说明：**
- `id`: VIP记录ID
- `stockName`: 股票名称
- `stockCode`: 股票代码
- `price`: 当前价格（已计算折扣）
- `stockType`: 股票类型
- `stockGid`: 股票GID
- `stockPlate`: 股票板块
- `isLock`: 是否锁定（0-未锁定，1-锁定）
- `stockNum`: 最小购买数量
- `startTime`: 开始时间
- `endTime`: 结束时间
- `discount`: 折扣率
- `residualShare`: 剩余股份

---

### 2. VIP下单

**接口地址：** `/user/buyStockVip.do`

**请求方式：** POST

**请求参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| stockCode | String | 是 | 股票代码 |
| password | String | 是 | 交易密码 |
| num | Integer | 是 | 购买数量 |

**请求示例：**
```
POST /user/buyStockVip.do
stockCode=000001&password=123456&num=100
```

**返回数据：**
```json
{
  "status": 0,
  "msg": "success",
  "data": "VIP交易下单成功"
}
```

**错误返回示例：**
```json
{
  "status": 1,
  "msg": "下单失败，请先实名认证"
}
```

**常见错误提示：**
- "下单失败，请先实名认证"
- "下单失败，账户已被锁定"
- "下单失败，系统设置错误"
- "周末或节假日不能交易！"
- "下单失败，密钥错误"
- "下单失败，当前股票不能交易"
- "频繁交易,X分钟内同一股票持仓不得超过X条"
- "频繁交易,X分钟内不能超过X手"
- "下单失败，购买数量最小为X股"
- "下单失败，购买数量大于X股"
- "报价0，请稍后再试"
- "ST和已退市的股票不能入仓"
- "下单失败，股票当前涨幅:X,大于最大涨幅:X"
- "下单失败，股票当前跌幅:X,大于最大跌幅:X"
- "下单失败，购买金额小于X元"
- "下单失败，不能超过可用资金的X%"
- "下单失败，融资可用金额小于X元"
- "X天内涨幅超过 X不能交易"

---

### 3. VIP下单列表

**接口地址：** `/user/buyStockVipList.do`

**请求方式：** POST

**请求参数：** 无（需要登录，从请求头获取用户信息）

**返回数据：**
```json
{
  "status": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "positionType": 4,
      "positionSn": "订单编号",
      "userId": 1001,
      "stockCode": "000001",
      "stockName": "股票名称",
      "buyOrderTime": "2024-01-01 10:00:00",
      "buyOrderPrice": 10.50,
      "orderNum": 100,
      "orderDirection": "买涨",
      "orderLever": 1,
      "orderTotalPrice": 1050.00,
      "profitAndLose": 0.00,
      "allProfitAndLose": 0.00
    }
  ]
}
```

**字段说明：**
- `positionType`: 持仓类型（4表示VIP交易）
- `positionSn`: 订单编号
- `userId`: 用户ID
- `stockCode`: 股票代码
- `stockName`: 股票名称
- `buyOrderTime`: 下单时间
- `buyOrderPrice`: 买入价格
- `orderNum`: 购买数量
- `orderDirection`: 交易方向（买涨/买跌）
- `orderLever`: 杠杆倍数
- `orderTotalPrice`: 订单总金额
- `profitAndLose`: 盈亏
- `allProfitAndLose`: 总盈亏

---

## 二、后台管理接口

### 1. 获取VIP列表（后台）

**接口地址：** `/admin/stockVip/getVipListByAdmin.do`

**请求方式：** POST/GET

**请求参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| keywords | String | 否 | 搜索关键词（股票名称、代码、类型） |

**请求示例：**
```
GET /admin/stockVip/getVipListByAdmin.do?keywords=000001
```

**返回数据：**
```json
{
  "status": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "stockName": "股票名称",
      "stockCode": "000001",
      "stockType": "股票类型",
      "stockGid": "sh000001",
      "stockPlate": "股票板块",
      "isLock": 0,
      "isShow": 1,
      "addTime": "2024-01-01 09:00:00",
      "spreadRate": 0.001,
      "increaseRatio": 0.0000,
      "stockNum": 100,
      "password": "123456",
      "startTime": "2024-01-01 09:00:00",
      "endTime": "2024-01-01 15:00:00",
      "discount": 0.95,
      "residualShare": 1000
    }
  ]
}
```

---

### 2. 新增VIP

**接口地址：** `/admin/stockVip/addByAdmin.do`

**请求方式：** POST

**请求参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| stockCode | String | 是 | 股票代码 |
| stockNum | String | 是 | 最小购买数量 |
| password | String | 是 | 交易密码 |
| startTime | String | 是 | 开始时间（格式：yyyy-MM-dd HH:mm:ss） |
| endTime | String | 是 | 结束时间（格式：yyyy-MM-dd HH:mm:ss） |
| discount | String | 是 | 折扣率 |
| residualShare | Integer | 否 | 剩余股份 |

**请求示例：**
```
POST /admin/stockVip/addByAdmin.do
stockCode=000001&stockNum=100&password=123456&startTime=2024-01-01 09:00:00&endTime=2024-01-01 15:00:00&discount=0.95&residualShare=1000
```

**返回数据：**
```json
{
  "status": 0,
  "msg": "添加成功"
}
```

**错误返回：**
```json
{
  "status": 1,
  "msg": "参数不能为空"
}
```
或
```json
{
  "status": 1,
  "msg": "股票代码不存在"
}
```

---

### 3. 删除VIP

**接口地址：** `/admin/stockVip/deleteByAdmin.do`

**请求方式：** POST

**请求参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | String | 是 | VIP记录ID |

**请求示例：**
```
POST /admin/stockVip/deleteByAdmin.do
id=1
```

**返回数据：**
```json
{
  "status": 0,
  "msg": "删除成功"
}
```

**错误返回：**
```json
{
  "status": 1,
  "msg": "删除失败"
}
```

---

### 4. 修改VIP

**接口地址：** `/admin/stockVip/updateByAdmin.do`

**请求方式：** POST

**请求参数：**
需要传递完整的StockVip对象，常用字段：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Integer | 是 | VIP记录ID |
| stockName | String | 否 | 股票名称 |
| stockCode | String | 否 | 股票代码 |
| isLock | Integer | 否 | 是否锁定（0-未锁定，1-锁定） |
| isShow | Integer | 否 | 是否显示（0-不显示，1-显示） |
| stockNum | Integer | 否 | 最小购买数量 |
| password | String | 否 | 交易密码 |
| startTime | Date | 否 | 开始时间 |
| endTime | Date | 否 | 结束时间 |
| discount | BigDecimal | 否 | 折扣率 |
| residualShare | Integer | 否 | 剩余股份 |

**请求示例：**
```json
POST /admin/stockVip/updateByAdmin.do
{
  "id": 1,
  "isLock": 0,
  "isShow": 1,
  "stockNum": 200,
  "discount": 0.90
}
```

**返回数据：**
```json
{
  "status": 0,
  "msg": "修改成功"
}
```

**错误返回：**
```json
{
  "status": 1,
  "msg": "修改失败"
}
```

---

## 三、通用说明

### 1. 响应格式

所有接口统一返回格式：
```json
{
  "status": 0,  // 0-成功，1-失败
  "msg": "success",  // 提示信息
  "data": {}  // 数据内容
}
```

### 2. 用户端接口认证

用户端接口（`/user/*`）需要：
- 用户登录状态
- 请求头中携带用户token或session信息

### 3. 后台管理接口认证

后台管理接口（`/admin/*`）需要：
- 管理员登录状态
- 相应的权限验证

### 4. 时间格式

所有时间字段统一使用格式：`yyyy-MM-dd HH:mm:ss`

### 5. 持仓类型

- `positionType = 3`: 大宗交易
- `positionType = 4`: VIP交易

### 6. 注意事项

1. VIP下单需要先进行实名认证
2. VIP下单有最小购买数量限制
3. VIP交易有时间限制（startTime - endTime）
4. VIP交易需要输入正确的交易密码
5. 周末和节假日不能交易
6. 股票涨幅/跌幅超过限制不能交易
7. 频繁交易会被限制

---

## 四、接口对比

VIP接口与大宗交易接口完全对应：

| 功能 | 大宗交易接口 | VIP交易接口 |
|------|------------|------------|
| 获取列表 | `/api/stock/getDzList.do` | `/api/stock/getVipList.do` |
| 下单 | `/user/buyStockDz.do` | `/user/buyStockVip.do` |
| 下单列表 | `/user/buyStockDzList.do` | `/user/buyStockVipList.do` |
| 后台列表 | `/admin/stockDz/getDzListByAdmin.do` | `/admin/stockVip/getVipListByAdmin.do` |
| 后台新增 | `/admin/stockDz/addByAdmin.do` | `/admin/stockVip/addByAdmin.do` |
| 后台删除 | `/admin/stockDz/deleteByAdmin.do` | `/admin/stockVip/deleteByAdmin.do` |
| 后台修改 | `/admin/stockDz/updateByAdmin.do` | `/admin/stockVip/updateByAdmin.do` |