═══════════════════════════════════════════════════
一、入站 Webhook（外部系统 → 本系统）
═══════════════════════════════════════════════════

请求方式：POST /api/webhook/incoming
Content-Type：application/json
鉴权方式：Header Authorization: Bearer <token> 或 body.token 或 ?token=

请求体（JSON）：
{
  "token":     "后台生成的鉴权Token",   // 必填
  "message":   "客户发送的消息",         // 必填
  "sessionId": "自定义会话ID",           // 可选，不传则自动生成
  "agentId":   "指定客服ID"              // 可选
}

成功响应（JSON）：
{
  "success": true,                        // 是否成功
  "reply":   "机器人的回复内容",           // 回复给客户的文本
  "sessionId": "会话ID",                  // 会话标识
  "mode":    "ai",                        // 回复来源（ai/wechat-bot/...）
  "contacts": [],                         // 提取到的联系方式
  "welcomeMessage": ""                    // 欢迎语（首次访问时返回）
}

═══════════════════════════════════════════════════
二、出站 Webhook 事件（本系统 → 外部系统）
（外部系统需要搭建 HTTP 接收端点来监听这些事件）
═══════════════════════════════════════════════════

推送方式：POST → 出站 Webhook URL（管理后台配置）
Header：Content-Type: application/json + X-Webhook-Secret（如配置了 secret）

统一推送格式（JSON）：
{
  "event":     "事件类型",                 // 见下表
  "timestamp": "2025-01-15T08:30:00.000Z", // ISO 时间戳
  "data":      { ... }                     // 事件数据，因事件类型而异
}

所有事件类型一览：
newMessage         ✅默认开启  用户发新消息
contactExtracted   ✅默认开启  提取到联系方式
transferToHuman    ✅默认开启  转人工
newVisitor         ✅默认开启  新访客首次访问
aiReply            ❌默认关闭  AI 回复
（事件开关可在管理后台 → 系统配置中修改）

各事件 data 字段说明：
• newMessage:      { sessionId, message, timestamp }
• aiReply:         { sessionId, reply, provider, timestamp }
• contactExtracted: { sessionId, contacts: [...], timestamp }
• transferToHuman: { sessionId, reason, timestamp }
• newVisitor:      { sessionId, visitorId, timestamp }

═══════════════════════════════════════════════════
三、SaaS 模式数据流（纯机器人模式）
═══════════════════════════════════════════════════

外部系统                本系统                  微信对话开放平台
  │                      │                        │
  │── POST 消息 ────────→│                        │
  │   {token, message}   │                        │
  │                      │── AES加密+签名 ───────→│
  │                      │   POST /v2/bot/query   │
  │                      │←── 加密的回复 ─────────│
  │                      │   {answer, status}     │
  │                      │   AES解密              │
  │←── {reply} ─────────│                        │
  │                      │                        │

说明：
• robotMode=knowledge_only + wxAiEnabled=true 时
• 客户消息经 AES-CBC 加密后发送到微信 /v2/bot/query
• 微信返回加密回复，本系统解密后返回给外部系统
• 微信命中(FAQ) → 返回微信回复内容
• 微信未命中(NOMATCH) → 返回引导留电话术

═══════════════════════════════════════════════════
四、接入示例
═══════════════════════════════════════════════════

① 入站：发送消息（curl）
curl -X POST https://t2.bjhgyjs.com/api/webhook/incoming \
  -H 'Content-Type: application/json' \
  -d '{"token":"你的Token","message":"SGS检测","sessionId":"user_001"}'

② 出站：监听事件（Node.js Express 示例）
const express = require('express');
const app = express();
app.use(express.json());

app.post('/your-webhook-endpoint', (req, res) => {
  const { event, data } = req.body;

  if (event === 'newMessage') {
    console.log('用户消息:', data.message);
    return res.json({ ok: true });
  }

  if (event === 'contactExtracted') {
    console.log('联系方式:', data.contacts);
    return res.json({ ok: true });
  }

  res.json({ ok: true });
});

app.listen(3000);

③ PHP 示例（入站消息）
$ch = curl_init('https://t2.bjhgyjs.com/api/webhook/incoming');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'token' => '你的Token',
    'message' => 'SGS检测',
    'sessionId' => session_id(),
  ]),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 30,
]);
$resp = json_decode(curl_exec($ch), true);
echo $resp['reply'];

④ JavaScript fetch 示例（入站消息）
const res = await fetch('https://t2.bjhgyjs.com/api/webhook/incoming', {
  method: 'POST',
  headers: {'Content-Type':'application/json'},
  body: JSON.stringify({
    token: '你的Token',
    message: '你好',
    sessionId: 'user_' + Date.now()
  })
});
const data = await res.json();
console.log(data.reply);

═══════════════════════════════════════════════════
一、本系统 WebSocket 接口格式
（外部系统 ↔ 本系统，本系统自定义格式）
═══════════════════════════════════════════════════

连接地址：
ws(s)://t2.bjhgyjs.com/ws?token=你的Token&sessionId=会话ID

客户端 → 服务端（发消息）：
// 方式1：发送纯文本（推荐，最简单）
ws.send("你好");

// 方式2：发送 JSON（可选）
ws.send(JSON.stringify({
  type: "message",
  message: "你好"
}));

服务端 → 客户端（回复）：
{
  "type":    "reply",             // 消息类型
  "reply":   "机器人的回复内容",   // 回复文本
  "sessionId": "会话ID",          // 会话标识
  "contacts": []                  // 提取到的联系方式
}

服务端其他消息类型：
• { type: "welcome",  message: "欢迎语" }
• { type: "push",     message: "静默推送话术" }
• { type: "pong" }                  // 心跳响应

═══════════════════════════════════════════════════
二、SaaS 模式数据流（纯机器人模式）
═══════════════════════════════════════════════════

外部系统                本系统                  微信对话开放平台
  │                      │                        │
  │── ws.send("你好") ──→│                        │
  │                      │── AES加密+签名 ───────→│
  │                      │   POST /v2/bot/query   │
  │                      │←── 加密的回复 ─────────│
  │                      │   {answer:"我很好"}    │
  │←── {type:"reply",    │   AES解密              │
  │      reply:"我很好"} │                        │
  │                      │                        │

说明：
• WebSocket 和 Webhook 走同一个 handleChat() 处理逻辑
• SaaS 模式下两者都会调用微信对话平台 /v2/bot/query
• 外部系统无需关心加解密，本系统自动处理

═══════════════════════════════════════════════════
三、接入示例
═══════════════════════════════════════════════════

JavaScript 示例：
const ws = new WebSocket(
  'wss://t2.bjhgyjs.com/ws?token=你的Token&sessionId=user_001'
);

ws.onopen = () => {
  console.log('已连接');
  ws.send('你好');  // 发送消息
};

ws.onmessage = (e) => {
  const data = JSON.parse(e.data);
  if (data.type === 'reply') {
    console.log('机器人回复:', data.reply);  // "我很好"
  }
};

ws.onclose = () => console.log('断开');

心跳保活（重要）：
// 每 30 秒发送一次，防止连接被断开
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send('ping');
  }
}, 30000);
// 服务端收到 'ping' 返回 { type: "pong" }