dsh-mobile 0.7.1 → 0.8.1

package/docs/WEB_PUSH.md

@@ -0,0 +1,118 @@
+# iPhone 与 iPad 网页推送
+
+[English](<WEB_PUSH.en.md>) · [文档索引](<README.md>)
+
+> **插件 0.8.0 起支持 iPhone / iPad 网页推送**。先用 Safari 配对并添加到主屏幕，再在 DSH 页面内主动开启通知。推送面向具备能力的 iOS/iPadOS **18.4+ 主屏幕 Web App**，不需要原生 iOS App，也不需要通知 SaaS 账号。
+
+## 在 iPhone 和 iPad 上使用 DSH Mobile
+
+DSH Mobile 插件运行在**电脑**上。iPhone/iPad 用户用 **Safari** 打开专用的移动访问页面，与电脑配对后，可将页面添加到主屏幕作为 Web App（PWA）使用，无需下载原生 iOS App。先按[连接教程](<../README.md#连接教程>)完成连接；无需开启通知也能使用 DSH 会话和工作区。
+
+添加到主屏幕不代表可以离线使用 DSH：电脑、DSH 和 Mobile Gateway 须保持运行，手机使用时也须能连接网关。下文 **18.4+ 的目标环境仅针对可选的网页推送**，不代表普通浏览器访问的最低版本；浏览器兼容性仍取决于 DSH 前端。
+
+## 使用条件
+
+- 支持页面级 `window.pushManager` 的 iPhone/iPad 主屏幕 Web App，并以独立模式打开。插件检查实际能力，不根据浏览器版本字符串放行；普通 Safari 标签页和不支持的浏览器没有 Service Worker 降级方案。
+- **固定、受信任的 HTTPS Origin**，以及现有 DSH Mobile 浏览器配对。HTTP 和绕过证书警告不属于受支持的推送配置；Android App 固定私有 CA，不等于 iPhone 浏览器信任该 CA。
+- 电脑端已更新到插件 **0.8.0 或更高版本**，DSH 和对应 HTTPS 地址的 Mobile Gateway 正在运行。推送的打包自动化检查覆盖 DSH **0.2.1-rc.2 / rc.3**；其他版本仍取决于所需公共服务是否可用，缺少服务只关闭推送，不关闭普通移动访问。
+- 主机和手机能出站连接 Apple 推送基础设施。不需要 Apple 开发者会员、通知 SaaS 账号或新增公网入站端口。此功能不创建 VPN、不改证书／防火墙，也不配置代理。
+
+使用公开受信任证书的私有 HTTPS 主机名在架构上可以使用。安装、启用、认证和打开会话时，手机仍须能访问该 Origin。私有／Tailscale Origin 的投递**尚未实测确认**；不要为了尝试推送把私有后端直接暴露到公网。随机隧道域名不适合作为长期安装地址：Origin 改变后，不自动迁移授权或订阅。需要长期地址时，可参考 [Cloudflare 命名隧道](<CLOUDFLARE_TUNNEL.md>)或[自有 HTTPS 反向代理](<SELF_HOSTED_ORIGIN.md>)；仅完成地址配置不代表推送已验证送达。
+
+## 明确启用
+
+1. 在目标 HTTPS 地址打开并配对专用 DSH Mobile 页面。通过 Safari **分享 → 添加到主屏幕**，再从图标启动，而不是普通标签页。若显示配对码表单，请按[新码恢复步骤](<#主屏幕-app-显示配对表单时>)操作，不要复用 Safari 已消耗的配对码，也不要为排障清除已有配对或网站数据。
+2. **在 DSH 页面内**打开**设置 → 通用设置**，找到**网页推送通知**；它与 Android 的**任务通知**入口分开，不是 iPhone/iPad 系统的“设置”App。
+3. 点击**启用**并处理浏览器权限提示。页面加载、重连和主机重启不会自动申请权限或创建订阅；主机成功保存同意状态后才算启用完成。
+4. 选择需要的类别。**发送测试**每个安装每分钟限一次，TTL 为 60 秒；成功仅代表**推送服务商接受请求**，不代表手机已送达、显示、阅读或回答。
+
+浏览器安装 ID 只用于区分容器，不是凭据。其他浏览器／配置或 Origin 各自管理同意状态；主机从已认证的配对设备判断归属，而不是相信页面提交的 ID。
+
+### 主屏幕 App 显示配对表单时
+
+Safari 与已安装 App 可能使用不同登录状态。本恢复步骤仅针对**配对码**表单，不适用于续期已有配对的普通重新连接页；也不以启用推送为前提。
+
+1. 在电脑端保持与主屏幕安装**相同的局域网／远程通道和 HTTPS Origin**。局域网先选**生成配对二维码**，再**复制配对链接**；远程先选**生成远程配对二维码**，再**复制远程配对链接**。复制操作会复用当前码；要替另一安装配对，须先生成新码，不能只重新复制已用过的链接。
+2. 从新链接的片段（`#` 后）取出 **`token=` 的 43 位值**，只把这段码填入已安装 App 的**配对码**栏，不要粘贴完整 URL 或 Android 的 `dsh1.`／`dsh2.` 密钥。若链接没有 `token=`，请检查是否选用了兼容浏览器的 HTTPS 入口，不要从 Android 密钥拆码，也不要绕过证书警告。
+3. 在新码到期前，在**主屏幕 App** 中完成配对，不要先在 Safari 消耗它。配对码只能使用一次，用过或到期后须生成新链接。完整链接和配对码均属秘密，不要贴到 issue 或日志；保留已有安装、配对设备记录和网站数据。
+
+### 日常通知须知
+
+推送是尽力而为，不是警报服务。主机睡眠／关机、Origin 停用、手机网络、专注模式和系统调度均可能延迟或阻止投递。
+
+关闭页面**不会**停用已保存的推送同意。用**停用**阻止后续合格发送；明确退出与撤销设备各有不同效果，见[下表](<#同意状态退出与撤销>)。点击通知可能需要重新登录，绝不会代为回答或批准；**发送测试**的通知打开应用根入口，而不是某个会话。
+
+## 会提醒什么
+
+明确开启总开关后，以下六类默认开启。范围是此设备已授权的用户可见会话，包括未在前台打开的会话和普通 fork，不限于手机当前查看的会话。
+
+| 类别 | 含义 |
+| --- | --- |
+| 问题 | 公开输入请求仍未解决／仍可回答。超时后继续执行的问题仍可能可答；已排队的匹配回答会压制过期提醒。 |
+| 计划 | 实际发出、尚未解决的计划审核请求。 |
+| 审批 | 确实通过公开请求生命周期发出的权限请求，不仅是审计记录。 |
+| 回复 | 普通非目标任务的响应已提交，合并等待后仍然有效。 |
+| 目标 | 已提交的目标完成或真正受阻，不是每轮继续执行都报成功。 |
+| 失败 | 已确认无法自动恢复、需要介入的最终失败，不是每个错误或重试。 |
+
+常规流式输出／进度、运行时子任务完成和用户主动停止不提醒。子任务阻塞只在 DSH 已通过所属工作流发出真实人工请求时观察，不伪造父会话问题、不读取子任务私有状态。快速自动决定可能在提醒延迟前结束，因此不通知。通知说明发生过某个事件，不保证目前已有某人认领等待。
+
+锁屏内容使用通用的英文、简体中文或意大利文，不包含问题正文、工具参数、目标内容、会话摘录或原始错误。通知 tag 不保证替换或撤回。
+
+## 同意状态、退出与撤销
+
+| 操作／事件 | 效果 |
+| --- | --- |
+| 关闭页面或短登录会话过期 | 持久配对授权与 Origin 仍有效时保留推送同意；打开 DSH 仍需认证。 |
+| 点击停用 | 先持久保存主机停发，再尽力取消本功能拥有的浏览器订阅；浏览器取消失败不会恢复主机同意。 |
+| 明确退出 Mobile | 清除短会话前，先关闭此配对设备在当前 Origin 的推送，保留配对。停用保存失败不能报告退出已完成。 |
+| 撤销／重置设备，或持久凭据过期 | 清理相关注册和队列，包含没有打开页面的休眠设备。 |
+| 停止 Gateway／服务商或更改 Origin | 停止该 Origin 发送；其他 Origin 保留各自同意，新地址须重新明确启用。 |
+| 重启 DSH | 保留密钥、同意和仍新鲜的受限投递状态，先重新检查授权与来源资格，不重播旧会话。 |
+
+停用或撤销前已被服务商接受／正在传输的通知仍可能送达，无法可靠撤回。重新启用不会向新注册安装播报旧历史。认证或代次冲突后只能刷新状态，再作新的明确操作，不自动重放旧的启用／类别／停用请求。
+
+## 点击行为与隐私
+
+通知打开同 Origin 根入口，并携带不透明投递引用。引用不含会话正文或授权令牌；Gateway 在认证配对设备后，检查范围、设备、Origin 和有效期再解析。短登录过期使用原有安全根路径返回流程；引用不能绕过登录。
+
+公开工作区和会话列表就绪后，Mobile 再检查会话存在，然后调用 DSH 正常 UI 打开动作。请求已解决时可以进入会话并显示中性提示；点击不会回答、批准或重新打开旧问题。引用过期、属于其他设备、缺失或目标已删除时使用中性的不可用／会话列表回退。消费引用只移除对应查询参数，不强制刷新。
+
+冷启动还是复用页面由浏览器决定；不要假定所有通知导航都会保留未发送草稿或进行中的发送。DSH 全新启动时可能先显示最近活跃会话，此时可从会话列表手动选择目标。插件不注册／注销 Service Worker，也不缓存已认证页面或 API 内容。
+
+## 数量、时效与失败处理
+
+- 每个配对设备最多 **4 个注册**；每个授权范围最多 **256 个注册和 256 个待投递项**；最多 **4 个并发发送**。满额时拒绝新通知工作，不删除其他安装，也不阻塞 DSH。
+- 人工关注提醒从原始请求起 **5 分钟**过期；结果提醒从来源事件起 **30 分钟**过期。重试不刷新时效。
+- 最多 **3 次尝试**，每次绝对预算 **10 秒**；重试先等 **1 秒**、再等 **5 秒**，Retry-After 也不能超出原有时效。
+- HTTP 404/410 删除失效注册；401/403 暂停相关投递并要求检查配置／密钥，不清除配对；其他永久错误丢弃该项；网络／429／5xx 仍只作有界重试。
+- 接受记录和点击引用均有上限。服务商接受后、记录保存前崩溃可能导致重复尝试，不保证恰好一次。
+
+发送器只接受验证过的 Apple HTTPS 推送地址，拒绝重定向及不安全 DNS 目标，使用 Web Push/VAPID 加密。订阅地址、密钥和私有通知状态属于凭据，不能粘贴到 issue 或日志。通知保存／网络失败不能改变 DSH 的回答、审批或轮次结果。
+
+## 排障与明确修复
+
+| 状态／问题 | 处理 |
+| --- | --- |
+| 没有入口／不可用 | 检查页面级能力、受信任 HTTPS、已认证的专用浏览器页面及 DSH 公共服务；没有 Worker 或旧 iOS 降级。 |
+| 提示安装 | 从主屏幕图标启动，不在普通标签页开启。 |
+| 权限拒绝 | 在系统／浏览器设置中修改该网站的通知权限，再返回 App 作新的明确启用；不会强制再次弹窗。 |
+| 保存失败／设置已过期 | 刷新或重开读取当前状态，再明确重试，不反复提交旧请求。 |
+| 现有订阅属于其他应用密钥 | 不自动取消它；主机密钥重置后仅重试启用无法解决，先确认归属，再安排明确的浏览器端修复。 |
+| 已暂停／需要修复 | 检查主机密钥、配置和私有文件访问；不要删除配对状态或静默更换 VAPID 密钥。 |
+| 暂时无法退出登录 | 已保存的通知同意尚不能安全关闭。保留页面，待电脑端推送服务恢复后明确重试退出；不要把关闭页面当作停用通知。 |
+| 测试已接受但未显示 | 检查手机权限／专注模式／网络、主机与网关是否运行，以及原有时效；服务商接受不是送达回执。 |
+
+已有注册而 VAPID 材料丢失／损坏时，功能安全关闭。主机管理员可以通过现有受信任本机桌面管理 API，向 `POST /api/mobile-access/push/reset` 发送 JSON `{ "confirm": "reset-web-push" }`，明确重置**通知状态而非配对**。这是破坏性的通知重置，不是手机接口或自动修复按钮；之后各浏览器须重新明确注册，配对保留。该重置**作用于主机整个注册表**——会清空所有已连接设备与 Origin 的注册，而不只是之后遇到冲突的那台浏览器——因此旧订阅可能让普通重新启用持续失败；此处不承诺任何经过验证的破坏性修复步骤。保留正常桌面 Host／Origin／来源保护，不能公开暴露此管理路径，也不要手动删除配对设备文件。
+
+## 独立通道与验收
+
+Android 原生权限／SSE 路径、APK 和签名保持不变。独立维护的 **dsh-ping** 不被修改或自动停用；同时开启可能收到不同通道的重复提醒。网页推送不增加跨通道去重，也不因页面在前台而压制通知。
+
+日常使用建议先发送一条测试通知，再检查自己关注的类别。保留现有主屏幕安装和配对数据；更新电脑端插件后重新打开页面即可加载新版界面。打包运行时检查与维护命令见[贡献指南](<../CONTRIBUTING.md#select-behavior-checks>)。
+
+## 验证状态
+
+本版采信贡献者在 **iPhone 17 Pro Max / iOS 27.0.1** 上的开发实测，覆盖六类提醒、后台／锁屏／关闭页面、通知点击、停用与撤销，以及离线和主机重启。维护者没有独立 Apple 真机复验；iPad 与其他设备／系统组合没有对应真机记录。
+
+自动化检查覆盖设置、鉴权、加密载荷、点击归属、重启与清理，不代表 Apple 实际送达。缺失目标的自动化检查使用未创建的会话；真正“先持久化再删除”的会话受当前 DSH 公共接口限制，尚无同类检查。推送为尽力投递，不能替代重要任务的人工确认。