ai-customer-service/prd/PRD.md

# 立交桥智能客服系统 PRD

## 1. 概述

### 一句话价值
在立交桥多平台Gateway（Telegram、Discord、微信等）上构建一套可自动解决用户初始化与使用过程问题的智能客服系统，将人工客服介入率降低 60% 以上。

### 用户问题
- 终端用户在初始化API Key、配置模型路由、排查配额/计费异常时，缺乏 7×24 自助诊断能力，导致问题滞留或流失。
- 内部运营/客服人员面对重复性咨询（占总量 70%+）无法释放精力处理复杂客诉与舆情。

### 业务意义
- 降低单用户服务成本（Cost Per Ticket）。
- 缩短首次响应时间与问题解决时间（MTTR）。
- 通过客服交互数据反哺产品文档缺失点与系统易用性缺陷。

---

## 2. 目标

### 业务目标
| 目标 | 基准值 | 目标值 | 观测周期 |
|---|---|---|---|
| 人工客服介入率 | 100% | ≤ 40% | 上线后 30 天 |
| 首次响应时间 | 人工排班时段内 | ≤ 10 秒（任意时段） | 上线后 30 天 |
| 常见问题一次解决率 | 0 | ≥ 75% | 上线后 30 天 |
| 用户满意度（CSAT） | 无 | ≥ 4.0 / 5.0 | 上线后 30 天 |

### 用户目标
- 终端用户：在任意渠道发起咨询后，10 秒内获得有效反馈；复杂问题可在 24 小时内得到明确处理结论。
- 内部运营/客服人员：每日重复性问题处理量减少 60%，工单系统仅接收需人工判断或敏感操作的请求。

### 成功定义
上线 30 天后，同时满足：
1. 人工客服介入率 ≤ 40%。
2. 常见问题一次解决率 ≥ 75%。
3. 系统可用性 ≥ 99.5%（基于健康检查与告警数据）。
4. 未发生因客服系统导致的数据泄露或权限越界事件（安全审计通过）。

---

## 3. 范围

### In Scope
1. **多渠道接入层**：通过立交桥现有 `gateway/` 接入 Telegram Bot、Discord Bot、微信公众号/小程序客服消息、网页嵌入式 Widget（至少覆盖这 4 个渠道）。
2. **对话引擎**：基于大模型的意图识别、上下文多轮对话、知识库检索增强生成（RAG）、工单自动生成。
3. **知识库管理**：立交桥产品文档（初始化、API Key 管理、模型路由、配额/计费、错误码释义）的结构化索引与更新机制。
4. **诊断能力**：对接 `platform-token-runtime/` 与 `supply-api/` 的只读查询接口，实现用户身份核验、配额查询、Token 消耗追溯、最近 5 条错误日志检索。
5. **转人工机制**：当置信度低于阈值、用户明确要求人工、或问题涉及账户封禁/退款/安全审计时，自动创建工单并通知人工客服队列。
6. **运营后台**：内部运营/客服人员使用的工单看板、会话历史查询、知识库条目增删改查、转人工原因统计。
7. **埋点与监控**：全链路日志、对话转化率、转人工原因分布、响应延迟 P99、错误率。

### Out of Scope
1. **电话/语音客服**：本期仅覆盖文本渠道，不接入语音呼叫中心。
2. **主动外呼/营销推送**：客服系统仅响应用户主动发起的咨询，不包含主动触达或营销场景。
3. **多语言支持**：本期优先中文，英文作为 P1 后续迭代，其他语言明确不在本期。
4. **实时视频/屏幕共享**：诊断过程不提供远程桌面或屏幕共享能力。
5. **直接修改用户数据**：客服系统仅拥有只读查询权限，任何写操作（如重置密码、修改配额）必须通过工单由人工授权后由独立管理后台执行。
6. **模型训练/微调基础设施**：不自建模型训练流水线，使用现有大模型 API（如 GPT-4o / Claude / 国内等效模型）通过 Prompt 工程与 RAG 满足需求。

### 假设与依赖
- 假设立交桥 `gateway/` 的 Telegram / Discord / 微信接口已具备 Webhook 接收与消息推送能力，客服系统以独立服务形式接入，不改造 gateway 核心路由逻辑。
- 假设 `platform-token-runtime/` 与 `supply-api/` 能提供稳定的只读查询 API（用户身份、配额、Token 消耗、近期错误日志），并具备速率限制与鉴权契约。
- 依赖大模型 API 供应商的可用性与 SLA（需配置多供应商 failover）。
- 依赖现有用户体系（OAuth / API Key）可用于客服渠道的身份关联。

