浅念
107 lines
4.9 KiB
Markdown
107 lines
4.9 KiB
Markdown
# 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）
|
||
```
|