AI-CS/doc/待实现需求清单.md

📋 待实现需求清单

第一阶段：核心功能优化（优先级：高）

1. UI 布局改进（客服端四栏布局）✅ 部分完成

完成状态：

• ✅ 四栏布局基础框架（已实现）
  • ✅ 最左侧导航菜单栏（固定宽度 64px）
  • ✅ 左侧对话列表栏（固定宽度 320px）
  • ✅ 中间聊天内容栏（自适应宽度）
  • ✅ 右侧访客详情栏（固定宽度 320px）
  • ✅ 统一顶部栏高度（h-16），三栏对齐
• ✅ 左侧栏对话列表（基础功能已实现）
  • ✅ 显示所有对话
  • ✅ 对话头像（圆形，基于 visitor_id 生成颜色）
  • ✅ 对话ID、访客ID、状态显示
  • ✅ 最后更新时间显示
  • ✅ 对话选择高亮
  • ✅ 搜索框（"Q Search"）- 已完成（支持搜索对话内容、对话ID、访客ID）
  • ✅ 最后一条消息预览 - 已完成（显示最后一条消息的前50个字符）
  • ✅ 搜索后点击对话自动定位到匹配消息 - 已完成（居中显示历史消息，最后一条滚动到底部）
  • ✅ 关键词高亮显示 - 已完成（黄色背景高亮）
  • ✅ 已读/未读状态图标 - 基础完成（单/双对勾 + 未读徽标，未读数量统计将继续迭代）
• ✅ 中间栏聊天内容（核心功能已实现）
  • ✅ 对话标题显示
  • ✅ 消息区域（滚动显示）
  • ✅ 访客消息（左侧，白色气泡）
  • ✅ 客服消息（右侧，蓝色气泡）
  • ✅ 时间戳显示（智能格式化）
  • ✅ 输入框和发送按钮
  • ✅ 自动滚动到底部
  • ✅ WebSocket 实时消息推送
  • ❌ 系统消息显示 - 待实现
  • ❌ "last seen" 信息 - 待实现（已显示但为静态数据）
• ✅ 右侧栏访客详情（UI 已实现，数据待完善）
  • ✅ 访客头像（基于 visitor_id 生成颜色）
  • ✅ 在线/离线状态显示（基于对话状态）
  • ✅ 联系信息区域（邮箱、电话、备注）
  • ✅ 技术信息区域（网站、来源、位置等）
  • ✅ 刷新按钮和更多选项图标
  • ❌ 联系信息手动添加功能 - 待实现（只有按钮占位）
  • ❌ 技术信息自动收集和显示 - 待实现（只有占位文本）
• ✅ 无需跳转切换对话（已实现）
  • ✅ 点击对话列表切换，中间栏和右侧栏自动更新
  • ✅ 对话切换时自动加载消息
  • ✅ WebSocket 连接自动切换

需求描述（剩余部分）：

• 左侧栏增强：
  • 搜索框（"Q Search"），支持搜索对话内容
  • 最后一条消息预览
  • 已读/未读状态图标（未读数量统计上限、批量操作待完善）
• 中间栏增强：
  • 系统消息显示（如 "Visitor opened the page", "You joined the chat"）
  • 实时 "last seen" 信息
• 右侧栏数据完善：
  • 联系信息手动添加/编辑功能
  • 技术信息自动收集和显示

技术要点：

• ✅ 路由已改为 /agent/dashboard（统一页面）
• ✅ 使用 React 状态管理当前选中的对话
• ❌ 响应式设计（移动端可能需要折叠侧栏）- 待实现
• ✅ 左侧栏：对话列表组件
• ✅ 中间栏：聊天内容组件
• ✅ 右侧栏：访客详情组件

预计剩余工作量：0.5-1 周（完成搜索、系统消息、数据收集等功能）

---

1.1. 会话搜索功能 ✅ 已完成

完成状态：

• ✅ 搜索框UI（已实现）
• ✅ 后端搜索接口（GET /conversations/search?q=关键词）
• ✅ 搜索范围：消息内容、对话ID、访客ID
• ✅ 前端实时搜索（300ms防抖）
• ✅ 搜索结果高亮显示（关键词黄色背景高亮）
• ✅ 点击搜索结果自动定位到匹配消息（历史消息居中显示，最后一条滚动到底部）
• ✅ 搜索结果实时更新

技术实现：

• 后端：SearchConversations 函数，支持搜索消息内容和ID
• 前端：防抖搜索、关键词高亮、消息定位

---

1.2. 客服个人资料管理 ✅ 已完成

完成状态：

• ✅ 数据库（已实现）
  • ✅ User 模型增加字段：avatar_url、nickname、email、created_at、updated_at