---

## 4. 用户场景

### 4.1 主流程：用户自助解决常见问题

```
1. 用户通过 Telegram / Discord / 微信 / 网页 Widget 发起文本咨询。
2. Gateway 将消息路由至智能客服系统。
3. 系统执行身份关联：
   a. 若渠道已绑定立交桥账户，提取 user_id。
   b. 若未绑定，请求用户提供注册邮箱或 API Key 前缀进行一次性核验（不存储完整 API Key）。
4. 系统进行意图识别与知识库检索（RAG）。
5. 若意图命中已知问题且置信度 ≥ 0.85：
   a. 返回结构化答案（含操作步骤、文档链接、代码示例）。
   b. 若答案涉及用户个人数据（如配额），调用 supply-api / runtime 只读接口查询后嵌入回复。
6. 用户确认问题是否解决：
   a. 用户反馈“已解决” → 会话关闭，记录解决标记。
   b. 用户反馈“未解决”或继续追问 → 进入多轮对话，最多 3 轮；仍无法解决则触发转人工。
```

### 4.2 异常流程：身份核验失败

```
1. 用户提供邮箱或 API Key 前缀无法匹配系统记录。
2. 系统回复：“未找到关联账户，请核对注册邮箱或联系人工客服处理账户问题。”
3. 同一会话中身份核验失败累计 3 次 → 自动触发转人工工单，并标记“身份核验失败”。
4. 系统不记录错误的 API Key 或密码，仅记录失败次数与事件类型。
```

### 4.3 异常流程：大模型 API 故障或超时

```
1. 系统在 5 秒内未收到大模型 API 响应。
2. 触发 failover：按优先级切换至备用模型供应商（配置至少 2 家）。
3. 若 failover 后 5 秒内仍无响应：
   a. 返回兜底回复：“当前咨询量较大，请稍等或提交工单由人工处理。”
   b. 自动生成工单，并附带用户原始问题与会话上下文。
   c. 记录故障事件至监控告警系统。
```

### 4.4 边缘流程：用户明确要求人工

```
1. 用户发送包含“人工客服”、“找人工”、“投诉”等明确关键词的消息。
2. 系统绕过自动回复逻辑，立即确认：“正在为您转接人工客服，预计排队时间 X 分钟。”
3. 生成工单并推送到客服队列；若队列空闲，立即分配；若排队超过 15 分钟，向用户发送排队进度通知。
```

### 4.5 边缘流程：涉及敏感操作（退款、封禁、安全审计）

```
1. 意图识别命中“退款申请”、“账户被封禁”、“怀疑数据泄露”等敏感意图。
2. 系统自动回复：“该问题需要人工核实，已为您创建优先工单，客服将在 24 小时内通过邮件/站内信回复。”
3. 工单标记为高优先级（P1），并触发内部通知（企业微信/钉钉/Slack）。
4. 客服系统本身不执行任何账户状态变更或资金操作。
```

### 4.6 用户故事

| 编号 | 角色 | 需求 | 价值 |
|---|---|---|---|
| US-01 | 终端用户 | 我希望在 Telegram 上询问 "如何生成 API Key" 后，10 秒内获得带截图指引的回复 | 减少查阅文档的时间 |
| US-02 | 终端用户 | 我希望询问 "我的配额用完了吗" 时，客服能直接查询并告知剩余额度 | 避免登录后台的繁琐步骤 |
| US-03 | 终端用户 | 我希望在问题未解决时，一键转人工并保留对话上下文 | 避免重复描述问题 |
| US-04 | 内部运营人员 | 我希望在后台看到每日转人工的原因分布 Top 10 | 识别知识库盲区并补充 |
| US-05 | 内部客服人员 | 我希望接手工单时，能看到用户与机器人的完整对话历史 | 快速定位问题，减少反复询问 |
| US-06 | 内部客服人员 | 我希望对机器人给出的错误答案进行标记并一键修正知识库 | 持续提升自助解决率 |

---

## 5. 验收标准（AC）

每条 AC 使用 Given-When-Then 格式，可直接转化为测试用例。

