ai-customer-service/specs/功能清单.md

AI Customer Service 功能清单（按钮级任务版）

版本：v1.0 日期：2026-04-27 说明：每个任务 5 分钟可完成，可直接安排进任务管理

---

Phase 1：Widget 渠道 + RAG 知识库 + 基础对话

模块 1.1：网页 Widget 接入

1.1.1 Widget 嵌入

• 任务：实现 Widget 组件（HTML snippet + JS），可通过 <script> 标签嵌入任意网页
• 任务：Widget 组件渲染浮动按钮（右下角，点击展开对话窗口）
• 任务：对话窗口渲染：标题栏（"智能客服"）/ 消息区（滚动）/ 输入框（支持 Enter 发送）/ 发送按钮
• 任务：实现 Widget 最小化按钮，点击后收起为悬浮球
• 任务：实现 Widget 消息气泡：用户消息（右侧蓝色）/ 机器人消息（左侧灰色）
• 任务：机器人消息支持 Markdown 格式渲染（支持代码块、粗体、链接）
• 任务：机器人消息支持展示链接按钮（点击可跳转外部页面）

1.1.2 Webhook 对接

• 任务：实现 Widget Webhook 端点 POST /api/v1/ai-customer-service/webhook/widget
• 任务：Webhook 接收消息后，解析 session_id（从 cookie 或 localStorage 生成）、user_message、channel=widget
• 任务：Webhook 返回 HTTP 200（异步处理模式），消息处理结果通过 WebSocket 推送回 Widget
• 任务：实现 WebSocket 连接管理（Widget 端建立长连接 /ws/widget）

模块 1.2：对话引擎

1.2.1 意图识别

• 任务：实现 IntentEngine.Recognize() 接口，输入用户消息，输出意图 + 置信度
• 任务：实现意图分类列表：api_key_管理 / 模型路由配置 / 配额计费 / 错误码诊断 / 账户问题 / 转人工
• 任务：实现置信度计算，阈值：>=0.85 = 高置信 / 0.60-0.85 = 中置信 / <0.60 = 低置信
• 任务：低置信度意图自动触发转人工流程
• 任务：实现"退款/账户封禁/数据泄露"等敏感意图识别（关键词匹配 + 意图分类），命中时强制转人工

1.2.2 RAG 检索

• 任务：实现知识库向量库初始化脚本（使用 Qdrant / PGVector），接入产品文档内容
• 任务：实现 RAGEngine.Retrieve(query, top_k) 接口，输入用户问题，输出 top_k 相关知识库片段
• 任务：RAG 检索使用混合策略：sentence embedding（语义）+ keyword match（关键词兜底）
• 任务：实现检索结果重排序（使用 cross-encoder 对 top_k*2 结果重新打分，取 top_k）
• 任务：RAG 检索 P99 延迟目标 <200ms

1.2.3 回复生成

• 任务：实现 ReplyGenerator.Generate(ctx, intent, rag_results, conversation_history) 接口
• 任务：Prompt 模板：System Prompt（你是立连桥智能客服，专回答产品使用问题，只引用知识库内容）+ User Query + RAG 结果 + 对话历史
• 任务：实现回复 Markdown 渲染（飞书/企微渠道），代码示例使用语法高亮
• 任务：涉及用户个人数据查询时，在 Prompt 中注入 user_id，强制模型只返回当前用户数据
• 任务：实现回复缓存（Redis，相同意图+相同用户问题的回复缓存 5 分钟）

模块 1.3：会话管理

1.3.1 会话状态机

• 任务：实现会话状态枚举：initializing / waiting / bot_replied / waiting_human / closed
• 任务：实现会话超时逻辑：用户 30 分钟无消息 → 自动发送"还在吗？"；仍无回复 → 30 分钟后关闭会话
• 任务：实现会话关闭事件记录：用户点击"已解决"或超时关闭 → 记录 session_resolved

1.3.2 上下文管理

• 任务：实现上下文窗口：保留最近 5 轮对话（用户+机器人各 5 条）
• 任务：上下文存储在 Redis（Key = cs:session:{session_id}，TTL = 24 小时）
• 任务：实现跨会话用户识别：Widget 用户首次访问时生成 anonymous_id 存入 cookie

模块 1.4：知识库管理

1.4.1 知识库后台

