瀏覽代碼

docs: 后台推送具体操作步骤(分阶段、含命令与验收)

Co-Authored-By: Claude Code <noreply@anthropic.com>
Huccct 3 小時之前
父節點
當前提交
0e7899c560
共有 1 個文件被更改,包括 309 次插入 和 0 次删除
  1. 309 0
      docs/02-design/plans/后台推送-具体操作步骤-20261118.md

+ 309 - 0
docs/02-design/plans/后台推送-具体操作步骤-20261118.md

@@ -0,0 +1,309 @@
+# 后台推送:具体操作步骤(可照做)
+
+> 2026-11-18 · 基于当前代码实际状态编写,每步含**命令/入口/验收方式**。
+
+---
+
+## 现状速览
+
+| 项 | 状态 |
+|---|---|
+| 推送代码(原生插件 + 前端) | ✅ 已写完,10 个组件齐全 |
+| Gradle 开关 `fmodeJpushEnabled` | ⚠️ 默认 `false` |
+| 前端开关 `JPUSH_OPTIONS.enabled` | ⚠️ 硬编码 `false` |
+| 极光 AppKey | ❌ 没有 |
+| 厂商通道证书 | ❌ 没有 |
+| 服务端推送链路 | ❌ 没有 |
+| 别名签发后台 | ❌ 没有 |
+| 隐私同意 UI | ❌ 没接入 |
+
+**当前 APK 不含推送 SDK**,权限干净,不会申请定位/电话/存储。
+
+---
+
+# 第一阶段:App 侧配置(我能做,需要你先给 AppKey)
+
+## 步骤 1:注册极光账号拿 AppKey
+
+**你要做的:**
+
+1. 打开 https://www.jiguang.cn ,注册(建议企业账号)
+2. 登录后 → 「创建应用」
+3. 填写:
+   - **应用名称**:`Fmode`
+   - **Android 包名**:`cn.fmode.app` ⚠️ **必须一字不差**
+4. 创建成功后,在应用详情页找到:
+   - **AppKey**(形如 `1a2b3c4d5e6f7a8b9c0d1e2f`)
+   - **Master Secret**(服务端调 API 用,**不要放进前端**)
+
+**验收**:你能看到一个 24 位左右的 AppKey。
+
+**然后告诉我 AppKey**,接下来的步骤我来做。
+
+---
+
+## 步骤 2:我配置 App 构建(约 30 分钟)
+
+拿到 AppKey 后我会做这些:
+
+### 2.1 打开 Gradle 开关
+
+`android/gradle.properties` 追加:
+```properties
+fmodeJpushEnabled=true
+```
+
+AppKey 通过环境变量传入(**不写进仓库**):
+```bash
+export JPUSH_APPKEY=<你给的 AppKey>
+```
+
+### 2.2 打开前端开关
+
+`src/app/core/jpush.plugin.ts` 第 36 行:
+```typescript
+factory: () => ({ enabled: false }),   // 改成 true
+```
+
+### 2.3 接入隐私同意 UI
+
+推送 SDK 启动前**必须**用户同意(代码已强制门控):
+
+```
+JPushPlugin.allowed() =
+    BuildConfig.JPUSH_ENABLED === true
+ && SharedPreferences("fmode-jpush").getBoolean("consent", false)
+```
+
+我会在「我的 → 通知」页加一个开关:
+```
+[ ] 开启后台消息推送
+    开启后可在地关闭 App 时收到新消息提醒
+```
+
+用户打开时调用 `push.start(true)`(传 `privacyConsent: true`)。
+
+### 2.4 构建验证
+
+```bash
+export JPUSH_APPKEY=<AppKey>
+pnpm run build && npx cap sync android
+cd android && ./gradlew assembleDebug
+```
+
+**验收**:
+```bash
+# APK 内应出现 JPush 类
+unzip -l android/app/build/outputs/apk/debug/app-debug.apk | grep -ci jiguang
+# 应 > 0
+```
+
+---
+
+# 第二阶段:厂商通道(你做,1-2 周,⭐ 最慢,先启动)
+
+**为什么必须**:没有厂商通道,App 被系统杀掉后**极光也推不到**。
+
+## 步骤 3:申请厂商推送服务
+
+按优先级申请(先做华为 + 小米,覆盖大部分用户):
+
+### 华为推送(1-2 周,需企业认证)
+
+1. 打开 https://developer.huawei.com ,注册开发者
+2. 完成**企业实名认证**(需要营业执照)
+3. 控制台 → 「我的项目」→ 创建项目 → 添加应用
+   - 包名:`cn.fmode.app`
+   - 上传**签名证书指纹**(需要你的 APK 签名,我可以帮你取)
+4. 开通「Push Kit」服务
+5. 记录:**AppID**、**AppSecret**
+
+### 小米推送(1-3 天)
+
+1. 打开 https://dev.mi.com ,注册开发者
+2. 控制台 → 消息推送 → 创建应用
+   - 包名:`cn.fmode.app`
+3. 记录:**AppID**、**AppKey**、**AppSecret**
+
+### OPPO / vivo(各 3-5 天,可选)
+
+同理,需要企业认证。
+
+## 步骤 4:把厂商凭证填进极光
+
+**你要做的:**
+
+极光控制台 → 你的应用 → 「应用设置」→「厂商通道」
+逐个填入上一步拿到的凭证。
+
+**验收**:极光控制台显示各厂商通道状态为「已开启」。
+
+---
+
+# 第三阶段:服务端开发(平台做,5-10 天)
+
+**这是最关键、也最缺的一环。** 可以和第二阶段的厂商审核**并行**。
+
+## 步骤 5:别名签发后台
+
+**目标**:让服务端知道「哪个用户 → 哪台设备」。
+
+### 接口设计
+
+```
+POST /api/bind-push-alias
+Header: X-Parse-Session-Token: <用户token>
+Body: { alias: "fm_<32位hex>", registrationId: "<极光返回的>" }
+
+响应: { code: 200 }
+```
+
+### 数据表
+
+```sql
+CREATE TABLE PushBinding (
+  userId         TEXT PRIMARY KEY,
+  alias          TEXT NOT NULL,
+  registrationId TEXT NOT NULL,
+  updatedAt      TIMESTAMP
+);
+```
+
+### 别名格式约束(代码已强制)
+
+`src/app/core/jpush.service.ts` 要求:
+```typescript
+/^fm_[a-f0-9]{32,60}$/
+```
+
+所以别名必须是 `fm_` + 32~60 位十六进制。
+
+### App 侧要配合的(我来写)
+
+用户登录成功后:
+```typescript
+const registrationId = await push.getRegistrationId();
+const alias = 'fm_' + hash(userId);   // 稳定、不可反推
+await fetch('/api/bind-push-alias', { ... });
+```
+
+用户登出时调 `push.unbindAccount()`(代码已实现)。
+
+**验收**:
+```bash
+# 登录 App 后,数据库应出现一条 PushBinding 记录
+```
+
+---
+
+## 步骤 6:服务端监听 Matrix → 推送
+
+### 架构
+
+```
+常驻进程(Node/Python 均可)
+   │
+   ├─ 用 Matrix Application Service 或 /sync 长轮询
+   │     监听所有用户的房间新消息
+   │
+   ├─ 判断「这条消息的接收者是谁」
+   │     排除自己发的、排除容器自己的回显
+   │
+   ├─ 查 PushBinding:userId → alias
+   │
+   └─ POST https://api.jpush.cn/v3/push
+```
+
+### 推送 API 示例
+
+```bash
+curl -X POST https://api.jpush.cn/v3/push \
+  -H "Authorization: Basic $(echo -n 'APPKEY:MASTER_SECRET' | base64)" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "platform": "android",
+    "audience": { "alias": ["fm_a1b2c3d4e5f6..."] },
+    "notification": {
+      "alert": "容器回复了你的消息",
+      "title": "Fmode",
+      "android": { "extras": { "fmodeJpushPayload": "{\"sessionId\":\"...\"}" } }
+    },
+    "options": { "time_to_live": 86400 }
+  }'
+```
+
+> ⚠️ `extras.fmodeJpushPayload` 这个 key **必须一致** —— App 端 `JPushClickActivity`
+> 靠它解析点击后跳转到哪个会话。
+
+**验收**:
+```bash
+# 手动调一次推送 API,手机应收到通知
+```
+
+---
+
+# 第四阶段:联调验收
+
+## 步骤 7:逐场景测试
+
+| # | 场景 | 预期 | 由谁测 |
+|---|---|---|---|
+| 1 | App 在前台收到消息 | 通知出现 | 你 |
+| 2 | App 切后台 1 分钟 | 通知出现 | 你 |
+| 3 | App 切后台 30 分钟 | 通知出现 | 你 |
+| 4 | App 被划掉(进程杀掉) | **通知出现**(需厂商通道) | 你 |
+| 5 | 手机重启后 | 通知出现 | 你 |
+| 6 | 点通知 | 拉起 App + 跳到对应会话 | 你 |
+| 7 | 换账号登录 | 收不到前一个账号的消息 | 你 |
+| 8 | 关闭推送开关 | 收不到任何推送 | 你 |
+
+---
+
+# 总览:谁做什么、要多久
+
+| 步骤 | 内容 | 谁 | 耗时 | 能否并行 |
+|---|---|---|---|---|
+| 1 | 注册极光拿 AppKey | **你** | 1 小时 | — |
+| 2 | App 构建配置 | 我 | 30 分钟 | 等步骤 1 |
+| 3 | **申请厂商通道** | **你** | **1-2 周** ⭐ | ✅ 可与其他并行 |
+| 4 | 厂商凭证填极光 | 你 | 10 分钟 | 等步骤 3 |
+| 5 | 别名签发后台 | 平台 | 3-5 天 | ✅ 可与步骤 3 并行 |
+| 6 | 服务端推送链路 | 平台 | 5-10 天 | ✅ 可与步骤 3 并行 |
+| 7 | 联调验收 | 你 + 我 | 1 天 | 等前面全部完成 |
+
+### 关键路径
+
+```
+步骤 3(厂商通道 1-2 周)
+   ↓
+步骤 4 → 步骤 7(联调)
+```
+
+**建议:立刻启动步骤 3 的华为认证**,因为它是唯一卡 1-2 周的环节。
+步骤 1/5/6 都可以在这期间并行完成。
+
+---
+
+# 如果暂时不做
+
+建议先把「我的 → 通知」的文案改准确,避免用户困惑:
+
+```
+消息通知仅在 App 打开时生效。
+关闭 App 后将无法收到新消息提醒。
+```
+
+**要我现在就改这个文案吗?** 一句话的事,能让用户明白限制。
+
+---
+
+# 附:常见坑
+
+| 坑 | 影响 | 怎么避 |
+|---|---|---|
+| 包名不一致 | 完全收不到 | 极光后台填 `cn.fmode.app`,一字不差 |
+| 华为需企业认证 | 做不了 | 提前准备营业执照 |
+| 忘了清理别名 | 换账号收到前一个人的消息 | 登出时调 `unbindAccount()`(已实现) |
+| 只配华为没配小米 | 小米手机收不到 | 各厂商要逐个配 |
+| `fmodeJpushPayload` key 写错 | 点通知跳转失败 | 与 `JPushClickActivity` 的 `CLICK_EXTRA` 保持一致 |
+| 极光免费版限流 | 推送失败 | 商用需付费版 |