### AC-01：多渠道消息接入
- **Given** 立交桥 Gateway 的 Telegram / Discord / 微信 / 网页 Widget 已配置 Webhook 指向客服系统
- **When** 用户通过任一渠道发送文本消息 "如何创建 API Key"
- **Then** 客服系统在 3 秒内收到该消息，并返回 HTTP 200 确认接收
- **And** 系统记录消息来源渠道标识与用户 open_id

### AC-02：意图识别与知识库回复
- **Given** 用户已绑定立交桥账户
- **When** 用户发送 "我想把 GPT-4 路由到供应商 A，供应商 B 做兜底"
- **Then** 系统在 5 秒内识别意图为 "模型路由配置"
- **And** 返回的回复中包含：配置路径、关键参数名、至少 1 个代码/配置示例
- **And** 回复内容的置信度评分 ≥ 0.85

### AC-03：用户数据只读查询
- **Given** 用户已绑定账户 user_id = U123
- **When** 用户发送 "我今天的 Token 消耗是多少"
- **Then** 系统在 3 秒内调用 `platform-token-runtime/` 或 `supply-api/` 的只读接口
- **And** 返回精确数值（如 "今日已消耗 12,345 Tokens，剩余配额 487,655 Tokens"）
- **And** 不暴露其他用户的 Token 消耗数据

### AC-04：多轮对话与上下文保持
- **Given** 用户在会话中先问 "怎么设置 API Key"
- **And** 系统在 T0 时刻回复了设置步骤
- **When** 用户在 T0+30 秒内追问 "那个 Key 的有效期是多久"
- **Then** 系统正确关联上下文，理解 "那个 Key" 指代上文提到的 API Key
- **And** 返回 API Key 有效期策略的准确说明
- **And** 上下文窗口保留最近 5 轮对话（用户+机器人各 5 条）

### AC-05：身份核验（未绑定用户）
- **Given** 用户通过网页 Widget 发起会话且未绑定立交桥账户
- **When** 用户输入注册邮箱 "user@example.com"
- **Then** 系统在 2 秒内验证邮箱存在且发送一次性验证码
- **And** 用户输入正确验证码后，会话关联至该账户
- **And** 用户输入错误验证码累计 3 次后，该会话被锁定并自动生成转人工工单

### AC-06：大模型故障 Failover
- **Given** 主模型供应商 API 被配置为返回 500 错误或超时（模拟故障）
- **When** 用户发送任意咨询消息
- **Then** 系统在 5 秒内检测到主模型失败
- **And** 自动切换至备用模型供应商
- **And** 用户收到的最终回复内容语义完整，不含内部错误堆栈

### AC-07：兜底回复与工单生成
- **Given** 主模型与备用模型均不可用（模拟双故障）
- **When** 用户发送 "我的账户被封了怎么办"
- **Then** 系统在 10 秒内返回兜底回复文本（内容预配置）
- **And** 自动生成工单，工单字段包含：用户 ID、渠道、原始问题、时间戳、会话 ID
- **And** 内部通知渠道收到告警消息

### AC-08：明确转人工
- **Given** 用户处于自动回复会话中
- **When** 用户发送 "我要找人工客服"
- **Then** 系统在 2 秒内停止自动回复逻辑
- **And** 返回排队提示，包含当前排队人数（若大于 0）
- **And** 生成工单并推送至客服队列
- **And** 用户对话历史完整附加至工单

### AC-09：敏感意图自动转人工
- **Given** 用户已绑定账户
- **When** 用户发送 "我要申请退款" 或 "我的数据可能被泄露了"
- **Then** 系统在 3 秒内识别意图为 "退款" 或 "安全投诉"
- **And** 不返回任何自助操作指引
- **And** 立即生成 P1 优先级工单
- **And** 内部通知渠道收到高优先级告警

### AC-10：工单后台分配与处理
- **Given** 内部客服人员登录运营后台
- **When** 打开工单看板
- **Then** 页面加载时间 ≤ 2 秒
- **And** 未处理工单按优先级（P1 > P2 > P3）与时间升序排列
- **And** 客服人员点击 "接收" 后，工单状态在 1 秒内变更为 "处理中" 并锁定为该客服

### AC-11：知识库条目管理
- **Given** 运营人员在后台新增知识库条目，标题为 "如何重置 API Key"，内容为 Markdown 格式
- **When** 点击 "发布"
- **Then** 条目在 30 秒内进入生效状态
- **And** 用户随后询问 "怎么重置 API Key" 时，回复内容引用该条目
- **And** 后台记录该条目的被引用次数

