chatapp3-flutter/需求进度.md

# 需求进度

## 当前总目标
- 分析当前 Flutter 包体过大的主要原因，识别多余组件、冗余依赖、过大资源或不合理构建配置，并给出可执行的优化建议。

## 已完成模块
- 创建进度跟踪文件。
- 初步确认仓库结构与当前工作区状态。
- 完成第一轮静态体积排查，拿到目录体积与大文件分布。
- 完成第二轮依赖使用情况排查，识别出未直接引用的重型插件与高风险依赖。
- 完成第一轮高置信度瘦身改动，移除 4 个当前未在业务层使用的插件依赖并清理相关平台声明。
- 完成构建阻塞项定位，确认 `image_cropper 5.0.1` 是当前 Android 构建失败的主要兼容性来源，并已切换到本地修补版依赖。
- 完成 Android 签名配置兜底，解决当前仓库缺少 `yumi.jks` / `yumi_debug.jks` 时无法继续本地构建分析的问题。
- 完成 Android release 包体构建与体积分析，拿到当前 APK 的真实大小和主要组成。

## 进行中模块
- 汇总最终结论，整理造成包体冗余的主因与后续优化优先级。

## 关键技术决策
- 先做无侵入体检：优先分析依赖、资源体积和构建配置，暂不直接删除业务代码或资源。
- 避开仓库中已有未提交改动，只在必要文件上新增或追加分析结果。
- 重点关注发布包相关项，而不是被 `build/`、iOS 中间产物这类本地构建缓存误导。
- 发布包体分析优先使用单 ABI 做 `--analyze-size`，因为当前工程配置了多 ABI，Flutter 不允许直接对多 ABI 产物做代码体积分析。
- 实际清理仅选择高置信度冗余项：`loading_indicator_view_plus`、`social_sharing_plus`、`flutter_foreground_task`、`on_audio_query`，暂不动 Agora、腾讯 IM、支付、WebView 等核心能力依赖。
- 对 `image_cropper` 不做升级式重构，先采用本地 path 依赖加最小兼容补丁的方式恢复构建，避免改动业务裁剪调用代码。
- 对 Android 签名配置采用条件回退策略：存在正式 keystore 时走正式签名，不存在时回退到 debug 签名，仅用于本地分析和构建验证。
- 即便传入 `--target-platform android-arm64`，当前 Gradle 的 `abiFilters` 仍会把 `arm64-v8a`、`armeabi-v7a`、`x86_64` 三套 so 一起打进 APK，因此后续瘦身必须回到 Gradle ABI 配置本身处理。

## 已改动文件
- `需求进度.md`
- `pubspec.yaml`
- `lib/ui_kit/components/dialog/dialog.dart`
- `android/app/src/main/AndroidManifest.xml`
- `ios/Runner/Info.plist`
- `local_packages/image_cropper-5.0.1-patched/android/src/main/java/vn/hunghd/flutter/plugins/imagecropper/ImageCropperPlugin.java`
- `local_packages/image_cropper-5.0.1-patched/`
- `android/app/build.gradle.kts`

