wecom_it_smart_desk/docs/02-技术文档/技术方案-REQ-用户-004-坐席在线状态查询.md

技术方案-REQ-用户-004-坐席在线状态查询

基本信息

字段	内容
需求编号	REQ-用户-004
版本	v1.2
日期	2026-07-25
状态	已实现（BUG-用户-001 已修复）
作者	Simon
关联文档	PRD-REQ-用户-004、BUG-用户-001

---

1. 技术架构设计

1.1 接口设计

1.1.1 新增 API

路径：GET /h5/agents/online-status

所属模块：backend/app/api/h5.py（Nginx 将 /h5/agents/* 代理到 FastAPI /h5/agents/*）

认证方式：公开接口，无需认证

请求参数：无

响应格式：

{
  "code": 0,
  "message": "success",
  "data": {
    "online": true
  }
}

响应字段说明：

字段	类型	说明
code	int	0=成功，非0=失败
message	string	响应描述
data.online	boolean	是否有在线坐席

1.2 数据流设计

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   H5前端    │  HTTP   │  后端API   │  SQL   │  PostgreSQL │
│ (轮询30秒)  │────────▶│ /h5/agents │───────▶│  agents表  │
│             │         │ /online-status│        │            │
└─────────────┘         └─────────────┘         └─────────────┘
       │                                               │
       │  online: true/false                           │
       ▼                                               ▼
┌─────────────┐                                 ┌─────────────┐
│  标题栏状态 │                                 │ status='online'│
│  坐席在线   │                                 │ 的坐席记录   │
└─────────────┘                                 └─────────────┘

---

2. 后端实现

2.1 接口实现

文件：backend/app/api/h5.py

@router.get("/h5/agents/online-status")
async def get_agents_online_status(db: AsyncSession = Depends(get_db)):
    """获取坐席在线状态（H5公开接口）。

    查询当前是否有在线坐席，返回 true/false。

    Returns:
        Dict: 统一响应格式，包含 online 字段
    """
    # 查询在线坐席数量
    stmt = select(func.count(Agent.id)).where(Agent.status == "online")
    result = await db.execute(stmt)
    count = result.scalar() or 0

    return success_response(data={"online": count > 0})

2.2 依赖导入

from sqlalchemy import select, func
from app.models.agent import Agent

2.3 路由注册

在 backend/app/api/router.py 中确认 h5 路由已注册：

# 确认已有
router.include_router(h5.router, prefix="/h5", tags=["H5"])

---

3. 前端实现

3.1 Store 修改

文件：frontend-h5/src/stores/conversation.ts

修改内容：

// 将硬编码改为从 API 获取
const agentOnline = ref<boolean>(false)

// 新增获取坐席在线状态的方法
async function fetchAgentOnlineStatus() {
  try {
    const res = await fetch('/api/h5/agents/online-status')
    const data = await res.json()
    if (data.code === 0) {
      agentOnline.value = data.data.online
    }
  } catch (e) {
    console.error('获取坐席在线状态失败:', e)
    // 失败时默认离线，避免误导
    agentOnline.value = false
  }
}

// 新增轮询定时器
let pollTimer: number | null = null

function startPolling() {
  if (pollTimer) return
  // 立即获取一次
  fetchAgentOnlineStatus()
  // 每30秒轮询
  pollTimer = window.setInterval(fetchAgentOnlineStatus, 30000)
}

function stopPolling() {
  if (pollTimer) {
    clearInterval(pollTimer)
    pollTimer = null
  }
}

// 页面可见性处理
if (typeof document !== 'undefined') {
  document.addEventListener('visibilitychange', () => {
    if (document.hidden) {
      stopPolling()
    } else {
      fetchAgentOnlineStatus()
      startPolling()
    }
  })
}

// 初始化时启动轮询
onMounted(() => {
  startPolling()
})

// 组件卸载时停止轮询
onUnmounted(() => {
  stopPolling()
})

3.2 模板修改

文件：frontend-h5/src/components/chat/ChatPanel.vue

现有模板已支持：

• v-if="store.agentOnline" 显示"坐席在线"
• v-else 显示"坐席离线"

无需修改。

---

4. WebSocket 断连自动离线

4.1 背景

坐席端关闭浏览器窗口时，需要自动将坐席状态更新为 offline，否则 H5 端将始终显示"坐席在线"。

4.2 实现

文件：backend/app/api/ws.py

在 agent_websocket_endpoint() 的 finally 块中添加离线更新逻辑：

finally:
    # 更新坐席状态为 offline（finally 块确保断开时一定执行）
    try:
        session_factory = _get_session_factory()
        async with session_factory() as db:
            # ⚠️ agent_id 在 URL 中对应 Agent.user_id（不是 Agent.id）
            stmt = select(Agent).where(Agent.user_id == agent_id)
            result = await db.execute(stmt)
            agent = result.scalar_one_or_none()
            if agent and agent.status != "offline":
                agent.status = "offline"
                await db.commit()
    except Exception as e:
        logger.warning(f"更新坐席状态失败: {e}")

4.3 Bug 根因（重要教训）

WS URL 参数 {agent_id} 实际传递的是企微 user_id（如 sxn），而非 DB 主键 Agent.id（如 agent-sxn-001）。最初代码错误使用 Agent.id == agent_id，导致每次都查不到坐席，离线状态从未生效。

字段	值	说明
Agent.id	agent-sxn-001	DB 主键（UUID 格式）
Agent.user_id	sxn	企微 userid
URL {agent_id}	sxn	实际传递的是 user_id

修复：Agent.id → Agent.user_id

---

5. Nginx 路由配置

5.1 问题

Nginx 中 /h5/ 被配置为静态文件 alias，导致 /h5/agents/online-status 返回 H5 首页 HTML 而非 JSON。

5.2 解决方案

在 nginx.conf 的 location /h5/ 之前添加代理规则（nginx 最长前缀匹配优先）：

# H5 坐席状态 API — /h5/agents/
location /h5/agents/ {
    proxy_pass http://backend_api/h5/agents/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

# H5 坐席队列状态 API — /h5/queue/
location /h5/queue/ {
    proxy_pass http://backend_api/h5/queue/;
    ...
}

# H5 用户端（兜底，静态文件）
location /h5/ {
    alias /usr/share/nginx/html/h5/;
    index index.html;
    try_files $uri /h5/index.html;
}

需要同时在 HTTPS (443) 和 HTTP (80) 两个 server block 中添加。

---

6. 部署与配置

6.1 无需新增配置

• 不需要新的环境变量
• 不需要新的数据库表
• 不需要新的 Redis 缓存

6.2 部署顺序

1. 部署后端（重启）
2. 部署 H5 前端

---

7. 测试要点

5.1 后端测试

# 测试接口返回
curl http://localhost:8000/api/h5/agents/online-status

# 预期响应
{"code":0,"message":"success","data":{"online":true}}

5.2 前端测试

测试场景	预期结果
有在线坐席	显示"坐席在线"（绿色）
无在线坐席	显示"坐席离线"（灰色）
30秒后	状态自动刷新
切换浏览器标签页	暂停轮询
切回浏览器标签页	立即刷新一次

---

8. 风险与回滚

8.1 风险

风险	影响	缓解措施
轮询频率过高	增加数据库查询压力	限制30秒，且只查 count
接口被恶意调用	无（只读数据）	-

8.2 回滚方案

• 后端：回滚 h5.py 中的接口代码
• 前端：恢复 agentOnline = true 硬编码

---

9. 变更记录

日期	版本	变更内容	变更人
2026-07-25	v1.0	初始版本	Simon
2026-07-25	v1.1	API 路径修正（/api/h5/ → /h5/）；新增 §4 WS 断连自动离线（含 Agent.id→user_id bug 修复）；新增 §5 Nginx 路由配置（/h5/agents/ 代理）；状态更新为已实现	Simon
2026-07-25	v1.2	BUG-用户-001 修复：新增 §10 离线限制呼叫人工（后端 shake 加在线检查 + 前端 InputBar 加 agentOnline 判断）	Simon

---

10. BUG-用户-001 补充：离线限制呼叫人工（v1.2）

10.1 问题

坐席离线时，用户点击"人工咨询"按钮，后端直接入队 queued，因无在线坐席永久无人接单。

10.2 后端修改

文件：backend/app/api/h5.py — shake 接口

在 conversation.status = "queued" 之前增加坐席在线检查：

# 前置校验：必须有在线坐席
from app.models.agent import Agent
from sqlalchemy import select, func
online_count = await db.execute(
    select(func.count(Agent.id)).where(Agent.status == "online")
)
count = online_count.scalar() or 0
if count == 0:
    raise AppException(
        code=1003,
        message="暂无在线坐席，请稍后再试。Duckula（达寇拉）仍在努力为您提供帮助～"
    )

10.3 前端修改

文件：frontend-h5/src/components/chat/InputBar.vue

callAgentState 计算属性首行增加坐席在线判断：

// 坐席离线 → 按钮禁用
if (!store.agentOnline) return 'disabled'

按钮提示文案调整：callAgentBtnTitle 中离线时显示"坐席离线，暂不可用"。

10.4 测试要点

场景	预期
坐席离线，AI ≥3次	按钮灰色，提示"坐席离线，暂不可用"
坐席上线(30s内)，AI ≥3次	按钮绿色，可点击
离线时 curl shake	{ code: 1003, message: "暂无在线坐席..." }