Forráskód Böngészése

docs: 后台推送完整实施指南

用户要求先记录、暂不实施。本文档供后续启动时直接照着做。

内容:
- 现状:为什么后台收不到(Android 暂停 WebView JS,非 bug)
- 完整链路图,标出缺的 3 环
- 已完成的 10 个组件(代码已就绪,默认关闭)
- 需要用户做的 2 件事:极光 AppKey(1 小时)、厂商通道(1-2 周,最慢)
- 需要平台做的 2 件事:服务端推送链路(5-10 天)、别名签发后台(3-5 天)
- 依赖关系与并行建议(厂商通道是关键路径,应最先启动)
- 验收标准、7 个常见坑

Co-Authored-By: Claude Code <noreply@anthropic.com>
Huccct 3 órája
szülő
commit
301d653266

+ 228 - 0
docs/02-design/plans/后台推送-完整实施指南-20261118.md

@@ -0,0 +1,228 @@
+# 后台推送:完整实施指南(需你做哪些操作)
+
+> 2026-11-18 整理。**当前状态:代码已就绪,但整条链路未打通。**
+> 用户裁决:暂不做,先记录。本文档供后续启动时直接照着做。
+
+---
+
+## 一、先说清楚:现在为什么收不到
+
+### 现象
+
+| 场景 | 能否收到通知 |
+|---|---|
+| App 在前台 | ✅ |
+| 切走后几秒内 | ⚠️ 不稳定 |
+| **后台超过 1-2 分钟** | ❌ |
+| App 被杀 / 重启后 | ❌ |
+
+### 根因
+
+Android 系统在 App 进入后台后会**暂停 WebView 的 JavaScript 执行**。
+App 里的 `TaskPulseService` 靠定时轮询检测「容器是否回复了」,轮询一停就什么都收不到。
+
+**这不是 bug,是 Android 的省电机制。** 唯一解法是**服务端主动推送**。
+
+### 完整链路(缺 3 环)
+
+```
+容器回复
+   ↓
+Matrix 事件
+   ↓
+【缺失 ①】某个后端常驻服务监听 Matrix 新消息
+   ↓
+【缺失 ②】根据收件人找到设备推送 ID → 调极光推送 API
+   ↓
+极光服务器
+   ↓
+【缺失 ③】厂商通道(华为/小米/OPPO/vivo)— 保证 App 被杀也能收到
+   ↓
+用户手机
+```
+
+---
+
+## 二、已经做完的部分(不用你管)
+
+| 组件 | 文件 | 状态 |
+|---|---|---|
+| Capacitor 桥接插件 | `JPushPlugin.java` | ✅ 已实现 |
+| SDK 适配层 | `JPushSdk.java` | ✅ 已实现 |
+| 消息接收器 | `JPushReceiver.java` | ✅ 已实现 |
+| 点击落地 Activity | `JPushClickActivity.java` | ✅ 已实现 |
+| 前台服务 | `JPushService.java` | ✅ 已实现 |
+| 隔离 Manifest(裁掉多余权限) | `android/app/src/jpush/AndroidManifest.xml` | ✅ 已实现 |
+| 前端状态机 | `src/app/core/jpush.service.ts` | ✅ 已实现 |
+| 生命周期钩子 | `src/app/core/jpush.lifecycle.ts` | ✅ 已实现 |
+| Gradle 开关 | `android/app/build.gradle` | ✅ 已实现(默认关) |
+| 隐私同意门控 | `JPushPlugin.allowed()` | ✅ 已实现 |
+
+**当前 APK 里不含推送 SDK**(`fmodeJpushEnabled=false`),权限清单干净,
+不会申请定位/电话/存储等敏感权限。
+
+---
+
+## 三、需要你做的事(按顺序)
+
+### 第 1 步:注册极光账号,拿 AppKey(约 1 小时)
+
+1. 打开 https://www.jiguang.cn ,注册企业账号
+2. 控制台 → 创建应用
+   - 应用名:`Fmode`
+   - 包名:**`cn.fmode.app`**(必须完全一致,否则收不到)
+3. 记下 **AppKey**(形如 `1a2b3c4d5e6f7g8h9i0j1k2l`)
+
+**完成后告诉我 AppKey**,我帮你配进构建。
+
+---
+
+### 第 2 步:申请厂商通道(最慢,1-2 周)
+
+**为什么必须做**:没有厂商通道,App 被系统杀掉后极光也推不到。
+
+需要逐个申请:
+
+| 厂商 | 入口 | 需要什么 | 耗时 |
+|---|---|---|---|
+| **华为** | developer.huawei.com → 推送服务 | **企业认证**(营业执照) | 1-2 周 |
+| **小米** | dev.mi.com → 推送 | 开发者账号 | 1-3 天 |
+| **OPPO** | open.oppomobile.com → 推送 | 企业认证 | 3-5 天 |
+| **vivo** | dev.vivo.com.cn → 推送 | 企业认证 | 3-5 天 |
+
+每个厂商申请完会给你:
+- `AppID`
+- `AppSecret`
+- `AppKey`(厂商自己的)
+
+**这些填到极光控制台** → 你的应用 → 厂商通道配置。
+
+> 💡 **可以先只做华为 + 小米**(覆盖大部分安卓用户),其余后续补。
+
+---
+
+### 第 3 步:配置隐私同意 UI(App 侧,我来做)
+
+推送 SDK 启动了就必须有用户同意。当前代码已实现门控:
+
+```typescript
+// JPushPlugin.allowed() 检查:
+BuildConfig.JPUSH_ENABLED === true
+  && SharedPreferences("fmode-jpush").getBoolean("consent", false)
+```
+
+**需要补的**:一个「开启推送通知」的开关界面(可以复用现有的通知权限引导弹层)。
+
+这一步**我来写**,你确认界面文案即可。
+
+---
+
+### 第 4 步:开发服务端推送链路(平台来做,5-10 天)
+
+**这是最关键、也最缺的一环。**
+
+需要一个常驻服务,做两件事:
+
+```
+① 监听 Matrix 新消息
+   · 用 Matrix 应用服务(Application Service)或长轮询 /sync
+   · 识别「接收方是谁」
+
+② 调极光推送 API
+   POST https://api.jpush.cn/v3/push
+   Header: Authorization: Basic base64(AppKey:MasterSecret)
+   Body: {
+     "platform": "android",
+     "audience": { "alias": ["<用户ID>"] },
+     "notification": { "alert": "容器回复了", "title": "Fmode" },
+     "options": { "apns_production": false }
+   }
+```
+
+**依赖第 5 步的别名系统**。
+
+---
+
+### 第 5 步:开发别名签发后台(平台来做,3-5 天)
+
+极光用「别名(alias)」识别设备。需要:
+
+```
+用户登录 App
+   ↓
+App 调极光 SDK 拿到 registrationId
+   ↓
+App 调你的接口:POST /api/bind-push-alias
+   { alias: "fm_<32位hash>", registrationId: "..." }
+   ↓
+服务端存表:userId ↔ alias ↔ registrationId
+   ↓
+推送时:userId → alias → 极光推送
+```
+
+**当前代码已有约束**:别名必须匹配 `/^fm_[a-f0-9]{32,60}$/`(见 `jpush.service.ts`),
+所以别名格式要按这个来。
+
+---
+
+## 四、总工作量与顺序
+
+| 步骤 | 谁做 | 耗时 | 能否并行 |
+|---|---|---|---|
+| 1. 极光 AppKey | **你** | 1 小时 | — |
+| 2. 厂商通道 | **你** | 1-2 周 | ✅ 可与 4/5 并行 |
+| 3. 隐私同意 UI | 我 | 0.5 天 | 等 1 完成 |
+| 4. 服务端推送链路 | 平台 | 5-10 天 | ✅ 可与 2 并行 |
+| 5. 别名签发后台 | 平台 | 3-5 天 | ✅ 可与 4 并行 |
+
+**关键路径**:第 2 步(厂商通道)最慢,**应该最先启动**。
+
+---
+
+## 五、如果暂时不做
+
+建议在 App 里明确告知用户,避免「为什么收不到消息」的困惑:
+
+```
+消息通知仅在 App 打开时生效。
+关闭 App 后将无法收到新消息提醒,请保持 App 在后台运行。
+```
+
+这个提示我可以加到「我的 → 通知」页面。
+
+---
+
+## 六、验收标准
+
+全部完成后,以下场景都应收到通知:
+
+| 场景 | 预期 |
+|---|---|
+| App 在前台 | ✅ 收到 |
+| App 切后台 1 分钟 | ✅ 收到 |
+| App 切后台 30 分钟 | ✅ 收到 |
+| App 被划掉(进程杀掉) | ✅ 收到(**需厂商通道**) |
+| 手机重启后 | ✅ 收到 |
+| 点击通知 | ✅ 拉起 App 并跳到对应会话 |
+
+---
+
+## 七、常见坑(提前知道)
+
+| 坑 | 说明 |
+|---|---|
+| **包名不一致** | 极光后台填的包名必须与 `cn.fmode.app` 完全一致 |
+| **华为需企业认证** | 没有营业执照做不了,个人账号不行 |
+| **极光免费版有频率限制** | 免费版每天推送次数有限,商用需付费 |
+| **别名要清理** | 用户登出时调 `deleteAlias`,否则换账号会收到前一个人的消息(代码已实现 `unbindAccount()`) |
+| **厂商通道要逐个开** | 只配华为不代表小米能收到 |
+
+---
+
+## 八、现在能立刻做的一件事
+
+如果你暂时不想投入 2 周等厂商审核,可以**先只做「前台通知」的产品化说明**:
+
+在「我的 → 通知」页把文案改成准确的描述,让用户知道限制。
+
+**要我改吗?** 一句话的事。