浅念
219 lines
12 KiB
Markdown
219 lines
12 KiB
Markdown
# HESUPIPE 建材 AI 客服 — 设计文档
|
||
|
||
- 日期：2026-09-29
|
||
- 状态：已与需求方逐节确认
|
||
- 参考项目：`D:\refactor\ai-kefu`（Hesu Auto 汽车出口 AI 客服，同集团姊妹业务）
|
||
- 本项目目录：`D:\refactor\ai-kefu-jc`
|
||
|
||
## 1. 背景与目标
|
||
|
||
集团汽车业务（hesucar.com）已有一个成熟的 AI 客服系统（FastAPI + SQLite + 智谱 GLM），
|
||
实现"AI 需求了解 + 留资获客 + 邮件/CRM 推送"闭环。现要为管道建材业务
|
||
（HESUPIPE，hesupipe.com，河南和硕集团）复制一套**功能相同**的 AI 客服。
|
||
|
||
**核心需求**：
|
||
- AI 客服嵌入 hesupipe.com 外贸站，服务全球 B2B 管道采购买家
|
||
- AI 只做"需求了解 + 留资"：价格/交期/MOQ 等实质问题一律转客户经理（不明确回答）
|
||
- 线索通过邮件 + UniService CRM 推送交给人工
|
||
- 管理后台查看会话/画像/意向/推送日志
|
||
|
||
**非目标（v1 明确不做）**：
|
||
- RAG/向量知识库（参考项目已论证否决，静态事实卡防编造）
|
||
- 人工坐席实时接管对话
|
||
- 前端界面 i18n / 阿语 RTL 适配（记 v2）
|
||
|
||
## 2. 方案选型
|
||
|
||
**方案 A（已选定）：完整拷贝 + 建材化定制** —— 复制参考项目全部架构与测试，
|
||
按清单定制 ~15% 行业相关内容。
|
||
|
||
已否决：方案 B（从零搭建，工作量翻倍易漏成熟机制）、方案 C（多行业单代码库改造，
|
||
动已上线的稳定项目）。
|
||
|
||
**方案 A 的固有代价**：两项目 ~85% 代码相同，上游修 bug 需手动同步。缓解：本项目
|
||
CLAUDE.md 记录上游项目路径与 changelog 目录，维护时对照。
|
||
|
||
## 3. 复制边界
|
||
|
||
**复制**：`app/`、`static/`、`tests/`、`scripts/`、`docs/`（changelog 归档保留）、
|
||
`Dockerfile`、`docker-compose.yml`、`deploy.sh`、`openresty.conf`、
|
||
`requirements*.txt`、`pytest.ini`、`.gitignore`、`.dockerignore`、`.env.example`。
|
||
|
||
**排除**：`.git/`（新项目新建仓库）、`data/cc_ai_kefu.db`（含生产数据，从空库开始）、
|
||
`.env`（含真实密钥）、`__pycache__/`、`.pytest_cache/`、`.ruff_cache/`、
|
||
`.playwright-mcp/`。
|
||
|
||
**顺手清理**：
|
||
- 删除 `static/blog.html`（WordPress 演示宿主页，与客服功能无关）
|
||
- 移除 redis：requirements 依赖、docker-compose 服务、.env.example 配置
|
||
（代码从未使用，纯减负）
|
||
|
||
## 4. 提示词建材化设计（核心定制）
|
||
|
||
四个文件框架结构全部保留，只换行业语义：
|
||
|
||
### 4.1 `system.md`（人设与边界）
|
||
- 六段结构保留：语言规则/职能边界/红线/说话风格/对话推进/好差示例
|
||
- 人设：HESUPIPE 管道出口外贸销售
|
||
- 知识域：管材品类（HDPE/PVC/PPR/球墨铸铁等）、口径（DN/mm/inch）、
|
||
压力等级（PN/SDR）、标准（ISO4427/ASTM/SCH 系列）、应用场景
|
||
（给水/燃气/排污/灌溉/疏浚/养殖）
|
||
- 预算路径：`"Which application? Water supply, gas, drainage or irrigation?"`
|
||
（替代汽车项目的 "SUV or sedan?"）
|
||
- 红线补充：MOQ、交期 lead time、装柜 container loading、样品费 sample、
|
||
认证证书清单、价格区间——一律不明确回答，引导留资转客户经理
|
||
- 好差示例改写为管道真实场景（如 PE100 给水管 DN110 PN16、PVC 排水管）
|
||
- **语言规则（含多语言墙配套，见 §6）**：保留"客户用什么语言就用什么语言回复"；
|
||
新增约束——**拒绝价格/交期/MOQ 等实质问题时，必须包含固定英文短句**
|
||
（"Please leave your contact and our manager will send the full quotation"），
|
||
保证输出墙正则可靠拦截
|
||
- 回复时效话术用 "reply within 12 hours" 类承诺，不提中国作息时间
|
||
|
||
### 4.2 `company_facts.md`（公司事实卡 = 全部知识库）
|
||
- 内容来源：抓取 hesupipe.com（首页/关于我们/产品分类页/证书页/销售网络/
|
||
新闻中的真实项目案例）
|
||
- 收录范围：公司概况（1998 年成立、2007 年起出口、河南郑州）、十大产品线总表、
|
||
应用领域、认证、销售网络
|
||
- **只收录可验证硬事实**，WordPress 模板化填充内容（物流/客服段落）一律不收
|
||
- **不含**：价格、交期、产能硬数据、MOQ——未知一律走"转客户经理"兜底
|
||
- 防编造原则（统一兜底/不扩展）原样保留
|
||
- **审核关卡（必经步骤）**：事实卡初稿完成后，需求方业务侧（懂管道产品的人）
|
||
逐条过目确认，审核通过才可上线——AI 说的每句公司情况都来自这张卡，卡错则
|
||
AI 一本正经说错话
|
||
|
||
### 4.3 `extractor.md`（信息提取字段）
|
||
中文键画像字段改建材语义：
|
||
- 意向品类（HDPE 给水管/PVC 排水管/…）
|
||
- **规格要求：自由文本保留客户原话**（不过度结构化——客户经理报价需要原文复述）
|
||
- **标准要求单独一列**（ISO/ASTM/EN/SCH）
|
||
- 采购数量、用途（给水/燃气/排污/灌溉）、项目类型、目标国家、预算提及
|
||
|
||
### 4.4 `evaluator.md`（意向评估）
|
||
三级（interested / not_interested / pending）保留；评估语义改管道采购：
|
||
明确品类+规格+数量 = 高意向；泛泛了解 = pending。
|
||
|
||
## 5. 代码级改动清单
|
||
|
||
| 位置 | 改动 |
|
||
|---|---|
|
||
| `app/services/conversation.py` | `BOUNDARY_TRIGGER_RE` 补建材触发词（MOQ、lead time、装柜、container loading、sample、certificate）；context 种子 `vehicle_name/vehicle_id` → `product_name/product_id`；提醒话术"车型"→"产品方案" |
|
||
| `app/services/boundary_filter.py` | 见 §6 多语言墙分层设计；汽车特定排除项（公里/km/年款/车龄）改为建材排除项（DN/mm/inch/PN/SDR 规格数字、ISO/ASTM 标准号） |
|
||
| `app/services/contact_pipeline.py` | canon 归一化加一行 Unicode→ASCII 数字转换（٠-٩→0-9，阿语号码 CRM 可直接拨） |
|
||
| `app/services/email_service.py` | 发件人名【XYH】→【HESUPIPE】 |
|
||
| `app/main.py` | FastAPI title → "HESUPIPE AI 客服" |
|
||
| `app/api/routes/chat_rest.py` | docstring、context 种子键名同步 |
|
||
| `app/services/rate_limit.py` | docstring 更新 |
|
||
| `scripts/breach_rate.py` | 价格词模式跟随多语言扩充同步 |
|
||
| DB 文件名 | `data/hesupipe_ai_kefu.db` |
|
||
| docker-compose 容器名 | `hs-ai-kefu`（redis 服务删除） |
|
||
| openresty.conf | 路径 `hesupipe_ai_kefu` |
|
||
|
||
**已验证无需改动**：`lead_push_service.py`（payload 的 profile 为 raw_info 整体
|
||
透传，零行业字段硬编码）、`static/admin.html` 画像渲染（Object.keys 动态）。
|
||
|
||
## 6. 多语言输出墙分层设计（漏洞 1 修订）
|
||
|
||
参考项目现状：提示词要求跟随任意语言，但正则墙只精确覆盖中英；语言无关的
|
||
零号码墙（≥10 位数字）和 `$`+数字模式兜底其余。汽车项目英语流量占绝对主力，
|
||
暴露面小；**建材项目南美（西语）/中东（阿语）/俄语区/欧洲流量占比高，必须扩充**。
|
||
|
||
分层设计（沿用参考项目思路 + 按建材市场扩充）：
|
||
|
||
1. **保留**：中英全量模式、零号码墙、邮箱墙（语言无关，已验证）
|
||
2. **扩充价格墙**：
|
||
- 货币：`€`+数字（参考项目没有，对欧出口必备）、`£`+数字（英国流量）
|
||
- 西语/葡语/俄语/阿语高频价格词+数字组合：
|
||
precio/costo/preço（巴西为南美最大单一市场）/цена/стоимость/سعر/ثمن
|
||
- 时间承诺：días/semanas/дней/недель/أيام
|
||
3. **迂回话术池**：EN/ZH 基础上加 ES 池（南美第一大流量）；其余语言 fallback
|
||
英文（与参考项目"粗匹配+默认英文"同构）
|
||
4. **提示词配套**（见 §4.1）：拒绝话术必含固定英文短句，保证正则可靠命中
|
||
5. **防误杀验证**：DN800、PN16、SDR11、PE100、600mm、SCH40、3/4 inch、
|
||
ISO4427、20ft/40ft 等规格形态不得触发价格墙/零号码墙（专项测试）
|
||
|
||
## 7. 集成与部署配置
|
||
|
||
| 项 | 配置 |
|
||
|---|---|
|
||
| UniService 推送 | 代码原样；`external_key_prefix=ai-kefu-jc`（与汽车项目线索隔离）；API URL/Key 沿用现有 UniService 账号 |
|
||
| 邮件 | SMTP 沿用现有配置；NOTIFY_EMAIL 指向管道业务客户经理邮箱 |
|
||
| LLM | 智谱 GLM（glm-4-flash），Key 复用或新建均可 |
|
||
| 端口 | 8017（汽车项目 8016 旁） |
|
||
| 域名 | 实施时需求方提供（如 ai.hesupipe.com） |
|
||
| 前端联系 | WhatsApp 与邮箱默认值见 §11（实施时需求方确认） |
|
||
|
||
**开发期安全流程（漏洞 2 修订）**：开发与验收阶段 `PUSH_ENABLED=false` +
|
||
`scripts/mock_uniservice.py` 本地联调 + NOTIFY_EMAIL 指测试邮箱；
|
||
**全部验收通过后一次性切换生产配置**。最终状态为启用（需求方已确认）。
|
||
|
||
## 8. 前端改动
|
||
|
||
- `chat.html` / `widget.js` / `chat.js`：HESU Support → HESUPIPE Support；
|
||
欢迎语改管道场景（"What kind of piping project are you working on?"）；
|
||
热门话题（Get Quotation / Pipe Specifications / Delivery & Shipping）；
|
||
WhatsApp/邮箱默认值更新
|
||
- `admin.html`：VOLT → HESUPIPE
|
||
- `theme.js` 默认品牌色：橙 `#f08a31` → HESUPIPE 品牌蓝（色值实施时从官网取；
|
||
widget `data-color` 覆盖机制保留）
|
||
- 头像图片：换管道主题/HESUPIPE logo（需求方提供或生成）
|
||
- **GDPR（第二轮深挖新增项）**：挂件首次对话前加一行
|
||
"By chatting, you agree to our privacy policy"（隐私政策页放 hesupipe.com，
|
||
WordPress 侧）；上线前完成，不阻塞开发
|
||
- **官网嵌入交付（第三轮补充，必交付物）**：产出一段可直接粘贴的挂件嵌入代码
|
||
（script 标签 + data-* 配置示例）+ 给官网管理员的一页接入说明
|
||
（贴在哪、怎么配主题色/位置/WhatsApp 号）。系统做完≠有人用——官网不挂上去，
|
||
买家看不到，等于白做
|
||
|
||
## 9. 测试策略
|
||
|
||
### 9.1 自动化测试（LLM 全 mock，验证代码正确性）
|
||
|
||
1. 全量拷贝 170+ 测试 → 更新含文案断言的用例（HESU/VOLT/车型示例 →
|
||
HESUPIPE/管材场景）
|
||
2. **多语言墙专项**：西语/俄语价格句必须拦截；DN800/PN16/SDR11/SCH40/
|
||
ISO4427/20ft 规格形态不得误杀；"USD 1200/ton"、"$500/ton"、€ 报价必须拦截
|
||
3. **阿语数字提取**：٠١٢٣٤٥٦٧٨٩ 形式号码提取并转 ASCII
|
||
4. extractor 建材字段提取用例
|
||
5. `pytest` 全绿 + `widget-test.html` 挂件手动验收 + mock_uniservice 联调验收
|
||
|
||
### 9.2 真人验收（真实 LLM，验证 AI 表现——mock 测不了这些）
|
||
|
||
pytest 全绿只证明代码没写错，不证明 AI 聊得好。上线前用真 Key 实聊验收清单
|
||
（参考汽车项目 `docs/test-checklist.md` 改写）：
|
||
|
||
- 英文问价 / 西语问价 / 问 MOQ / 要样品 / 问交期 / 问认证 → 一律不正面回答，
|
||
引导留资，回复语言跟随客户
|
||
- 客户留电话 → 画像更新、触发邮件（测试邮箱）+ mock 推送
|
||
- 客户中途换号码 → 更正邮件触发、不重复轰炸
|
||
- 已留资后再问价 → 不再索要联系方式
|
||
- 建材规格聊天（DN110 PN16 之类）→ 不误杀、正常聊
|
||
- 管理后台能看到上述会话、画像 chips、意向分级、推送日志
|
||
|
||
### 9.3 上线观察期（第一周）
|
||
|
||
上线不是终点。第一周跑 `scripts/breach_rate.py`（同步多语言词表后）观测：
|
||
漏放的价格形态、误杀的规格数字，发现即补正则。参考项目当年也是逐圈修出来的。
|
||
|
||
## 10. 风险登记
|
||
|
||
| 风险 | 等级 | 缓解 |
|
||
|---|---|---|
|
||
| 多语言墙覆盖不全 | 中 | §6 分层 + 专项测试；上线后跑 breach_rate 观测 |
|
||
| 事实卡收录模板化内容导致编造 | 中 | §4.2 只收硬事实 + 人工审核事实卡 |
|
||
| GDPR 欧洲合规 | 低 | §8 隐私提示；不阻塞 |
|
||
| 双项目长期同步代价 | 低 | CLAUDE.md 记录血缘；changelog 对照 |
|
||
| 与汽车项目共用智谱 Key/SMTP 额度 | 低 | 现量小无碍；某一方爆量时再拆分独立账号 |
|
||
| glm-4-flash 多语言提取/评估退化 | 低 | 测试覆盖；必要时升级模型 |
|
||
|
||
## 11. 需求方提供的凭据/资源（实施时）
|
||
|
||
| 项 | 说明 |
|
||
|---|---|
|
||
| 智谱 API Key | 复用参考项目 .env 或新建 |
|
||
| SMTP 账号密码 | 复用参考项目 .env |
|
||
| UniService API Key | 复用参考项目 .env（同一 CRM 账号） |
|
||
| NOTIFY_EMAIL | 管道业务询盘收件邮箱（需求方指定） |
|
||
| WhatsApp 号码二选一 | 15937108317（官网主号码）/ 15890151617；邮箱 hesu@hesuu.com |
|
||
| 客服头像图 | HESUPIPE logo 或管道主题图 |
|
||
| 部署域名 + 服务器 | 如 ai.hesupipe.com |
|