跳转至

ISSUE-0116 · 手机列表格式不统一

症状(Tony 截图)

手机列表(去重)里同一批 NANP 号码三种写法混排:

1-800-815-3378        ← 11 位带 1、无 +
907-842-5201          ← 10 位裸号
+1 907-968-2248       ← 国际格式
+1 907-698-2208 (地图)

Tony 问「国家代码 不完善吗 / 格式不清洗吗」。

根因:不是识别缺陷,是阶段 1/2 没接线

inferPhoneCountry 的三级降级(① 号码自带 + → ② 同行 countryCode → ③ 同行地图号反哺 → ④ 不猜)早就实现好了,normalizeCountryCode 的映射层容错、 29 条测试也都在。但 SPEC-012 阶段 0 明确「只打诊断日志、不改行为、不落库」。

展示口 splitAndDedupePhones 只用行内 detectPrimaryCC(singles): 某商家行内只有一个裸号、没有任何 + 号 ⇒ primaryCC=null ⇒ 不做 NANP 归一 ⇒ 与 +1 907-… 各占一行、写法还不统一。

而 countryCode 是 Google Maps 地址解析出来的权威值(parse-data.ts:60/141), 库里一直有,只是没人读。

修法

阶段 1:splitAndDedupePhones 的 primaryCC 加兜底 —— detectPrimaryCC(singles) ?? ccFromRowCountry(r.countryCode)。 ccFromRowCountry 走 normalizeCountryCode(大小写/iso3/英文全名容错)+ 新增的 dialPrefixForIso2(PREFIX_TO_ISO2 反向索引),并过一遍 COMPOSITE_CC_FOLD —— dialPrefixForIso2('AX') 给的是 35818,而带 + 的 奥兰号在 canonKeyForDedupe 里被折成 358|18…,不折就对不上、同号两条。

阶段 2:新建 src/utils/phone-format.ts,引 libphonenumber-js/max(SPEC-012 已选型) 做 E.164 + 可读国际格式。展示层规范化,不改写库 —— 存量数据自动受益、随时可回退(摘掉调用点即可),原始串在 rawPhone 里永远保留。

CSV 导出加 E.164 列:展示列给人读、E.164 给拨号器/CRM 用,不让用户自己转。

🔴 自测抓到的头号风险:规范化会消灭噪音的可识别性

SPEC-012 第 55-70 行早就警告过「经纬度对去掉标点凑成合法号码、被洗白成 E.164」。 本刀在真实语料上实测复现了:

raw "0 4.1566.84285"  → 规范化后 "+49 4156 684285"
raw "0 2.7793.34348"  → 规范化后 "+49 2779 334348"

这俩是经纬度残片。原样显示时用户一眼看出是垃圾(小数点、形态怪异), 洗成漂亮的德国号之后看起来就是个正常号,用户会当真号拨出去。 噪音数量没变,但可识别性被规范化消灭了 —— 这是本刀新引入的伤害。

守卫:形态可疑的串不规范化(保持原样继续暴露),不丢条、不隐藏。

⚠️ 这与 SPEC-012「不用 libphonenumber 做是不是电话的判断」不冲突: 它不参与丢不丢的决策,只决定要不要美化。

🔴 订正:初版的自证方法是错的,覆盖面被我高估了

本文初稿写「判据边界实测 14/14」「真实语料 86 条…洗白残留 0」。 那两个数字都是在我自己挑的样本上得出的,而仓库里早就有专门为这个问题建的基准集 (tests/fixtures-coord-noise.json,Tony 2026-08-31 真实采集数据的两张截图)。

sonnet5 复核用那个基准集一跑就现形。随后我用全基准集实测,逐条发现:

版本 误伤真号 拦住噪音
初版 /\d\.\d{4,}/ 4/20(212.555.0100、415.555.0132、1.800.555.0199、800.555.0175 四条美式点分隔真号) 24/76
初版 + 带 + 豁免 仍误伤上述 4 条 24/76
当前 (?:^|\D)\d{1,2}\.\d{4,} + 带 + 豁免 0/20 24/76

判据形态:首段 1-2 位 + 紧跟 4 位以上小数。经纬度的整数部分只有 1-2 位 (4.1566 / 1.5681),而美式点分隔号首段是 3 位区号(415.555.0132)、 带前置 1 的免费号第二段是 3 位(1.800.555.0199)。 带 + 的串一律豁免 —— 国家码来自号码自身(第一级 plus-prefix),可信度最高, 不该被形态启发式推翻(+351.91.234.5678、+44.20.7946.0958 点后都是 4 位)。

拦不住的 52 条:字符串层无解,不假装能治

_known_miss_reason 原文已经论证过三次:

三路对抗实测证明:继续在字符串层加规则会误杀真号码 —— 西班牙全国号码是 3-3-3 分组(+34.912.345.678),与德式千分位(5.944.689.955)形状完全相同… ⇒ 这批维持放行(宁可漏判不可误删)。🔴 仍是开放集合。