## 已验证结果
- 仓库存在 `pubspec.yaml`、Android/iOS 构建配置以及大量图片资源和多个 `local_packages` 本地包。
- 当前工作区存在用户已有未提交改动，后续分析将避免覆盖。
- 目录体积显示：`build/` 约 4.7G、`.dart_tool/` 约 347M、`ios/` 约 250M、`sc_images/` 约 48M、`local_packages/` 约 6.1M。
- `android/app/build.gradle.kts` 中 release 构建关闭了 `minify`、`shrinkResources`、`zipAlign`，会直接放大发布包体。
- Android ABI 当前包含 `arm64-v8a`、`armeabi-v7a`、`x86_64`，如果打通用包会把不必要架构一起带进去。
- 当前资源中存在多张 2MB 以上的大图，例如 `sc_images/person/sc_icon_edit_userinfo_bg.png`、`sc_images/splash/sc_splash.png` 和多张 2.2MB 左右的 `webp` 背景图。
- 资源子目录中较大的部分主要是：`sc_images/index/` 约 18M、`sc_images/room/` 约 17M、`sc_images/person/` 约 5M、`sc_images/splash/` 约 2.5M。
- 本地包体积中较大的部分主要是：`local_packages/tancent_vap-1.0.0+1` 约 4.2M、`local_packages/flutter_foreground_task-9.1.0` 约 1.1M。
- 依赖引用扫描结果显示：`social_sharing_plus`、`flutter_foreground_task`、`on_audio_query` 当前在 `lib/` 与 `test/` 中没有直接 import，属于优先核查是否可移除的候选项。
- 明确在业务中使用的重型能力包括：`agora_rtc_engine`、`tencent_cloud_chat_sdk`、`tancent_vap`、`flutter_svga`、`firebase_auth/core/crashlytics`、`in_app_purchase`、`webview_flutter`。
- 执行 `flutter build apk --release --analyze-size` 时失败，Flutter 明确提示当前多 ABI 配置下必须指定单一 `--target-platform` 才能输出体积分析。
- `app-debug.apk` 当前约 405MB；拆包后可见最大组成是三套 ABI 的 `libflutter.so`、Agora 系列 so、腾讯 IM so，以及 `sc_images/index`、`sc_images/room` 等大资源目录。
- `.flutter-plugins-dependencies` 已证明 Android 端存在大量 `native_build` 插件注册；即使 Dart 代码没有 import，插件仍会进入原生构建链路。
- 已将 `loading_indicator_view_plus` 的使用替换为 Flutter 自带 `CircularProgressIndicator`，为后续移除该插件铺平路径。
- 已从工程依赖中删除 `loading_indicator_view_plus`、`social_sharing_plus`、`flutter_foreground_task`、`on_audio_query`，并同步清理 Android 前台服务与媒体音频权限、iOS 前台任务标识与媒体库用途说明。
- `flutter pub get` 后，上述 4 个冗余插件已不再出现在 Flutter 当前插件注册链路中；搜索结果仅残留在未重新执行 `pod install` 的 `ios/Podfile.lock` 旧记录里。
- 继续构建时又发现 `image_cropper 5.0.1` 的 Android 插件源码仍引用已移除的 `PluginRegistry.Registrar`，这会同时阻塞 debug/release。
- 已复制 `image_cropper 5.0.1` 到工作区本地包，并删除其过时的 `registerWith` 兼容入口，准备再次验证构建。
- 当前仓库下 `android/app/yumi.jks` 与 `android/app/yumi_debug.jks` 都不存在，原始 Gradle 配置会在签名校验阶段阻塞 release 构建。
- 已将 Gradle 配置调整为：正式 keystore 缺失时自动回退到 debug 签名，从而继续完成本地分析构建。
- `flutter build apk --release --target-platform android-arm64 --analyze-size` 已成功执行，生成 `build/app/outputs/flutter-apk/app-release.apk`。
- 当前 release APK 文件大小约 `271MB`，构建输出显示约 `284.6MB`，分析总压缩体积约 `271MB`。
- 当前 release APK 的压缩后主要组成是：
- `lib/arm64-v8a` 约 `101.3MB`
- `lib/x86_64` 约 `64.4MB`
- `lib/armeabi-v7a` 约 `58.2MB`
- `assets/flutter_assets` 约 `49.9MB`
- `classes.dex + classes2.dex + classes3.dex` 合计约 `8.8MB`
- 三套 ABI 合计约 `223.8MB`，其中 `x86_64 + armeabi-v7a` 两套额外架构合计约 `122.5MB`，是当前包体过大的头号原因。
- release APK 中最大的 native so 主要来自 Agora 与腾讯 IM：
- `libagora-rtc-sdk.so` 合计约 `79.4MB`
- `libagora-ffmpeg.so` 合计约 `17.8MB`
- `libagora_lip_sync_extension.so` 合计约 `13.7MB`
- `libagora_spatial_audio_extension.so` 合计约 `13.4MB`
- `libImSDK.so` 合计约 `10.2MB`
- `libflutter.so` 约 `11.3MB`
- release APK 中最大的资源目录主要是：
- `sc_images/index` 约 `18.9MB`
- `sc_images/room` 约 `16.9MB`
- `sc_images/person` 约 `5.1MB`
- `sc_images/level` 约 `2.9MB`
- `sc_images/splash` 约 `2.6MB`
- 单文件大图中比较明显的包括：
- `sc_images/person/sc_icon_edit_userinfo_bg.png` 约 `2.64MB`
- `sc_images/splash/sc_splash.png` 约 `2.37MB`
- 多张 `sc_icon_gamebroad_lv*.webp` 单张约 `2.0MB - 2.35MB`
- Flutter 的 Dart AOT 符号在分析里约 `11MB`，其中 `package:yumi` 自身约 `2MB`，说明业务 Dart 代码不是主要膨胀来源。
- `MaterialIcons-Regular.otf` 在 release 中已自动 tree-shake 到约 `3.7KB`，图标字体不是问题。
- 本轮为恢复构建额外处理了两个工程兼容问题：`loading_indicator_view_plus` 缺少 Android namespace、`image_cropper 5.0.1` 旧注册接口不兼容当前 Flutter/AGP。

## 已知问题
- `ios/Podfile.lock` 还保留旧插件记录，因为本轮未执行 `pod install`；但 Flutter 当前依赖与插件注册链路已经不再包含已移除插件。
- 目前 release 仍关闭了 `minify` / `shrinkResources` / `zipAlign`，这部分尚未动手优化，因为可能影响 Agora、腾讯 IM、Firebase 等反射或资源引用行为。
- Android 构建配置中的 `abiFilters` 仍然固定包含三套架构，导致单 ABI 分析构建时 APK 里依旧带入 `x86_64` 与 `armeabi-v7a`。

## 下一步要做什么
- 调整 Android ABI 策略，至少移除 `x86_64`，并根据发包方式决定是否保留 `armeabi-v7a`。
- 压缩或替换 `sc_images/index`、`sc_images/room`、`sc_images/person` 中的超大图片资源。
- 评估 Agora 扩展能力是否都需要，优先核查 lip sync、spatial audio、clear vision、segmentation、face capture 等扩展库能否裁剪。
- 在补齐必要 keep rules 后，再尝试开启 `minify`、`shrinkResources`、`zipAlign` 做第二轮正式瘦身。