# HESUPIPE 建材 AI 客服

为 HESUPIPE（hesupipe.com，河南和硕集团管道建材出口业务）打造的官网 AI 客服系统。
服务全球 B2B 管道采购买家：AI 了解需求（品类/规格/数量/用途/目标国家）→ 引导留资 →
线索经邮件 + UniService CRM 推送交人工客户经理跟进。

AI 只做"需求了解 + 留资"：价格、交期、MOQ、样品费、质保年限等实质问题一律不正面回答，
多语言输出墙（中/英/西/葡/俄/阿 + €/£ 货币符号）兜底拦截，引导留资转客户经理。

> 本项目复制自同集团汽车业务 AI 客服（`ai-kefu`，~85% 代码同源）并建材化定制。
> 血缘与同步规则见 `CLAUDE.md`；设计文档见
> `docs/superpowers/specs/2026-09-29-building-materials-ai-kefu-design.md`。

## 技术栈

- **后端**：Python / FastAPI + SQLAlchemy(async) + SQLite（`data/hesupipe_ai_kefu.db`）
- **LLM**：智谱 GLM（默认 glm-4-flash，`zhipuai` SDK，流式输出）
- **前端**：原生 JS 挂件（`static/widget.js`，Shadow DOM 隔离，可嵌入任意官网）+
  WebSocket 流式对话
- **线索出口**：SMTP 邮件（aiosmtplib）+ UniService CRM HTTP 推送（httpx，带重试矩阵）
- **部署**：Docker + docker compose + OpenResty 反代

## 本地启动

```bash
pip install -r requirements.txt

cp .env.example .env
# 编辑 .env，至少填入：
#   ZHIPU_API_KEY=...          智谱 API Key（必需）
#   其余 SMTP / 推送配置可先留占位

uvicorn app.main:app --host 0.0.0.0 --port 8017
```

- 聊天演示页：http://localhost:8017/
- 管理后台：http://localhost:8017/admin
- 健康检查：http://localhost:8017/health
- 挂件本地测试页：`static/widget-test.html`

## 测试

```bash
pip install -r requirements-dev.txt
pytest
```

- **230 项全绿是合并门槛**（LLM 全 mock，验证代码正确性）。
- 真实 LLM 验收（守边界/语言跟随/留资链路/推送联调）用 `scripts/mock_uniservice.py`
  配合真实智谱 Key 进行，清单与最近一次验收结果见 `docs/test-checklist.md`。

## 部署（生产）

```bash
# 服务器上（.env 已按生产配置就绪）
bash deploy.sh
```

`deploy.sh` = docker compose 停旧 → 构建 → 启动（容器名 `hs-ai-kefu`，宿主端口 8017）→
健康检查。外层用 OpenResty 反代到公网（配置见 `openresty.conf`，后端路径
`hesupipe_ai_kefu`），WebSocket（`/ws/chat`）与 HTTP 同端口。

### 上线切换检查单（开发 → 生产，一次性完成）

- [ ] **事实卡业务侧审核**（设计文档 §4.2 必经关卡）：懂管道产品的人逐条过目
      `app/prompts/company_facts.md`——AI 说的每句公司情况都来自这张卡
- [ ] **清验收测试数据**：删除或归档 `data/hesupipe_ai_kefu.db`
      （含验收期的 15 个测试会话与推送日志，直接上生产会污染后台视图）
- [ ] `.env` 中 `PUSH_ENABLED=true`（开发期为 `false`，防测试线索推爆生产 CRM）
- [ ] `PUSH_API_URL` / `PUSH_API_KEY` 换成真实 UniService 地址与 Key
      （`PUSH_EXTERNAL_KEY_PREFIX=ai-kefu-jc` 保持不变，与汽车项目线索隔离）
- [ ] `NOTIFY_EMAIL` 换成管道业务客户经理邮箱（非测试邮箱）
- [ ] SMTP 配置为真实发件账号（已在生产服务器就绪）
- [ ] 绑定生产域名（如 `ai.hesupipe.com`）并配好 HTTPS 证书
- [ ] 官网按 `docs/embed-guide.md` 嵌入挂件
- [ ] 上线后第一周跑 `scripts/breach_rate.py` 观测漏放/误杀（设计文档 §9.3）

## 管理后台

入口 `/admin`（登录走 `/api/admin/login`）。三视图：

- **会话列表**：全部对话、消息数、意向分级、联系方式、邮件已发标记
- **会话详情**：完整对话记录 + 客户画像 chips（意向品类/规格要求/标准要求/采购数量/
  用途/目标国家/联系方式）
- **推送日志**：lead / correction 推送记录与状态（含重试轨迹）

## 挂件嵌入官网

挂件由本服务 `/static/widget.js` 提供，一行 `<script>` 即可嵌入官网（WordPress 或任意
建站系统）。嵌入代码、配置项（位置/主题色/WhatsApp/邮箱/自动邀请等）、三种 WordPress
粘贴方式与上线检查单，见 **[docs/embed-guide.md](docs/embed-guide.md)**。

主题色默认已是 HESUPIPE 品牌蓝 `#066fc0`，可用 `data-color` 覆盖，整套配色自动派生。

## 目录速览

```
app/
  prompts/          4 个提示词（system/company_facts/extractor/evaluator）——建材化核心
  services/         会话管理、boundary_filter 多语言墙、留资管道、推送、邮件
  api/              WebSocket + REST 路由、admin 路由
static/             widget.js（官网挂件）、chat.html、admin.html、js/theme.js
scripts/            mock_uniservice.py（联调）、breach_rate.py（上线观测）
docs/               changelog 归档、test-checklist.md、embed-guide.md、设计文档
tests/              230 项 pytest（LLM 全 mock）
```