fix: normalize jpush aliases

docs/third/IM-极光推送前后端对接文档.md

@@ -24,7 +24,15 @@
 - iOS：配置 APNs 证书或 Token Authentication，申请通知权限。
 - HarmonyOS：按鸿蒙 SDK 文档初始化并配置通知分类。
 
-客户端启动后取得 `registration_id`，登录 IM 后把 alias 绑定为当前 `user_id`。同一用户多设备允许绑定同一个 alias。
+客户端启动后取得 `registration_id`，登录 IM 后把 alias 绑定为当前 `user_id` 的极光安全别名。同一用户多设备允许绑定同一个 alias。
+
+极光 alias 不支持中横线 `-` 和下划线 `_`，而 IM `user_id` 可能包含这两个字符。客户端和后端统一使用以下映射：
+
+```text
+jpush_alias = user_id.replace("-", ".").replace("_", "|")
+```
+
+示例：`usrd6Ag5opa-ww` 对应极光 alias `usrd6Ag5opa.ww`。
 
 ### 2.2 上报 Push Token
 
@@ -306,7 +314,7 @@ Content-Type: application/json
 | 步骤 | 操作 | 验证 |
 | --- | --- | --- |
 | 1 | 客户端初始化 JPush SDK | 能拿到 `registration_id`。 |
-| 2 | 登录 IM 并绑定 alias=`user_id` | 极光控制台能查到别名或设备。 |
+| 2 | 登录 IM 并绑定 alias=`user_id.replace("-", ".").replace("_", "|")` | 极光控制台能查到别名或设备。 |
 | 3 | 调用设备上报接口 | 服务端设备记录 provider=`jpush`。 |
 | 4 | 目标用户退出或断网 | IM 判断为离线或不可 WS 投递。 |
 | 5 | 发送 P2P 消息 | 离线用户收到 Push。 |

docs/third/IM-极光推送完整调用流程.md

@@ -42,7 +42,7 @@
 | `jpush_apns_production` | `false/true` | iOS APNs 环境，测试包用 false，生产包用 true。 |
 | `jpush_default_ttl_seconds` | `86400` | 离线 Push 默认保留时长。 |
 | `jpush_call_ttl_seconds` | `60` | 来电 Push 保留时长，建议短一些。 |
-| `jpush_use_alias` | `true` | 是否优先使用 alias=user_id 投递。 |
+| `jpush_use_alias` | `true` | 是否优先使用极光安全 alias 投递。 |
 | `jpush_test_model` | `false` | 极光测试模式，仅联调测试设备时开启。 |
 | `jpush_classification` | `1` | 重要业务通知建议按系统消息分类处理，需结合厂商通道规则确认。 |
 | `jpush_log_payload` | `false` | 生产关闭 payload 明文日志，避免敏感信息进入日志。 |
@@ -59,7 +59,7 @@
 2. 初始化 SDK 使用 `jpush_app_key`。
 3. 申请系统通知权限。
 4. 取得 `registration_id`。
-5. 登录 IM 后绑定 alias，建议 alias 使用当前 IM `user_id`，例如 `usr...`。
+5. 登录 IM 后绑定 alias。极光 alias 不支持中横线 `-` 和下划线 `_`，客户端必须将当前 IM `user_id` 转成极光安全别名：`user_id.replace("-", ".").replace("_", "|")`。示例：`usrd6Ag5opa-ww` 对应 `usrd6Ag5opa.ww`。
 6. 调用 IM 后端设备接口上报 Push Token。
 
 ### 4.2 设备上报
@@ -357,7 +357,7 @@ Push 中的 `topic`、`seq`、`call_id` 只用于定位和补偿，不作为业
 
 | 验收项 | 期望结果 |
 | --- | --- |
-| 客户端初始化 | SDK 返回 registration_id，alias 绑定为当前 `usr...`。 |
+| 客户端初始化 | SDK 返回 registration_id，alias 绑定为 `user_id.replace("-", ".").replace("_", "|")`。 |
 | 设备上报 | `PUT /v1/im/devices/{device_id}/push-token` 返回成功，服务端记录 provider=`jpush`。 |
 | 普通离线消息 | 用户离线后收到 Push，点击后进入会话并补齐 Topic seq。 |
 | 群 @ 提醒 | 被 @ 用户离线时只收到一次提醒，重连后定位到对应消息。 |