### AC-12：对话埋点与监控
- **Given** 系统已上线运行
- **When** 任意用户完成一次会话（关闭或转人工）
- **Then** 系统在 5 秒内上报事件至监控平台，包含：会话 ID、渠道、是否解决、转人工原因（若有）、响应延迟 P99 采样值
- **And** Grafana 大盘在 1 分钟内刷新并展示该数据点

### AC-13：权限边界
- **Given** 攻击者尝试通过客服系统调用非只读接口（如修改配额、删除用户）
- **When** 该请求到达客服系统
- **Then** 系统在 100ms 内拒绝该请求
- **And** 返回 HTTP 403
- **And** 记录安全审计日志，包含请求来源 IP、时间、目标接口

---

## 6. 边缘情况与失败路径

| 编号 | 场景 | 预期行为 | 监控/告警 |
|---|---|---|---|
| EC-01 | 用户发送超长消息（> 2000 字） | 截断至 2000 字后处理，并在回复中提示 "消息较长，已处理前 2000 字，如需补充请分段发送" | 记录截断事件，不告警 |
| EC-02 | 用户在 1 秒内连续发送 10 条消息 | 启用频率限制：合并为 1 条上下文，回复后解锁；若 1 分钟内触发 3 次频率限制，临时静默 60 秒并提示 | 触发风控埋点，达到阈值时告警 |
| EC-03 | 知识库检索无结果且意图置信度 < 0.60 | 直接触发转人工，回复 "该问题暂未收录，已为您转接人工客服" | 记录 "知识库未命中" 事件，每日汇总 |
| EC-04 | 用户提供的 API Key 前缀匹配到多个账户 | 请求补充注册邮箱进行二次核验；若仍无法唯一确定，转人工 | 记录模糊匹配事件 |
| EC-05 | supply-api / runtime 查询超时（> 3 秒） | 回复中省略个人数据部分，仅提供通用说明，并提示 "账户数据查询暂时不可用，请稍后重试或联系人工" | 触发依赖服务超时告警 |
| EC-06 | 同一用户在多渠道同时发起会话 | 各渠道会话独立处理，不强制合并；若用户身份已绑定，客服后台可查看该用户全渠道最近 5 条会话摘要 | 记录多渠道并发事件 |
| EC-07 | 用户发送非文本内容（图片、文件、语音） | 回复 "暂不支持该类型消息，请用文字描述您的问题"；图片若包含二维码或敏感信息，不解析、不存储 | 记录消息类型分布 |
| EC-08 | 系统维护窗口期（计划内停机） | 提前 24 小时在 Gateway 层配置维护公告，用户消息收到固定回复 "客服系统维护中，预计 X 点恢复，紧急问题请发邮件至 support@example.com"；不生成工单积压 | 维护期间关闭自动工单生成，维护结束后恢复 |
| EC-09 | 客服队列满员（> 20 个未处理 P1/P2 工单） | 新工单仍生成，但向用户提示 "当前人工客服繁忙，预计等待时间超过 30 分钟，建议您先查看帮助文档 [链接]"；触发运营 Slack 告警 | 队列深度超过阈值触发 P1 告警 |
| EC-10 | 数据库连接池耗尽 | 新会话进入降级模式：仅返回静态 FAQ 链接，不执行查询、不生成工单；健康检查返回非 200，触发容器重启或扩容 | 触发 P0 告警 |

---

## 7. 上线与运营准备

### 7.1 发布策略
- **Phase 1（灰度）**：仅对网页 Widget 渠道开放，覆盖 10% 流量，持续 3 天。观察 MTTR、转人工率、模型幻觉率。
- **Phase 2（扩展）**：开放 Telegram 与 Discord 渠道，覆盖 50% 流量，持续 5 天。
- **Phase 3（全量）**：开放微信渠道，100% 流量。保留 1 周内一键关闭各渠道客服系统路由的 Gateway 配置开关。

### 7.2 灰度/回滚
- **Gateway 层回滚**：每个渠道的 Webhook 路由配置独立，可在 1 分钟内将某渠道消息路由回原有处理逻辑（或静默丢弃后引导至邮件）。
- **模型层回滚**：模型供应商配置存储于配置中心，可在 30 秒内切换主备模型或关闭大模型调用（进入静态回复模式）。
- **数据库回滚**：知识库与工单数据使用独立 schema，不影响立交桥核心用户/配额数据；发布前执行 schema 备份。

