# 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/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 `+8615937108317`（官网主号码）、邮箱 `hesu@hesuu.com`（备选号 15890151617，实施时确认） |

**开发期安全流程（漏洞 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 |