⇒ 本刀不再往字符串层加规则。缓解手段改成 不隐藏证据: rawPhone 进 CSV 导出列(见下),用户能自己核对 「这个 +49 7164 909791 的原始形态是 0 71 6490 97 91」从而看穿它。 测试里有一条断言如实锁住「空格分隔整数残片仍会被规范化」—— 哪天有人加了新判据让它变绿,会红,提醒去核实有没有误杀真号。

⚠️ 顺带订正复核报告里的一处:它把 07157 56840 算进「被洗白的 9 条」, 但那条是 MUST_KEEP_real_phones 里 +49 7157 56840 的国内写法 —— 它是真号, 规范化它是正确行为。照它建议「让 KNOWN_MISS 全部不规范化」会误伤这一条。

🔴 治标不治本:这些残片本就不该被抓成电话(上游 isLikelyCoordinateNoise 的既有缺口,ISSUE-0080 recurring)。本刀只保证「规范化不让它更难认」+「不藏证据」。

其它设计约束

  • 猜不出国家就不格式化,原样返回。宁可显示不统一,不显示一个错国家码的号 —— 用户拿去拨号/群发,错的国家码比不统一有害得多。
  • 库判不合法时保留原样,不丢条、不隐藏(噪音过滤在上游,不在这里)。
  • (地图) 标记跟着展示值走,不进 E.164。
  • phone-format 不 import phone-merge —— 那会造成 phone-merge → phone-format → phone-merge 循环依赖,剥标记自带一份副本 (两处判据必须同步改)。

效果

修前 修后
截图三种写法 三行、格式各异 一行 +1 907 968 2248,e164=+19079682248
真实语料 86 条 全部原样 规范化 68 条(79%),带点形态洗白 0,条数不丢 ——⚠️ 这个 0 只覆盖带点形态,空格分隔的整数残片仍会被规范化(上述)
包体积 4.6 MB 4.79 MB(+4.1%,与 SPEC-012 选型预估同量级)

证据

全量 806 全绿;变异自测 7 路(阶段 1+2)+ 3 路(洗白守卫)咬住。

⚠️ 一条如实记录的例外:dialPrefixForIso2 里「取最短前缀」那行是防御性死代码 —— 实测 250 条国家数据里多前缀国家数 = 0,把 < 改成 > 变异自测全绿咬不住。 测试里改成锁数据集事实(哪天出现多前缀国家会红,提醒复核那行), 而不是假装那行被覆盖了。

第二轮复核(sonnet5 快审 · NO-GO,两条 P0)

C 面(critical,已修):NANP 走通用剥 trunk-0 = 结构性丢号

if (primaryCC && !EXC_CC_NO_TRUNK.has(primaryCC) && digits.startsWith('0')) {
  return `${primaryCC}|${digits.slice(1)}`;   // ← 无位数校验
}

v0.10.142 起 primaryCC 可能来自商家 countryCode('US' → '1'), 而 NANP 域内号没有 trunk-0 惯例。于是任何「11 位、0 开头」的域外号 (UK 及多数欧洲国家的国内写法)剥掉前导 0 后结构上必然产出合法的 10 位 NANP key —— 不是小概率碰撞,是命名空间被结构性共享。实证(跨国集团注册地 = US):

UK  020 7946 0958   → 1|2079460958
US  +1 207-946-0958 → 1|2079460958    ⇒ 撞 key,UK 真号被静默吞掉

受害号在 UI 与 CSV 里都不再出现且无任何提示。 修法:primaryCC !== '1' —— 下面本来就有按 10/11 位精确匹配的专门 NANP 分支。 截图场景与德国 trunk-0 零回归(有断言锁)。

B 面(high,记档不修):借来的国家码可能凭空造出一个号

德国商家页面挂美国免费电话 800-555-0199、countryCode='DE' ⇒ 展示成 +49 800 5550199(一个编造的德国号),normalized: true。 与 A 面同根(权威值 ≠ 号码归属地),但触发形状不同。 无完整解;缓解同样靠 rawPhone 进导出 —— 用户能看到原始的 800-555-0199。

D 面(medium,已部分采纳)

  • ✅ rawPhone 进 CSV 导出列 —— 兑现「原始串并存」承诺,同时是 A/B 面的缓解手段
  • ❌ 未采纳「复制改取 E.164」:复制是最高频动作,改变它的输出形态会打断用户已有习惯, 属于产品决策,留给 Tony 拍板。CSV 里 电话 / E.164 / 原始写法 三列并存已够用。

E/F 面:核实无缺陷

复核确认无循环依赖(phone-country 零反向引用)、两份 stripSourceLabel 逐字符等价、 libphonenumber 没被打进 background.js(SW 字节数与引库前完全一致 454993 B)、 畸形输入全部安全回退不抛异常、formatInternational() 只用空格分隔不会让 splitPhones 误拆。

证据边界

  • 语料复验用的 countryCode 是统一假定为 DE 灌进去的(语料是 HTML 快照, 不带真实商家 countryCode)⇒ 79% 规范化率是该假定下的数字, 真实数据里 countryCode 的填充率与准确率未实测。
  • 未在真实 Chrome 扩展里端到端跑过采集 → 展示 → 导出全链路。