ai-cs/doc/系统角色说明.md

系统角色说明

当前系统状态

✅ 已实现：访客端（/chat 页面）

访客的特点：

• 不需要登录注册
• 访问 /chat 页面时自动生成访客ID
• 访客ID存储在浏览器的 localStorage 中
• 发送消息时，sender_is_agent: false, sender_id: 0
• 可以直接测试，无需任何配置！

访客能做什么：

• ✅ 自动创建对话
• ✅ 发送消息
• ✅ 查看历史消息
• ✅ 刷新页面后消息还在

测试访客功能：

# 1. 启动后端和前端
# 2. 浏览器打开 http://localhost:3000/chat
# 3. 直接发送消息测试，无需登录！

---

❌ 未实现：客服端（需要单独开发）

客服的特点（未来功能）：

• 需要登录（使用 /register 和 /login 接口）
• 登录后获取客服ID
• 发送消息时，sender_is_agent: true, sender_id: 客服ID
• 需要创建一个新的页面，比如 /agent/chat

客服需要能做什么（未来功能）：

• 登录系统
• 查看所有对话列表
• 选择某个对话进行回复
• 发送消息时标识为客服

后端已支持：

• ✅ 后端代码已经支持客服发送消息（sender_is_agent: true）
• ✅ 后端会检查：如果是客服，sender_id 必须提供且不能为0

---

代码逻辑说明

后端检查逻辑（backend/service/service.go）

// 第122-125行
if req.SenderIsAgent && req.SenderID == 0 {
    c.JSON(http.StatusBadRequest, gin.H{"error": "客服id不能为空"})
    return
}

含义：

• 如果 sender_is_agent == true（是客服），那么 sender_id 不能为0
• 如果 sender_is_agent == false（是访客），sender_id 可以为0

所以访客可以直接发送消息，不需要ID！

前端发送逻辑（frontend/app/chat/page.tsx）

// 第187-188行
sender_is_agent: false,  // false = 访客发的
sender_id: 0,            // 访客ID（0表示不需要）

这是访客端页面，所以固定为 false 和 0

---

未来开发计划

客服端页面开发（待实现）

需要创建：

1. 客服登录页面：/agent/login

   • 使用现有的 /login 接口
   • 登录后保存客服ID和token

2. 客服对话列表页面：/agent/conversations

   • 显示所有未关闭的对话
   • 显示每个对话的访客ID、最后消息时间等

3. 客服聊天页面：/agent/chat/[conversationId]

   • 类似访客聊天页面
   • 发送消息时：sender_is_agent: true, sender_id: 客服ID
   • 显示对话双方的消息（访客在左，客服在右）

---

测试建议

当前可以测试的（访客端）

1. ✅ 访问 /chat 页面
2. ✅ 发送消息（以访客身份）
3. ✅ 查看历史消息
4. ✅ 刷新页面后消息还在

暂时无法测试的（客服端）

1. ❌ 客服登录（页面还没创建）
2. ❌ 客服查看对话列表（页面还没创建）
3. ❌ 客服回复消息（页面还没创建）

但你可以用两个浏览器窗口测试：

• 窗口1：访客A，发送消息
• 窗口2：访客B，查看对话（看到访客A的消息）

---

总结

当前状态：

• ✅ 访客端完全可用，可以直接测试
• ❌ 客服端还未开发，需要单独实现

测试时：

• 你就是在模拟访客角色
• 不需要任何登录或配置
• 直接访问 /chat 就可以发送消息！

后端已经准备好了，支持访客和客服两种角色，只是前端客服页面还没做而已。