• ✅ 后端（已实现）
  • ✅ 文件存储服务（backend/infra/storage.go）：本地存储服务，可扩展为云存储
  • ✅ 个人资料服务（backend/service/profile_service.go）：提供获取、更新个人资料和上传头像功能
  • ✅ 个人资料控制器（backend/controller/profile_controller.go）：处理 HTTP 请求
  • ✅ 新增接口：
    • ✅ GET /agent/profile/:user_id：获取个人资料
    • ✅ PUT /agent/profile/:user_id：更新个人资料（昵称、邮箱）
    • ✅ POST /agent/avatar/:user_id：上传头像（支持 jpg、png、gif，最大 10MB）
  • ✅ 静态文件服务：/uploads 路径用于访问上传的头像等文件
• ✅ 前端（已实现）
  • ✅ 个人资料 API 服务（frontend/features/agent/services/profileApi.ts）
  • ✅ 个人资料 Hook（frontend/features/agent/hooks/useProfile.ts）：管理个人资料状态
  • ✅ 个人资料弹窗组件（frontend/components/dashboard/ProfileModal.tsx）：
    • ✅ 显示和编辑昵称、邮箱
    • ✅ 上传头像（支持预览、上传进度、错误提示）
    • ✅ 实时更新个人资料
  • ✅ DashboardHeader：显示头像和设置按钮，点击打开个人资料弹窗
  • ✅ 头像工具函数（frontend/utils/avatar.ts）：拼接完整的头像 URL、生成头像颜色、获取头像显示文本

功能特性：

• ✅ 支持头像上传（jpg、png、gif，最大 10MB）
• ✅ 支持修改昵称和邮箱
• ✅ 头像实时预览
• ✅ 如果没有上传头像，显示彩色圆形头像（基于用户ID生成颜色）
• ✅ 头像显示在 DashboardHeader 中

技术要点：

• ✅ 文件存储采用可扩展设计，目前使用本地存储，后续可切换为云存储（OSS、S3 等）
• ✅ 头像 URL 拼接逻辑：如果后端返回相对路径，前端自动拼接 API_BASE_URL
• ✅ 头像上传支持文件类型和大小验证
• ✅ 个人资料更新实时刷新 UI

预计工作量：已完成

---

1.3. 访客信息收集和显示 ✅ 部分完成

完成状态：

• ✅ 右侧栏 UI 显示（已实现）
  • ✅ 联系信息区域（邮箱、电话、备注）
  • ✅ 技术信息区域（网站、来源、位置、语言、浏览器、操作系统、User Agent、IP地址）
  • ✅ 添加按钮（邮箱、电话、备注）
• ✅ 自动收集技术信息
  • ✅ 网站（当前页面URL）
  • ✅ 来源（referrer，从哪个页面跳转过来）
  • ✅ 浏览器信息（User Agent解析）
  • ✅ 操作系统（User Agent解析）
  • ✅ 语言（浏览器语言设置）
  • ✅ IP地址（后端获取）
  • ❌ 位置（通过IP地址定位，需要第三方服务）
• ✅ 手动添加联系信息
  • ✅ 邮箱添加/编辑功能（PUT /conversations/:id/contact）
  • ✅ 电话添加/编辑功能（PUT /conversations/:id/contact）
  • ✅ 备注添加/编辑功能（PUT /conversations/:id/contact）

需求描述（剩余部分）：

• 自动收集：访客端自动收集技术信息
  • 网站（当前页面URL）
  • 来源（referrer，从哪个页面跳转过来）
  • 浏览器信息（User Agent解析）
  • 操作系统（User Agent解析）
  • 语言（浏览器语言设置）
  • IP地址（后端获取）
  • 位置（通过IP地址定位，需要第三方服务）
• 手动添加：客服可以手动添加/编辑联系信息（已支持，后续可迭代优化校验/权限）
• 新增能力：支持清空邮箱/电话/备注（输入空值即可）

技术要点：

• 数据库：
  • 对话表增加字段：website, referrer, browser, os, language, ip_address, location
  • 访客表或对话表增加字段：email, phone, notes（客服手动添加）
• 前端（访客端）：
  • 页面加载时收集：window.location.href, document.referrer, navigator.userAgent, navigator.language
  • 发送到后端保存
• 后端：
  • 接收访客信息并保存
  • 获取IP地址（从请求头）
  • IP地址定位（可选，需要第三方API）
