wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-126-坐席在线状态查询.md

任务说明书-126-坐席在线状态查询

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

---

📋 基本信息

项目	内容
任务名称	坐席在线状态查询功能开发
任务ID	#126
优先级	🟠P1
类型	功能开发
状态	✅ 已完成
负责人	Simon
创建日期	2026-07-25
计划完成日期	2026-07-25

---

📥 输入项来源

产品需求

来源文档	相关章节	说明
01-产品文档/05-用户端H5/PRD-REQ-用户-004-坐席在线状态查询-v1.0.md	§1-§3	需求描述、用户故事、功能需求

技术方案

来源文档	相关章节	说明
02-技术文档/技术方案-REQ-用户-004-坐席在线状态查询.md	§1-§2	API接口设计、后端实现、前端实现

原型设计

来源文档	页面	说明
01-产品文档/05-用户端H5/原型-REQ-用户-000-H5用户端-v2.0.html	标题栏区域	坐席在线/离线状态显示（已存在）

需了解的现有代码（历史现状）

模块/文件	说明	需了解的内容
backend/app/api/h5.py	H5 API 模块	新增接口位置、已有接口模式
frontend-h5/src/stores/conversation.ts	Pinia 状态管理	agentOnline 状态定义、轮询实现
frontend-h5/src/components/chat/ChatPanel.vue	聊天面板组件	标题栏状态显示逻辑

---

📤 输出成果要求

交付物清单

#	交付物	类型	说明
1	backend/app/api/h5.py 新增接口	代码	GET /api/h5/agents/online-status
2	frontend-h5/src/stores/conversation.ts 修改	代码	实现轮询和可见性处理
3	技术方案文档	文档	更新验证要点

代码要求

• 遵循项目代码规范
• 所有新增代码通过 ESLint / Pylint 检查

文档要求

• 更新技术方案文档中的验证要点

---

🔧 验证方式

功能验证

验证项	验证方法	预期结果
API 接口正常	curl http://localhost:8000/api/h5/agents/online-status	返回 {"code":0,"data":{"online":true/false}}
有在线坐席时显示正确	手动测试（数据库有 online 坐席）	显示"坐席在线"
无在线坐席时显示正确	手动测试（数据库无 online 坐席）	显示"坐席离线"
轮询机制正常	等待30秒观察	状态自动刷新
页面可见性处理	切换浏览器标签页再切回	状态立即刷新

---

✅ 完成标准

验收条件

• 后端 API 代码已完成
• 前端轮询逻辑已完成
• 功能验证通过

产出确认

• 代码已提交
• 接口测试通过
• 页面显示验证通过

---

📊 工作分解

子任务

子任务	负责人	预估工时	状态
后端：新增 GET /h5/agents/online-status 接口	Simon	0.5h	✅ 完成
前端：修改 conversation.ts 实现轮询	Simon	0.5h	✅ 完成
测试：curl 验证 + 浏览器验证	Simon	0.5h	✅ 完成

---

📞 依赖与阻塞

前置依赖

依赖任务	依赖说明	状态
REQ-用户-004 PRD	需求已完成	已完成
REQ-用户-004 技术方案	设计已完成	已完成

阻塞因素

阻塞项	影响范围	解决方案
无	-	-

---

📈 变更记录

日期	变更内容	变更人	说明
2026-07-25	创建任务	Simon	初始版本
2026-07-25	完成	Simon	API 路径修正为 /h5/agents/online-status；Nginx 添加 /h5/agents/ 代理；30秒轮询实现；功能验证通过

---

📎 附件

• PRD-REQ-用户-004-坐席在线状态查询-v1.0.md
• 技术方案-REQ-用户-004-坐席在线状态查询.md
• 原型-REQ-用户-000-H5用户端-v2.0.html