@agentunion/fastaun-browser 0.5.3 → 0.5.6

package/_packed_docs/AUN/347/246/273/347/272/277/346/216/250/351/200/201/346/234/215/345/212/241/346/236/266/346/236/204/344/270/216/350/257/246/347/273/206/345/256/236/347/216/260/350/256/241/345/210/222-codex.md

@@ -0,0 +1,994 @@
+# AUN 离线推送服务架构与详细实现计划
+
+> 状态：架构方案已收敛，尚未实施  
+> 日期：2026-07-24  
+> 适用范围：AUN Gateway、Message、Group、独立 Push Service、aun-console 三中心、Python SDK 与测试用 Mock Push Server
+
+## 1. 背景与结论
+
+P2P Message 和 Group Message 的接收者全部离线时，Gateway 无法通过 WebSocket RPC 或事件把在线通知送到移动端。需要增加一条独立于消息可靠存储的离线唤醒链路，由应用方 Push Server 调用 APNs、FCM 或其他厂商推送服务。
+
+Push Service 必须是独立的 AUN Go 服务，并由 aun-console 的控制中心、注册中心和配置中心统一纳管。现有 `docs/protocol/15-离线推送通知协议.md` 只作为历史参考，其中把 PushAggregator、push_config 和 ACK 状态放在 Gateway 内的架构不再采用。
+
+最终边界如下：
+
+- Gateway 只负责认证、可信上下文注入、服务路由、在线 Session 查询和事件投递。
+- Message / Group 只在消息持久化成功后产生推送候选，不管理 token，不判断最终离线状态。
+- Push Service 负责注册、持久化、聚合、频控、最终离线检查、批次、ACK、重试和恢复。
+- Push Server 是普通 AUN 客户端 AID，负责验证 opaque token 并调用传统推送服务。
+- Python SDK 只为测试和仓库外 Rust SDK 提供参考实现；Go、TypeScript、JavaScript SDK 本阶段不同步。
+
+本方案不新增 Kernel RPC、不新增 Kite 核心事件、不修改事件订阅机制，也不要求 Watchdog 增加特殊逻辑。
+
+## 2. 设计目标与非目标
+
+### 2.1 设计目标
+
+- P2P 和 Group 的本域、跨域离线接收者均能收到传统移动推送。
+- 消息主链不受 Push Service、Push Server、APNs 或 FCM 故障影响。
+- Push Service 接收候选后具备持久化、幂等、有限重试和重启恢复能力。
+- 支持一个 AID 的多设备、多 slot 和不同 push token。
+- 支持三中心 desired-state 启停、配置下发、服务发现、状态展示和节点迁移。
+- 所有推送 payload 均不包含消息正文或 E2EE 密文。
+- 正常、错误、异常、竞态和超时路径均有明确状态与诊断日志。
+
+### 2.2 非目标
+
+- Push Service 不直接集成 APNs、FCM 或厂商 SDK。
+- Push Service 不读取 Message、Group 或客户端数据库。
+- Push Service 不保证移动设备已经展示通知，只确认 Push Server 或第三方平台是否接受。
+- 本阶段不解决多 Gateway 的集群级在线 Session 汇聚。
+- 本阶段不为 Go、TypeScript、JavaScript SDK 增加 Push facade。
+- 推送不是消息可靠传输通道，真实消息仍通过 `message.pull` 或 `group.pull` 获取。
+
+## 3. 总体架构
+
+```mermaid
+flowchart LR
+    C[移动端 / Python 测试客户端]
+    MG[Message / Group]
+    GW[Gateway]
+    PS[Push Service\nGo / 三中心纳管]
+    DB[(aun_push)]
+    PNS[Push Server AID\nPython Mock / 真实服务]
+    PP[APNs / FCM / 厂商推送]
+    CC[AUN 三中心]
+    L[Launcher]
+
+    C -->|push.register / unregister| GW
+    MG -->|push.enqueue| GW
+    GW --> PS
+    PS --> DB
+    PS -->|gateway.query_sessions| GW
+    PS -->|event/push.offline_message| GW
+    GW --> PNS
+    PNS -->|push.ack| GW
+    GW --> PS
+    PNS --> PP
+    PP --> C
+
+    CC -->|配置 / desired-state / 服务发现| L
+    L -->|启动、停止、迁移、drain| PS
+```
+
+模块间仅通过环境变量、WebSocket JSON-RPC 2.0、HTTP 诊断接口和数据库格式约定协作。Push Service 不 import 其他 Kite/AUN 服务的代码，满足零共享代码依赖原则。
+
+## 4. 组件职责
+
+| 组件 | 核心职责 | 明确禁止 |
+| --- | --- | --- |
+| Message / Group | 消息持久化成功后产生推送候选；本域目标分片；跨域目标域触发 | 读取 push token；等待 Push Server ACK；因推送失败而使 send 失败 |
+| Push Service | 注册、加密存储、候选去重、聚合、在线确认、批次、ACK、重试、频控、恢复 | 读取消息正文；调用 APNs/FCM；信任客户端自报 AID/device |
+| Gateway | 注入 `_auth` / `_caller_id`；路由 `push.*`；查询 Session；投递 Push 事件 | 存储 push_config；实现聚合器；解释 opaque token |
+| Push Server | 验证 token；调用平台服务；按 delivery_id 幂等；逐项 ACK | 通过事件正文替代 AUN pull；ACK 不属于自己的批次 |
+| aun-console 三中心 | desired-state、单实例策略、配置、服务发现、状态和诊断 | 直接参与业务消息或 Push batch 调度 |
+
+## 5. 对历史协议的重构
+
+历史协议保留以下原则：
+
+- 推送由目标 AID 所属域负责。
+- V1 中任意一个设备在线即不触发该 AID 的离线推送。
+- `push_token` 对 AUN 服务不透明，由 Push Server 自签、自验。
+- 推送只携带唤醒元数据，不携带消息正文和密文。
+
+需要删除或替换的设计：
+
+| 历史设计 | 新设计 |
+| --- | --- |
+| `auth.login/auth.connect` 携带 push 字段 | 显式调用 `push.register` |
+| Gateway 保存 `push_config` | Push Service 独立数据库保存 |
+| Gateway 内置 PushAggregator | Push Service 内置调度器和持久化状态机 |
+| 每个 AID 只有一条配置 | 每个 `(aid, device_id, slot_id)` 一条注册 |
+| 最后一次连接覆盖所有设备 | 每个安装独立更新和注销 |
+| 批次级 `push.ack(batch_id)` | 逐 `delivery_id` 返回标准化结果 |
+| ACK 超时后直接放弃 | 有限重试，受候选 TTL 和最大尝试次数约束 |
+| Gateway 决定 token 是否可用 | Push Server 返回 normalized result，Push Service按注册版本处理 |
+
+## 6. 对外协议
+
+### 6.1 `push.register`
+
+调用者为已完成 Gateway 认证的普通客户端。
+
+客户端参数：
+
+- `push_server_aid`：负责该安装的 Push Server AID。
+- `push_token`：由 Push Server 签发的 opaque token。
+- `provider`：可选，仅用于诊断，例如 `mock`、`apns`、`fcm`。
+- `app_id`：可选，标识应用或租户。
+
+可信身份只能使用 Gateway 注入的：
+
+- `_auth.aid`
+- `_auth.device_id`
+- `_auth.slot_id`
+- `_auth.connection_id`
+
+客户端参数中出现 `aid`、`device_id` 或 `slot_id` 时不得覆盖可信身份。
+
+处理规则：
+
+1. 校验已认证身份完整。
+2. 校验 `push_server_aid` 属于本域并存在于配置中心白名单。
+3. 校验 token 非空、长度不超过上限。
+4. 使用当前密钥版本加密 token。
+5. 按 `(aid, device_id, slot_id)` UPSERT，并递增注册版本。
+6. 返回 `registration_id`、`registration_version` 和更新时间，不返回 token。
+
+客户端应在首次获取 token、token 变化和应用重新激活时调用。重复注册相同 token 是幂等更新。
+
+### 6.2 `push.unregister`
+
+调用者为已认证普通客户端。默认只注销当前 `_auth.aid/device_id/slot_id` 对应安装。
+
+注销是幂等操作：不存在注册时仍返回成功。已经进入事件投递阶段的通知不可撤回；尚未 dispatch 的 delivery 在发送前再次检查注册版本并终止。
+
+### 6.3 `push.enqueue`
+
+调用者只能是 Message 或 Group 服务。Push Service 必须校验 Gateway 注入的 `_caller_id`：
+
+- `_caller_id=message`
+- `_caller_id=group`
+
+普通客户端或其他服务调用必须拒绝。
+
+每个候选项包含：
+
+- `candidate_id`：确定性幂等键。
+- `kind`：`p2p` 或 `group`。
+- `target_aid`：目标 AID。
+- `occurred_at_ms`：消息提交时间。
+- `expires_at_ms`：候选过期时间。
+- 可选的内部 trace 信息。
+
+禁止携带：
+
+- 消息正文。
+- E2EE 密文。
+- push token。
+- 客户端私钥、证书或认证 token。
+
+批量调用必须设置条数和总字节数上限。单个无效 item 不应阻塞其他合法 item，响应按 item 返回 accepted、duplicate 或 rejected。
+
+Push Service 只有在数据库提交成功后才返回 accepted。Message / Group 使用同一 `candidate_id` 重试不会产生重复任务。
+
+### 6.4 `event/push.offline_message`
+
+Push Service 通过 `gateway.dispatch_event` 向 Push Server AID 的一个确定 Session 投递事件，且固定设置 `federation_forward=false`。
+
+批次公共字段：
+
+- `protocol_version`
+- `batch_id`
+- `expires_at_ms`
+- `items`
+
+每个 item 包含：
+
+- `delivery_id`
+- `target_aid`
+- `device_id`
+- `slot_id`
+- `push_token`
+- `category`
+- `new_count`
+- `latest_at_ms`
+
+V1 默认不包含 sender AID、message ID、group ID、消息正文和密文。Push Server 生成通用通知，移动端上线后再通过 AUN 拉取真实消息。
+
+### 6.5 `push.ack`
+
+调用者为 Push Server AID，使用 Gateway 注入的 `_auth.aid` 鉴权。`_auth.aid` 必须与 batch 所属 `push_server_aid` 一致。
+
+请求包含 `batch_id` 和逐项结果：
+
+| status | 语义 | Push Service 行为 |
+| --- | --- | --- |
+| `accepted` | 第三方平台已接受 | delivery 进入成功终态 |
+| `retryable_failure` | 临时失败 | 按 `retry_after_ms` 或服务退避规则重试 |
+| `permanent_failure` | 永久失败 | delivery 进入永久失败终态 |
+
+只有 `permanent_failure` 且错误码为 `invalid_token` 或 `unregistered` 时才自动禁用注册。禁用前必须确认当前注册版本仍等于发送快照版本，避免旧 token 的迟到 ACK 禁用新 token。
+
+ACK 规则：
+
+- 重复 ACK 幂等。
+- 部分 ACK 只终结已返回的 items。
+- 未返回的 items 保持 inflight，等待 ACK 超时。
+- ACK 中出现不属于该 batch 的 delivery 必须拒绝。
+- batch 过期后的迟到 ACK 只返回当前终态，不重新激活任务。
+
+## 7. 正常业务流程
+
+### 7.1 注册流程
+
+```mermaid
+sequenceDiagram
+    participant App as 移动端
+    participant PNS as Push Server
+    participant GW as Gateway
+    participant PS as Push Service
+    participant DB as aun_push
+
+    App->>PNS: 申请 opaque push_token
+    PNS-->>App: push_token
+    App->>GW: push.register(push_server_aid, push_token)
+    GW->>PS: 注入可信 _auth 后转发
+    PS->>PS: 白名单、域、长度校验
+    PS->>DB: 加密 UPSERT 注册并递增版本
+    DB-->>PS: commit
+    PS-->>App: registration_id/version
+```
+
+### 7.2 本域 P2P 离线推送
+
+```mermaid
+sequenceDiagram
+    participant A as Sender
+    participant M as Message
+    participant PS as Push Service
+    participant GW as Gateway
+    participant PNS as Push Server
+    participant B as Target Mobile
+
+    A->>M: message.send(to=B)
+    M->>M: 持久化成功
+    M-->>A: message accepted
+    M->>PS: 异步 push.enqueue
+    PS->>PS: 去重、聚合、频控
+    PS->>GW: gateway.query_sessions(B)
+    GW-->>PS: online=false
+    PS->>GW: query Push Server sessions
+    GW-->>PS: 选择一个 connection_id
+    PS->>GW: event/push.offline_message
+    GW->>PNS: Push batch
+    PNS->>PNS: 验证 token、调用 APNs/FCM
+    PNS->>PS: push.ack
+    PNS-->>B: 传统推送通知
+    B->>M: 上线后 message.pull
+```
+
+### 7.3 Group 离线推送
+
+Group 服务在持久化完成并确定本域成员后，按目标 AID 批量产生候选。Push Service 不读取群成员表，也不重新计算群成员。
+
+Group 消息候选必须满足：
+
+- 不为发送者自身产生候选。
+- 本域 Group 只提交本域成员。
+- federation 目标域 Group 只为目标域成员提交候选。
+- federation 重放使用相同 `candidate_id`，由 Push Service 唯一约束去重。
+- 单次 `push.enqueue` 按条数和总字节数分批，防止大群 fanout 占满 RPC 队列。
+
+### 7.4 跨域原则
+
+P2P：
+
+- 源域 Message 不为外域目标产生候选。
+- 目标域 Message 在目标消息持久化成功后产生候选。
+- 只有目标域 Push Service 可以读取目标域注册并向目标域 Push Server 投递。
+
+Group：
+
+- 源域 Group 为本域成员产生候选。
+- 经过 `group.relay_event` 到达目标域后，目标域 Group 为本域成员产生候选。
+- Push 事件本身不进行 federation 转发。
+
+## 8. 在线判断与竞态规则
+
+### 8.1 V1 在线策略
+
+注册按安装保存，但在线抑制按 AID 判断：目标 AID 只要存在任意在线 Session，本轮所有设备均不发送传统推送。
+
+选择该策略的原因：
+
+- 避免同一用户正在一个终端使用时，其他终端持续产生通知噪音。
+- 当前 Gateway 已能可靠回答 AID 是否存在 Session。
+- 不需要在 Push Service 中复制 Session 目录。
+
+### 8.2 最终检查时点
+
+Message / Group 不在 enqueue 时判断在线。Push Service 在真正 dispatch 前调用 `gateway.query_sessions`：
+
+- `online=true`：候选进入 `suppressed_online`。
+- `online=false`：进入注册查询和批次构建。
+- RPC 错误、超时或响应非法：不得当作离线，候选进入 `retry_wait`。
+
+### 8.3 无法消除的竞态
+
+- 目标在 query 之前上线：本轮推送被抑制。
+- 目标在 query 之后、dispatch 之前上线：仍可能发送一条冗余通知。
+- 目标在事件已到 Push Server 后上线：通知不可撤回。
+- unregister 在 batch 构建前完成：终止 delivery。
+- unregister 在事件已送达后完成：不撤回已经提交的平台推送。
+
+这些竞态只影响通知是否冗余，不影响 AUN 消息的唯一性、顺序或 pull 可靠性。
+
+## 9. 持久化模型
+
+Push Service 使用独立 MySQL 数据库 `aun_push`，不与其他模块共享表或 ORM 代码。
+
+### 9.1 注册表
+
+关键约束：
+
+- 唯一键：`(aid, device_id, slot_id)`。
+- 保存 `registration_id`、`push_server_aid`、加密 token、密钥版本、注册版本、启用状态和更新时间。
+- 保存 token 指纹用于幂等判断和诊断，但不得保存可逆明文或直接记录 token。
+- token 永久失效只禁用与 delivery 快照版本一致的注册。
+
+### 9.2 候选表
+
+关键约束：
+
+- `candidate_id` 唯一。
+- 保存目标、类型、调度时间、过期时间、状态、尝试时间和诊断原因。
+- 不保存消息正文、密文或 push token。
+- terminal 候选按保留周期清理。
+
+### 9.3 批次和 delivery 表
+
+批次保存：
+
+- `batch_id`
+- `push_server_aid`
+- 当前 dispatch attempt
+- ACK deadline
+- lease owner / lease deadline
+- 批次状态
+
+delivery 保存：
+
+- `delivery_id`
+- 关联候选和 batch
+- 注册 ID 与注册版本快照
+- item 状态、尝试次数、下次尝试时间
+- normalized error code
+
+### 9.4 频控状态
+
+按 target AID 和 Push Server 维护：
+
+- 最后成功 dispatch 时间。
+- 下一允许 dispatch 时间。
+- 当前 in-flight 数。
+- 窗口计数。
+
+频控状态可以使用数据库作为恢复真源，内存只作为单实例运行时缓存。
+
+## 10. 状态机与并发控制
+
+```text
+pending → ready → dispatching → inflight → accepted
+             ├→ suppressed_online
+             ├→ no_registration
+             ├→ retry_wait → ready
+             ├→ permanent_failed
+             └→ expired
+```
+
+并发规则：
+
+- scheduler 使用数据库租约领取任务。
+- 领取、状态变更和 attempt 增加必须使用事务或条件 UPDATE。
+- ACK 可以在 dispatch RPC 返回前到达，ACK 写入的终态优先。
+- dispatch worker 更新状态时必须附带旧状态条件，不能覆盖已经 ACK 的状态。
+- 服务迁移时旧实例停止领取新任务，未完成租约到期后由新实例恢复。
+- 多实例短暂重叠允许产生重复事件，但不允许产生不同 `delivery_id`。
+
+### 10.1 Gateway event_id 与 delivery_id
+
+- `delivery_id` 在所有重试中保持不变，供 Push Server 端到端去重。
+- Gateway `event_id` 按 `batch_id + dispatch_attempt` 生成。
+- 同一次 dispatch 因响应丢失而重试时复用相同 event_id，利用 Gateway 去重。
+- ACK 超时后开始新的 attempt，生成新 event_id，使 Push Server 能重新收到事件并重新 ACK。
+
+## 11. 可靠性边界
+
+### 11.1 Message / Group 到 Push Service
+
+该段为有界异步 best-effort：
+
+- 消息持久化成功后立即向发送者返回成功。
+- 推送候选进入本进程有界队列，按目标 AID 合并并保留最新提示。
+- Push Service 暂时不可用时按候选 TTL 有限重试。
+- Message / Group 进程在 Push Service 确认接收前崩溃，该通知提示丢失，但真实消息仍可 pull。
+- 队列满或任务过期必须产生计数和诊断日志，不得静默吞掉。
+
+不采用跨服务分布式事务，也不把 Push outbox 写入失败升级为消息发送失败。
+
+### 11.2 Push Service 接收之后
+
+该段为持久化至少一次：
+
+- `push.enqueue` 只有在数据库 commit 后才返回 accepted。
+- 服务重启、Gateway 重连和三中心节点迁移后继续处理。
+- dispatch、ACK 或响应丢失会重试。
+- Push Server 必须按 `delivery_id` 幂等，并在收到重复事件时重新返回 ACK。
+
+### 11.3 Push Server 到传统推送平台
+
+Push Server 将 AUN 的 normalized status 映射到具体平台结果。`accepted` 只表示平台接受请求，不表示移动设备已经联网、展示或点击通知。
+
+## 12. 异常和超时处理
+
+| 场景 | 确定行为 |
+| --- | --- |
+| Gateway Session 查询超时 | 不发送，进入退避重试 |
+| Gateway 返回非法在线状态 | 记录协议错误，不推断离线 |
+| 目标存在任意在线 Session | 候选终止为 `suppressed_online` |
+| 目标没有有效注册 | 候选终止为 `no_registration` |
+| Push Server 没有在线 Session | 保持待发，直到恢复或候选过期 |
+| `gateway.dispatch_event` delivered=0 | 不进入 inflight，退避重试 |
+| dispatch 成功但响应丢失 | 同 attempt 重试，Gateway 和 Push Server 双层去重 |
+| ACK 在 dispatch 响应前到达 | ACK 状态优先，dispatch worker 条件更新失败即停止覆盖 |
+| ACK 只包含部分 items | 已 ACK 项终结，缺失项等待 ACK timeout |
+| ACK timeout | 缺失项进入下一 attempt，直到次数或 TTL 耗尽 |
+| token 永久失效 | 只禁用版本匹配的注册 |
+| DB 启动时不可用 | 不报告 ready，启动失败或保持初始化状态 |
+| DB 运行时不可用 | 暂停 scheduler，RPC 返回可重试错误，健康状态 degraded |
+| Gateway 启动时不可用 | 状态为 `waiting_gateway`，不得伪装 ready |
+| 发现多个 Gateway 实例 | 状态为 `blocked_gateway_multi_instance`，停止 Push dispatch |
+| Push Service 正在 drain | 停止接收新业务和领取新任务，允许 ACK 与已进入处理的事务完成 |
+
+## 13. 安全设计
+
+### 13.1 Push Server 白名单
+
+- 配置中心维护 `allowed_push_server_aids`。
+- 白名单为空时 Push 功能处于禁用状态，不允许注册。
+- `push_server_aid` 必须属于当前 issuer domain。
+- 白名单移除某 AID 后，其现有注册被禁用，未发送 delivery 终止。
+
+### 13.2 token 加密
+
+- 使用 AES-256-GCM。
+- 配置中心通过 secret 或环境变量注入密钥环和 active key ID。
+- 数据库保存 key ID、nonce、ciphertext 和认证 tag。
+- 新注册使用 active key；旧 key 保留解密能力，支持逐步轮换。
+- token 明文只在注册处理和事件构建的短生命周期内存在。
+
+### 13.3 日志脱敏
+
+日志中禁止出现：
+
+- `push_token`
+- 数据库 ciphertext
+- AUN 登录 token
+- 私钥或证书完整内容
+- 消息正文或 E2EE payload
+
+允许记录：
+
+- `candidate_id`
+- `batch_id`
+- `delivery_id`
+- 注册版本
+- token 指纹的短前缀
+- AID 的安全摘要或按现有诊断规范允许的 AID
+
+### 13.4 ACK 授权
+
+- ACK 使用 `_auth.aid`，不接受请求体自报的 Push Server AID。
+- ACK AID 必须与 batch 所有者一致。
+- delivery 必须属于指定 batch。
+- Push Server 只能影响自身 batch 和注册版本快照。
+
+## 14. 推荐配置
+
+以下为默认运行参数，不属于不可变协议：
+
+| 参数 | 默认值 | 说明 |
+| --- | ---: | --- |
+| `offline_grace_ms` | 2000 | 给在线事件和快速重连留出时间 |
+| `aggregate_window_ms` | 5000 | 同一目标聚合窗口 |
+| `target_cooldown_seconds` | 60 | 同一 AID 的最小通知间隔 |
+| `candidate_ttl_seconds` | 600 | 过时通知不再发送 |
+| `ack_timeout_seconds` | 30 | Push Server ACK 等待时间 |
+| `max_delivery_attempts` | 5 | delivery 最大尝试次数 |
+| `batch_size` | 100 | 单批最大 delivery 数 |
+| `max_event_bytes` | 524288 | 单事件最大字节数 |
+| `max_inflight_per_server` | 4 | 每 Push Server 并行批次 |
+| `registration_ttl_days` | 90 | 长期未刷新注册自动失效 |
+| `terminal_retention_days` | 7 | 终态诊断数据保留时间 |
+| `rate_limit_per_server_per_minute` | 1000 | 单 Push Server 保护 |
+| `rate_limit_global_per_minute` | 5000 | 服务整体保护 |
+
+## 15. 三中心纳管方案
+
+### 15.1 服务形态
+
+- 服务名：`push`
+- 目录：`extensions/services/push/`
+- runtime：`binary`
+- binary：`./go/bin/push-go`
+- 默认状态：enabled，由 managed desired-state 最终决定
+- 路由：Gateway service-plane `round_robin`，控制面限制集群单实例
+- 数据库：`aun_push`
+
+Push Service 只实现 Go 版本，不创建 `module.py.md` 或 Python Push Service。
+
+### 15.2 控制中心
+
+- 加入 managed service 集合。
+- 默认 `single_instance_required=true`。
+- 加入 protected single-instance 集合，V1 不允许管理员切换为 multi-active。
+- 按 `node_id + slot_id` desired-state 启停。
+- 节点迁移使用现有单实例停止、等待、再启动流程；数据库租约负责恢复未完成任务。
+
+### 15.3 注册中心
+
+- Push Service 通过注册中心发现唯一 Gateway 的 `business_ws`。
+- 不依赖 Push 所在节点的本机 Gateway。
+- 服务注册 actual state、健康状态、能力和可选 `diagnostics_http`。
+- Gateway 不存在时报告 `waiting_gateway`。
+- Gateway 数量大于 1 时报告 `blocked_gateway_multi_instance`。
+
+### 15.4 配置中心
+
+配置通过 `AUN_RESOLVED_CONFIG_JSON` 覆盖本地默认值，至少包含：
+
+- `db.*`
+- `enabled`
+- `allowed_push_server_aids`
+- token 密钥环和 active key ID
+- 聚合、频控、TTL、ACK 和重试参数
+- 诊断 HTTP 参数
+
+配置变更沿用现有 config revision 和 managed restart，不新增热更新协议。
+
+### 15.5 生命周期
+
+启动顺序：
+
+1. 读取 Launcher `boot_info`。
+2. 注册 Kernel 控制面能力。
+3. 解析 resolved config 并校验安全参数。
+4. 连接数据库并执行幂等 migration。
+5. 从注册中心发现 Gateway。
+6. 验证当前只有一个活动 Gateway。
+7. 连接 `/ws/service` 并完成 `service.attach`。
+8. 启动 RPC dispatcher、scheduler 和 diagnostics。
+9. 满足所有条件后发送 `module.ready`。
+
+停止顺序：
+
+1. 标记 draining，停止领取新候选和新 delivery。
+2. 调用 `service.drain` 使 Gateway 不再路由新 RPC。
+3. 等待当前 RPC、ACK 和数据库事务结束。
+4. 释放或缩短未完成租约。
+5. 停止 scheduler 和 diagnostics。
+6. 断开 Gateway、Kernel 和数据库。
+7. 上报 stop_ready。
+
+## 16. Gateway 改造
+
+Go Gateway 与 Python Gateway 必须同步修改，避免默认 Go 与显式 Python 回退产生协议差异。
+
+改动范围：
+
+- 将 `push` 加入业务 namespace。
+- 将 `push` 加入客户端默认直连 namespace。
+- 将 `push` 纳入通用业务背压和指标分类。
+- 允许 Push Service 调用 `gateway.query_sessions`。
+- 继续允许 Push Service 调用 `gateway.dispatch_event`、`gateway.health`、`gateway.status`。
+- 允许 `source_module=push` 发布 `push.offline_message`。
+- 校验 Push Service attach 声明了所调用的 Gateway methods。
+- 增加 Go/Python Gateway 契约对齐测试。
+
+Gateway 不增加 push 数据表、不解释 ACK、不解析 token、不实现 scheduler。
+
+## 17. Message / Group 接入
+
+### 17.1 接入点
+
+候选只能在消息已经形成可靠事实后产生：
+
+- P2P：目标域 Message 持久化成功后。
+- Group：Group 消息持久化并确定本域成员后。
+- Federation Group：目标域 relay 已通过可信 federation 校验后。
+
+验证失败、权限失败、限流拒绝、数据库回滚和 WAL 失败均不得产生候选。
+
+### 17.2 异步候选队列
+
+Message 和 Group 各自独立实现，不共享代码：
+
+- 有界容量。
+- 按 target AID 合并，保留最新唤醒提示。
+- 使用确定性 `candidate_id`。
+- Push Service 不可用时指数退避。
+- 超过候选 TTL 后终止。
+- queue depth、drop、retry、accepted 和 expired 均有指标。
+- 关闭时只做有界 drain，不阻塞服务无限退出。
+
+### 17.3 服务端 runtime 一致性
+
+Push Service 本身只实现 Go。Message / Group 的生产 Go runtime 必须接入候选；Python 服务端回退也应增加同一候选 adapter，防止切换 runtime 后离线推送功能无声消失。Python adapter 不是 Python Push Service。
+
+## 18. Python SDK 改造
+
+### 18.1 API
+
+新增 `PushFacade`：
+
+- `client.push.register(...)`
+- `client.push.unregister(...)`
+- `client.push.ack(...)`
+
+facade 只做参数整理和 `push.*` RPC 调用，不签发或解释 push token。
+
+### 18.2 事件
+
+Python transport 会把非 `app.*` 协议事件发布为 `_raw.<event>`。客户端增加内部订阅：
+
+```text
+_raw.push.offline_message → push.offline_message
+```
+
+Push Server 应通过公共事件注册回调。事件回调处理和 ACK 不能阻塞 transport WebSocket reader；必须沿用异步 dispatcher。
+
+### 18.3 其他 SDK
+
+Go、TypeScript 和 JavaScript SDK 本阶段不增加 facade、事件别名或测试。协议文档为仓库外 Rust SDK 提供实现依据。
+
+## 19. Python Mock Push Server
+
+Mock Push Server 是普通 AUN 客户端，不是三中心 managed service。
+
+### 19.1 功能
+
+- 使用固定 Push Server AID 连接目标 Gateway。
+- 订阅 `push.offline_message`。
+- 提供测试 HTTP 接口签发 HMAC mock token。
+- 验证 token 中的 target AID、device ID、slot ID 和签名。
+- 按 `delivery_id` 持久化去重。
+- 记录不含 token 的通知 JSONL。
+- 调用 `client.push.ack`。
+
+### 19.2 故障注入
+
+HTTP 控制面支持：
+
+- ACK 延迟。
+- 完全丢弃 ACK。
+- 指定 delivery 临时失败。
+- 指定 delivery 永久失败。
+- invalid token。
+- partial ACK。
+- 主动断开 AUN 连接。
+- 模拟重复事件。
+
+### 19.3 测试数据保护
+
+- Mock AID 使用独立固定 identity 目录。
+- 不得在测试脚本中自动执行 `setup_aids.py`。
+- 不得删除或重建既有 key、cert、key.json 或本地数据库。`key.json` 的解密 seed 在构造 `AIDStore`（或对应语言的 SDK 身份存储）时显式传入；身份目录不保存 seed，也不从 seed 文件恢复。
+- 首次需要新增 Mock AID 时必须获得明确授权后一次性创建。
+- Mock 只进入 Tester Compose，不进入生产 Compose。
+
+## 20. 可观测性
+
+### 20.1 状态
+
+Push Service 状态至少包括：
+
+- `initializing`
+- `waiting_database`
+- `waiting_gateway`
+- `blocked_gateway_multi_instance`
+- `ready`
+- `degraded`
+- `draining`
+
+### 20.2 指标
+
+至少提供：
+
+- 注册总数、启用数、过期数。
+- candidates accepted、deduped、rejected、expired。
+- online suppressed、no registration。
+- ready、dispatching、inflight、retry、permanent failed 数量。
+- backlog depth 和 oldest age。
+- Session query timeout/error。
+- dispatch delivered/deduped/failed。
+- ACK accepted、partial、duplicate、timeout、unauthorized。
+- 按 Push Server 的 in-flight、速率和最近在线时间。
+- token invalid 自动禁用次数。
+
+### 20.3 诊断日志
+
+每个状态转换记录：
+
+- trace ID。
+- candidate / batch / delivery ID。
+- 旧状态、新状态和原因。
+- attempt、next retry 和 elapsed time。
+- Gateway RPC 方法、结果类别和错误码。
+
+不得用 `except Exception: pass` 或等价方式静默吞异常。降级路径至少记录带上下文的 warning/error 和计数。
+
+## 21. 详细实施计划
+
+所有阶段使用 TDD：先建立失败测试，再实现最小功能，最后重构和运行受影响回归。不得先写完整实现再补测试。
+
+### Phase 0：协议与契约冻结
+
+目标：先把跨组件契约变成可执行测试，避免各模块自行理解字段。
+
+任务：
+
+1. 建立 `push.register/unregister/enqueue/ack` 请求和响应 fixtures。
+2. 建立 `event/push.offline_message` fixtures。
+3. 建立错误、部分 ACK、重复 ACK、token 失效 fixtures。
+4. 建立敏感字段扫描测试。
+5. 建立 Go Gateway、Python Gateway、Go Push、Python SDK 的契约加载测试。
+
+出口：
+
+- 所有新契约测试先红。
+- 字段、状态、幂等键和 normalized error 不再存在开放项。
+
+### Phase 1：Go Push Service 骨架与持久化
+
+目标：不接真实 Gateway，完成可单测的核心状态机。
+
+任务：
+
+1. 创建 `extensions/services/push/module.md` 和独立 Go module。
+2. 实现 boot_info、配置解析、日志和状态模型。
+3. 实现 MySQL schema 与幂等 migration。
+4. 实现注册、加密、版本更新和注销 repository。
+5. 实现 candidate 幂等入库。
+6. 实现 batch/delivery/lease 状态机。
+7. 使用 fake clock、fake Gateway 和内存 repository 测试 scheduler。
+8. 实现 token 日志脱敏测试。
+
+重点竞态测试：
+
+- 并发 register 版本递增。
+- unregister 与 batch 构建并发。
+- ACK 先于 dispatch 响应。
+- lease 过期恢复。
+- 旧 token invalid ACK 与新注册并发。
+
+出口：
+
+- 核心单元测试通过。
+- race test 通过。
+- 数据库 migration 可重复执行。
+
+### Phase 2：Gateway 路由与 ACL
+
+目标：客户端和服务均能通过现有 Gateway business plane 到达 Push Service。
+
+任务：
+
+1. Go Gateway 增加 namespace、直连、背压、ACL 和事件白名单测试。
+2. 实现 Go Gateway 最小修改。
+3. Python Gateway 增加同构测试和实现。
+4. 测试客户端不能伪造 `_caller_id`。
+5. 测试 Push Service 未声明 method 时 Gateway 拒绝调用。
+6. 测试 Push 事件只能由 attached module `push` 发布。
+7. 测试定向 connection ID 投递和 delivered=0。
+
+出口：
+
+- Go/Python Gateway 契约一致。
+- 现有 Message/Group/Storage/Service Proxy 路由回归通过。
+
+### Phase 3：Push Service 垂直闭环
+
+目标：通过真实 Gateway 完成注册、离线检查、事件和 ACK。
+
+任务：
+
+1. 实现 Gateway discovery，验证活动 Gateway 数量。
+2. 实现 `service.attach`、heartbeat、reconnect 和 drain。
+3. 实现客户端 RPC dispatcher。
+4. 实现 `gateway.query_sessions` 调用和保守失败策略。
+5. 实现 Push Server Session 选择。
+6. 实现 event dispatch、attempt event ID 和 ACK timeout。
+7. 实现并发 reader/pending response demux，避免 ACK 与 outgoing RPC 死锁。
+8. 实现 private diagnostics HTTP。
+
+出口：
+
+- 进程内 fake Gateway E2E 通过。
+- Gateway 断开重连后 backlog 继续处理。
+- shutdown/drain 无未关闭 goroutine 和悬挂租约。
+
+### Phase 4：Message / Group 候选接入
+
+目标：不改变消息主链结果的前提下产生正确候选。
+
+任务：
+
+1. 为 P2P V1/V2 写持久化成功/失败候选测试。
+2. 为 Group V1/V2 写本域成员 fanout 测试。
+3. 为 P2P federation 写“源域不 enqueue、目标域 enqueue”测试。
+4. 为 Group relay 写目标域成员 enqueue 和重放去重测试。
+5. 实现 Go Message / Group 异步候选队列。
+6. 实现 Python Message / Group 回退 adapter。
+7. 增加队列满、Push Service 不可用、退出 drain 和 TTL 测试。
+
+出口：
+
+- `message.send/group.send` 在 Push Service 不可用时仍按原契约成功。
+- 数据库回滚、权限失败和 validation error 不产生候选。
+- 每个目标每条逻辑消息只产生一个确定性 candidate。
+
+### Phase 5：Python SDK 与 Mock Push Server
+
+目标：形成可自动验证的端到端测试工具。
+
+任务：
+
+1. 先写 `PushFacade` API 单测。
+2. 写 `_raw.push.offline_message` 到公共事件的测试。
+3. 实现 facade 和 `client.push`。
+4. 实现 Mock token HTTP API。
+5. 实现事件处理、delivery 去重和 ACK。
+6. 实现故障注入和通知查询接口。
+7. 验证事件回调中调用 ACK 不阻塞 transport reader。
+
+出口：
+
+- Python SDK 单测通过。
+- Mock 的正常、partial、timeout、invalid token 和重复事件测试通过。
+
+### Phase 6：三中心纳管与 Docker
+
+目标：Push Service 能在默认、三节点、双域和线上镜像中被一致管理。
+
+任务：
+
+1. aun-console 加入 managed service、显示名称、business RPC 和配置 schema。
+2. 将 Push 设为 protected single-instance。
+3. Launcher 增加 Push 的 AUN drain 和 diagnostics credential 注入。
+4. Dockerfile 编译、复制并授权 `push-go`。
+5. `init.sql` 增加 `aun_push`。
+6. 默认 Compose、分布式 Compose、federation Compose 增加安全配置和 desired-state。
+7. 更新默认 Go manifest 测试，明确 Push 是 Go-only 服务。
+8. 更新服务端公网验收和部署材料校验列表。
+
+出口：
+
+- Compose config 静态检查通过。
+- 镜像内存在可执行 `push-go`。
+- aun-console 能展示、启停、迁移和读取 Push 状态。
+
+### Phase 7：单实例集成测试
+
+测试矩阵：
+
+1. 注册、重复注册、token 更新、注销。
+2. P2P V1 离线通知。
+3. P2P V2 离线通知。
+4. Group V1/V2 离线通知。
+5. 目标在线不通知。
+6. 多设备中任意设备在线不通知。
+7. 全部离线时为每个有效注册产生 delivery。
+8. 目标在聚合窗口内上线。
+9. Push Server 离线后恢复。
+10. partial ACK、ACK timeout 和 duplicate ACK。
+11. invalid token 禁用与重新注册。
+12. Push Service 重启恢复。
+13. Gateway 重启恢复。
+14. 通知 payload 无消息正文和密文。
+15. 目标重连后能 pull 到真实消息。
+
+每轮必须收集 Gateway、Push、Message/Group、Mock 和 Python SDK 日志，按 candidate/batch/delivery ID 串起调用链。
+
+### Phase 8：三节点与双域测试
+
+三节点：
+
+- Push desired-state 只在一个 node/slot 运行。
+- Push、Gateway、Message/Group 位于不同节点时链路正常。
+- 迁移 Push 节点后 backlog 继续处理。
+- Gateway 未启动时 Push 不进入 ready。
+- 多 Gateway 配置下 Push 明确阻断 dispatch。
+
+双域：
+
+- A 域发往 B 域的 P2P 只由 B 域 Push Server 收到。
+- B 域发往 A 域同理。
+- 跨域 Group 的每个域只处理本域成员。
+- 源域无法读取或收到目标域 token。
+- federation relay 重放不产生重复 delivery。
+
+### Phase 9：公网与负载验收
+
+公网：
+
+- Python Mock 使用测试 AID 连接公网 WSS。
+- 全链路启用 TLS 校验。
+- P2P、Group、注册、ACK 和重连均只通过公网协议完成。
+- 不读取远端 MySQL，不操作远端 Docker，不重启远端服务。
+
+负载与安全：
+
+- 大群 fanout 分批和公平性。
+- 慢 Push Server 不阻塞其他 Push Server。
+- backlog 上限、老化和清理。
+- 数据库连接耗尽和恢复。
+- Gateway query/dispatch 超时风暴。
+- token 和消息内容日志扫描。
+- Go race、vet、gofmt 和跨平台构建。
+
+### Phase 10：文档、灰度和回滚
+
+文档：
+
+- 重写 `docs/protocol/15-离线推送通知协议.md`。
+- 更新 Python SDK API/RPC 手册。
+- 更新默认、分布式和公网测试指南。
+- 同步根级和 SDK 文档索引。
+
+灰度顺序：
+
+1. 先部署 Gateway namespace、ACL 和事件兼容层。
+2. 部署 Push Service，保持 `enabled=false` 或白名单为空。
+3. 验证数据库、三中心纳管、status 和 diagnostics。
+4. 配置 Mock Push Server 白名单，验证注册和手工 enqueue。
+5. 启用 Message 候选。
+6. 启用 Group 候选。
+7. 观察 backlog、ACK、timeout 和 token invalid 指标。
+8. 再加入真实 Push Server AID。
+
+回滚：
+
+- 关闭 Message / Group 的 `offline_push_enabled`。
+- 通过 desired-state 停止 Push Service。
+- 保留 `aun_push` 数据库、注册、固定身份和加密密钥。
+- Gateway namespace/ACL 和 Python SDK facade 均为加法变更，无需删除。
+- 严禁通过清库、删除身份或重建 AID 完成回滚。
+
+## 22. 实施审批点
+
+正式编码前需要明确授权：
+
+1. 新增 `push.register`、`push.unregister`、`push.enqueue`、`push.ack`。
+2. 新增 `event/push.offline_message`。
+3. 修改 Go/Python Gateway 的业务 namespace、路由和 ACL。
+4. 修改 Launcher 的 AUN drain 与 diagnostics 服务集合。
+5. 首次创建 Mock Push Server 固定 AID 身份材料。
+
+上述授权不扩大到删除身份、清理数据库、重写 Git 历史或启动 Kite 测试环境。
+
+## 23. 关键源码与文档索引
+
+- 历史协议：`docs/protocol/15-离线推送通知协议.md`
+- 默认测试指南：`docs/aun测试运行指南.md`
+- 分布式测试指南：`docs/aun分布式测试运行指南.md`
+- 公网测试指南：`docs/aun公网测试运行指南.md`
+- Go Gateway：`../extensions/services/gateway/go/internal/httpserver/server.go`
+- Python Gateway：`../extensions/services/gateway/service_plane.py`、`../extensions/services/gateway/ws_server.py`
+- Message Go：`../extensions/services/message/go/`
+- Group Go：`../extensions/services/group/go/`
+- aun-console：`../extensions/services/aun_console/`
+- Launcher：`../launcher/entry.py`、`../launcher/process_manager.py`
+- Python SDK：`python/src/aun_core/client.py`、`python/src/aun_core/facades.py`、`python/src/aun_core/transport.py`
+- Docker：`../docker-deploy/Dockerfile`、`../docker-deploy/docker-compose.yml`、`../docker-deploy/docker-compose.distributed.yml`