### 7.3 埋点/监控/FAQ
- **埋点事件清单**：
  - `cs_session_start`：会话开始（含渠道、用户标识）
  - `cs_bot_reply`：机器人回复（含延迟、模型供应商、置信度）
  - `cs_handoff`：转人工（含原因分类：用户要求、置信度低、敏感意图、身份失败、模型故障）
  - `cs_ticket_created`：工单创建（含优先级、渠道）
  - `cs_ticket_resolved`：工单关闭（含处理时长、解决方式）
  - `cs_kb_miss`：知识库未命中
  - `cs_user_satisfied` / `cs_user_dissatisfied`：用户显式反馈
- **监控大盘（Grafana）**：
  - QPS、P50/P95/P99 响应延迟
  - 各渠道会话量分布
  - 转人工原因饼图（Top 10）
  - 模型供应商可用性与 failover 次数
  - 工单队列深度与处理时效
- **告警规则**：
  - P0：系统健康检查失败 > 1 分钟；数据库连接池耗尽；安全审计拦截事件 > 0
  - P1：模型双供应商故障 > 30 秒；工单队列深度 > 20；API 查询超时率 > 10%
  - P2：单渠道消息丢失率 > 1%；知识库未命中率 > 30%
- **FAQ 预填充**：上线前知识库必须覆盖以下 20 个高频问题的准确答案（抽样验收通过后方可上线）：
  1. 如何注册与登录
  2. 如何生成与管理 API Key
  3. API Key 有效期与轮换策略
  4. 如何配置模型路由（供应商优先级与兜底）
  5. 支持的模型列表与版本差异
  6. 配额（Quota）的分配与消耗逻辑
  7. 如何查询实时 Token 消耗与余额
  8. 计费模式（按 Token / 按调用 / 包月）说明
  9. 常见错误码（401/403/429/500/503）排查步骤
  10. 请求超时或响应缓慢的诊断方法
  11. 如何查看请求日志与审计记录
  12. 账户被封禁的可能原因与申诉路径
  13. 子账户/团队成员的权限管理
  14. Webhook 配置与接收消息验证
  15. 速率限制（Rate Limit）规则与提升方式
  16. 如何导出账单与发票申请
  17. 供应商侧模型下线或变更的应对
  18. 数据隐私与留存政策
  19. 退款政策与申请流程
  20. 如何联系人工客服（含工作时间说明）

---

## 8. 商业化与价值闭环

### 收益路径
1. **成本降低**：将单 ticket 人工成本从当前 100% 人工处理降至 ≤ 40% 人工处理，释放客服人力投入高价值客诉与运营活动。
2. **留存提升**：7×24 自助服务减少用户因等待回复而放弃使用的场景，提升次日/周留存率。
3. **产品改进**：通过转人工原因分布与知识库未命中数据，定向补充产品文档、优化错误提示、改进 onboarding 流程，减少未来咨询量。
4. **可定价增值服务**：未来可将 "专属客服通道"、"1 对 1 技术支持" 作为企业版或高阶套餐的增值服务。

### 北极星指标
- **自助问题解决率** = （机器人会话且用户标记已解决数） / （机器人总会话数 - 明确转人工会话数）
- 目标：上线 30 天后 ≥ 75%

### 失败判定线
满足以下任一条件即判定本期交付失败，需启动复盘与止损：
1. 上线 14 天后，人工介入率仍 > 70%（说明自动回复未产生实质替代效果）。
2. 上线 7 天内，发生 ≥ 2 起用户数据泄露或权限越界事件。
3. 上线 30 天后，用户满意度 CSAT < 3.0 / 5.0。
4. 系统可用性在任意 7 天滑动窗口内 < 99%。

### 止损条件
- **立即下线**：发现客服系统接口可被未授权访问并读取其他用户数据；或模型回复中系统性地泄露内部系统架构、密钥信息。
- **停止扩量**：Phase 1/2 中单日转人工率 > 90%，或模型幻觉率（事实性错误被客服标记）> 20%。
- **技术债熔断**：若开发过程中发现需改造 `gateway/` 核心鉴权/路由逻辑才能接入，则退回评估，改为独立邮件/工单形式交付，不强行耦合。

---

## 9. 依赖与风险

