Shaobo Pocket Carrier

🎉 Release v3.7.1 - 联通滑块与移动教程默认新标签页打开、修复翻译异常及联通重认证风控流程

🌟 核心更新 (What's Changed)

1. 🚀 配置流全流程弹窗保护：联通滑块与移动教程强制新标签页（New Tab）打开

• 彻底告别页面被冲掉：此前在 Home Assistant 添加集成或重新认证弹窗中，点击“中国联通腾讯滑块验证”或“中国移动 12.5 抓包教程”链接时，因同源策略容易直接在当前页面跳转，导致配置弹窗丢失、输入内容被清空；
• 全局前端辅助脚本（carrier-helper.js）：
  • 通过 Home Assistant 原生 frontend.add_extra_js_url 全局注册辅助模块，不仅在仪表盘生效，在【设置 -> 设备与服务 -> 添加集成 / 重新认证】所有页面均能自动生效；
  • 穿透 Shadow DOM 在事件捕获最顶层拦截目标链接，强制以 window.open(..., "_blank", "noopener,noreferrer") 打开新标签页，当前配置向导稳如泰山。

2. 🛡️ 根治 Translation error: INVALID_TAG 异常

• 严格遵循 Home Assistant 官方 intl-messageformat（ICU MessageFormat）规范，移除翻译模板中可能触发 formatjs 解析器异常的 HTML 属性，全量使用标准 Markdown 链接语法，彻底杜绝语言包报错。

3. 🎯 联通腾讯滑块验证页面（HTML）体验升级与智能回退

• 智能回退与防丢兜底：
  • 若手机端部分极速浏览器或 Webview 拦截了新窗口弹出，页面顶部新增直观提示：🔙 若未在新标签页打开，点此返回 Home Assistant；
• 智能关闭 / 返回机制：
  • 拖动滑块通过并成功下发短信后，页面倒计时 2 秒执行智能回退：
    • 新标签页模式下直接安全关闭当前标签页（window.close()）；
    • 非新标签页模式下自动平滑后退（history.back()）返回 Home Assistant 配置弹窗输入短信验证码，并配有专属快捷返回按钮。

4. 🔧 修复中国联通会话过期重新认证（Reauth）异常

• 补齐了联通在 Home Assistant 官方触发 Reauth 流程时的风控预处理链路（trigger_risk 与 prepare_captcha），规范会话上下文，确保凭据过期时重新滑块短信验证 100% 成功。

Shaobo Pocket Carrier

🎉 Release v3.7.0 - 中国移动 12.5 App 原生多维凭据接入，打破 30 分钟硬限制，架构全量瘦身

🌟 核心更新 (What's Changed)

1. 📱 中国移动 12.5 App 原生凭据接入：彻底打破微信 H5 30 分钟硬限制

• 告别脆弱架构：彻底告别此前微信 H5 端 30 分钟强制超时的硬限制与高频短信风控；
• 原生 App 核心接口全量支持：深度接入中国移动 12.5 官方 App 客户端原生数据网关（包含 /biz-orange/DH/MyPage/getFamilyCube、原生话费、流量余额等权威数据通路）；
• 智能万能凭据解析：
  • 支持直接粘贴各大抓包工具（小黄鸟 HttpCanary、Reqable、StormSniffer、Stream 等）导出的 完整 cURL 命令 (bash)、原始 Request Headers 文本 或 Cookie 字符串；
  • 核心解析器毫秒级自动萃取有效会话要素（JSESSIONID、UID、ticketID、x-token 等），无需用户手工截取拼接，一键粘贴即可完成绑定。

2. 🔬 实测突破 3 小时+ 长期保活，实锤单设备互斥机制与保活指南

• 实测连续保活突破 190 分钟（3 小时 10 分钟+）：
  • 在保持手机端 App 关闭的对照测试下，每 10 分钟一次轮询连续 20 轮 100% 成功，彻底破除 30 分钟掉线魔咒；
• 单设备会话互斥策略验证：
  • 实测确认移动服务端采用严格的“单设备最新会话互斥策略”——若在手机端重新打开/唤醒中国移动 App，客户端会自动向服务器申请新票并注销旧 Session，从而导致 HA 凭据失效；
  • 长期保活指南：抓包完成后彻底划掉手机上的移动 App，或者使用备用机/安卓模拟器抓包供 HA 专用，即可保持长期稳定在线；
• 配置与教程全量红色高对比度警示：
  • HA 配置弹窗与内置图文教程页面全面增加醒目红色警示框，并在深色与浅色主题下均做高对比度优化，防顶号指南一目了然。

3. 🧹 架构大瘦身：彻底清理移动短信登录废弃实体与逻辑

• 删除冗余代码：全量清理 mobile_auth.py、mobile_login.py 等不再需要的短信登录模块；
• 实体列表大幅精简：移除移动的短信验证码文本实体、短信登录按钮与自动登录开关；
• 历史实体自动迁移注销：集成启动时自动执行 _async_cleanup_mobile_stale_entities，静默清理已废弃的历史短信实体，彻底消除实体管理器残留。

4. 🎴 前端卡片（v5.11.17）细节打磨与专属单页优化

• 移动专属单页视图：针对中国移动无详单流水特性，卡片全面隐藏“详单管理”、“刷新详单流水”等按钮与日期选择控件，界面极致清爽；
• 虚假实体渲染修复：重构详单按钮判断逻辑，仅在联通/电信存在有效详单实体时才渲染相关交互；
• 内置原生离线教程视图：集成内置 /api/shaobo_pocket_carrier/mobile_tutorial 图文抓包指引，多平台（Android/iOS）图文步骤开箱即查。

Shaobo Pocket Carrier

🎉 Release v3.6.1 - 可视化卡片编辑器重构优化，改名体验丝滑升级！

🌟 核心更新 (What's Changed)

1. 🎴 配套前端通讯卡片重构升级 (v5.11.16)

• 彻底解决可视化改名回弹 Bug：
  • 彻底重构了 PocketCarrierCardEditor 可视化配置编辑器的生命周期机制；
  • 过去在可视化界面修改卡片标题（name）或手机卡槽备注名称（tel_x_name）时，一旦按退格键删除文字，会瞬间被后台推送的 set hass 强行重绘覆盖弹回旧值；本次更新彻底解耦了后台状态推送与表单 DOM 渲染；
  • 引入输入焦点智能保护（activeElement 保护），打字和删除过程中绝对不覆盖正在编辑的控件，杜绝光标丢失、跳行与中文输入法候选框被打断。
• 移除硬编码名称强行回弹：
  • 移除卡槽备注名称清空时强制回填“我的”的硬编码逻辑，允许自由清空、留空与完全自定义命名。
• 即时响应输入：
  • 卡槽手机号码与备注名称由传统的失焦 change 事件升级为即时 input 事件，边输边生效，预览即时同步。

2. 📲 中国移动原生全套传感器开箱即用 (v3.6.0 功能延续与巩固)

• 纯 Python 逆向中国移动微信端 H5 接口，破解固定 AES-128-CBC 密钥体系；
• 免浏览器、免抓包、0 额外内存消耗，全平台通用；
• 独创 10 分钟滑动窗口自动延期保活并持久化存盘，HA 重启不掉线；
• 离线自动短信重登开关与防清零历史数据保护锁。

---

Full Changelog: v3.6.0...v3.6.1

Shaobo Pocket Carrier

🎉 Release v3.6.0 - 三大运营商大团圆！中国移动原生接入，纯 Python 逆向落地

🌟 核心更新 (What's Changed)

1. 📲 中国移动原生全套传感器开箱即用 (免浏览器 / 免抓包)

• 技术突破：深度逆向中国移动微信端 H5（wx.10086.cn）前端底层架构，- 免浏览器轻量运行：彻底抛弃 Playwright 与 Chromium 浏览器加载项，纯 Python requests 原生毫秒级请求，0 额外内存消耗，全平台通用。
• 原生短信验证码登录：配置流与实体层直接支持输入手机号下发验证码、提交验证码完成绑定与登录。
• 全维度数据拉取：
  • 实时可用话费余额、当月实时消费（本月账单）、欠费状态与欠费金额；
  • 剩余通用流量、国内总览用量、细分定向流量包清单与使用进度；
  • 剩余通话分钟数、已用分钟数、套餐短信条数；
  • 官方真实脱敏机主姓名（如 丛*，非写死“已实名”）；
  • 主套餐全称、网龄天数换算（如 3年8个月）；
  • 移动星级评定、商城可用积分。

2. 🔄 独创滑动会话窗口持久化：无限续期永不掉线

• 移动官方单次会话有效期为 30 分钟，但支持滑动顺延。
• 掌上运营商默认按 10 分钟定时自动轮询，每次成功拉取自动接收服务端延期的新 shareToken，并即时持久化存盘到配置条目与磁盘存储。
• 彻底解决 Home Assistant 容器重启后读取旧 Cookie 导致掉线的问题，实现无人值守永久在线。

3. 🛡️ 离线自动短信重登与历史数据保活锁

• 自动短信登录：新增 switch.<phone>_auto_login 开关，长假停机或断网超 30 分钟恢复后，系统检测到掉线自动下发短信，配合自动化写入即刻静默重登；
• 防清零兜底锁：接口维护或凭证失效时牢牢锁定上一轮真实数据，严禁用全 0 伪数据覆盖。

4. 🎴 前端卡片优化

• 针对移动无详单的特性，卡片自动锁定为单页展示，禁用手势滑动并隐藏指示点。

---

Full Changelog: v3.5.3...v3.6.0

Shaobo Pocket Carrier

📱 掌上运营商 v3.5.3 发布公告

发布日期：2026-10-06 ｜ 版本：v3.5.3 ｜ 适配系统：Home Assistant 2024.1+

---

🛠️ 本次更新亮点

🐛 修复：联通 sensor.*_sms_remain 的「套餐短信总额」显示为 {} 条 模板占位符问题 (Fixes #9)

• 问题分析：在联通数据刷新流程中，短信余量接口原本将套餐短信总额存储在 sms_total 字段；但在随后的短信详单流水处理中，由于详单合计字典也命名为 sms_total，导致余量字段被覆盖为空字典 {}，在属性字符串格式化时被直接转义为 "{}" 条。
• 分离字段命名：将短信余量中的套餐总额规范命名为 sms_package_total，彻底与详单统计字典 sms_total 解耦隔离。
• 智能计算与容错兜底：
  • 若运营商接口返回总额为 0 但已有剩余短信时，自动计算 sms_package_total = sms_remain + sms_used；
  • 传感器属性增加严格类型检查与转换，即便遇到字典或非数字类型，也能安全兜底展示为 0 条，彻底杜绝任何形式的占位符露出。

---

⬆️ 如何升级

方式一：HACS 升级（推荐）

1. 打开 Home Assistant → HACS → 集成 → 找到 掌上运营商 (Shaobo Pocket Carrier)
2. 点击右上角三个点 → 选择 「重新下载 (Redownload)」
3. 版本选择 v3.5.3 并确认下载
4. 重启 Home Assistant

方式二：手动升级

1. 下载 Release 页面源码压缩包
2. 将 custom_components/shaobo_pocket_carrier/ 完整复制覆盖至 HA 的对应集成目录
3. 重启 Home Assistant

Shaobo Pocket Carrier

📱 掌上运营商 v3.5.2 发布公告

发布日期：2026-10-02 ｜ 版本：v3.5.2 ｜ 适配系统：Home Assistant 2024.1+

---

🛠️ 本次更新亮点

1. 🛡️ 联通核心接口增加超时瞬时抖动“原地重试”机制

• 痛点解决：中国联通服务器偶发十几秒不响应（Read timed out），而保活接口与核心用户信息接口没有容错降级路径，一旦偶发报错会导致整轮刷新失败、所有传感器实体变为“不可用”。
• 原地重试：新增网络异常重试包装器，捕获超时（Timeout）与网络连接错误（ConnectionError）后立即重试一次：
  • onLine.htm 滚动保活接口：重试时重新生成 reqtime 请求时间戳，保障会话滚动延续；
  • queryUserInfoSeven 核心用户信息接口：重试保障核心数据稳定产出，轻松扛过运营商服务器的偶发网络毛刺。

2. ⚡ 首次失败 1 分钟快速重试，无需干等 10 分钟

• 智能退避：在协调器中引入动态重试间隔（retry_after）：
  • 首次失败（上一轮正常，多为偶发网络超时）：设置 60 秒后立即补刷一次，使实体能以最快速度恢复在线可用状态；
  • 持续失败：自动恢复为正常的 10 分钟轮询周期，避免在运营商接口真正故障时频繁请求造成负担。

3. 🎯 主动详单请求防丢失保护

• 任务不落空：如果某一轮刷新包含了用户主动触发的任务（例如按了「刷新详单流水」按钮或每日定时拉取详单），若本轮遭遇网络异常失败，集成会自动保留详单拉取标记并在下一轮补刷时继续获取，彻底防止详单拉取请求无故落空。

---

⬆️ 如何升级

方式一：HACS 升级（推荐）

1. 打开 Home Assistant → HACS → 集成 → 找到 掌上运营商 (Shaobo Pocket Carrier)
2. 点击右上角三个点 → 选择 「重新下载 (Redownload)」
3. 版本选择 v3.5.2 并确认下载
4. 重启 Home Assistant

方式二：手动升级

1. 下载 Release 页面源码压缩包
2. 将 custom_components/shaobo_pocket_carrier/ 完整复制覆盖至 HA 的对应集成目录
3. 重启 Home Assistant

---

Shaobo Pocket Carrier

📱 掌上运营商 v3.5.1 发布公告

发布日期：2026-10-02 ｜ 版本：v3.5.1 ｜ 适配系统：Home Assistant 2024.1+

---

🛠️ 本次更新亮点

1. ⏰ 联通详单改为每天定时拉取一次（行为变更，联通用户请留意）

• 以前：开启「自动获取通话记录」后，每一轮轮询（默认 10 分钟）都会拉取通话 / 短信 / 上网三类详单。
• 现在：轮询只刷新话费与流量；三类详单只在每天「自动获取通话记录时间」（默认 08:00）拉取一次，其余时间展示本地缓存，大幅降低对运营商详单接口的请求频率。
• 立即刷新：打开开关或重启 Home Assistant 时不再立即拉取；需要马上查看最新详单，按「刷新详单流水」按钮（button.<手机号>_button）即可。
• 按需补拉：修改查询起始日期、跨月、首次安装尚无缓存时仍会额外拉取一次，保证查询日期与详单对得上。
• 关闭开关：不再定时拉取，需要时手动按「刷新详单流水」。

2. 📅 联通定时拉取不再改动查询起始日期

• 每日定时任务直接按「通话详单查询起始日期」当前所在月份拉取，不再强制改回当月 1 日。
• 查询日期只由「每日重置查询起始日期」开关管理（默认开启，每天 06:00 恢复为当月 1 日）；关闭该开关后，手动选择的历史月份会一直保留，定时任务也按该月份拉取。
• 电信行为不变。

3. 🐛 修复：月初 / 无记录月份的详单一直显示「未获取」

• 详单改为每天拉取一次后，若某次拉到的通话、短信、上网三类详单全为空（例如月初尚无记录），之后的轮询会一直显示「未获取」。
• 现在会把「该月暂无记录」也写入本地缓存，正确显示「本月暂无通话」等无记录状态。
• 同月已有记录的缓存不会被空结果覆盖（同月记录只增不减，全空多半是接口异常），历史流水不会凭空消失。

4. ✏️ 实体说明文案修正

• 联通详单传感器原来的「未获取 (自动获取已关闭)」在开关开启时也会出现，改为不随开关状态变化的说明。
• 「刷新详单流水」按钮属性显示每日拉取时间，例如「已开启（每天 08:00 拉取一次详单）」。
• 「自动获取通话记录」开关与时间实体的功能说明同步更新。

5. 🧹 代码清理

• 清理电信详单验证码提交逻辑中多余的类型转换（Pyrefly 静态检查警告），不影响功能。

---

⬆️ 如何升级

方式一：HACS 升级（推荐）

1. 打开 Home Assistant → HACS → 集成 → 找到 掌上运营商 (Shaobo Pocket Carrier)
2. 点击右上角三个点 → 选择 「重新下载 (Redownload)」
3. 版本选择 v3.5.1 并确认下载
4. 重启 Home Assistant

方式二：手动升级

1. 下载 Release 页面源码压缩包
2. 将 custom_components/shaobo_pocket_carrier/ 完整复制覆盖至 HA 的对应集成目录
3. 重启 Home Assistant

💡 升级后联通详单会在下一个设定时间（默认 08:00）定时拉取；想立即看到最新详单，按一次「刷新详单流水」即可。

Shaobo Pocket Carrier

📱 掌上运营商 v3.5.0 发布公告

发布日期：2026-10-01 ｜ 版本：v3.5.0 ｜ 适配系统：Home Assistant 2024.1+

---

🌟 本次版本重磅亮点

1. 🌐 中国联通：通话 / 短信 / 上网流量三大详单全套接入（免二次认证）

• 全方位对齐电信详单能力：联通手机号现已全面支持拉取 通话流水、短信详单 以及 上网流量详单（含明细会话与按天用量汇总）。
• 原生免二次认证：联通官方接口无需机主身份证与短信验证码二次认证，集成初始化后即可全自动静默获取！
• 专属手动刷新按钮：新增控制实体 button.<手机号>_button（“刷新详单流水”），与电信二次认证按钮保持统一实体后缀，方便卡片一键触发最新流水刷新。
• 本地持久化缓存兜底：同电信一样引入了本地持久化缓存机制，即使在轮询关闭或接口网络波动时，历史流水清单依然稳定展示，不凭空丢失。

2. 🎴 内置独立 Lovelace 通讯卡片（开箱即用）

• 集成内置专属卡片：集成自带专属前端通讯卡片 pocket-carrier-card.js。
• 全自动注册静态路由：无需手动到处找 JS 文件或手动修改 Lovelace 资源列表，集成启动时自动注册 /shaobo_pocket_carrier 资源路径并关联 Lovelace。
• 极简配置（支持双卡/多卡切换）：

  type: custom:pocket-carrier-card
  name: 家庭通讯总览
  tel_1: 13800138000
  tel_1_name: 我的联通
  tel_2: 18900189000
  tel_2_name: 家里电信

  只需填手机号，卡片即可自动推导并联动所有相关实体！

3. 🛡️ 月初月结出账期防抖保护

• 拦截出账期数据抖动：联通每月 1 日 00:00 ~ 08:00 为系统月结锁账期，接口锁定返回余额为 0 或 --。
• 平滑继承历史有效余额：新增月初出账期智能防抖机制，出账期间自动保留并显示出账前有效余额，并附带出账期通知属性，彻底根治月初余额断崖归零或触发误报警的问题。

4. ⚙️ 控制实体多平台全面完善与设备自动纠偏

• 通用控制实体扩展：通话详单查询起始日期（date）、自动获取通话记录（switch）、每日重置查询日期（switch）、号码归属地自动更新（switch）全面适配并扩展支持联通。
• 设备归属自动迁移：修复了部分情况下联通控制实体误挂载至电信设备的历史遗留问题，启动时自动平滑迁移实体设备归属，并自动安全清理残留空设备。
• 避免选项更新死循环：重构 async_update_options 配置项快照比对机制，仅当轮询间隔真正改动时才重载，彻底消除写回 token_online 触发无限刷新的隐患。

5. 🚀 性能优化与非阻塞异步准备

• 离线库加载异步化：号码归属地离线库与城市地理经纬度准备工作全面迁移至线程池（Executor）中异步加载，杜绝启动首轮刷新卡顿或阻塞 Home Assistant 事件循环。

---

⬆️ 如何升级

方式一：HACS 升级（推荐）

1. 打开 Home Assistant → HACS → 集成 → 找到 掌上运营商 (Shaobo Pocket Carrier)
2. 点击右上角三个点 → 选择 「重新下载 (Redownload)」
3. 版本选择 v3.5.0 并确认下载
4. 重启 Home Assistant

方式二：手动升级

1. 下载 Release 页面源码压缩包
2. 将 custom_components/shaobo_pocket_carrier/ 完整复制覆盖至 HA 的对应集成目录
3. 重启 Home Assistant

---

Shaobo Pocket Carrier

📱 掌上运营商 v3.4.1 发布公告

发布日期：2026-09-30 ｜ 合并自：PR #8 by @chjspp520

---

🛠️ 本次更新亮点

✉️ 短信详单对端号码精准还原

• 修复取号逻辑：底层接口深度解析电信官方详单数据中的 sendNo 与 receiveNo 字段，严格根据短信方向（发送 / 接收）准确提取真实的对端手机号或 106 服务号。
• 归属地与地图坐标联动：对端号码精准还原后，号码归属省市、运营商识别以及城市经纬度坐标同步实现 100% 精确映射。

⚡ 实体属性轻量化与数值化改造

• 短信记录实体 (sensor.<手机号>_sms)：
  • 属性引入字段投影裁剪，移除非必要冗余参数；
  • 短信费用统一转为标准浮点纯数值（元），不再带有中文后缀，更方便前端卡片做求和与图表统计；
  • 「合计」节点直接提供 count、sent、received、fee 四项精炼核心指标。
• 上网记录实体 (sensor.<手机号>_traffic)：
  • 会话清单与按天汇总仅保留日期时间、流量 (MB)、时长 (秒)、业务类型及费用数值，属性体积大幅瘦身。

🛡️ 数据总览节点防膨胀与条数裁剪

• 白名单属性过滤机制：总览实体（overview）新增 OVERVIEW_NODE_ATTR_KEYS 严格白名单限制，详单类子节点仅聚合清单、天级汇总与合计，不再重复搬运子实体的基础元数据，彻底阻断总览节点体积成倍膨胀。
• 安全防超限：结合 overview_call_limit 上限裁剪配置，保障 Home Assistant Recorder 长期稳定记录，彻底解决属性超过 16KB 产生警告的问题。

📍 号段识别库健壮性增强

• phone_region.py 进一步优化 106 行业短信服务号段、95/96 特服号以及物联网号段的容错与解析速度。

---

📂 变更文件概览

Shaobo Pocket Carrier

📱 掌上运营商 v3.4.0 发布公告

发布日期：2026-09-30 ｜ 合并自：PR #7 by @chjspp520

---

✨ 本次更新亮点

✉️ 新增电信「短信记录」详单实体

• 新增实体 sensor.<手机号>_sms（TelecomSmsRecordSensor）
• 实体状态：当月发送/接收条数及产生的短信费用概览（例如：9月 12 条（发 8 / 收 4）· 0.00 元）
• 详单清单属性：详细记录每条短信的收发时间、对方号码、收发类型（发送/接收）、短信费用与号码归属地
• 按天汇总：统计每天的发信条数、收信条数与费用分布
• 本地持久化缓存兜底：二次认证过期后自动采用本地缓存历史数据展示，详单记录永不清零

🌐 新增电信「上网记录」流量详单实体

• 新增实体 sensor.<手机号>_traffic（TelecomNetRecordSensor）
• 实体状态：当月总流量（MB/GB 自适应换算）、累计在线时长（XX小时XX分）与套餐外费用（例如：9月 45.20 GB · 120小时30分 · 0.00 元）
• 会话清单属性：展示每次上网会话的起始时间、连接网络制式（5G/4G/WiFi）、持续时长、消耗流量与业务类型
• 智能筛选与排序：支持上报电信官方会话排序与分类过滤项
• 本地持久化缓存兜底：认证失效后保持历史记录平稳展示

🔐 详单三合一·共用同一次二次认证

• 之前仅支持通话流水二次认证，现全面升级为通话、短信、上网流量三大详单共用同一次二次认证！
• 仅需输入一次机主姓名 + 身份证号 + 短信验证码，在 30 分钟安全有效期内一键同步拉取三大业务详单，彻底告别频繁验证码骚扰！
• 数据协调器统一管理详单认证状态与缓存生命周期。

📊 数据总览聚合实体同步升级

• 数据总览聚合实体（overview）同步纳入「短信记录」与「上网会话清单」
• 配合 overview_call_limit 属性上限裁剪控制，既能在一卡片集中展示全部数据，又可彻底避免 Home Assistant Recorder 单状态属性超限（16KB 截断）问题。

📍 号段库智能识别扩展

• 离线归属地库新增对 106 行业短信服务号段、物联网卡专属号段（140/141/144/146/148 等）以及常用特服号段的智能识别，短信清单里的服务号归属地展示更加清晰准确。

---

📂 变更文件概览