152 lines
7.3 KiB
Markdown
152 lines
7.3 KiB
Markdown
# Client User Identity｜客户端用户标识建立（用于 PUSH Token 绑定）｜Spec
|
||
|
||
> 阶段：高层规范（spec）
|
||
>
|
||
> 目标：在**无账号体系或账号可选**的前提下，为客户端生成一个稳定的“客户端用户标识”（下称 `client_user_id`），用于与 APNs/FCM 的 Push Token 建立绑定关系，便于后端精准下发 PUSH，并支持 Token 变更/多设备/环境隔离等场景。
|
||
|
||
---
|
||
|
||
## 1. 背景与动机（摘要）
|
||
|
||
Push Token（APNs device token / FCM registration token）会发生变化（重装、系统升级、重新授权、token rotate 等），且同一用户可能多设备。为了能稳定地“找到这个客户端实例/用户侧主体”并维护 Token 映射，需要一个**与 Token 解耦**、可持久化、不可推断的标识。
|
||
|
||
---
|
||
|
||
## 2. 目标（Goals）
|
||
|
||
- **建立 `client_user_id`**：客户端可生成并持久化一个稳定标识，作为后端 Push Token 绑定的主键之一。
|
||
- **Token 绑定可更新**：支持 Token 变更时“同一 `client_user_id` 重新上报即可更新”。
|
||
- **多设备兼容**：同一个账号（若未来引入）可关联多个 `client_user_id`；一个 `client_user_id` 可存在多个 Token（例如同设备多渠道/多应用包形态）时需可扩展。
|
||
- **环境隔离**：dev/prod、iOS/Android、bundle id / package name 维度隔离，避免串绑。
|
||
- **隐私友好**：不使用可追踪的硬件标识（IMEI/IDFA/Android ID 等），不引入额外合规风险。
|
||
|
||
---
|
||
|
||
## 3. 非目标（Non-goals）
|
||
|
||
- 不在本阶段引入完整账号体系、登录态、用户合并策略（如“同一人多设备合并为一个 user_id”）。
|
||
- 不在本阶段强制接入设备证明（App Attest/Play Integrity）；仅在安全章节提出可选增强方向。
|
||
- 不定义具体数据库表结构与迁移脚本（属于 plan 阶段细化）。
|
||
|
||
---
|
||
|
||
## 4. 术语与对象（Definitions）
|
||
|
||
- **`client_user_id`**：客户端生成并持久化的随机标识，代表“一个客户端安装实例（或一段时间内的用户侧主体）”，用于 Push 绑定。
|
||
- **`push_token`**：系统/厂商下发的推送 token（iOS/APNs，Android/FCM），可能变化。
|
||
- **`account_id`（可选）**：若未来存在登录账号，则用于把多个 `client_user_id` 归属到同一账号。
|
||
|
||
---
|
||
|
||
## 5. 关键决策：使用 UUID 做 `client_user_id` 是否合适？
|
||
|
||
结论：**合适**，推荐用**随机 UUID（UUID v4 为默认）**，并把它当作后端与客户端都不解析的**不透明字符串**。
|
||
|
||
### 5.1 为什么 UUID 合适
|
||
|
||
- **唯一性足够**：v4 基于随机数，碰撞概率极低，满足全局唯一需求。
|
||
- **不可推断**：相较自增 ID，不易被枚举；相较设备硬件标识，更隐私友好。
|
||
- **跨端易实现**：iOS/Android/JS 都可稳定生成与序列化（字符串）。
|
||
|
||
### 5.2 需要明确的边界与注意事项
|
||
|
||
- **UUID 不等于“真实用户”**：它更像“安装实例 ID”。用户重装/清数据后可能变化；这对 Push 绑定通常可接受（新装产生新 token 与新 id）。
|
||
- **不要用设备硬件/系统可追踪 ID 替代**：避免隐私与合规风险，也避免系统限制导致的不稳定。
|
||
- **安全边界**：如果后端完全信任客户端上报的 `client_user_id`，存在“伪造绑定”风险；应结合登录态或签名/证明（见第 9 节）降低滥用。
|
||
|
||
### 5.3 UUID 版本建议
|
||
|
||
- **默认**：UUID v4（实现最简单、兼容最好）。
|
||
- **可选增强**：UUID v7（有时间有序性，利于日志/索引与写入局部性），但需要确保两端实现一致与依赖可控。
|
||
|
||
---
|
||
|
||
## 6. 客户端行为规范（Client Contract）
|
||
|
||
### 6.1 生成与持久化
|
||
|
||
- 首次启动（或首次需要注册 Push 时）：
|
||
- 若本地不存在 `client_user_id`：生成一个新的 UUID（字符串），写入持久化存储。
|
||
- 若已存在：直接复用。
|
||
- 存储建议（不做强约束，但必须“尽量稳定”）：
|
||
- iOS：Keychain
|
||
- Android：Keystore 保护的加密存储/SharedPreferences（或等价方案）
|
||
- React Native/Expo：使用安全存储能力（例如 SecureStore/Keychain wrapper）
|
||
|
||
### 6.2 Push Token 获取与上报时机
|
||
|
||
- 在以下任一时机触发“注册/更新”：
|
||
- 用户同意 Push 权限后获得 token
|
||
- App 冷启动获取到 token（含 token 变更）
|
||
- 账号登录/登出（若存在账号）
|
||
- 环境切换（dev/prod）或应用更新（可选）
|
||
|
||
---
|
||
|
||
## 7. 后端接口契约（API Contract，摘要）
|
||
|
||
> 具体路由/鉴权方式在 plan 阶段落地；此处先定义字段语义与幂等行为。
|
||
|
||
### 7.1 注册/更新绑定
|
||
|
||
- `POST /v1/push/register`
|
||
- 请求体（最小集）：
|
||
- `client_user_id`: string（UUID 字符串）
|
||
- `platform`: `"ios" | "android"`
|
||
- `push_token`: string
|
||
- `app_id`: string（bundle id / package name，用于隔离）
|
||
- `env`: `"dev" | "prod"`
|
||
- （可选）`account_id`: string
|
||
- （可选）`device_meta`: `{ model, os_version, app_version, locale, timezone }`
|
||
- 行为要求（幂等）：
|
||
- 以 `push_token + env + app_id` 维度做唯一性约束，避免重复记录。
|
||
- 若同一 `client_user_id` 上报了新 token：应更新/新增映射，旧 token 进入失效或保留历史（由实现决定，但必须可控）。
|
||
|
||
### 7.2 解绑（可选但建议）
|
||
|
||
- `POST /v1/push/unregister`
|
||
- 请求体：
|
||
- `client_user_id`
|
||
- `platform`
|
||
- `push_token`（或让后端按 `client_user_id` 批量解绑，二选一）
|
||
- `app_id`
|
||
- `env`
|
||
|
||
---
|
||
|
||
## 8. 数据模型（逻辑约束）
|
||
|
||
最小需要表达的关系：
|
||
|
||
- 一个 `client_user_id` 可对应 0..N 个 `push_token`（考虑多端、多渠道、token rotate）。
|
||
- 一个 `push_token` 在同一 `env + app_id` 下应只对应一个“当前归属”（避免重复推送）。
|
||
- 若存在 `account_id`：
|
||
- 一个 `account_id` 可关联 0..N 个 `client_user_id`（多设备）。
|
||
|
||
---
|
||
|
||
## 9. 安全与滥用防护（高层约束）
|
||
|
||
- **最小要求**：接口需具备基本鉴权与频率限制（例如基于设备指纹/匿名 session/应用侧签名的任一组合），避免被脚本批量绑定垃圾 token。
|
||
- **若存在登录态**：推荐绑定写入需要登录态（或在登录后把 `client_user_id` 归属到 `account_id`），降低“抢绑”风险。
|
||
- **可选增强（后续）**：接入 iOS App Attest / Android Play Integrity，或对注册请求做一次性挑战签名。
|
||
|
||
---
|
||
|
||
## 10. 边界场景与处理原则
|
||
|
||
- **用户拒绝 Push 权限**：允许只有 `client_user_id`，不产生 token 绑定；后端不应报错。
|
||
- **token 变化**：客户端重新调用 `register`，后端必须幂等更新，避免重复推送。
|
||
- **重装/清数据**：`client_user_id` 变化可接受；若未来有 `account_id`，可在登录后重新建立关联。
|
||
- **多环境**：dev/prod token 不可混用；必须以 `env + app_id` 隔离。
|
||
|
||
---
|
||
|
||
## 11. 验收标准（Acceptance Criteria）
|
||
|
||
- 客户端能稳定生成并持久化 `client_user_id`（重复启动不变）。
|
||
- 在 token 获取/变更后，调用注册接口可在后端建立（或更新）绑定关系，且接口幂等。
|
||
- 同一 `push_token` 在同一 `env + app_id` 下不会产生多条“当前有效”绑定，避免重复推送。
|
||
- 在用户拒绝 Push 权限、无 token 的情况下，不影响 App 正常使用与后续再次授权后的绑定。
|
||
|