### 依赖项
| 依赖 | 提供方 | 状态要求 | 风险等级 |
|---|---|---|---|
| Gateway Webhook 接入能力 | `gateway/` 团队 | 已具备 Telegram/Discord/微信消息接收与回复接口 | 中 |
| 用户身份与配额只读 API | `platform-token-runtime/` / `supply-api/` | 提供带鉴权的只读查询接口，延迟 < 500ms，可用性 ≥ 99.9% | 高 |
| 大模型 API 供应商（已接入运营商中选择） | 外部（至少 2 家，从已接入的主流运营商中选择） | 确认 SLA、TPM 限额，签署数据保密协议，支持 Failover | 高 |
| 向量数据库 / 检索引擎 | 内部选型（如 Milvus / Qdrant / PGVector） | 支持中文语义检索，延迟 < 200ms | 中 |
| 客服工单数据库 | 本项目新设 | Schema 定稿、迁移脚本可回滚 | 低 |

### 风险清单
| 风险 | 影响 | 概率 | 缓解措施 |
|---|---|---|---|
| 大模型幻觉导致错误指导用户配置，引发业务损失 | 高 | 中 | 1. 限制回答范围至知识库内容；2. 涉及操作步骤必须附带官方文档链接；3. 运营每日抽检 5% 对话；4. 高风险意图（计费、安全）强制转人工 |
| 用户通过 Prompt Injection 诱导客服系统泄露敏感数据 | 高 | 中 | 1. 系统 Prompt 中明确禁止回复非当前用户数据；2. 所有数据查询强制携带 user_id 校验；3. 安全审计日志全量记录；4. 定期红队测试 |
| 模型供应商 API 涨价或停服 | 中 | 低 | 1. 至少签约 2 家供应商并具备 30 分钟内切换能力；2. 核心兜底回复不依赖大模型（静态模板）；3. 评估开源本地模型作为极端降级方案 |
| 接入 Gateway 改造成本超出预期 | 中 | 中 | 1. Phase 1 先验证网页 Widget 独立接入；2. 明确客服系统不改造 Gateway 核心路由，仅增加旁路 Webhook |
| 知识库维护跟不上产品迭代速度 | 中 | 高 | 1. 产品文档变更时同步更新知识库为发布 checklist 项；2. 每周生成知识库未命中报告，驱动文档补充；3. 预留半日/周的运营人力 |

---

## 10. 技术栈与集成约束

### 统一技术栈
本项目必须与立交桥主项目保持一致：
- **语言**: Go 1.22+
- **HTTP框架**: 标准库 `net/http` + 自定义中间件（禁止引入 Gin/Echo 等第三方框架，保持与 gateway/ 和 supply-api/ 的一致性）
- **数据库**: PostgreSQL 15+ ，驱动 `jackc/pgx/v5`
- **缓存**: Redis，客户端 `redis/go-redis/v9`
- **配置**: YAML + Viper，环境变量覆盖敏感字段
- **日志/审计**: 结构化日志，审计事件模型与 supply-api/ 一致
- **错误码**: `{SOURCE}_{CATEGORY}_{CODE}` 格式，例如 `CS_SES_4001`
- **健康检查**: `/actuator/health` 、 `/actuator/health/live` 、 `/actuator/health/ready`
- **测试**: Go testing + testify，覆盖率门槛 domain ≥ 70%、service/handler ≥ 80%

### 独立运行与集成运行
本系统必须同时支持两种运行模式：

| 模式 | 特征 | 部署方式 | 适用场景 |
|------|------|---------|---------|
| **独立运行** | 自有 `cmd/ai-customer-service/main.go`，独立数据库 schema，独立 docker-compose | `docker-compose up` 或单独容器 | 外部用户只需要客服能力，不想接入立交桥全套 |
| **集成运行** | 作为 Go module 被 `gateway/` 引入，共享数据库连接池和配置，通过内部接口注册 | 编译时作为子模块编译，运行时挂载到 gateway 主进程 | 立交桥用户希望获得一体化客服能力 |

**集成约束**:
- 独立运行时，系统必须提供完整的 HTTP API 、Webhook 接入和运营后台。
- 集成运行时，系统必须提供 `IntegrationPlugin` 接口，允许主程序通过配置开关启用/禁用各模块。
- 数据库 schema 必须使用独立的 `cs_` 前缀，避免与主项目表名冲突。
- 配置文件必须支持分离加载：独立运行时读取自己的 `config.yaml`，集成运行时合并到主项目配置。

