fix: P0-1 RateLimiter并发写安全 + P0-2工单操作错误码区分 + P1 rows.Close修复

P0-1 (limits.go): Allow()方法改为全程使用写锁保护counters map读写，避免RLock写入时的data race P0-2 (ticket_workflow.go+ticket_handler.go): Assign/Resolve/Close操作先查询ticket存在性和状态，返回明确的CS_TICKET_4001/CS_TKT_4002/CS_TICKET_4092/CS_TICKET_4093错误码，handler根据错误前缀路由HTTP状态码 P1-1 (ticket_store.go): 移除GetStats中3处手动rows.Close()，只保留defer Close()
2026-05-01 20:56:25 +08:00
parent bd2d848009
commit cf46b27610
103 changed files with 16428 additions and 0 deletions
--- a/prd/PRD.md
+++ b/prd/PRD.md
@@ -0,0 +1,431 @@
+# 立交桥智能客服系统 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] 没有使用"优化、支持、友好、尽量、快速"等模糊词替代明确要求（全文档使用具体数值、明确状态、限定条件）
+
+---