sj-miniprogram/online-service/backend-service/docs/API接口文档.md

API 接口文档

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

---

一、会话管理接口

1.1 创建/获取会话

场景: 用户/商家进入聊天页面时调用，若已有进行中的会话则复用

POST /session/create

Request Body:

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

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

Response:

{
  "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:

{
  "sessionId": 1,
  "lastReadMsgId": 99
}

---

三、结算单接口

3.1 查询结算单状态

GET /order-card/{orderCardId}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "status": "completed",
  "reply": "您好，问题已处理完毕..."
}

---

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

6.1 查询用户订单列表（右侧面板）

GET /user-order/list?userId=10001&type=all&page=1&pageSize=10

Response:

{
  "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	客户端发送消息到服务端