docs: HESUPIPE 建材AI客服设计文档
基于 D:\refactor\ai-kefu 汽车AI客服项目复制+建材化定制的完整设计。 方案A：完整拷贝+定制，含多语言输出墙分层、开发期推送隔离等修订。 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
@@ -0,0 +1,189 @@
|
||||
# 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——未知一律走"转客户经理"兜底
|
||||
- 防编造原则（统一兜底/不扩展）原样保留
|
||||
|
||||
### 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/цена/стоимость/سعر/ثمن
|
||||
- 时间承诺：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 `+8615987108317`、邮箱 `hesu@hesuu.com`（两个官网号码最终用哪个，实施时确认） |
|
||||
|
||||
**开发期安全流程（漏洞 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 侧）；上线前完成，不阻塞开发
|
||||
|
||||
## 9. 测试策略
|
||||
|
||||
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 联调验收
|
||||
|
||||
## 10. 风险登记
|
||||
|
||||
| 风险 | 等级 | 缓解 |
|
||||
|---|---|---|
|
||||
| 多语言墙覆盖不全 | 中 | §6 分层 + 专项测试；上线后跑 breach_rate 观测 |
|
||||
| 事实卡收录模板化内容导致编造 | 中 | §4.2 只收硬事实 + 人工审核事实卡 |
|
||||
| GDPR 欧洲合规 | 低 | §8 隐私提示；不阻塞 |
|
||||
| 双项目长期同步代价 | 低 | CLAUDE.md 记录血缘；changelog 对照 |
|
||||
| glm-4-flash 多语言提取/评估退化 | 低 | 测试覆盖；必要时升级模型 |
|
||||
|
||||
## 11. 需求方提供的凭据/资源（实施时）
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 智谱 API Key | 复用参考项目 .env 或新建 |
|
||||
| SMTP 账号密码 | 复用参考项目 .env |
|
||||
| UniService API Key | 复用参考项目 .env（同一 CRM 账号） |
|
||||
| NOTIFY_EMAIL | 管道业务询盘收件邮箱（需求方指定） |
|
||||
| WhatsApp 号码二选一 | 15937108317 / 15890151617 |
|
||||
| 客服头像图 | HESUPIPE logo 或管道主题图 |
|
||||
| 部署域名 + 服务器 | 如 ai.hesupipe.com |
|
||||
Reference in New Issue
Block a user