# API 接口文档

> **Base URL**: `http://localhost:8080/api/chat`
> **认证方式**: Bearer Token（若依 JWT，Header: `Authorization: Bearer {token}`）
> **数据格式**: JSON

---

## 一、会话管理接口

### 1.1 创建/获取会话
**场景**: 用户/商家进入聊天页面时调用，若已有进行中的会话则复用

```
POST /session/create
```

**Request Body:**
```json
{
  "sessionType": 1,         // 1=小程序用户, 2=PC商家
  "fromUserId": 10001,
  "fromUserName": "南风未起",
  "fromUserAvatar": "https://..."
}
```

**Response:**
```json
{
  "code": 200,
  "data": {
    "sessionId": 1,
    "sessionNo": "SESSION_20240316_10001_abc123",
    "waiterInfo": {
      "waiterId": 5,
      "waiterName": "客服小A",
      "waiterAvatar": "https://...",
      "isOnline": true
    }
  }
}
```

---

### 1.2 获取会话列表（坐席端）
**场景**: PC 坐席端左侧会话列表

```
GET /session/list?sessionType=1&status=1&keyword=南风&page=1&pageSize=20
```

**Response:**
```json
{
  "code": 200,
  "data": {
    "total": 5,
    "rows": [
      {
        "sessionId": 1,
        "sessionNo": "SESSION_20240316_10001",
        "sessionType": 1,
        "fromUserId": 10001,
        "fromUserName": "南风未起",
        "fromUserAvatar": "https://...",
        "lastMsg": "您好，这个结算单显示已失效了",
        "lastMsgTime": "2024-03-16 13:18:22",
        "unreadCount": 2,
        "status": 1
      }
    ]
  }
}
```

---

### 1.3 结束会话
```
PUT /session/{sessionId}/end
```

---

### 1.4 强制结束会话（坐席端）
```
PUT /session/{sessionId}/force-end
```

---

## 二、消息接口

### 2.1 获取历史消息
**场景**: 进入会话时加载历史记录

```
GET /message/history?sessionId=1&page=1&pageSize=50&beforeMsgId=100
```

**Response:**
```json
{
  "code": 200,
  "data": {
    "total": 25,
    "rows": [
      {
        "msgId": 88,
        "sessionId": 1,
        "msgNo": "MSG_xxxx",
        "senderType": 2,
        "senderId": 5,
        "senderName": "客服小A",
        "senderAvatar": "https://...",
        "msgType": "job_card",
        "content": null,
        "fileUrl": null,
        "payload": {
          "title": "审计员",
          "salary": "13K-23K",
          "tags": ["实习", "五险一金", "985"],
          "company": "华财仁合",
          "location": "上海市·黄浦区",
          "urgency": "急招",
          "quota": "1 人",
          "deadline": "2025-12-12 24:00"
        },
        "sendTime": "2024-03-16 13:15:56",
        "isRead": 1
      },
      {
        "msgId": 92,
        "msgType": "order_card",
        "payload": {
          "orderCardId": 3,
          "name": "审计师一级入职定金",
          "price": "29.9",
          "status": "expired",
          "expireTime": "2024-03-16 13:17:10",
          "countdown": 0
        },
        "sendTime": "2024-03-16 13:16:10"
      }
    ]
  }
}
```

---

### 2.2 发送文本/Emoji 消息（HTTP 备用，主要走 WebSocket）
```
POST /message/send/text
```

**Request Body:**
```json
{
  "sessionId": 1,
  "msgNo": "MSG_client_uuid_123",
  "msgType": "text",
  "content": "您好，有什么可以帮助您的？"
}
```

---

### 2.3 上传图片消息
```
POST /message/send/image
Content-Type: multipart/form-data
```

**Form Data:**
- `sessionId`: 1
- `msgNo`: MSG_xxx
- `file`: [图片文件]

**Response:**
```json
{
  "code": 200,
  "data": {
    "msgId": 99,
    "fileUrl": "https://minio.example.com/chat/images/2024/xxx.jpg",
    "thumbnailUrl": "https://..."
  }
}
```

---

### 2.4 上传附件消息
```
POST /message/send/file
Content-Type: multipart/form-data
```

**Form Data:**
- `sessionId`: 1
- `msgNo`: MSG_xxx
- `file`: [文件]

---

### 2.5 发送岗位卡片（坐席端）
```
POST /message/send/job-card
```