• ✅ 新增接口：PUT /conversations/:id/contact（更新访客邮箱/电话/备注）
• 前端（客服端）：
  • ✅ 右侧栏显示所有信息（UI 已实现）
  • ✅ 编辑弹窗支持新增/修改邮箱、电话、备注
  • ✅ 保存后实时刷新访客详情
  • ❌ 更丰富的表单校验/批量编辑 - 待实现

预计工作量：0.5 周（完成 IP->地理位置、表单校验优化等收尾工作）

---

1.4. 系统消息记录 ✅ 初版完成

完成状态：

• ✅ 消息表新增 message_type 字段（区分 user_message / system_message）
• ✅ 新建对话时自动记录访客事件
  • "Visitor opened the page [页面URL]"
  • "Visitor came from [referrer URL]"（有来源时记录）
• ✅ 前端以灰色居中样式展示系统消息
• ❌ 客服行为事件（如 "You joined the chat"）- 后续扩展

后续迭代方向：

• 扩展更多系统事件（客服加入、对话状态变化等）
• 支持系统消息筛选/折叠

---

2. 对话状态管理（在线/离线）✅ 基础功能已完成，优化待实现

完成状态：

• ✅ 右侧栏状态显示（已实现，基于对话状态）
  • ✅ 显示在线/离线状态（绿色圆点表示在线，灰色表示离线）
  • ✅ 基于对话状态（status === "open" 显示在线）
• ✅ 实时状态更新（基础功能已实现）
  • ✅ 访客打开页面时自动标记为在线（WebSocket 连接建立）
  • ✅ 访客关闭/离开页面时自动标记为离线（WebSocket 断开）
  • ✅ 后端维护在线状态，通过 WebSocket 推送给客服端
  • ✅ 实时同步状态到客服端
  • ✅ 在对话列表中显示在线/离线图标（绿色圆点 = 在线）
  • ✅ 记录最后活跃时间（last_seen_at）- 已实现（在 ConversationDetail 中）

需求描述（剩余部分）：

• ❌ 通过 WebSocket 心跳机制检测在线状态（定期更新 last_seen_at）- 待实现
• ❌ 根据 last_seen_at 判断是否在线（例如，如果 last_seen_at 在最近 60 秒内，则认为在线）- 待实现
• ❌ 在右侧栏显示"last seen"信息（如 "last seen today at 11:08"）- 待实现（已显示但为静态数据）
• ❌ 定期轮询对话列表，更新所有对话的状态 - 待实现

技术要点：

• ✅ 右侧栏状态显示（已实现，基于对话状态）
• ✅ 使用 WebSocket 检测访客在线状态 - 已实现（连接/断开时更新状态）
• ❌ 心跳间隔：30 秒 - 待实现
• ❌ 离线判定：断开后 60 秒标记为离线 - 待实现（目前是断开后立即标记为离线）
• ✅ 后端维护在线状态，通过 WebSocket 推送给客服端 - 已实现
• ✅ 记录最后活跃时间（last_seen_at）- 已实现
• ✅ 对话列表中显示在线/离线图标（绿色圆点 = 在线）- 已实现

已实现功能：

• 后端：ConversationService.UpdateVisitorOnlineStatus 和 UpdateLastSeenAt 方法
• 后端：Hub 回调机制，在客户端连接/断开时调用回调函数
• 后端：Client 添加 isVisitor 字段，区分访客和客服
• 后端：通过 WebSocket 广播 visitor_status_update 事件
• 前端：WebSocket 客户端添加 isVisitor 参数
• 前端：客服端接收 visitor_status_update 事件，刷新对话详情
• 前端：在对话列表中显示在线/离线图标

预计工作量：0.5 周（完成心跳机制和离线判定优化）

---

第二阶段：AI 功能（优先级：中高）

3. AI 客服功能 ❌ 待实现

需求描述：

• 客户可以选择：人工客服 / AI 客服
• AI 客服通过 API 调用（如 OpenAI、文心一言等）
• 对话中可切换人工客服

技术要点：

• 对话表增加字段：service_type（human / ai）
• 前端：选择服务类型界面
• 后端：根据类型路由到人工或 AI 处理
• AI 处理：调用 AI API，返回回复
• 需要配置 AI API Key

待确认：

• AI 服务商选择（OpenAI、文心一言、通义千问等）
• API Key 配置方式
• 成本控制（是否需要限制调用次数）

预计工作量：2-3 周

---

第三阶段：完整功能（优先级：中）

4. 文件上传和图片发送 ❌ 待实现

需求描述：

• 支持文件上传（文档、图片等）
• 支持粘贴图片发送
• 显示文件/图片预览
• 文件下载功能

技术要点：

