diff --git a/docs/acceptance/pc-boundary.md b/docs/acceptance/pc-boundary.md new file mode 100644 index 0000000..33d2f6a --- /dev/null +++ b/docs/acceptance/pc-boundary.md @@ -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）的唯一改动态范围。 diff --git a/docs/acceptance/sdk-compat-gate.md b/docs/acceptance/sdk-compat-gate.md new file mode 100644 index 0000000..024dc1a --- /dev/null +++ b/docs/acceptance/sdk-compat-gate.md @@ -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`。 diff --git a/docs/acceptance/visual-spec-token-entry.md b/docs/acceptance/visual-spec-token-entry.md new file mode 100644 index 0000000..4c2eff3 --- /dev/null +++ b/docs/acceptance/visual-spec-token-entry.md @@ -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 覆盖旧样式；本卡未落地任何视觉改动。 diff --git a/docs/mobile-next-baseline-import.md b/docs/mobile-next-baseline-import.md index 49e6f4f..da159f2 100644 --- a/docs/mobile-next-baseline-import.md +++ b/docs/mobile-next-baseline-import.md @@ -101,7 +101,7 @@ APK 元数据（aapt badging）：package `io.openim.flutter.demo`，versionName 回退命令： ``` -git revert cbfced2 +git revert 8046ec7483d68f67011913da12e5e671479b5ff0 ``` 或直接删除并行目录（不影响现网）： diff --git a/docs/mobile-next-hotfix-sdk-verification.md b/docs/mobile-next-hotfix-sdk-verification.md index 6bf3f3b..2f9e355 100644 --- a/docs/mobile-next-hotfix-sdk-verification.md +++ b/docs/mobile-next-hotfix-sdk-verification.md @@ -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/`、服务器与现网均不受影响。 diff --git a/docs/upstream/baseline.md b/docs/upstream/baseline.md new file mode 100644 index 0000000..8d5ac6f --- /dev/null +++ b/docs/upstream/baseline.md @@ -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`。 diff --git a/docs/upstream/build-and-rollback.md b/docs/upstream/build-and-rollback.md new file mode 100644 index 0000000..f11bf52 --- /dev/null +++ b/docs/upstream/build-and-rollback.md @@ -0,0 +1,61 @@ +# mobile-next 构建与回退方法（docs/upstream） + +## 前置环境 + +```bat +set JAVA_HOME= +set ANDROID_HOME= +set PATH=%JAVA_HOME%\bin;\bin;%PATH% +set GRADLE_OPTS=-Xmx4096M +``` + +`mobile-next/android/local.properties` 需包含（本机路径，不入库）： + +``` +sdk.dir= +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`。