docs(mobile-next): 建立 docs/upstream 与 docs/acceptance，回退引用对齐本分支提交
- 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:
编码工程师
@@ -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`。
|
||||
@@ -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`。
|
||||
Reference in New Issue
Block a user