**Request Body:**
```json
{
  "sessionId": 1,
  "msgNo": "MSG_xxx",
  "payload": {
    "jobId": 501,
    "title": "审计员",
    "salary": "13K-23K",
    "tags": ["实习", "五险一金", "985"],
    "company": "华财仁合",
    "location": "上海市·黄浦区",
    "urgency": "急招",
    "quota": "1 人",
    "deadline": "2025-12-12 24:00"
  }
}
```

---

### 2.6 发送结算单（坐席端）⚡ 核心接口
**场景**: 客服向小程序用户发送 60 秒倒计时结算单

```
POST /message/send/order-card
```

**Request Body:**
```json
{
  "sessionId": 1,
  "msgNo": "MSG_xxx",
  "payload": {
    "orderName": "审计师一级入职定金",
    "orderPrice": 29.90,
    "orderType": "岗位入职定金"
  }
}
```

**Response:**
```json
{
  "code": 200,
  "data": {
    "msgId": 100,
    "orderCardId": 5,
    "expireTime": "2024-03-16 13:17:10",
    "countdownSeconds": 60
  }
}
```

> 🔧 **服务端逻辑**: 发送后立即记录 `expireTime = now() + 60s`；
> 启动定时任务，60 秒后若 status 仍为 `pending`，自动更新为 `expired`
> 并通过 **WebSocket broadcast** 通知双端更新 UI 状态。

---

### 2.7 标记消息已读
```
PUT /message/read
```
**Request Body:**
```json
{
  "sessionId": 1,
  "lastReadMsgId": 99
}
```

---

## 三、结算单接口

### 3.1 查询结算单状态
```
GET /order-card/{orderCardId}
```

**Response:**
```json
{
  "code": 200,
  "data": {
    "orderCardId": 5,
    "status": "pending",
    "expireTime": "2024-03-16 13:17:10",
    "countdown": 38,
    "orderName": "审计师一级入职定金",
    "orderPrice": 29.90
  }
}
```

---

### 3.2 小程序用户支付结算单
```
POST /order-card/{orderCardId}/pay
```

**Response:**
```json
{
  "code": 200,
  "data": {
    "payUrl": "weixin://...",
    "orderCardId": 5,
    "status": "paid"
  }
}
```

---

## 四、坐席管理接口

### 4.1 获取坐席列表
```
GET /seat/list?keyword=客服&status=1&module=小程序&page=1&pageSize=10
```

### 4.2 新增坐席
```
POST /seat
```
**Request Body:**
```json
{
  "seatName": "客服小D",
  "avatar": "base64://... 或 URL",
  "module": "小程序",
  "status": 1,
  "waiterIds": [1001, 1002]
}
```

### 4.3 编辑坐席
```
PUT /seat/{id}
```

### 4.4 删除坐席
```
DELETE /seat/{id}
```

### 4.5 切换坐席状态
```
PUT /seat/{id}/status
```
**Request Body:** `{"status": 0}`

### 4.6 上传坐席头像
```
POST /seat/avatar/upload
Content-Type: multipart/form-data
```

---

## 五、工单接口

### 5.1 工单列表
```
GET /ticket/list?status=pending&source=小程序&keyword=&page=1&pageSize=10
```

### 5.2 工单详情
```
GET /ticket/{ticketId}
```

### 5.3 处理工单
```
PUT /ticket/{ticketId}/handle
```
**Request Body:**
```json
{
  "status": "completed",
  "reply": "您好，问题已处理完毕..."
}
```

---

## 六、订单查询接口（集成现有业务）

### 6.1 查询用户订单列表（右侧面板）
```
GET /user-order/list?userId=10001&type=all&page=1&pageSize=10
```

**Response:**
```json
{
  "code": 200,
  "data": {
    "rows": [
      {
        "orderId": "CP2024031601",
        "orderName": "初级审计员岗位测评订单",
        "amount": "29.90",
        "createTime": "2024-03-16 10:22:00",
        "status": "paid",
        "statusLabel": "已支付"
      }
    ]
  }
}
```

### 6.2 查询商家套餐订单列表
```
GET /merchant-order/list?merchantId=20001&page=1&pageSize=10
```

---

## 七、WebSocket 接口（实时消息推送）

> 详见 `WebSocket消息协议.md`

| 端点 | 说明 |
|---|---|
| `ws://host/ws/chat` | WebSocket 握手端点 |
| 订阅: `/topic/session/{sessionNo}` | 订阅该会话的实时消息（双端） |
| 订阅: `/user/{userId}/queue/notify` | 用户私聊通知（新会话、已读回执） |
| 发布: `/app/chat/send` | 客户端发送消息到服务端 |