leefer/tongxunruanjian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

docs(mobile-next): 建立 docs/upstream 与 docs/acceptance，回退引用对齐本分支提交

Browse Source 
- 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>
This commit is contained in:
编码工程师
2026-08-19 15:55:45 +08:00
co-authored by multica-agent
parent 2c9dab160e
commit e26abad4e1
7 changed files with 216 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/acceptance/pc-boundary.md
+36
View File
@@ -0,0 +1,36 @@
# PC 端可改边界封存（docs/acceptance）
> 只读核对，本卡不改 PC 界面。依据架构方案 B-90 的 PC 目录边界，对当前 PC 工程做只读核对，封存后续允许改动目录。
## 核对结论（2026-08-19，只读）
PC 工程 `pc-client/` 当前核心边界确认如下：
### 不可动（通信核心，冻结）
| 目录/文件 | 内容 | 理由 |
|---|---|---|
| `pc-client/electron/` | 主进程（`main/`）、预加载（`preload/`）、SDK 资产与打包核心 | 进程/打包核心，改动即破坏客户端稳定性 |
| `pc-client/src/store/` | 会话（`conversation.ts`）、联系人（`contact.ts`）、用户（`user.ts`）状态 | 会话/联系人/用户状态唯一来源 |
| `pc-client/src/layout/MainContentWrap.tsx` | SDK 初始化与连接（`@openim/electron-client-sdk` 实例化、`IMSDK`、登录检查） | SDK 初始化与连接入口 |
| `pc-client/src/pages/chat/queryChat/ChatFooter/useSendMessage.ts` | 消息发送（`IMSDK.sendMessage`） | 消息发送核心逻辑 |
| `pc-client/src/pages/chat/queryChat/useHistoryMessageList.tsx` | 历史消息（`IMSDK.getAdvancedHistoryMessageList`） | 历史消息核心逻辑 |
| SDK 版本 | `@openim/electron-client-sdk ^3.8.3-patch.10`、`@openim/wasm-client-sdk ^3.8.3-patch.10`（`package.json`） | 锁定版本，不做无收益升级 |
### 可改（界面层，后续重整范围）
| 目录 | 内容 |
|---|---|
| `pc-client/src/layout/LeftNavBar/` | 导航外观 |
| `pc-client/src/pages/contact/**` | 联系人展示与入口 |
| `pc-client/src/components/**` | 通用 UI 组件 |
| `pc-client/src/styles/` | 统一视觉 Token 唯一来源（依据视觉规范 v2） |
### 明确禁止
- 不建设 PC 语音通话：不提供发起/接听/来电弹窗；对手机发来的通话自定义消息静默过滤，不显示原始 JSON。
- 不改 `electron/`、`src/store/`、SDK 初始化、消息发送与历史逻辑。
## 回退与复核
- 本卡未改动任何 PC 文件（只读核对）；上述边界已记录，作为后续 PC 界面重整（阶段 4）的唯一改动态范围。
docs/acceptance/sdk-compat-gate.md
+44
View File
@@ -0,0 +1,44 @@
# mobile-next SDK 兼容门禁验收记录（docs/acceptance）
> 目标：官方 `mobile-next` 基线只把 `flutter_openim_sdk` 切到 `3.8.3+hotfix.12` 后，对接现网
> （OpenIM API `http://192.168.200.11:10002` / WS `ws://192.168.200.11:10001`）完成双机冒烟。
> 任一核心门禁失败即停止后续迁移并在本卡汇报；不得以「同属 3.8.3」代替实测。
## 冒烟矩阵（2026-08-19，两 x86_64 模拟器 emulator-5554/5556，真实 OpenIM 现网）
- 测试账号：`t1001`（Test One，emulator-5554）、`t1002`（Test Two，emulator-5556）。
- 登录凭据：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`（GoLog 日志） |
| 2 | 登录（userID+imToken） | 双端自动登录 | 通过 | 双端 `login start` → `login success`（82ms/161ms）→ `conn start`（ws sendID/token，sdkVersion=3.8.0）→ `onConnectSuccess` |
| 3 | 会话同步 | 启动拉取会话 | 通过 | 双端 `get_full_conversation_ids` 返回 `si_t1001_t1002`；UI 会话列表可见「Test Two」及群会话 |
| 4 | 断线重连 | 开/关飞行模式 | 通过 | 断网 `onConnectFailed` + `reConn`（dial tcp network unreachable）；恢复后 `reConn` → `connSuccess` → `onConnectSuccess` → `syncEnded` |
| 5 | 好友 | 通讯录→My Friends / 服务端 `get_friend_list` | 通过 | 服务端返回 t1001↔t1002 好友关系（friendUser t1002 "Test Two"，addSource 2）；UI 通讯录可见 |
| 6 | 群组 | 服务端 `get_joined_group_list` / UI 群会话 | 通过 | t1001 已入群 `hotfix-grp-test`（groupID 1893538836 / 1481671100）；UI 会话列表可见群会话 |
| 7 | 文字消息 A→B | t1001 发送 | 通过 | `B95TextAtoB_154855`（seq 13，status 2），t1002 收到（received a new message，unreadCount 1），服务端落库复核 |
| 8 | 文字消息 B→A | t1002 发送 | 通过 | `B95TextBtoA_155112`（seq 14，status 2），t1001 收到，服务端落库复核 |
| 9 | 图片消息 | 相册选图发送 | 通过 | contentType 102，URL `msg_picture_…png`，t1002 收到（B-137 基线同码实测，服务端 `/msg/search_msg` status 2） |
| 10 | 文件消息 | 文件选择器发送 | 通过 | contentType 105，`hotfix-file-test.txt` 66B 上传，t1002 UI 显示文件卡片（B-137 基线同码实测，status 2） |
| 11 | 语音消息 | 按住说话 | 通过 | contentType 103，`.m4a` 33,866B 上传，t1002 收到（B-137 基线同码实测，status 2） |
服务端 `/msg/search_msg` 复核：消息均 `status=2`（已发送）。
## 完成标准核对
- [x] `mobile-next` 官方原版 debug/release 可复现构建（见 `docs/upstream/build-and-rollback.md`，本卡实测 SHA256 与包/签名）。
- [x] SDK hotfix.12 兼容冒烟逐项有「通过」结果与证据（初始化/登录/会话同步/断线重连/好友/群组/文字双向/图片/文件/语音），非版本号相近代替实测。
- [x] 任一核心门禁失败即停止：本阶段全部通过，可进入后续公司功能迁移（第 4 阶段）。
- [x] 旧版 `mobile/`、`pc-client/`、`account-service/`、现网服务器与已发布安装包均未改动。
## 已知差异 / 备注
- 登录链路：HTTP 工号密码校验（account-service `/api/login`）属公司业务层，本阶段未接入 mobile-next（符合「不得公司业务迁移」）；SDK 登录使用与账号服务同源的 userID+imToken 实测通过。
- hotfix 插件自身 `android/build.gradle` 声明 AGP 8.7.3/compileSdk 35，被应用工程工具链（AGP 7.3.1/compileSdk 34）覆盖，行为以应用工程为准，双构建均通过。
- 语音通话（LiveKit）不在本阶段范围，未测。
- 图片/文件/语音三条在 B-137 基线以相同代码完成实测，本卡按同码基线复核服务端落库记录。
## 回退
见 `docs/upstream/build-and-rollback.md`；SDK 接入提交（2c9dab1）仅改 4 个依赖文件，可单独 `git revert`。
docs/acceptance/visual-spec-token-entry.md
+15
View File
@@ -0,0 +1,15 @@
# 视觉规范唯一来源与 Token 入口（docs/acceptance）
本卡不做视觉换壳，但为后续双端重建预留唯一来源，避免叠加样式。
## 唯一视觉规范
- 唯一视觉规范：子任务 B-91 附件 `changlian-visual-spec-v2.md`（v2 自发布起替代 v1，作为双端重建唯一视觉依据）。
- 本地工作副本已随 B-95 评审归档；仓库内正式引用位置由后续品牌/视觉迁移阶段在 `docs/` 下固化，本卡不复制视觉规范内容进 `mobile-next/`。
## 后续 Token 入口（预留，本卡未实施）
- 手机端：`mobile-next/` 采用官方 `openim_common/lib/src/res/styles.dart` 作为统一样式入口；公司视觉 Token 后续应落在 `mobile-next/lib/company/brand/` 单一目录（依据架构方案 B-90 目录边界），不得在页面内叠加新 CSS/样式覆盖旧样式。
- PC 端：`pc-client/src/styles/` 为统一视觉 Token 的唯一来源（依据架构方案 B-90），界面层后续重整只改该处与展示组件，不改核心逻辑。
> 施工铁律：改样式只改统一来源（设计 Token），禁止叠加新 CSS 覆盖旧样式；本卡未落地任何视觉改动。
docs/mobile-next-baseline-import.md
+1 -1
View File
@@ -101,7 +101,7 @@ APK 元数据（aapt badging）：package `io.openim.flutter.demo`，versionName
回退命令：
```
git revert cbfced2
git revert 8046ec7483d68f67011913da12e5e671479b5ff0
```
或直接删除并行目录（不影响现网）：
docs/mobile-next-hotfix-sdk-verification.md
+3 -3
View File
@@ -1,6 +1,6 @@
# mobile-next 通信组件热修接入与核心能力实测记录（B-137）
# mobile-next 通信组件热修接入与核心能力实测记录（B-95/B-137）
> 基线：`0a2fbac`（官方 openim-flutter-demo 3.8.3-patch.3 固定基线导入）+ `44ac7d9`（文档修正）。
> 基线：`8046ec7`（官方 openim-flutter-demo 3.8.3-patch.3 固定基线导入）。
> 本阶段只做一件事：把 `flutter_openim_sdk` 从 `3.8.3+3` 升级到 `3.8.3+hotfix.12`，锁定依赖、完成 debug/release 双构建、用两个测试账号逐项实测核心通信能力。未开始品牌换壳或公司业务迁移。
## 一、依赖升级与差异记录
@@ -103,7 +103,7 @@ APK 元数据（aapt badging，debug 与 release 一致）：package `io.openim.
本提交只改动 4 个依赖声明文件（`mobile-next/` 内），可单独回退：
```
git revert <本提交哈希>
git revert 2c9dab160eefcaa5a4ad76a24ec2948bffaccc7e
```
或手动把 4 个文件的 `flutter_openim_sdk` 改回 `3.8.3+3` 并 `flutter pub get`。`mobile/`、`pc-client/`、`account-service/`、服务器与现网均不受影响。
docs/upstream/baseline.md
+56
View File
@@ -0,0 +1,56 @@
# mobile-next 官方固定基线（docs/upstream）
## 上游来源与固定版本
| 项 | 值 |
|---|---|
| 上游仓库 | `https://github.com/OpenIMSDK/openim-flutter-demo.git` |
| 固定标签 | `3.8.3-patch.3` |
| 固定提交 | `b3dfdb1e8aaeaaf6f0793e10cadd20d5c184a31f`（"Updated IM SDK"，2025-03-07） |
| 校验方式 | `git ls-remote --tags` 解析 tag `^{}` 指向即上述提交 |
| 许可证 | OpenIM Open Source License（AGPL-3.0 + 附加条款），原文随导入保留在 `mobile-next/LICENSE`；子包 `openim_common/LICENSE`、`openim_live/LICENSE`、`local_plugin/flutter_openim_live_alert/LICENSE` |
> 必须固定在该提交，禁止追随上游 `main`。重建基线命令见 `docs/upstream/build-and-rollback.md`。
## 与本卡仓库（tongxunruanjian）的差异
基线在官方原版基础上只做了「必须才能构建/入库」的最小改动，业务代码零改动：
| 文件 | 差异 | 原因 |
|---|---|---|
| `mobile-next/.gitignore` | 追加 `/build/`、`/android/.gradle/`、`/android/local.properties` | 上游未忽略 Flutter 构建产物与本机 SDK 路径，避免构建垃圾入库 |
| `mobile-next/pubspec.lock` | `flutter_openim_sdk` 由锁文件 `3.8.3+2` 对齐为 `3.8.3+3`（`flutter pub get` 按 `pubspec.yaml` 声明 `3.8.3+3` 重新解析） | 上游锁文件落后于 pubspec 声明，属官方产物 |
除上述两处外，`mobile-next/` 与上游提交 `b3dfdb1e` 的整棵工作树一致（不含 `.git`、`.DS_Store`、`build/`、`.dart_tool/` 等非跟踪内容）。本卡已用 `git diff --no-index` 与上游归档树复核：零差异（仅上述 2 处）。
## 工具链锁定
| 工具 | 版本 | 位置 |
|---|---|---|
| Flutter | 3.24.5 stable（revision `dec2ee5c1f`，engine `a18df97ca5`） | `C:\flutter324` |
| Dart | 3.5.4（随 Flutter 3.24.5 分发） | 同上 |
| Java / JDK | Temurin 17.0.20+8 | `toolchain\jdk17` |
| Gradle | 7.6.3（`mobile-next/android/gradle/wrapper/gradle-wrapper.properties` 锁定） | 自动下载缓存 |
| Android Gradle Plugin | 7.3.1（`mobile-next/android/build.gradle`） | - |
| Kotlin | 1.9.23（`mobile-next/android/build.gradle` `ext.kotlin_version`） | - |
| compileSdk / targetSdk / minSdk | 34 / 33 / 24（`mobile-next/android/app/build.gradle`） | - |
| build-tools | 36.0.0 | Android SDK |
| 依赖锁文件 | `mobile-next/pubspec.lock` | 已入库 |
### 关键依赖（对照）
| 依赖 | 版本 | 说明 |
|---|---|---|
| `flutter_openim_sdk` | 3.8.3+3（基线自带，仅对照）；兼容门禁目标 `3.8.3+hotfix.12`（SDK 接入提交） | 升级差异见 SDK 接入提交与 `docs/acceptance/sdk-compat-gate.md` |
| `livekit_client` | 2.2.5（上游自带，仅对照；正式迁移不采用，保留现有 2.5.0+hotfix.3） | 不随本卡迁移 |
| `flutter_webrtc` / `dart_webrtc` | 0.12.10 / 1.5.2+hotfix.1（上游自带，仅对照） | 不随本卡迁移 |
## 许可证状态与门禁
- 本卡只构建并保留 OpenIM 标识与许可证的官方基线，不做「畅联」换标，不产出/发布试用或生产安装包。
- AGPL-3.0 附加条款（禁止未经授权的商业使用、禁止删除/修改/隐藏 OpenIM LOGO 与版权信息）的内部商用与换标边界，尚未取得书面结论；未确认前不得进入品牌迁移或对外/内部试用发布。
## 回退
- 基线导入提交：`git revert 8046ec7483d68f67011913da12e5e671479b5ff0`（本卡固定基线导入提交），可单独回退，不影响 `mobile/`、`pc-client/`、`account-service/` 与现网。
- 或直接删除并行目录：`git rm -r mobile-next`。
docs/upstream/build-and-rollback.md
+61
View File
@@ -0,0 +1,61 @@
# mobile-next 构建与回退方法（docs/upstream）
## 前置环境
```bat
set JAVA_HOME=<JDK17 目录>
set ANDROID_HOME=<Android SDK 目录>
set PATH=%JAVA_HOME%\bin;<Flutter SDK 目录>\bin;%PATH%
set GRADLE_OPTS=-Xmx4096M
```
`mobile-next/android/local.properties` 需包含（本机路径，不入库）：
```
sdk.dir=<Android SDK 目录，反斜杠转义>
flutter.sdk=<Flutter SDK 目录，反斜杠转义>
```
首次依赖解析（生成 `.dart_tool`，不产生源码改动）：
```
cd mobile-next
flutter pub get
```
## 构建命令
```bat
flutter build apk --debug :: 产物 build/app/outputs/flutter-apk/app-debug.apk
flutter build apk --release :: 产物 build/app/outputs/flutter-apk/app-release.apk
```
- release 使用上游自带 keystore `android/app/openim`（alias/password 均为 `openim`），保留 OpenIM 标识与签名。
- 注意：上游 `android/app/build.gradle` 的 `ndk { abiFilters "arm64-v8a" }` 只打 arm64；如需 x86_64 模拟器联调，临时放开 `"x86_64"` 再还原（本地产物，不入库）。
## 本卡实测结果（2026-08-19，本机锁定环境）
| 构建 | 结果 | 产物 | 大小 | SHA256 |
|---|---|---|---|---|
| debug | 成功 | `app-debug.apk` | 109,454,925 B | `DD7D9700BC1F5830B7495875387948AAD536CA63FDC3EF66B4C0F4D152407B72` |
| release | 成功 | `app-release.apk` | 53,323,411 B | `4969AF4A4800A8E7C0B0C2F50687CB8C765925E4F2B3B7A53762D1D9E49CA604` |
APK 元数据（aapt badging）：package `io.openim.flutter.demo`，versionCode `180`，versionName `3.8.3`，minSdk 24 / targetSdk 33 / compileSdk 34。
release 签名（apksigner verify --print-certs）：CN=openim，证书 SHA-256 `1f38a82fb3c33be7951fb5d964ef5bd9c6c9bfc084ae1e2a8a40a0d1f44ae1fe`，与官方基线同一 keystore。
构建期告警（不影响产物）：Flutter Gradle 插件 apply-script 弃用提示；部分依赖 Kotlin metadata 版本（1.8.x）高于工程 Kotlin（1.9.23 预期 1.6.0/1.8.0）的警告，均属上游依赖组合特性，debug/release 均通过。
## 失败停止点
任一核心门禁失败即停止后续迁移，在本卡汇报并附错误证据，不得继续迁移。本阶段 debug/release 均构建成功，无失败步骤。
## 逐提交回退
本卡分支基于回退基线 `fa8584a`，主题提交相互独立，可单独回退：
| 主题 | 提交 | 回退命令 |
|---|---|---|
| 官方基线导入 + 双构建 | 8046ec7483d68f67011913da12e5e671479b5ff0 | `git revert 8046ec7483d68f67011913da12e5e671479b5ff0` 或 `git rm -r mobile-next` |
| SDK hotfix.12 接入 + 核心能力实测 | 2c9dab160eefcaa5a4ad76a24ec2948bffaccc7e | `git revert 2c9dab160eefcaa5a4ad76a24ec2948bffaccc7e`（仅 4 个依赖文件） |
回退任一提交均不影响 `mobile/`、`pc-client/`、`account-service/`、现网服务器与已发布安装包。SDK hotfix 提交的手动回退：把 `mobile-next/pubspec.yaml`、`openim_common/pubspec.yaml`、`openim_live/pubspec.yaml` 中 `flutter_openim_sdk` 改回 `3.8.3+3` 后 `flutter pub get`。