docs: 官网嵌入指南+CLAUDE.md血缘+README

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-09-29 20:12:26 +08:00
parent e5335c5787
commit 7b78c9bfd0
3 changed files with 326 additions and 0 deletions
@@ -0,0 +1,85 @@
 # CLAUDE.md
 HESUPIPE 管道建材 AI 客服（hesupipe.com，河南和硕集团）。
 FastAPI + SQLite + 智谱 GLM，嵌入外贸官网，做"AI 需求了解 + 留资获客 + 邮件/UniService
 CRM 推送"，AI 不回答价格/交期/MOQ 等实质问题，一律引导留资转客户经理。
 ## 血缘与上游同步（重要）
 本项目**复制自**参考项目 `D:\refactor\ai-kefu`（Hesu Auto 汽车出口 AI 客服，同集团姊妹
 业务），约 **85% 代码同源**。复制时的架构决策见
 `docs/superpowers/specs/2026-09-29-building-materials-ai-kefu-design.md`（方案 A：完整拷贝
 + 建材化定制）。
 **同步规则**：上游修 bug / 改正则 / 调提示词机制后，本项目需**手动同步**。
 1. 看上游 `D:\refactor\ai-kefu\docs\` 下的 changelog 文件（按日期命名，如
   `2026-09-28-lead-push-changelog.md`）——本项目 `docs/` 下有同批文件的拷贝（截至
   复制日 2026-09-29），对比两边目录即可发现上游新增的变更记录；
 2. 评估该修复是否适用于本项目（建材差异部分见下），适用则同步代码 + 同步测试；
 3. 同步后在本次提交信息里注明"同步自上游 <changelog 文件名>"。
 **禁止反向操作**：不要把本项目的建材定制覆盖回上游。
 ## 与上游的关键差异清单（改这些地方时别照抄上游）
 | 差异点 | 本项目 | 上游（ai-kefu） |
 |---|---|---|
 | 行业与提示词 | 4 个提示词全部建材化：`system.md`（管道外贸人设+MOQ/交期/样品/认证红线）、`company_facts.md`（HESUPIPE 事实卡）、`extractor.md`（意向品类/规格要求/标准要求/采购数量等字段）、`evaluator.md`（管道采购意向分级） | 汽车（Hesu Auto）语义 |
 | boundary_filter 多语言墙 | 墙按建材市场扩充：`€`/`£`+数字、西葡俄阿价格词（precio/costo/custo/preço/цена/стоимость/سعر/أسعار/ثمن，含复数与阿语定冠词 ال 连写形态）+天数词（días/дней/أيام 等）；迂回话术池 EN/ZH/**ES**；规格防误杀（DN/PN/SDR/PE100/SCH/ISO4427/20ft 不拦） | 只中英 + `$` + 零号码墙 |
 | 线索键前缀 | `PUSH_EXTERNAL_KEY_PREFIX=ai-kefu-jc`（与汽车项目线索空间隔离，**勿改回 ai-kefu**） | `ai-kefu` |
 | 端口 | 8017 | 8016 |
 | Docker 容器名 | `hs-ai-kefu` | （上游原名不同） |
 | 品牌 | HESUPIPE，品牌蓝 `#066fc0`（theme.js 与 widget.js 中的主题派生单元整块同步，`tests/test_theme_static.py` 强制一致） | HESU，橙色 |
 | DB 文件 | `data/hesupipe_ai_kefu.db` | `data/cc_ai_kefu.db` |
 | openresty 路径 | `hesupipe_ai_kefu` | （上游路径） |
 | context 种子键 | `product_name` / `product_id` | `vehicle_name` / `vehicle_id` |
 主题派生单元（调色板函数块）在 `static/widget.js` 与 `static/js/theme.js` 中逐字相同，
 只可整块替换，不可单边修改——`tests/test_theme_static.py` 会强制校验。
 ## 开发约定
 - **推送开关**：开发/测试期 `.env` 保持 `PUSH_ENABLED=false`，防止测试线索推爆生产 CRM。
  生产环境必须 `true`（需求方已确认最终状态为启用）。全量验收通过后一次性切换。
 - **合并门槛**：`pytest` **230 项全绿**。LLM 全 mock，验证代码正确性。
 - **真实 LLM 验收**：mock 测不了 AI 表现（守边界/语言跟随/不回显号码）。用真实智谱 Key +
  `scripts/mock_uniservice.py`（本地 9099，`PYTHONUTF8=1` 启动，期待 `X-Api-Key: test-key-123`）
  联调，验收清单与现状见 `docs/test-checklist.md`（2026-09-29 已通过，含 4 项不阻塞残差）。
 - **提示词改动**：`app/prompts/` 下 4 个 .md 是 AI 行为的源头；改动后跑 pytest（有文案断言）
  并视改动性质补一轮真实验收。
 - **环境坑（Windows）**：mock_uniservice 必须以 `PYTHONUTF8=1` 启动，否则 GBK 控制台遇
  emoji payload 即崩溃；中文文档用 Write 工具写，别用 bash heredoc。
 ## 常用命令
 ```bash
 # 测试（合并门槛，230 项）
 pytest
 # 本地启动（端口 8017）
 pip install -r requirements.txt
 cp .env.example .env   # 填 ZHIPU_API_KEY 等
 uvicorn app.main:app --host 0.0.0.0 --port 8017
 # 本地联调推送（PUSH_ENABLED=false 时不影响；验证推送链路用）
 PYTHONUTF8=1 python scripts/mock_uniservice.py   # 监听 9099，X-Api-Key: test-key-123
 # 生产部署（服务器上）
 bash deploy.sh    # docker compose 构建并启动，健康检查 127.0.0.1:8017/health
 ```
 - 聊天演示页 `/`，管理后台 `/admin`，健康检查 `/health`。
 - 挂件嵌入官网指引：`docs/embed-guide.md`。
 ## 上线观察期（第一周必做）
 上线不是终点。**上线后第一周**跑 `scripts/breach_rate.py` 观测双向偏差：
 - **漏放**：AI 回复里出现价格/交期/MOQ 数字而墙没拦下（多语言新词表已随建材化扩充，
  仍可能有长尾语言形态漏网）；
 - **误杀**：正常建材规格聊天（DN800/PN16/SDR11 之类）被墙误拦。
 发现即补正则 + 补测试，流程见设计文档 §9.3。已知 4 项不阻塞残差（西语模板句翻译、
 样品措辞、extractor 占位词、多轮压力下偶发漂移）记录在 `docs/test-checklist.md`，
 靠此观察期收敛。