• 任务：实现知识库管理页路由 /cs/dashboard/knowledge
• 任务：知识库列表每行显示：条目ID / 标题 / 分类 / 覆盖意图 / 引用次数 / 状态 / 操作
• 任务：渲染"新增条目"按钮，点击进入条目编辑器
• 任务：知识库编辑器字段：标题（必填）/ 分类（下拉：API Key/路由/配额/错误码/账户/其他）/ 正文（Markdown 富文本）/ 覆盖意图标签（多选）/ 状态（草稿/发布）
• 任务：编辑器实现 Markdown 实时预览
• 任务：条目发布后，自动触发向量库更新（异步，30 秒内生效）
• 任务：每个知识库条目支持上传附件（PDF/图片），附件存储在 OSS
• 任务：知识库列表支持按分类筛选 / 按标题搜索 / 按引用次数排序

1.4.2 知识库导入导出

• 任务：实现"批量导入"按钮，支持上传 Markdown zip 包批量导入条目
• 任务：实现"导出全部"按钮，导出为 Markdown zip 包

---

Phase 2：Telegram + Discord + 意图识别 + 转人工

模块 2.1：多渠道接入适配

2.1.1 Telegram Bot 接入

• 任务：申请 Telegram Bot（通过 @BotFather），获取 Bot Token
• 任务：实现 Telegram Webhook 端点 POST /api/v1/ai-customer-service/webhook/telegram
• 任务：Webhook 解析 Telegram Update：提取 chat.id（作为 user_id）、message.text（作为 user_message）
• 任务：实现 Telegram 回复方法：调用 Bot API sendMessage，传入 chat.id 和回复内容
• 任务：实现 Telegram 消息格式化：Markdown → Telegram MarkdownV2 格式转换
• 任务：在 Gateway 配置 Telegram Bot Webhook URL 指向本系统

2.1.2 Discord Bot 接入

• 任务：创建 Discord Application，开通 Bot 功能，获取 Bot Token
• 任务：实现 Discord Webhook 端点 POST /api/v1/ai-customer-service/webhook/discord
• 任务：Webhook 解析 Discord interaction：提取 channel_id / member.user.id / content
• 任务：实现 Discord 回复方法：调用 Discord Webhook API 或 Bot sendMessage
• 任务：Discord 支持 slash command（如 /客服问题）触发对话
• 任务：在 Gateway 配置 Discord Webhook 指向本系统

2.1.3 统一消息格式

• 任务：实现 ChannelAdapter 接口族（TelegramAdapter / DiscordAdapter / WidgetAdapter / WechatAdapter）
• 任务：每个 Adapter 将各自渠道的消息格式统一转换为 UnifiedMessage（包含：message_id / channel / open_id / user_id / content / timestamp）
• 任务：实现统一会话 ID 生成规则：{channel}:{open_id}

模块 2.2：身份核验

2.2.1 绑定用户身份识别

• 任务：实现 GET /api/v1/ai-customer-service/auth/check?channel={ch}&open_id={id} 接口，返回绑定状态
• 任务：已绑定用户：返回 {bound: true, user_id: "xxx"}
• 任务：未绑定用户：返回 {bound: false}，触发身份核验流程

2.2.2 邮箱验证码核验

• 任务：未绑定用户输入邮箱后，点击"验证"按钮，POST /api/v1/ai-customer-service/auth/verify-code/send
• 任务：后端验证邮箱是否存在（调用 supply-api 的邮箱查询接口），存在则发送 6 位数字验证码（有效期 5 分钟）
• 任务：用户输入验证码，POST /api/v1/ai-customer-service/auth/verify-code/check
• 任务：验证成功后，将 {channel, open_id, user_id} 写入 cs_user_bindings 表
• 任务：验证失败 3 次后，自动触发转人工工单（标签：identity_verification_failed）

2.2.3 API Key 前缀核验

• 任务：用户输入 API Key 前缀，POST /api/v1/ai-customer-service/auth/apikey/lookup
• 任务：后端用前缀模糊查询 supply_api_keys 表（前 8 位），返回匹配到的账户列表（隐藏中间位）
• 任务：若匹配到 1 个 → 直接绑定；若匹配到多个 → 要求补充邮箱二次确认；若 0 个 → 提示"未找到账户"
• 任务：验证过程不存储用户输入的完整 API Key，仅记录前缀用于关联

模块 2.3：转人工流程

2.3.1 触发转人工

• 任务：实现转人工触发条件检测：a）用户发送"人工客服/找人工/投诉"关键词 b）意图置信度 <0.60 c）身份核验失败 3 次 d）用户反馈"未解决"累计 3 轮
• 任务：触发转人工时，更新会话状态 = waiting_human
• 任务：触发转人工时，显示机器人消息："正在为您转接人工客服，请稍候..."

2.3.2 工单生成

