编码工程师andmultica-agent
e26abad4e1
- docs/upstream/baseline.md: 上游来源/固定版本/许可证原文位置/工具链锁定/差异 - docs/upstream/build-and-rollback.md: 构建命令、本机实测 SHA256、逐提交回退方法 - docs/acceptance/sdk-compat-gate.md: hotfix.12 兼容冒烟矩阵（初始化/登录/会话同步/断线重连/好友/群组/文字双向/图片/文件/语音） - docs/acceptance/pc-boundary.md: PC 端只读核对的可改边界封存 - docs/acceptance/visual-spec-token-entry.md: 视觉规范 v2 唯一来源与 Token 入口预留 - 修正导入/验证文档中回退引用为 B-95 分支实际提交 Co-authored-by: multica-agent <github@multica.ai>
110 lines
7.8 KiB
Markdown
110 lines
7.8 KiB
Markdown
# mobile-next 通信组件热修接入与核心能力实测记录（B-95/B-137）
|
||
|
||
> 基线：`8046ec7`（官方 openim-flutter-demo 3.8.3-patch.3 固定基线导入）。
|
||
> 本阶段只做一件事：把 `flutter_openim_sdk` 从 `3.8.3+3` 升级到 `3.8.3+hotfix.12`，锁定依赖、完成 debug/release 双构建、用两个测试账号逐项实测核心通信能力。未开始品牌换壳或公司业务迁移。
|
||
|
||
## 一、依赖升级与差异记录
|
||
|
||
### 变更文件（仅 4 个，全部为版本号）
|
||
|
||
| 文件 | 变更 |
|
||
| --- | --- |
|
||
| `mobile-next/pubspec.yaml` | `flutter_openim_sdk: 3.8.3+3` → `3.8.3+hotfix.12` |
|
||
| `mobile-next/openim_common/pubspec.yaml` | 同上 |
|
||
| `mobile-next/openim_live/pubspec.yaml` | 同上 |
|
||
| `mobile-next/pubspec.lock` | `flutter_openim_sdk` sha256 与 version 同步更新 |
|
||
|
||
`openim_common` / `openim_live` 为 `mobile-next/` 内的本地子包，同样引用该 SDK，必须一致升级，否则 `flutter pub get` 解析失败。
|
||
|
||
### 依赖解析结果
|
||
|
||
`flutter pub get` 输出仅 `flutter_openim_sdk 3.8.3+hotfix.12 (was 3.8.3+3)`，**其余全部依赖无变化**。
|
||
|
||
### pubspec.lock 差异
|
||
|
||
```diff
|
||
flutter_openim_sdk:
|
||
dependency: "direct main"
|
||
description:
|
||
name: flutter_openim_sdk
|
||
- sha256: "09149d60b4c096acab52279365285409123f15f9111d5fc84cc2481b29343a04"
|
||
+ sha256: b57d1fd63f52fa5cbd7c257fccc9d04902c266e96172f5112c00b428af2f2ff5
|
||
url: "https://pub.dev"
|
||
source: hosted
|
||
- version: "3.8.3+3"
|
||
+ version: "3.8.3+hotfix.12"
|
||
```
|
||
|
||
### hotfix 与旧版 API 差异（基于 pub.dev 下载的源码 diff）
|
||
|
||
`flutter_openim_sdk 3.8.3+hotfix.12` 相对 `3.8.3+3` 的 Dart API 变化均为**新增/放宽**，向后兼容：
|
||
|
||
- `FriendshipManager` 新增 `getFriendApplicationListAsRecipient` / `getFriendApplicationListAsApplicant` / `getFriendApplicationUnhandledCount`。
|
||
- `GroupManager` 新增 `getGroupApplicationUnhandledCount`；`inviteUserToGroup` / `kickGroupMember` 返回类型由 `Future<List<GroupInviteResult>>` 放宽为 `Future`。
|
||
- `ConversationManager` 删除 2 行（内部实现），无公开 API 变更。
|
||
|
||
`dart analyze lib test` 对应用代码 **0 error**（仅有上游自带 info/warning 级 lint，与本次升级无关）。应用内调用 `inviteUserToGroup` / `kickGroupMember` 的地方（`lib/pages/chat/group_setup/group_setup_logic.dart:401,421`）不依赖返回值，编译通过。
|
||
|
||
### Android 原生侧差异（影响构建产物，不改变应用代码）
|
||
|
||
- hotfix 的 `android/build.gradle`：AGP `7.3.1`→`8.7.3`、compileSdk `34`→`35`、Java `1.8`→`11`；核心库 `io.openim:core-sdk:3.8.3-patch3@aar` → `3.8.3-patch12@aar`。
|
||
- 应用工程 `mobile-next/android/`（固定基线）仍为 AGP 7.3.1 / compileSdk 34 / Java 1.8，构建时以应用工程为准，hotfix 插件用应用工程工具链编译，双构建均通过。
|
||
|
||
## 二、构建与产物
|
||
|
||
工具链：Flutter 3.24.5（`C:\flutter324`）、JDK 17.0.20（Temurin）、Android SDK（platforms 34/35/36，build-tools 36.0.0）、Gradle 7.6.3 / AGP 7.3.1（应用工程锁定）。
|
||
|
||
| 构建 | 结果 | 产物 | 大小 | SHA256 | 签名 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| debug | 成功 | `app-debug.apk` | 109,454,753 B | `9020C291B9BE12C5B50720264797B06AF1D9C21708A5B8AD2847594C486DB642` | CN=openim keystore（与 release 同源） |
|
||
| release | 成功 | `app-release.apk` | 53,323,403 B | `A746DC83C3DB2E35A7AFA90B7FC1A02EAF751631F1DA9AAAF1799B28529B7F84` | CN=openim, cert SHA-256 `1f38a82fb3c33be7951fb5d964ef5bd9c6c9bfc084ae1e2a8a40a0d1f44ae1fe` |
|
||
|
||
APK 元数据（aapt badging，debug 与 release 一致）：package `io.openim.flutter.demo`，versionName `3.8.3`，versionCode `180`，minSdk 24 / targetSdk 33 / compileSdk 34。
|
||
|
||
构建期警告与基线相同（Flutter Gradle 插件 apply-script 弃用提示、部分依赖 Kotlin metadata 版本高于工程 Kotlin 的提示），不影响产物。release 包字体 tree-shaking 正常。
|
||
|
||
> 说明：x86_64 模拟器测试用的 fat APK（`--target-platform android-x64` 临时放开 abiFilters 构建）仅为本地联调产物，未入库，交付物以 arm64 debug/release 为准。
|
||
|
||
## 三、核心能力实测（2026-08-19，两 x86_64 模拟器）
|
||
|
||
环境：模拟器 A=emulator-5554 登录 t1001（"Test One"），模拟器 B=emulator-5556 登录 t1002（"Test Two"）；连真实 OpenIM `192.168.200.11:10002/:10001`。登录凭据 userID+imToken 与公司账号服务签发链路一致（OpenIM `/auth/get_user_token`），SDK 版本日志 `3.8.0`（hotfix 内核 3.8.3-patch12）。
|
||
|
||
| # | 能力 | 方法 | 结果 | 证据 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 1 | SDK 初始化 | App 启动 `initSDK(apiAddr, wsAddr, listener…)` | 通过 | 双端 `IM SDK Status: connecting → connectionSucceeded → syncStart → syncEnded` 日志 |
|
||
| 2 | 登录（userID+imToken） | 双端自动登录 | 通过 | 双端 `conn start`（ws 带 sendID/token），`onConnectSuccess` |
|
||
| 3 | 会话同步 | 启动拉取会话 | 通过 | 双端 `get_full_conversation_ids` 返回 `si_t1001_t1002` 等；UI 会话列表可见 |
|
||
| 4 | 断线重连 | 关 WiFi → 开 WiFi | 通过 | 断网 `onConnectFailed` + `reConn`，恢复后 `onConnectSuccess`，随后发送 `reconnectOK_3` 送达（seq 11） |
|
||
| 5 | 好友 | 通讯录→My Friends | 通过 | t1001 好友列表含 "Test Two"；早前好友申请通知已接受（`friendApplicationAccepted`） |
|
||
| 6 | 群组 | 建群 + 群消息 | 通过 | 建群 `hotfix-grp-test`（1481671100，成员 t1001+t1002），双端会话列表出现，群消息 `grp148_msg_ok` 送达 t1002（seq 2） |
|
||
| 7 | 文字消息 | t1001→t1002 / t1002→t1001 | 通过 | `regHotfixText_1_`（seq 6）、`hotfixBtoA_2`（seq 7）双端 UI + 服务端落库（status 2） |
|
||
| 8 | 图片消息 | 相册选图发送 | 通过 | `contentType 102`，URL `msg_picture_…png`，t1002 收到（seq 8，hasReadTime 回执） |
|
||
| 9 | 文件消息 | 文件选择器发送 | 通过 | `contentType 105`，`hotfix-file-test.txt` 66B 上传，t1002 UI 显示文件卡片（seq 9） |
|
||
| 10 | 语音消息 | 按住说话 | 通过 | `contentType 103`，`.m4a` 33,866B 上传，t1002 收到（seq 10，duration 1s） |
|
||
|
||
服务端落库通过 `/msg/search_msg` 复核，均为 `status=2`（已发送）。
|
||
|
||
## 四、完成标准核对
|
||
|
||
- [x] debug、release 真实构建成功，构建与产物信息齐全（含包名/版本/签名/SHA256）。
|
||
- [x] 核心能力逐项有"通过"结果与证据（初始化/登录/会话同步/重连/好友/群组/文字/图片/文件/语音），均为双账号实测，非版本号代替。
|
||
- [x] 任一核心门禁失败则停止后续迁移：本阶段**全部通过**，可进入公司功能迁移（阶段4）。
|
||
- [x] 旧版安装包、`mobile/`、PC 客户端、现网服务均未改动。
|
||
|
||
## 五、已知差异 / 备注
|
||
|
||
- 登录链路的 HTTP 工号密码校验（account-service `/api/login`）属于公司业务层，本次未接入 mobile-next（禁止公司业务迁移）；SDK 登录用与账号服务同源的 userID+imToken 实测通过。部署账号服务管理口令已改（非默认值），本次未触碰服务端任何配置与数据。
|
||
- 语音通话（LiveKit）不在本阶段范围（阶段4 迁移），未测。
|
||
- hotfix 插件自身 `android/build.gradle` 目标升级到 AGP 8.7.3/compileSdk 35，但被应用工程工具链（AGP 7.3.1/compileSdk 34）覆盖，行为由应用工程决定；已按基线记录。
|
||
- 模拟器测试时照片选择器因"受限访问"需在系统设置授予"允许所有照片"，为 Android 14+ 权限行为，非 SDK 问题。
|
||
|
||
## 六、回退方法
|
||
|
||
本提交只改动 4 个依赖声明文件（`mobile-next/` 内），可单独回退：
|
||
|
||
```
|
||
git revert 2c9dab160eefcaa5a4ad76a24ec2948bffaccc7e
|
||
```
|
||
|
||
或手动把 4 个文件的 `flutter_openim_sdk` 改回 `3.8.3+3` 并 `flutter pub get`。`mobile/`、`pc-client/`、`account-service/`、服务器与现网均不受影响。
|