# 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`，
靠此观察期收敛。