xinyouhe/ai-kefu-jc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9d2e2b224dad5a7de255b7d3fc24de1485f22481
ai-kefu-jc/docs/superpowers/specs/2026-10-08-cc-ip-country-confirm-design.md
T

7.8 KiB
Raw Blame History

设计：号码区号补全（IP 推测 + 回显确认）— 终版 v2

  • 日期：2026-10-08（v2 融合版：两轮独立审查 + 上游同日设计对照吸收 + 需求方三处优化）
  • 前置：2026-10-08-dual-contact-and-country-code-design.md 及墙层增补——本设计 替换其中"请客户重发完整号"路径
  • 对照：上游汽车项目同日设计 D:\refactor\ai-kefu\docs\superpowers\specs\ 2026-10-08-whatsapp-cc-completion-design.md（吸收其 6 点，见 §8）

1. 目标

客户号码缺国家区号时：按 IP 推测 → 补全为 E.164 → 回显给客户确认（顺带 暴露抄错的数字）→ 首封线索邮件即带补全号（零延迟、可拨、标注透明）。杜绝 发出拨不通的本地格式号码，同时不阻塞线索交付。

2. 架构（确定性优先，LLM 只做它擅长的）

职责 归属 理由
判定（有无码/建议国）、E.164 补全、状态机、邮件渲染 Python 确定性（新模块 cc_completion + phonenumberslite） 状态不可能被幻觉；可离线确定性测试；邮件触发不押在 LLM
客户答语理解（肯定/否定/国名） extractor LLM（schema 加 cc_reply 可选字段，单轮无状态分类） "yeah that's right"/"naur"/"我在迪拜"正则极脆弱，恰是 LLM 强项；extractor 本每轮跑，零额外调用
话术生成与确认句必出 提醒注入 + 既有墙骨架（白名单放行/缓冲替换——四轮生产实测过的机制） GLM 对反惯性指令 0/8 服从的血泪教训，确认回显必须墙保

3. 判定树（cc_completion.classify(number, ip_iso)）

号码
 ├─ 以 +/00 开头 ──────────────────► HAS_CC（现有流程直走，不动）
 ├─ 以 IP 国码开头且去码后剩余合法 ──► HAS_CC_NAKED → 静默规范化（无对话动作）
 ├─ phonenumbers region=IP国 解析合法 ─► NEED_CC，建议=IP 国（高置信）
 └─ 均不匹配（VPN/罕见格式）─────────► NEED_CC，建议=naive（去前导0+IP码，回显靠客户纠错）
 IP 无效/未知 → NEED_CC 无建议国 → 问"方便发带区号完整号吗"（1 轮为限）

4. 状态机（每 canon 组独立，存 raw_info["_cc"] 结构化 dict）

raw_info["_cc"] = {
  "whatsapp": {"e164": "+254712345678", "intl": "+254 712 345 678",
               "confirmed": false, "attempts": 0,
               "source": "ip_proposed",   # ip_proposed|naive|ip_confirm|
                                          # prefix_normalized|customer_stated|no_ip|fallback
               "canon": "0712345678"}}
  • canon 组：phone 与 whatsapp 同号（canon 相同）共享一个确认流，确认一次； 不同号各自独立状态——换号（canon 变化）即重置该组状态机重走判定树 （结构性解决"改号残留"：旧补全永不跟随新号）
  • attempts 只被 canon 变化重置；国名重述不重置（防"无限换国名"）
  • 回显确认轮（NEED_CC 且有建议国）：AI 注入逐字句 "…reach you at {intl} — is that right?"（中英双语）；墙白名单放行该精确号码 （no_contact_value(allow_number=...)，逐匹配段 digits_only 比对，只放 系统注入的那一个号）；确认句墙（缓冲机制）保证必出
  • 答语（下一轮 extractor 的 cc_reply）：
    • affirm=true → confirmed=true, source=ip_confirm → 落定
    • affirm=false, country=X → NAME_TO_REGION[X]（中英映射表）转 ISO 重算 e164 → 再回显（attempts+1）
    • affirm=false 无 country → 请重发完整号（新号到达=canon 变化自然重置）
    • 无回应/不可解析 → attempts 随轮递增，每渠道上限 2 轮 → 落定 confirmed=false（保持现有 e164 建议，不无限纠缠）
  • 内部状态卫生（三通道封堵，上游对照吸收）：
    1. extractor 入口 $existing_info 过滤 _ 前缀键（我们已有，复核）
    2. extractor 出口：消费 cc_reply 后即剥离（瞬态分类非事实，不残留）
    3. extractor 出口：防御性丢弃任何回传的 _ 前缀键（防 LLM 回显 _cc 覆盖 Python 管理的状态机——上游发现的洞）
  • 存量迁移：升级部署时存量 _cc_asked=True 且号码裸的会话 → 映射为 _cc{confirmed:false, source:fallback}（已问过，不再追问，直通邮箱轻补）