### NewAPI / Sub2API 适配支持
本系统的核心能力必须能够对接 NewAPI 和 Sub2API 系统：
- **Webhook 接入**: 提供标准化的 Webhook 接口，NewAPI/Sub2API 可配置将用户消息转发至本系统。
- **工单推送**: 提供标准化工单接口，NewAPI/Sub2API 可定期获取待处理工单状态。
- **知识库共享**: 提供知识库查询接口，NewAPI/Sub2API 可消费此数据补充自己的帮助文档。
- **独立部署时**: 通过配置文件指定 NewAPI/Sub2API 的 Webhook 地址和鉴权信息，本系统通过适配层（Adapter）与之交互。
- **集成部署时**: 若立交桥 gateway/ 已接入 NewAPI/Sub2API，本系统通过 gateway/ 的内部路由接口接入客服能力。

### 对外接口契约
- 必须提供 OpenAPI 3.0 接口文档，确保 NewAPI/Sub2API 开发者可以独立接入。
- 接口路径前缀默认为 `/api/v1/customer-service/`，集成运行时可通过配置改为 `/internal/customer-service/` 。

---

## 11. 阶段门控结论

### 当前状态：需补充信息后方可进入 TechLead

### 待澄清项（阻塞性）
1. ~~**Gateway Webhook 契约确认**：`gateway/` 团队需书面确认 Telegram / Discord / 微信消息的 Webhook 格式、鉴权方式、回复接口的速率限制，以及是否允许客服系统以独立服务形式接入而不改造核心路由。~~ ✅ **已确认：允许独立服务旁路接入。**
2. **只读 API 契约确认**：`platform-token-runtime/` 与 `supply-api/` 团队需提供可对外暴露的只读接口清单（用户身份核验、配额查询、Token 消耗、近期错误日志），包括接口路径、请求/响应 Schema、鉴权方式、QPS 限制。
3. **数据合规与隐私评估**：需法务/安全团队确认客服系统存储用户对话记录、查询用户 Token 消耗的合规性要求（尤其是涉及跨境渠道如 Telegram / Discord 时）。
4. **大模型供应商选型**：需明确已接入的主流模型运营商（如 OpenAI / Anthropic / 阿里云 / 火山引擎 / 百度等），主备配置从已接入运营商中选择至少 2 家，并确认各运营商的 SLA、TPM 限额和数据保密协议签署状态。

### 非阻塞性建议
- 建议在 TechLead 阶段前完成向量数据库选型（Milvus vs Qdrant vs PGVector）的 POC，验证中文语义检索延迟 < 200ms。
- 建议提前准备 20 条高频问题的标准答案与文档链接，作为知识库种子数据。

### 门控决策记录
- 若上述 4 项阻塞性待澄清项在 5 个工作日内全部确认，则门控结论更新为 **可进入 TechLead**。
- 若任一项无法确认（如 Gateway 不允许独立旁路接入、只读 API 无法提供、合规评估不通过），则门控结论维持 **退回重新定义**，并调整方案为独立邮件/工单系统，不与 Gateway 实时渠道耦合。
- **技术栈与集成约束已明确**：统一 Go 标准库、独立/集成双模式、NewAPI/Sub2API 适配层已纳入范围。

---

## 自检清单

- [x] 已明确真实目标（降低人工介入率、提升自助解决率），不是只复述功能
- [x] 已写清 In Scope / Out of Scope
- [x] 每个 AC 都可被 QA 或测试用例直接验证（Given-When-Then 格式，含具体数值阈值）
- [x] 已覆盖异常流（身份失败、模型故障）、边缘流（超长消息、频率限制、多渠并发）与失败路径（双模型故障、数据库耗尽）
- [x] 已补齐上线、运营、监控、回滚要求（Phase 灰度、Gateway/模型/数据库三层回滚、埋点清单、告警分级）
- [x] 已定义商业化/价值闭环（成本降低、留存提升、产品改进、未来增值服务）
- [x] 已定义成功指标（自助解决率 ≥ 75%、人工介入率 ≤ 40%）与失败判定线（14 天介入率 > 70%、数据泄露 ≥ 2 起、CSAT < 3.0、可用性 < 99%）
- [x] 已明确当前是否可进入 TechLead 阶段（需补充 4 项阻塞性信息后进入）
- [x] 没有使用"优化、支持、友好、尽量、快速"等模糊词替代明确要求（全文档使用具体数值、明确状态、限定条件）

---