xinyouhe/ai-kefu-jc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

test: 真人验收清单+API级联调验收

Browse Source 
真实 GLM 五轮实跑(EN/ES/ZH/换号/敏感问)+mock推送+admin三视图,核心项全过。
修复: 中文轮漂英文→语言跟随提醒; extractor裸字符串联系方式→500崩溃兜形;
号码回显/样品承诺/标记词泄漏 prompt加固; 测试env耦合断言; .env前缀对齐。

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
2026-09-29 20:02:03 +08:00
parent 7da1e22446
commit c2f2ddf82f
9 changed files with 256 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/test-checklist.md
+136 -267
View File
@@ -1,324 +1,193 @@
# Chat Widget Redesign - Final Acceptance Test Checklist
# HESUPIPE 建材 AI 客服 - 真人验收清单（真实 LLM + mock 推送联调）
依据设计文档 `docs/superpowers/specs/2026-09-29-building-materials-ai-kefu-design.md` §9.2 全项。
pytest 全绿（mock LLM）只证明代码没写错；本清单用真实 GLM 实聊，验证 AI 表现——
守边界（不报价格/交期/MOQ/质保数字）、跟语言、引导留资、画像建材化、推送链路。
## Test Environment
- **Branch:** `chany_dev`
- **Base Branch:** `master`
- **Test Date:** 2026-04-22
- **Tester:** Claude Code
- **Branch:** `feat/building-materials-implementation`
- **Test Date:** 2026-09-29
- **Tester:** Claude Code（API 级实跑，非浏览器）
- **LLM:** 智谱 GLM（真实 Key，需求方提供）
- **推送:** mock UniService（`scripts/mock_uniservice.py`，本地 9099，期待 X-Api-Key: test-key-123）
- **SMTP:** 占位（无测试邮箱）——邮件实发验证留待需求方提供测试邮箱；触发痕迹从服务日志观察
- **API:** REST（`/api/chat/session` + `/api/chat/message`，与 WS 挂件同 `ConversationManager`）
- **库:** SQLite `data/hesupipe_ai_kefu.db`（conversations/messages/customer_profiles/evaluations/lead_push_logs）
---
## 1. Visual Design Verification ✅
## 1. 职能边界：敏感问题一律不正面回答，引导留资（§9.2 第 1 项）
### 1.1 Entry Button (Widget Mode)
- [x] **横条卡片式设计** - Implemented in `widget.js` line 44-45
- [x] **橙色背景 (#f08a31)** - Confirmed
- [x] **圆角设计 (30px border-radius)** - Confirmed
- [x] **悬停放大效果 (scale 1.1)** - Line 45
- [x] **白色文字和图标** - Confirmed
- [x] **阴影效果** - Line 44: `box-shadow: 0 4px 16px rgba(240,138,49,0.4)`
每问验证三点：**AI 回复无价格/数字承诺**（人工读消息）、**含引导留资**（模板句或转接句）、
**回复语言跟随客户**（英文客户英文回、西语客户西语叙述+英文模板句、中文客户中文回）。
### 1.2 Chat Header
- [x] **橙色背景 (#f08a31)** - `style.css` line 45
- [x] **48px 头像** - Line 51-58
- [x] **绿色在线状态点** - Line 63-73, 14px green dot with border
- [x] **白色文字** - Line 46
- [x] **最小化/关闭按钮** - `chat.html` line 18-19, styled in CSS line 88-107
- [x] **按钮悬停效果** - Line 105-107
### 1.1 英文问价（英文轮内）
- [x] "how much per meter?"（HDPE water pipe DN110 语境）→ 无任何价格数字/区间/占位符，引导留资
（实测："Prices depend on the specification, quantity, and destination. Could you please leave your contact details? Our manager will send the full quotation."）
- [x] 回复为英文
### 1.3 Help Block
- [x] **"How can we help?" 标题** - `chat.html` line 33
- [x] **浅黄背景 (#fef9f3)** - `style.css` line 322
- [x] **Call us 按钮** - `chat.html` line 35-39
- [x] **WhatsApp 链接** - Confirmed: `https://wa.me/+8619037179250`
- [x] **橙色按钮样式** - `style.css` line 346-366
- [x] **悬停效果** - Line 363-366
### 1.2 西语问价
- [x] "¿Cuál es el precio del tubo PE100?" → 西语叙述 + 引导留资、无价格数字
（实测："El precio del tubo PE100 depende de la especificación, cantidad y destino. Por favor, déjenos su contacto..."）
- [ ] 英文模板句保持原文不翻译——**残差**：glm-4-flash 仍倾向把模板句译成西语
（已两轮 prompt 加固+当轮提醒；确认句（"Got it — our manager will..."）能逐字英文输出，价格迂回句会翻译。
语言跟随与守边界均通过，属措辞级偏差，不阻塞；列入调优迭代，上线后 breach_rate 观测）
- [x] 不整段切英文拒绝
### 1.4 Welcome Message
- [x] **32px 头像** - `style.css` line 149-161
- [x] **橙色圆形头像** - Line 152
- [x] **阴影效果** - Line 160
- [x] **欢迎文字** - `chat.html` line 43
### 1.3 问 MOQ
- [x] "what's your MOQ?" → 不给任何起订量数字（"The MOQ ... can vary depending on the specific product and quantity ... feel free to leave your contact"）
### 1.5 Orange Separator
- [x] **1px 高度** - `style.css` line 215-220
- [x] **30% 透明度** - Line 218: `opacity: 0.3`
- [x] **橙色背景** - Line 217: `background: #f08a31`
### 1.4 要样品
- [x] "can you send me a free sample?" → 不报样品费、无价格数字，引导留资
- [ ] 严格转接句——**残差**：回复仍含 "we can arrange a sample"（承诺主体未完全让位经理），
但寄送执行已归 manager、无免费承诺。两轮 prompt 加固后由"承诺免费寄样"降级为措辞残差，列入调优迭代
### 1.6 Input Container
- [x] **#fef9f3 浅黄背景** - `style.css` line 235
- [x] **28px 圆角** - Line 236: `border-radius: 28px`
- [x] **内边距** - Line 234: `padding: 12px 16px`
- [x] **阴影效果** - Line 237
### 1.5 问交期
- [x] "how long is the lead time?" → 不给任何天数/周数（"Lead time ... depends on your order details and production schedule"，与模板句语义一致）
### 1.7 Send Button
- [x] **"➤ Send" 文字** - `chat.html` line 57-59
- [x] **橙色渐变背景** - `style.css` line 274: `linear-gradient(135deg, #f08a31, #f59e0b)`
- [x] **圆角** - Line 273: `border-radius: 12px`
- [x] **阴影效果** - Line 280
- [x] **悬停效果** - Line 287-289
### 1.8 Footer Bar
- [x] **橙色文字** - `style.css` line 376: `color: #d97706`
- [x] **左侧隐私政策文字** - `chat.html` line 67
- [x] **右侧 "AI + human support"** - Line 70
- [x] **11px 字体** - `style.css` line 375
- [x] **白色背景** - Line 371
### 1.6 问认证
- [x] "do you have ISO certificates? warranty?" → 事实卡简答 ISO 9001/14001/45001（与事实卡逐字一致），
质保不给年限（"warranty terms are confirmed by our manager"）
---
## 2. Functionality Testing ✅
## 2. 留资与画像（§9.2 第 2 项）
### 2.1 Widget Mode (`widget.js`)
- [x] **入口按钮点击展开/收起** - Line 137-144
- [x] **WebSocket 连接** - Line 146-200
- [x] **会话恢复** - Line 152-156
- [x] **流式响应** - Line 165-179
- [x] **Enter 键发送** - Line 229-231
- [x] **输入验证** - Line 221
- [x] **禁用状态处理** - Line 185-187
- [x] **自动重连** - Line 197-199
- [x] **错误处理** - Line 190-194
### 2.1 客户留电话（每语言轮各一次）
- [x] AI 确认收到（"Got it — our manager will reach out to you at your WhatsApp shortly with the full quote!"），
**不回显号码**、不再索要（EN/ES/ZH 三轮留资句均验证；prompt 补对比示例后通过）
- [x] `customer_profiles.raw_info` 画像更新：联系方式入库；字段建材化——实测 EN 轮
`{意向品类: HDPE给水管, 规格要求: DN110 PN16, 采购数量: 5000米, 目标国家: 沙特阿拉伯, 用途: 给水, 项目类型: 市政工程}`，
ZH 轮 `{意向品类: HDPE双壁波纹管, 规格要求: DN800, 标准要求: SN8等级, 用途: 市政排污}`
- [x] `lead_push_logs` 新增 pending → `status=success`、`push_type=lead`（终跑 8 会话 13 条 success）
- [x] mock UniService 收到推送（X-Api-Key=test-key-123 全部 200），payload 含
`external_key=ai-kefu-jc-<conv_id>`、contact.phone/whatsapp、intent_level=high、完整对话
- [x] uvicorn 日志出现邮件发送痕迹（SMTP 占位 → "Failed to send lead email" 异常日志 = 已触发，共 12 次）
### 2.2 Standalone Mode (`chat.js`)
- [x] **WebSocket 连接** - Line 21-86
- [x] **会话持久化** - Line 2, 36-40
- [x] **历史消息加载** - Line 39, 154-155
- [x] **流式响应** - Line 43-58
- [x] **Enter 键发送** - Line 158-163
- [x] **Shift+Enter 换行支持** - Line 159
- [x] **禁用状态处理** - Line 63-66
- [x] **自动重连** - Line 78-80
- [x] **错误处理** - Line 69-74
### 2.2 客户中途换号码（换号轮）
- [x] 画像联系方式更正为新号码（最新显式自述优先；`+212661223344 → +212665544332` 实测）
- [x] 触发 correction 推送：`push_type=correction`、`event=update`（此前同会话已有 success 推送）、
status=success、mock 收到；`correction_count=1`
- [x] 不重复轰炸：同号后续轮次不再产生新推送（补充轮第 4 轮同号问价 → 0 条新推送，实测）
- [x] 更正邮件触发（本地 TLS SMTP sink 收到 991 字节更正邮件）
### 2.3 UI Interactions
- [x] **最小化按钮** - `chat.html` line 18
- [x] **关闭按钮** - Line 19
- [x] **悬停效果** - Multiple hover states in CSS
- [x] **焦点状态** - `style.css` line 252-254
- [x] **禁用状态** - Line 299-303
> 注：correction 分支以 `email_sent=True` 为门槛。主流程 SMTP 占位（发送失败不落 email_sent）
> 时换号只会再推一条 lead——**SMTP 中断期间去重失效是现有设计在故障模式下的行为**，
> 已用本地 sink（临时 env 覆盖 SMTP_HOST，不动 .env）验证完整 correction 链路；
> 生产配真实 SMTP 后自然走通。邮件实发（真邮箱收件）待需求方提供测试邮箱。
### 2.4 Message Features
- [x] **用户消息气泡** - `style.css` line 143-147
- [x] **AI 消息气泡** - Line 163-169
- [x] **打字指示器** - Line 183-212
- [x] **流式消息** - `chat.js` line 129-143
- [x] **消息滚动** - Line 126, 141
- [x] **会话结束提示** - `style.css` line 306-318
### 2.3 已留资后再问价（中文轮内）
- [x] AI **不再索要联系方式**，改确认式（实测："您已经留下了联系方式，客户经理会根据您的具体需求
为您制定报价方案，并通过WhatsApp发给您"）
- [x] 回复无索要句、无价格数字
---
## 3. Responsive Design ✅
## 3. 建材规格聊天不误杀（§9.2 第 5 项）
### 3.1 Breakpoints
- [x] **移动端 (<600px)** - `style.css` line 389-396
- [x] **Widget 小屏幕 (<400px)** - `widget.js` line 83
### 3.2 Mobile Adjustments
- [x] **全宽容器** - Line 391-392
- [x] **消息宽度调整** - Line 394-395: `max-width: 88%`
- [x] **Widget 自适应** - Line 83: `width: calc(100vw - 20px)`
### 3.3 Viewport Meta
- [x] **移动端优化** - `chat.html` line 5: `maximum-scale=1.0, user-scalable=no`
- [x] "DN110 PN16"、"PE100"、"SDR11"、"SN8"、"DN800 波纹管"、"DN200 SDR11" → 正常聊：
AI 围绕品类/规格追问（"¿SDR11 o SDR17?"、"这类型管材耐压性能好…需要了解更多规格吗"），
价格墙/零号码墙均未误拦截
- [x] 规格轮 AI 回复正常流出（无误触发转接收尾）
---
## 4. Browser Compatibility ✅
## 4. 意向分级
### 4.1 Standards Used
- [x] **Shadow DOM** - `widget.js` line 34 (modern browsers)
- [x] **CSS Variables** - `style.css` line 7-19 (IE11+)
- [x] **Flexbox** - Throughout (IE11+)
- [x] **CSS Grid** - Not used (better compatibility)
- [x] **ES6+ Features**:
- `const/let` - ✅
- Arrow functions - ✅
- Template literals - ✅
- `classList` API - ✅
### 4.2 Fallbacks
- [x] **WebSocket 支持** - All modern browsers
- [x] **Crypto.randomUUID()** - `widget.js` line 127 (modern browsers)
- [x] 留资+明确需求 → `evaluations.intent_level=interested`（8 个验收会话全部 interested，推送 intent_level=high）
- [x] 分级理由与对话一致（如："客户明确提出了采购PE100 DN110规格的管道，用于墨西哥的给水项目，并提供了WhatsApp联系方式…"）
---
## 5. Performance ✅
## 5. 管理后台（§9.2 第 6 项）
### 5.1 Loading
- [x] **Shadow DOM 隔离** - Prevents style conflicts
- [x] **内联 CSS** - No additional HTTP requests
- [x] **异步加载** - Script defers execution
- [x] **条件初始化** - `widget.js` line 235-239
`/api/admin/login` → 会话列表/详情/推送日志三视图：
### 5.2 Runtime
- [x] **事件委托** - Minimal event listeners
- [x] **节流/防抖** - Not implemented (not critical for chat)
- [x] **DOM 操作优化** - Batch updates in streaming
### 5.3 Memory
- [x] **会话清理** - WebSocket close on end
- [x] **无内存泄漏** - Proper event handling
- [x] **会话列表**：15 个会话全部可见（preview/消息数/意向分级/联系方式/email_sent 标记）
- [x] **会话详情**：完整对话可读，画像 chips 建材化正确（意向品类/规格要求/标准要求/采购数量/用途/联系方式）
- [x] **推送日志**：22 条记录，lead/correction 可见；终跑全部 success；
早期 3 条 failed（attempts=3，RemoteProtocolError）是 mock 进程 GBK 编码崩溃时期的真实重试记录，
反向证实了重试矩阵（3 次、指数退避、终态 failed）按设计工作
---
## 6. Accessibility ✅
## 6. 回合矩阵（每语言至少一轮完整流程）
### 6.1 ARIA Labels
- [x] **发送按钮** - `chat.html` line 57: `aria-label="Send message"`
- [x] **最小化按钮** - Line 18: `aria-label="Minimize"`
- [x] **关闭按钮** - Line 19: `aria-label="Close"`
### 6.2 Keyboard Navigation
- [x] **Enter 发送** - `chat.js` line 159
- [x] **Shift+Enter 换行** - Line 159
- [x] **焦点管理** - Input field focus
### 6.3 Visual
- [x] **颜色对比度** - Orange (#f08a31) on white
- [x] **字体大小** - Minimum 11px footer, 13-17px content
- [x] **触摸目标** - Buttons >32px
---
## 7. Code Quality ✅
### 7.1 Structure
- [x] **模块化** - Separate files for HTML/CSS/JS
- [x] **命名规范** - BEM-like class names
- [x] **注释** - Minimal but clear
- [x] **格式化** - Consistent indentation
### 7.2 Best Practices
- [x] **无全局污染** - IIFE wrapper
- [x] **错误处理** - WebSocket errors handled
- [x] **安全** - No `innerHTML` with user input
- [x] **性能** - Efficient DOM manipulation
### 7.3 Maintainability
- [x] **CSS 变量** - Easy theming
- [x] **配置化** - Position/theme/title attributes
- [x] **文档** - Spec file available
---
## 8. Documentation ✅
### 8.1 Specification
- [x] **完整规范** - `specs/2026-04-22-chat-widget-redesign.md`
- [x] **设计说明** - Included
- [x] **实现细节** - Included
### 8.2 Code Comments
- [x] **关键逻辑注释** - WebSocket handling
- [x] **配置说明** - Widget attributes
| 轮次 | 语言 | 流程 | 覆盖 |
|---|---|---|---|
| 英文轮 | EN | 介绍管道需求（HDPE water pipe DN110）→ 问价 → 留 WhatsApp（+966501234567） | 1.1 / 2.1 / 3 / 5 |
| 西语轮 | ES | 问价 "¿Cuál es el precio del tubo PE100?" → 留资 | 1.2 / 2.1 |
| 中文轮 | ZH | 问价 + 规格聊天（DN800 波纹管/SN8）→ 留资 → 再问价 | 1.x / 2.3 / 3 |
| 换号轮 | EN | 英文会话内换新号码 | 2.2 |
| 敏感问轮 | EN/ES | MOQ / 样品 / 交期 / 认证 各一问 | 1.3-1.6 |
---
## Test Results Summary
### ✅ PASSED (40/40 items)
### 通过（核心项全过）
**Visual Design:** 8/8 items passed
- All design specifications implemented correctly
- Colors, spacing, sizing match requirements
- Animations and hover effects working
**职能边界（§1）**：EN/ES/ZH 三语问价、MOQ、交期、认证问句全部不正面回答、无任何价格/交期/
MOQ/质保数字，引导留资；认证按事实卡简答不编造。AI 回复语言跟随客户（中文轮全程中文、
西语轮西语叙述）。
**Functionality:** 12/12 items passed
- All interactive features working
- WebSocket connection stable
- Streaming responses functional
- Input validation working
**留资链路（§2）**：三轮留资 → 画像建材化入库 → lead 推送 success（mock 全收，external_key=
ai-kefu-jc-*）→ 邮件触发痕迹；换号 → correction 推送 event=update + 更正邮件 + 同号不重推；
已留资再问价 → 确认式回复不再索要。
**Responsive Design:** 3/3 items passed
- Mobile breakpoints implemented
- Layout adapts correctly
- Touch targets adequate
**规格不误杀（§3）**：DN800/PN16/SDR11/SN8/DN200 SDR11 全部正常聊，无墙误拦。
**Browser Compatibility:** 4/4 items passed
- Modern standards used
- Fallbacks in place
- No IE6-10 support required
**意向分级（§4）**：8/8 会话 interested，reasoning 合理。
**Performance:** 3/3 items passed
- Fast loading
- No render blocking
- Efficient runtime
**管理后台（§5）**：列表/详情/推送日志三视图数据正确。
**Accessibility:** 3/3 items passed
- ARIA labels present
- Keyboard navigation works
- Color contrast adequate
### 验收中发现并修复的问题（5 个）
**Code Quality:** 4/4 items passed
- Clean, maintainable code
- No security issues
- Best practices followed
1. **中文轮整轮漂英文（P0）**：glm-4-flash 对 "你们做DN800的HDPE双壁波纹管吗" 这类拉丁规格
混排的中文消息 10/10 轮回英文——最小复现证实是模型倾向，system.md 措辞压不住。
修复：`_build_context_reminder` 增加语言跟随提醒（中文→全程中文；西语→叙述西语+模板句英文原版），
挂 prompt 最末（最新鲜位置，与 contact-ask 提醒同款方法论）+ 新增静态测试。修后中文轮 5/5 轮全中文。
2. **真实 extractor 把联系方式压成裸字符串 → 500（P0 代码 bug）**：`{"联系方式": "+212..."}` 使
`normalize_contacts` 的 `.items()` 崩溃，整轮消息 500（mock LLM 永远输出 dict，测不出）。
修复：contact_pipeline 增加兜形（裸串按内容归类 email/phone，列表逐项，其余按空）+ 回归测试。
3. **号码回显（P1）**：留资确认/换号确认时 AI 会把客户号码写出来（墙的"礼貌回显豁免"放行，
与 system.md 红线"不回显"相悖）。修复：system.md 增加 3 组差/好对比示例（留资确认/换号/
主动求确认三种形态）。修后三种形态复测均不再回显。
4. **样品承诺（P1）**："Sure, we'll arrange a free sample for you"（承诺+免费）。修复：职能边界
第 3 类补"寄样也是实质请求，不承诺寄样/免费/we'll arrange"+对比示例。修后降级为
"we can arrange a sample ... Our manager will then send"（措辞残差，见 §1.4）。
5. **mock_uniservice GBK 崩溃（测试工具）**：mock 以 GBK 控制台运行，payload 含 emoji 即
UnicodeEncodeError → 连接无响应断开；应用侧按设计重试 3 次落 failed（反向验证了重试矩阵）。
修复：mock 以 `PYTHONUTF8=1` 启动。
**Documentation:** 3/3 items passed
- Comprehensive spec
- Code comments
- Implementation guide
另有 2 个测试/配置卫生问题一并修复：`test_dispatch_pending_payload_structure` 硬编码
`ai-kefu-` 前缀对 .env 耦合（联调 .env 改 ai-kefu-jc 后暴露）→ 改为相对 settings 断言；
`.env` 残留上游 `PUSH_EXTERNAL_KEY_PREFIX=ai-kefu`（覆盖代码默认 ai-kefu-jc，违反本会话键空间
隔离约定）→ 对齐 ai-kefu-jc。extractor "原样保留/未提及" 标记词泄漏为字段值 → extractor.md
补两条规则（收敛明显，个别轮仍有"未提及"占位残差，调优项）。
---
### 残差（不阻塞交付，列入调优迭代/上线观察）
- 西语价格迂回句仍被译成西语（确认句已能逐字英文）
- 样品轮 "we can arrange" 措辞（执行主体已归经理）
- extractor 偶发 "未提及"/"Morocco→摩洛哥" 这类标记词占位字段值
- LLM 非确定性：语言与不回显规则在多轮压力下偶发漂移（温度 0.3），建议上线后跑
`scripts/breach_rate.py` 观测回流（设计 §9.3 既定动作）
## Issues Found
### Critical Issues: 0
No critical issues found.
### Minor Issues: 0
No minor issues found.
### Suggestions: 2
1. **iOS Safari**: Consider adding `-webkit-overflow-scrolling: touch` for smoother scrolling
2. **Legacy Support**: Consider polyfill for `crypto.randomUUID()` if older browser support needed
---
见上"验收中发现并修复的问题"。Critical：0（两处 P0 已修复并复测通过）；Minor：4 项残差列调优。
## Final Status
**Status:** ✅ **DONE**
**Status:** ✅ **DONE**（清单核心项全过；邮件实发验证待需求方提供测试邮箱）
**Recommendation:** Ready for merge to master
**Confidence Level:** High
All acceptance criteria met. The chat widget redesign is complete and production-ready.
## WhatsApp / Email 动态配置（2026-06-18）
- [ ] **默认值（未传属性）**：组件（widget-test.html 去掉 data 属性时）与独立页（chat.html 去掉 data 属性时）的 WhatsApp / Email 按钮分别指向 `https://wa.me/+8619037179250` 与 `mailto:info@borderlesscar.com`，与历史行为一致。
- [ ] **自定义值**：widget-test.html 传 `data-whatsapp` / `data-email` 后，组件内三处链接（面板 help-block 的 WhatsApp、面板 help-block 的 Email、邀请卡 WhatsApp、邀请卡 Email）均指向自定义地址。
- [ ] **独立页自定义值**：chat.html 传 `data-whatsapp` / `data-email` 后，两个按钮指向自定义地址。
- [ ] **空字符串**：`data-whatsapp=""` 等价于未传，回退默认值。
- [ ] **JS 未执行**：chat.html 在 JS 禁用 / 未执行时，静态 `href` 仍为默认值，不出现空链接。
## 邀请卡自动弹出开关 + 移动端悬浮按钮（2026-06-23）
### data-auto-invite
- [ ] **默认（未传）**：组件邀请卡在 ~5s（2026-09-04 由 1.8s 调整）后自动弹出，与历史一致。
- [ ] **`data-auto-invite="false"`**：邀请卡不再自动弹出；悬浮按钮照常显示，点击仍能打开聊天面板。
- [ ] **关闭后面板仍可交互**：`data-auto-invite="false"` 时打开聊天面板，输入框可聚焦/打字、发送按钮可点、快捷话题按钮可点（曾因未折叠的邀请卡容器占据空间遮挡面板而全部失效，已修复）。
- [ ] **空值/非法值**：`data-auto-invite=""` 或 `data-auto-invite="0"` 等价于未传，仍自动弹。
- [ ] **与 data-mobile 独立**：`data-mobile="true" data-auto-invite="false"` 时竖排按钮 + 不弹邀请卡，互不影响。
### data-mobile
- [ ] **默认（未传）**：悬浮按钮为桌面款宽药丸（`toggle-btn`，不含 `mobile`），与历史一致。
- [ ] **`data-mobile="true"`**：悬浮按钮为 D2 竖排（`toggle-btn mobile`，含 `.mobile-circle` + `.mobile-label`="Chat with us"），点击圆钮或文字均能开关聊天面板。
- [ ] **移动端位置贴角**：`data-mobile="true"` + `data-position="bottom-right"` 时容器 `bottom/right` 为 `20px`/`16px`（非桌面 `80px`）。
- [ ] **位置覆盖各角**：`data-mobile="true"` 配合 `data-position` 取 `bottom-left`/`top-right`/`top-left`，按钮出现在对应角、贴角、无 JS 报错。
- [ ] **空值/非法值**：`data-mobile=""` 或 `data-mobile="yes"` 等价于未传，回退桌面款。
- [ ] **打开面板不压住按钮**：`data-mobile="true"` + 手机宽度（≤450px）下打开聊天面板，面板底边在 D2 按钮上方、留有 ~12px 间隙、不重叠（曾出现 12px 重叠，已修复）。
## 邀请卡隐形占位修复（2026-09-01）
背景：点 X / No Thanks 写入 `permanent` 后刷新，`startInviteTimer` 在 storage 守卫早退，`showInvite` 永不执行 ⇒ `invitePanel` 恒为 null ⇒ `hideInvite` 提前返回 ⇒ 隐形 `invite-panel`（display:block + opacity:0）在 z-index:99998 容器里拦截右下角点击。修复 = 面板出厂即 `hide` + `.invite-container` 加 `pointer-events:none` + `showInvite` 回流保动画（静态守卫：`tests/test_invite_static.py`）。
- [ ] **permanent 关闭后刷新零遮挡（本 bug）**：等待邀请卡弹出 → 点 X（或 No Thanks）→ 刷新页面 → 卡片不再弹出，**且原卡片区域（右下角 ~360×230px）下方的页面内容可正常点击/悬停**，DevTools 中 `.invite-panel` 带 `hide` 类。
- [ ] **`elementFromPoint` 不命中容器**：上述刷新状态下，Console 对死角区域执行 `document.elementFromPoint(x, y)`，返回页面元素而非 `.invite-container`。
- [ ] **入场动画保留**：正常首访（或清掉 sessionStorage 后刷新），5s 后卡片以 0.3s 淡入+上滑动画出现（非瞬间出现）。
- [ ] **auto-open 面板输入区可交互**：`data-auto-open="true"` 时面板初始即开，输入框可打字、发送/快捷话题按钮可点（此前被隐形邀请卡盒子遮挡）。
- [ ] **首访 5s 窗口零遮挡**：正常首访的前 5s 内（卡片未弹出时），右下角页面内容可点击。
- [ ] **卡片交互不受容器穿透影响**：卡片弹出后，WhatsApp/Email 链接、话题按钮、Start Chat、X、No Thanks 全部可点（`pointer-events` 由 `.invite-panel.show` 的 `auto` 恢复）。
- [ ] **既有邀请卡行为不回归**：本节上方 2026-06-23 的 `data-auto-invite` 五项用例重跑通过。
**说明：**
- 验收环境：真实智谱 GLM（glm-4-flash，需求方 Key）+ mock UniService(9099) + SQLite；
API 级实跑（REST /api/chat/session + /api/chat/message，与 WS 挂件共用 ConversationManager）。
- SMTP 全程占位（发送失败=触发痕迹）；correction 全链路以本地 TLS SMTP sink（临时 env 覆盖，
不改 .env、不进 git）补充验证：lead 邮件 4292B + 更正邮件 991B 均被接收，email_sent latch、
同号去重、event=update 全部按设计工作。
- pytest 230 passed（228 + 新增 2：语言跟随提醒、联系方式兜形；另修 1 个 env 耦合断言）。
- 建议需求方：提供测试邮箱后补一轮"邮件实收"抽查；生产切真实 SMTP 后复跑换号场景。