5. 邮件/推送时序（需求方定案：首封即发补全号）

时点 发什么 标注
首封（裸号 confirmed 当轮，零延迟） 判定树同步算出的 e164 补全号（ip_proposed/naive/prefix_normalized） confirmed=false 时尾注 "（区号按 IP 推测，未经客户确认）"；no_ip 时裸号 + "（缺国家区号）"
客户确认（号码未变） 不补发（首封已可拨；后续渲染自动去标注） 状态升级透明
客户纠正/换号 现有改号更正通道（canon 变化自然触发） 现有机制零新逻辑
  • 渲染点：email_service（正文联系方式行 + 更正/回头客路径，签名加参取 _cc）； lead_push 的 contact 给干净 e164（契约要求"带国际区号且有效"），标注走 profile 派生（出站时由 _cc 计算，不落正常键——零 LLM 泄漏面）
  • profile_out 先消费 _cc 生成补全 → 再过滤 _ 键（顺序钉死）
  • 面板同步：cc-pending 期间 ev.contact_info 带未确认标注（防"邮件带 补全、后台显裸号"的分裂）
  • 邮箱轻补串行：号码确认流落定（confirmed 或 attempts 耗尽）后才注入

6. IP 入口与基础修复

  • /session 路由注入 Request，XFF 第一段合并进 conv.client_info（WS 路由 已有同款；chat_rest.py:107 只喂限流修不到数据流）
  • ip_service 新增 resolve_region_code(ip) -> ISO（iptocc 直透）； 修既有 bug："AU": "加拿大" 重复键（应为 CA）

7. 依赖与测试

  • requirements.txt + phonenumberslite（~3MB、零传递依赖、离线、Apache 2.0）
  • 测试（离线确定性 + 集成）：
    1. 判定树矩阵（号码形态 × IP 国，含静默规范化分支）
    2. 状态机全转移（确认/否定/国名/换号重置/2 轮无回应/国名重述不重置/ 同 canon 组共享）
    3. 三通道卫生（入口过滤/出口剥离 cc_reply/丢弃 _ 回显）
    4. 邮件时序（首封带补全+标注、确认后不补发、改号走更正、no_ip 兜底）
    5. 墙（白名单精确放行：同号放/异号拦；确认句缓冲替换）
    6. 存量迁移；推送 contact 纯 e164；NAME_TO_REGION 映射
    7. 真实 LLM 验收（cc_reply 分类质量、回显确认全流程、误判对照）
  • 既有测试迁移：D1 断言"confirmed 即发"若 fixture 用本地格式号 → 更新为 "confirmed 且判定树已同步跑"（行为等价，渲染值变化）

8. 与上游设计的对照结论

吸收：判定树静默规范化分支、_cc 结构化+canon 重置、extractor 答语分类、 出口卫生三封堵、同 canon 组共享、面板同步闸。 不采纳：上游"待确认暂缓发信"（违背零阻塞——以首封补全号+标注替代，兼得 及时性与可拨性）；上游墙豁免参数（我们已有四轮实测的墙骨架+白名单）。

9. 风险

风险 等级 缓解
IP 误判（VPN）致首封补全号错 中 标注"未经客户确认"透明 + 客户否定走重算/改号更正双通道
naive 补全结构错 低 回显确认天然暴露；confirmed=false 标注兜底
cc_reply 分类错误 低 最坏=多问一轮或保持未确认标注；attempts 上限防纠缠
NAME_TO_REGION 覆盖不足 低 映射失败=未捕获，attempts 递增走兜底
墙白名单滥用扩大 低 逐段精确比对 + 评审断言锁死
Reference in New Issue View Git Blame Copy Permalink