# 任务说明书-127-坐席离线状态更新

> **版本**: v1.0 | **日期**: 2026-07-25

---

## 📋 基本信息

| 项目 | 内容 |
|------|------|
| **任务名称** | 修复坐席离线状态更新逻辑 |
| **任务ID** | #127 |
| **优先级** | 🟠P1 |
| **类型** | Bug修复 |
| **状态** | ✅ 已完成 |
| **负责人** | Simon |
| **创建日期** | 2026-07-25 |

---

## 📥 输入项来源

### 关联缺陷
| 来源 | 说明 |
|------|------|
| 需求 REQ-用户-004 | 坐席在线状态查询功能 |

### 需了解的现有代码
| 模块/文件 | 说明 |
|-----------|------|
| `backend/app/api/ws.py` | WebSocket 端点，断开时调用 disconnect() |
| `backend/app/services/ws_manager.py` | ConnectionManager，disconnect() 方法 |
| `backend/app/models/agent.py` | Agent 模型，status 字段 |

---

## 📤 输出成果要求

### 交付物
- 修改 `ws_manager.py` 或 `ws.py`，在 WebSocket 断开时更新坐席状态为 offline

---

## 🔧 验证方式

1. 坐席登录 → 状态变为 online
2. 坐席关闭浏览器窗口
3. 查询 API `/api/h5/agents/online-status` → 返回 `online: false`

---

## ✅ 完成标准

- [x] 坐席关闭浏览器后，数据库状态自动更新为 offline
- [x] API 能正确返回坐席离线状态

### Bug 根因记录

WS URL 参数 `{agent_id}` 实际传递的是企微 `user_id`（如 `sxn`），而非 DB 主键 `Agent.id`（如 `agent-sxn-001`）。代码错误使用 `Agent.id == agent_id` 导致每次都查不到坐席。修复为 `Agent.user_id == agent_id`。

---

## 📎 附件

- [PRD-REQ-用户-004-坐席在线状态查询-v1.0.md](../01-产品文档/05-用户端H5/PRD-REQ-用户-004-坐席在线状态查询-v1.0.md)