@@ -0,0 +1,102 @@
 # 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 同端口。
 ### 上线切换检查单（开发 → 生产，一次性完成）
 - [ ] `.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）
 ```
@@ -0,0 +1,139 @@
 # HESUPIPE AI 客服挂件 — 官网嵌入指南
 给官网管理员的接入说明。不需要写代码，只需要复制粘贴一段代码。
 全程约 10 分钟。
 ---
 ## 1. 嵌入代码（直接复制粘贴）
 在正式开始前，请先向开发确认一件事：**客服系统部署后的域名是什么**（例如 `ai.hesupipe.com`）。
 下面代码里的 `https://ai.hesupipe.com` 请替换成实际域名。
 ```html
 <!-- HESUPIPE AI 客服挂件 开始 -->
 <script
    src="https://ai.hesupipe.com/static/widget.js"
    data-position="bottom-right"
    data-color="#066fc0"
    data-title="HESUPIPE Support"
    data-whatsapp="https://wa.me/+8615937108317"
    data-email="mailto:hesu@hesuu.com"
    data-auto-invite="true"
 ></script>
 <!-- HESUPIPE AI 客服挂件 结束 -->
 ```
 粘贴后刷新官网任意页面，右下角应出现蓝色 "Chat with us" 胶囊按钮，即嵌入成功。
 > **本地/测试环境预览**：部署前想先看效果，把 `src` 换成本地服务地址
 > `http://localhost:8017/static/widget.js`（需本地启动服务）。
 ---
 ## 2. 贴到哪里（WordPress 三种主流方式，任选其一）
 ### 方式 A：自定义 HTML 小工具（最简单，推荐）
 1. WordPress 后台 → **外观 → 小工具**
 2. 找到 **自定义 HTML** 小工具，添加到 **Footer（页脚）** 区域
 3. 把上面的嵌入代码整段粘贴进内容框
 4. 保存，刷新官网前台页面验证
 ### 方式 B：主题设置里的"页脚脚本"输入框
 很多商业主题自带代码注入功能：
 1. **外观 → 自定义**（或 主题设置），找类似 **Footer Scripts / 页脚代码 / 跟踪代码** 的输入框
 2. 把嵌入代码整段粘贴进去
 3. 保存发布
 > 如果主题同时有"页眉脚本"和"页脚脚本"，选**页脚**（页面加载更快）。
 ### 方式 C：直接编辑页脚模板 footer.php（懂一点主题编辑时用）
 1. **外观 → 主题文件编辑器** → 右侧选择 **Footer (footer.php)**
 2. 找到 `</body>` 标签，把嵌入代码粘贴到 `</body>` 的**上一行**
 3. 点"更新文件"
 > **注意**：直接改主题文件时，主题更新后改动会被覆盖。建议在**子主题（Child Theme）**里改，
 > 或改用方式 A/B。
 ---
 ## 3. 可调配置说明
 以下配置全部写在 `<script>` 标签上（即上面代码里 `data-xxx` 的部分），改属性值即可。
 **所有配置都可省略**——省略时用默认值，默认值就是 HESUPIPE 官方配置。
 | 属性 | 作用 | 可选值 / 默认值 |
 |---|---|---|
 | `data-position` | 挂件在页面上的位置 | `bottom-right`（默认，右下）/ `bottom-left` / `top-right` / `top-left` |
 | `data-color` | 主题色（16 进制色值） | 默认 `#066fc0`（HESUPIPE 品牌蓝）。改一个色值，按钮、面板、邀请卡整套颜色自动跟着变 |
 | `data-title` | 聊天窗口顶部的标题 | 默认 `HESUPIPE Support` |
 | `data-whatsapp` | 挂件内 WhatsApp 按钮的跳转链接 | 默认 `https://wa.me/+8615937108317` |
 | `data-email` | 挂件内 Email 按钮的跳转链接 | 默认 `mailto:hesu@hesuu.com` |
 | `data-auto-invite` | 是否在访客停留约 5 秒后自动弹出邀请卡片 | 默认 `true`（弹出）。不想要自动弹卡改为 `"false"` |
 | `data-theme` | 聊天窗口明暗风格 | 默认 `light`；可选 `dark` |
 | `data-auto-open` | 页面打开时是否自动展开聊天窗口 | 默认 `false`（不展开）。一般不建议设 `true`，会打扰访客 |
 | `data-mobile` | 移动端专用样式（圆形按钮+文字标签） | 默认 `false`。移动端页面可设 `"true"` |
 | `data-avatar` | 客服头像图片地址 | 默认使用系统自带的 HESUPIPE 客服头像 |
 **最常改的三个**：位置（`data-position`）、主题色（`data-color`）、WhatsApp 号（`data-whatsapp`）。
 ---
 ## 4. 主题色说明
 - 默认主题色已经是 **HESUPIPE 品牌蓝 `#066fc0`**，**正常情况什么都不用配**。
 - 只有当官网改版换品牌色时，才需要在 `<script>` 标签上加（或修改）`data-color` 属性，
  例如换成绿色：`data-color="#0a7d4f"`。
 - 色值必须是 `#` 开头的 6 位 16 进制（如 `#066fc0`）。填错时挂件会自动退回品牌蓝并在
  浏览器控制台提示，不会显示成怪颜色。
 ---
 ## 5. 隐私政策（GDPR）配套要求
 挂件的聊天窗口底部和自动邀请卡上，都会显示一行固定提示：
 > By chatting, you agree to our privacy policy.
 其中 "privacy policy" 链接指向 **https://hesupipe.com/privacy-policy/**。
 上线前请确认：
 - [x] 该隐私政策页面**真实存在且可访问**（2026-09 已验证可打开，为 HESU Technologies
  完整隐私政策页）；
 - [ ] 页面内容涵盖"聊天记录用于客户联络"的说明（如现有政策未覆盖，请让法务/业务侧补充）；
 - [ ] 若日后隐私政策 URL 变更（如换域名、换路径），**需通知开发修改挂件代码**——
  该链接写死在 `static/widget.js` 中，改链接不是改配置就能完成的。
 ---
 ## 6. 常见问题
 **Q：贴上去没反应？**
 检查 `<script>` 的 `src` 域名是否写对（必须是客服系统实际部署的域名，浏览器直接打开
 `https://你的域名/static/widget.js` 应能看到一串代码）。再检查代码是否被 WordPress
 编辑器自动加了转义或换行破坏。
 **Q：会拖慢官网吗？**
 挂件代码很小，且放在页脚不影响首屏渲染。聊天连接只在访客点击按钮后建立。
 **Q：访客关掉了邀请卡还会一直弹吗？**
 不会。访客点 X 或 "No Thanks" 后，本次浏览器会话内不会再自动弹出。
 **Q：想同时改 WhatsApp 号码和邮箱怎么办？**
 改 `data-whatsapp` 和 `data-email` 两个属性的值即可，见第 3 节表格。
 ---
 ## 7. 上线检查单
 - [ ] 客服系统已在生产域名部署并可访问（`https://你的域名/health` 返回 ok）
 - [ ] 嵌入代码中 `src` 已替换为生产域名
 - [ ] 已按第 2 节方式之一贴入官网，前台刷新后右下角可见挂件
 - [ ] 官网隐私政策页可访问（见第 5 节）
 - [ ] 手机浏览器打开官网验证显示正常（建议顺手测一台 Android 和一台 iPhone）
 - [ ] 发一条测试消息，确认 AI 正常回复；留下测试联系方式，确认客户经理能收到通知