• 任务：触发转人工时，自动写入 cs_tickets 表（字段：ticket_id / session_id / user_id / channel / priority / status=open / created_at / 原始问题 / 会话历史摘要）
• 任务：转人工时，若用户处于多轮对话，附加最近 5 轮对话历史到工单 conversation_history 字段
• 任务：触发转人工时，发送飞书通知到客服群（包含用户ID/渠道/问题摘要/排队位置）
• 任务：实现 GET /api/v1/ai-customer-service/tickets/queue-position?ticket_id={id}，返回当前排队人数

2.3.3 人工接管

• 任务：客服人员点击"接单"按钮，POST /api/v1/ai-customer-service/tickets/{id}/accept
• 任务：接单后，工单状态更新为 processing，locked_by = 客服ID
• 任务：机器人向用户发送："人工客服已接单，预计 {X} 分钟内回复"
• 任务：客服在工单处理页发送消息，POST /api/v1/ai-customer-service/tickets/{id}/reply，消息推送给用户

---

Phase 3：微信渠道 + 用户数据查询 + 工单后台

模块 3.1：微信接入

3.1.1 微信公众号 Webhook

• 任务：配置微信公众号服务器地址（URL + Token + EncodingAESKey）
• 任务：实现微信公众号 Webhook 验证（GET 请求，验证 Token）
• 任务：实现微信公众号消息接收 POST /api/v1/ai-customer-service/webhook/wechat
• 任务：解析微信 XML 消息格式：提取 FromUserName（作为 open_id）、MsgType、Content
• 任务：实现被动回复（用户发消息后，微信服务端在 5 秒内必须回复，否则重试）
• 任务：支持接收事件推送（用户关注/取关）

3.1.2 微信公众号客服消息

• 任务：实现模板消息发送（用于通知类消息，如工单状态变更）
• 任务：客服在后台发送的消息，通过微信公众号客服消息接口推送（调用 https://api.weixin.qq.com/cgi-bin/message/custom/send）

模块 3.2：用户数据查询（只读）

3.2.1 Token 消耗查询

• 任务：用户发送"我的 Token 消耗是多少"，识别意图为 quota_check
• 任务：后端调用 GET /api/v1/ai-customer-service/diagnostics/token-usage?user_id={uid}&date=today
• 任务：内部调用 platform-token-runtime 的只读接口获取今日 Token 消耗
• 任务：机器人回复格式："今日已消耗 {N} Tokens，剩余配额 {M} Tokens（{percent}%）"

3.2.2 错误日志诊断

• 任务：用户发送"我的请求报错了"或错误码，识别意图为 error_diagnosis
• 任务：后端调用 GET /api/v1/ai-customer-service/diagnostics/recent-errors?user_id={uid}&limit=5
• 任务：内部调用 supply-api 的只读接口获取用户最近 5 条错误日志
• 任务：机器人回复展示：请求时间 / 错误码 / 错误描述 / 建议操作

3.2.3 供应商状态查询

• 任务：用户发送"供应商X是不是挂了"，识别意图为 supplier_status_check
• 任务：后端调用 GET /api/v1/ai-customer-service/diagnostics/supplier-status?supplier={name}
• 任务：内部调用 supply-intelligence 的供应商状态 API
• 任务：机器人回复格式："供应商 {X} 当前状态：正常运行（延迟 {N}ms）/ 部分可用（{详情}）"

模块 3.3：工单后台

3.3.1 工单列表页

• 任务：实现工单列表页路由 /cs/dashboard/tickets
• 任务：工单列表顶部渲染状态 Tab：全部 / 待处理（open）/ 处理中（processing）/ 已关闭（closed）
• 任务：工单列表顶部渲染优先级 Tab：全部 / P1（红色）/ P2（橙色）/ P3（灰色）
• 任务：工单列表每行显示：工单ID / 用户ID / 渠道图标 / 问题摘要 / 优先级 / 状态 / 等待时长 / 客服 / 创建时间
• 任务：工单行按优先级（P1>P2>P3）和等待时长升序排列
• 任务：工单行渲染"接单"按钮（仅 open 状态且未锁定的工单可见）
• 任务：工单行渲染"查看"按钮，点击进入工单详情页

3.3.2 工单详情页

• 任务：工单详情页路由 /cs/dashboard/tickets/{ticket_id}
• 任务：详情页左侧渲染会话历史时间线（用户消息+机器人回复+系统消息）
• 任务：详情页右侧渲染工单信息面板：用户ID / 渠道 / 优先级 / 状态 / 等待时长 / 关联会话数
• 任务：详情页底部渲染回复输入框（支持 Markdown + 附件上传）+ "发送"按钮
• 任务：发送回复后，通过对应渠道推送给用户
• 任务：详情页渲染"关闭工单"按钮（仅 processing 状态），点击后确认，确认后状态 = closed
• 任务：详情页渲染"转交"按钮（选择其他客服接手）

