# 📋 待实现需求清单

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

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

### 第二阶段（2-3 周）
- [ ] AI 客服功能

### 第三阶段（3-5 周）
- [ ] 文件上传和图片发送
- [ ] 消息已读/未读状态（未读计数待实现）
- [ ] 事件管理页面
- [ ] 知识库功能
- [ ] 用户管理功能

---

## 已确认的技术决策

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