• 文件存储：可扩展设计（目前本地存储，后续可切换云存储）
• 文件大小限制：10MB
• 支持类型：图片（jpg, png, gif）、文档（pdf, doc, docx, txt）
• 数据库：消息表增加 file_url、file_type、file_name 字段
• 后端：文件上传接口，文件存储抽象层（便于切换云存储）
• 前端：文件选择器、拖拽上传、粘贴图片监听
• 图片预览：缩略图显示

预计工作量：1 周

---

5. 消息已读/未读状态 ✅ 部分完成

完成状态：

• ✅ 数据库：消息表新增 is_read、read_at 字段
• ✅ 后端：提供批量标记已读接口 PUT /messages/read
• ✅ WebSocket：推送 messages_read 事件，同步状态
• ✅ 前端（客服端）：聊天气泡与对话列表显示单/双对勾，系统消息灰色居中
• ✅ 前端（访客端）：聊天气泡显示已读回执
• ✅ 自动标记逻辑：双方打开对话（滚动到底部）即触发已读
• ❌ 未读数量统计（对话列表数字提示）- 待实现
• ❌ 自定义已读触发条件（更精确的滚动检测）- 待优化

后续计划：

• 统计对话未读数量并在列表展示
• 为客服提供“标记全部已读”操作
• 进一步区分系统消息、客服消息的回执逻辑

---

6. 事件管理页面（FAQ/知识库）❌ 待实现

需求描述：

• 事件的增删查改
• 记录问题和答案
• 关键词组合搜索（用 % 分隔关键词）
• 搜索逻辑：包含所有关键词（AND 查询）
• 示例：openai%api%调用 → 搜索包含 "openai" AND "api" AND "调用" 的记录

技术要点：

• 数据库：事件表（id, question, answer, keywords, created_at, updated_at 等）
• 后端：CRUD 接口 + 关键词搜索接口
• 搜索范围：问题、答案、关键词字段
• 匹配方式：包含所有关键词（AND）
• 前端：事件管理页面（列表、添加、编辑、删除、搜索）
• 搜索框：支持 % 分隔关键词

待确认：

• 事件分类：暂时不需要
• 关联对话：是否关联到具体对话（待定）

预计工作量：1-2 周

---

7. 知识库功能（AI 结合文档）❌ 待实现

需求描述：

• 客服上传技术文档（PDF、Word、TXT、Markdown 等）
• AI 结合知识库内容回复
• 支持文档管理（上传、删除、查看）

技术要点：

• 文档存储：本地文件系统或对象存储
• 文档处理：解析、向量化（用于检索）
• AI 回复：检索相关文档 → 结合文档内容生成回复
• 管理界面：文档上传、列表、删除
• 向量化方案：本地向量库或云服务

待确认：

• 文档格式支持（PDF、Word、TXT、Markdown）
• 向量化方案选择
• 存储方式（本地存储还是云存储）

预计工作量：2 周

---

8. 用户管理功能 ❌ 待实现

需求描述：

• 管理员对客服的增删查改
• 权限管理（角色、权限分配）

技术要点：

• 用户列表页面
• CRUD 操作
• 权限系统（基于角色的访问控制）
• 角色：管理员、客服、只读（待定）
• 权限粒度：查看、编辑、删除、创建用户

预计工作量：1 周

---

实施时间线

第一阶段（2-3 周）

• UI 布局改进（四栏布局）
  • 左侧栏：对话列表
  • 中间栏：聊天内容
  • 右侧栏：访客详情
• 会话搜索功能
• 客服个人资料管理（头像上传等）
• 访客信息收集和显示
  • 自动收集技术信息
  • 手动添加联系信息
  • 系统消息记录
• 对话状态管理（在线/离线）

第二阶段（2-3 周）

• AI 客服功能

第三阶段（3-5 周）

• 文件上传和图片发送
• 消息已读/未读状态（未读计数待实现）
• 事件管理页面
• 知识库功能
• 用户管理功能

---

已确认的技术决策

1. 文件存储：可扩展设计，目前本地存储，后续可切换云存储
2. 已读判定：客服打开对话并滑动到底部
3. 事件搜索：包含所有关键词（AND 查询）
4. 事件分类：暂时不需要
5. UI 布局：四栏布局（最左侧导航、左侧对话列表、中间聊天内容、右侧访客详情）
6. 会话搜索：支持搜索对话内容，定位到对应消息
7. 客服资料：支持头像上传和个人信息修改
8. 访客信息：
   • 自动收集：网站、来源、浏览器、OS、语言、IP地址、位置
   • 手动添加：邮箱、电话、备注（客服可编辑）
9. 系统消息：记录访客打开页面、来源页面、客服加入等事件
10. 头像：访客使用默认头像（颜色区分），客服可上传头像