3.3.3 统计分析

• 任务：实现统计页路由 /cs/dashboard/stats
• 任务：统计页渲染转人工原因分布饼图（Top 10）
• 任务：统计页渲染每日会话量柱状图（近 30 天）
• 任务：统计页渲染自助解决率趋势折线图（近 30 天）
• 任务：统计页渲染平均首次响应时长趋势（近 30 天）
• 任务：统计页渲染知识库未命中率趋势（近 30 天）

模块 3.4：模型 Failover

3.4.1 多模型配置

• 任务：实现模型配置页路由 /cs/dashboard/settings/models
• 任务：模型列表每行显示：模型名称 / 类型（主/备） / 供应商 / 状态（启用/禁用） / 操作
• 任务：渲染"添加备选模型"按钮，点击后弹出配置表单（模型名称 / API Endpoint / API Key / 优先级）
• 任务：模型配置支持拖拽排序（设置优先级顺序）

3.4.2 Failover 执行

• 任务：主模型 API 调用超时（5 秒内无响应）→ 自动切换到优先级最高的可用备模型
• 任务：主模型 API 返回 5xx → 自动切换到备模型，记录 failover 事件
• 任务：备模型也失败时（双故障）→ 返回兜底静态回复 + 生成工单
• 任务：Failover 事件写入 cs_model_failover_events 表（字段：session_id / from_model / to_model / reason / occurred_at）

3.4.3 兜底回复

• 任务：预配置兜底回复模板（静态文本，不依赖大模型）
• 任务：双故障时返回兜底回复："抱歉，当前客服系统繁忙，请稍后再试，或联系 support@example.com"
• 任务：双故障时，飞书通知技术负责人（P1 告警）

---

全局模块

模块 G1：权限与认证

• 任务：实现 JWT 认证中间件（与立连桥统一认证打通）
• 任务：实现客服角色：客服（处理工单）/ 运营（知识库+统计）/ 管理员（全部）
• 任务：权限不足返回 HTTP 403，错误码 CS_AUTH_1001

模块 G2：健康检查

• 任务：实现 GET /actuator/health / /actuator/health/live / /actuator/health/ready
• 任务：Readiness probe 检查：PostgreSQL 连接 + Redis 连接 + Qdrant 连接

Module G3: OpenAPI

• 任务：实现 Swagger UI 路由 /docs
• 任务：实现 OpenAPI 3.0 spec 端点 /openapi.json

模块 G4：Webhook 安全

• 任务：实现 Telegram Webhook Secret Token 校验（X-Telegram-Bot-Api-Secret-Token）
• 任务：实现 Discord Request Signature 校验（X-Signature-Ed25519）
• 任务：实现微信消息体签名校验（msg_signature）
• 任务：校验失败返回 HTTP 403

---

技术基础设施

T1：项目骨架

• 任务：初始化 Go module github.com/lijiaoliao/ai-customer-service
• 任务：创建 cmd/ai-customer-service/main.go，支持 api 和 worker 两种运行模式
• 任务：创建 internal/ 目录结构（domain/service/handler/infrastructure/repository）
• 任务：配置 Viper 读取 config.yaml
• 任务：配置 log/slog 结构化日志
• 任务：创建 PostgreSQL schema migration，表前缀 cs_
• 任务：配置 Redis 连接池
• 任务：配置 Dockerfile 和 docker-compose.yml

T2：单元测试

• 任务：为 domain 层函数编写单元测试，覆盖率 >= 70%
• 任务：为 service 层函数编写单元测试，覆盖率 >= 80%
• 任务：配置 GitHub Actions CI

T3：IntegrationPlugin 接口

• 任务：实现 IntegrationPlugin 接口
• 任务：实现插件模式下各渠道的开关配置
• 任务：实现 Webhook 路径前缀可配置（默认 /api/v1/ai-customer-service/）

---

任务估算汇总

Phase	模块	任务数	估计工时
Phase 1	1.1 Widget + 1.2 对话引擎 + 1.3 会话 + 1.4 知识库	38	5 人天
Phase 2	2.1 TG/Discord + 2.2 身份核验 + 2.3 转人工	30	4 人天
Phase 3	3.1 微信 + 3.2 数据查询 + 3.3 工单后台 + 3.4 Failover	38	5 人天
全局	G1 权限 + G2 健康 + G3 文档 + G4 Webhook安全	14	1.5 人天
技术基础设施	T1 骨架 + T2 测试 + T3 插件	12	1.5 人天
合计		132	~17 人天