chat-widget

用途

本技能用于构建一个实时客服聊天系统，包含面向用户的悬浮聊天组件（Widget）和面向客服人员的后台管理面板（Admin Dashboard）。当用户希望为应用添加实时聊天、构建客户支持聊天功能、实现用户与管理员之间的实时消息、或添加应用内支持渠道时，可使用本技能。

主要能力

• 用户端悬浮聊天按钮与消息面板，支持未读徽章、连接状态指示。
• 管理后台聊天列表（活跃/归档）与对话详情视图，支持归档/恢复控制、用户信息展示。
• 基于 WebSocket 与 REST API 的实时通信。
• 数据模型：support_chats（每个用户一个聊天）与 support_messages（每个聊天多条消息）。
• 未读状态跟踪、归档软删除、用户新消息自动取消归档。
• 管理员回复后延迟 5 分钟的邮件通知（若用户仍未读则发送）。
• 消息去重、按时间排序、连接状态处理。

使用方式

技能按步骤提供实现指导：

1. 数据模型：创建 support_chats 和 support_messages 表，定义索引与模型关系，实现 touch_last_message、unread_for_admin?、mark_viewed_by_admin、archive、unarchive、archived? 等方法，以及消息创建后的广播与通知逻辑。
2. API 端点：用户端 GET /support_chat、PATCH /support_chat/mark_read；管理端 GET /admin/chats、GET /admin/chats/:id、POST /admin/chats/:id/archive、POST /admin/chats/:id/unarchive。
3. WebSocket 频道：ChatChannel（每个聊天）与 AdminNotificationChannel（全局管理员通知），包含订阅授权与消息广播。
4. 前端用户组件：ChatWidget 根容器、ChatButton、ChatPanel、MessageList、MessageBubble、InputArea，以及 useSupportChat 状态管理钩子。
5. 前端管理后台：聊天列表页与聊天详情页，支持标签过滤、未读指示、日期分组、归档/恢复。
6. 邮件通知：SupportReplyNotificationJob，延迟 5 分钟调度，发送前检查是否已读。
7. TypeScript 类型定义：SupportMessage、SupportChat、SupportChatListItem、AdminSupportChat、ChatChannelMessage、AdminNotificationMessage。

技能还提供关键设计决策、测试清单、常见陷阱，以及 Ruby on Rails 和 React 的框架特定代码示例。

适用场景

• 为 Web 应用添加实时客服聊天。
• 构建用户与管理员之间的实时消息系统。
• 需要应用内支持渠道的产品。
• 需要管理后台处理客服对话的场景。

限制

• 资料未提供具体的收费、价格、平台或效果信息。
• 框架特定指导仅涵盖 Ruby on Rails 与 React，其他框架暂未提供。
• 邮件通知的具体邮件服务实现暂未提供。