提示信息
# 同伴 Flutter 项目升级计划
> 目标：移除 `adaptive_platform_ui`（苹果 iOS26 Liquid Glass 风格），全面切换 Material 3 体系；
> 同步对齐新项目 `tongban_app` 的依赖版本；对接最新后端 API 规范。
>
> 保留的苹果组件：`CupertinoTabBar`（底部导航栏）、`CupertinoSwitch`（开关）。
---
## 一、涉及组件替换速查表
| Adaptive 组件 | 替换为 | 说明 |
|---|---|---|
| `AdaptiveApp` / `AdaptiveApp.router` | `MaterialApp.router` | 直接用 Material |
| `AdaptiveScaffold` | `Scaffold` | - |
| `AdaptiveAppBar` | `AppBar` | - |
| `AdaptiveBottomNavigationBar` | **`CupertinoTabBar`（保留）** | 底部 Tab 保持苹果风格 |
| `AdaptiveNavigationDestination` | `BottomNavigationBarItem` | 配合 CupertinoTabBar |
| `AdaptiveListTile` | `ListTile` | - |
| `AdaptiveFormSection` | `Card` + `Column` + `Divider` | 可封装为 `AppFormSection` 组件 |
| `AdaptiveButton` | `ElevatedButton` / `TextButton` / `OutlinedButton` | 按场景选型 |
| `AdaptiveAlertDialog` | `showDialog` + `AlertDialog` | - |
| `AdaptiveCard` | `Card` | - |
| `AdaptiveTextField` | `TextField` | - |
| `AdaptivePopupMenuButton` / `AdaptivePopupMenuItem` | `PopupMenuButton` / `PopupMenuItem` | - |
| `AdaptiveAppBarAction` | `IconButton` | - |
| `AdaptiveSwitch` | **`CupertinoSwitch`（保留）** | 开关保持苹果风格 |
| `AdaptiveSnackBar` | `ScaffoldMessenger.of(context).showSnackBar` | - |
| `AdaptiveDatePicker` | `showDatePicker` | - |
| `AdaptiveSlider` | `Slider` | - |
| `AdaptiveContextMenu` / `AdaptiveContextMenuAction` | `PopupMenuButton` 或长按 `showMenu` | - |
| `AdaptiveBadge` | `Badge`（Material 3 内置） | - |
---
## 二、依赖升级（pubspec.yaml）
### 2.1 升级现有依赖
| 包 | 当前版本 | 目标版本 | 备注 |
|---|---|---|---|
| `flutter_riverpod` | ^2.4.9 | ^3.3.1 | **Breaking：API 有变更** |
| `riverpod_annotation` | ^2.3.3 | ^4.0.2 | 配套升级 |
| `go_router` | ^13.0.1 | ^17.1.0 | **Breaking：API 有变更** |
| `just_audio` | ^0.9.36 | ^0.10.5 | - |
| `wechat_assets_picker` | ^9.4.1 | ^10.1.1 | - |
| `record` | ^5.2.0 | ^6.2.0 | - |
| `flutter_openim_sdk` | ^3.5.1 | ^3.8.3 | - |
| `connectivity_plus` | ^6.0.3 | ^7.0.0 | - |
| `remixicon` | ^1.0.0 | ^1.4.0 | - |
| `flutter_widget_from_html` | ^0.15.1 | ^0.17.1 | - |
| `environment sdk` | >=3.2.0 | >=3.8.0 | - |
| `flutter_lints` (dev) | ^3.0.1 | ^6.0.0 | - |
| `riverpod_generator` (dev) | ^2.3.9 | ^4.0.3 | 配套升级 |
| `build_runner` (dev) | ^2.4.8 | ^2.12.2 | - |
| `flutter_launcher_icons` (dev) | ^0.13.1 | ^0.14.4 | - |
### 2.2 新增依赖
| 包 | 版本 | 用途 |
|---|---|---|
| `hooks_riverpod` | ^3.3.1 | Riverpod + Hooks 组合 |
| `flutter_hooks` | ^0.21.3 | 函数式状态管理 |
| `skeletonizer` | ^2.1.3 | 加载骨架屏（支持 Flutter 3.32+） |
| `flutter_animate` | ^4.5.0 | 声明式动画 |
| `freezed_annotation` | ^3.1.0 | 不可变数据模型 |
| `json_annotation` | ^4.11.0 | JSON 序列化注解 |
| `velocity_x` | ^4.0.0 | 敏捷布局扩展 |
| `flex_color_scheme` | ^8.4.0 | 主题生成工具 |
| `lottie` | ^3.0.0 | Lottie 动画 |
| `freerasp` | ^7.5.0 | 安全防护（越狱/root 检测） |
| `device_info_plus` | ^12.3.0 | 设备信息 |
| `flutter_udid` | ^4.1.2 | 设备唯一标识 |
| `envied` | ^1.3.3 | 环境变量安全存储 |
| `talker_flutter` | ^5.1.15 | 统一日志面板 |
| `talker_dio_logger` | ^5.1.15 | Dio 请求日志 |
| `talker_riverpod_logger` | ^5.1.14 | Riverpod 状态日志 |
| `app_tracking_transparency` | ^2.0.6+1 | iOS ATT 弹窗 |
| `package_info_plus` | ^8.1.0 | 应用版本信息 |
| `google_fonts` | ^8.0.2 | 字体（可选） |
| `image_gallery_saver_plus` | ^4.0.1 | 保存图片到相册（替换旧包） |
**dev_dependencies 新增：**
| 包 | 版本 |
|---|---|
| `freezed` | ^3.2.5 |
| `json_serializable` | ^6.11.2 |
| `envied_generator` | ^1.3.3 |
| `mocktail` | ^1.0.4 |
### 2.3 移除依赖
| 包 | 原因 |
|---|---|
| `adaptive_platform_ui`（本地包） | **核心：移除苹果 UI** |
| `shared_preferences` | 已被 `mmkv` 替代 |
| `image_picker` | 已被 `wechat_assets_picker` 替代 |
| `audioplayers` | 已被 `just_audio` 替代 |
| `flutter_slidable` | 新设计不使用 |
| `umeng_common_sdk` | 暂停接入，待合规评估 |
| `aliyun_face_plugin`（本地插件） | 待评估是否保留 |
| `image_gallery_saver` | 替换为 `image_gallery_saver_plus` |
| `dependency_overrides: record_linux` | record 升级后不再需要 |
---
## 三、页面改写任务清单
> 影响文件共约 **50+**，按模块分批进行。优先级：核心框架 > 高频页面 > 工具/辅助。
### Phase 1：核心框架（阻塞全局，优先处理）
- [ ] **`lib/app.dart`** — `AdaptiveApp.router` → `MaterialApp.router`
- [ ] **`lib/main.dart`** — 移除 adaptive 初始化，接入 talker
- [ ] **`lib/shared.dart`** — 移除 adaptive 导入，新增通用 Material 导入
- [ ] **`lib/features/home/home_shell.dart`** — `AdaptiveScaffold` + `AdaptiveBottomNavigationBar` → `Scaffold` + `CupertinoTabBar`（保留）
### Phase 2：Settings 模块（苹果风格最集中，约 8 个文件）
- [ ] `lib/features/settings/settings_page.dart`（25处 Adaptive 引用）
- [ ] `lib/features/settings/account_security_page.dart`（15处）
- [ ] `lib/features/settings/cache_management_page.dart`（14处）
- [ ] `lib/features/settings/privacy_settings_page.dart`（13处）
- [ ] `lib/features/settings/about_us_page.dart`（13处）
- [ ] `lib/features/settings/minor_mode_page.dart`（9处）
- [ ] `lib/features/settings/system_permissions_page.dart`
- [ ] `lib/features/settings/appearance/appearance_page.dart`
### Phase 3：用户/资料模块
- [ ] `lib/features/user/profile_edit_page.dart`（17处）
- [ ] `lib/features/user/complete_profile_page.dart`（9处）
- [ ] `lib/features/user/verification_page.dart`（11处）
- [ ] `lib/features/user/visitors_page.dart`（6处）
- [ ] `lib/features/user/user_list_page.dart`（10处）
- [ ] `lib/features/user/profile_edit/mbti_test_page.dart`（8处）
- [ ] `lib/features/user/profile_edit/widgets/text_editor_sheet.dart`
- [ ] `lib/features/user/profile_edit/widgets/full_screen_text_editor.dart`
- [ ] `lib/features/user/profile_edit/widgets/orientation_editor_sheet.dart`
- [ ] `lib/features/user/profile_edit/widgets/interest_editor_sheet.dart`
### Phase 4：Chat 模块
- [ ] `lib/features/chat/messages_page.dart`（11处）
- [ ] `lib/features/chat/chat_page.dart`
- [ ] `lib/features/chat/chat_settings_page.dart`（13处）
- [ ] `lib/features/chat/widgets/chat_input_bar.dart`
### Phase 5：Signal 模块
- [ ] `lib/features/signal/send_signal_page.dart`（11处）
- [ ] `lib/features/signal/signal_detail_page.dart`（7处）
- [ ] `lib/features/signal/signal_inbox_page.dart`（5处）
- [ ] `lib/features/signal/widgets/my_signal_list.dart`（5处）
### Phase 6：其他页面
- [ ] `lib/features/profile/user_profile_page.dart`（7处）
- [ ] `lib/features/mine/mine_page.dart`（7处）
- [ ] `lib/features/auth/login_page.dart`（6处）
- [ ] `lib/features/common/report_page.dart`（6处）
- [ ] `lib/features/common/notices/system_notice_page.dart`
- [ ] `lib/features/common/user_list_page.dart`（10处）
- [ ] `lib/features/discovery/discovery_page.dart`
- [ ] `lib/features/vip/vip_center_page.dart`
- [ ] `lib/features/store/store_page.dart`
- [ ] `lib/features/activity/invite_page.dart`（8处）
- [ ] `lib/features/activity/douyin_activity_page.dart`（8处）
### Phase 7：共享 Widget / Utils
- [ ] `lib/widgets/common/error_dialogs.dart`（10处）
- [ ] `lib/widgets/common/privacy_dialog.dart`（8处）
- [ ] `lib/widgets/common/app_full_screen_page.dart`（5处）
- [ ] `lib/widgets/common/app_nav_action.dart`
- [ ] `lib/widgets/common/paged_list_view.dart`
- [ ] `lib/widgets/common/pin_input_dialog.dart`
- [ ] `lib/widgets/common/permission_sheet.dart`
- [ ] `lib/widgets/empty/app_empty.dart`
- [ ] `lib/widgets/update/app_update_dialog.dart`
- [ ] `lib/core/utils/toast_util.dart`（9处）
- [ ] `lib/core/utils/permission_util.dart`（8处）
---
## 四、Riverpod v2 → v3 迁移要点
| 变更点 | v2 写法 | v3 写法 |
|---|---|---|
| `StateNotifierProvider` | `StateNotifier<S>` | 改用 `Notifier<S>` 或 `AsyncNotifier<S>` |
| `ProviderObserver` | 基本不变 | 可接入 `TalkerRiverpodLogger` |
| `AsyncValue.guard` | 相同 | - |
| codegen 注解 | `@riverpod` | 相同，但 generator 版本升至 ^4.0.3 |
| `ref.listenSelf` | 无 | v3 新增 |
| `Notifier.build` 返回类型 | - | 必须明确声明 |
**迁移步骤：**
1. 升级 pubspec，运行 `dart pub get`
2. 运行 `dart pub run build_runner build --delete-conflicting-outputs` 重新生成 `.g.dart`
3. 逐一修复编译错误（主要是 StateNotifier 废弃警告）
---
## 五、go_router v13 → v17 迁移要点
| 变更点 | 说明 |
|---|---|
| `StatefulNavigationShell` | API 基本稳定，保持不变 |
| `GoRoute` | 相同 |
| `redirect` 回调 | v17 中 `BuildContext` 参数类型变更，需检查 |
| `GoRouterState` 属性 | 部分属性重命名，如 `params` → `pathParameters` |
| `pushNamed` / `goNamed` | 相同 |
---
## 六、后端 API 对接调整
后端已更新（见 `/Applications/MAMP/htdocs/同伴最新版/CLAUDE.md`）：
- **响应格式**：`{"code":0, "msg":"success", "data":null, "server_time":...}`
- 检查 `api_client.dart` 的响应拦截器是否正确处理 `server_time`
- **错误码新增**：1005（Token 过期，用 refresh 刷新）、1006（Refresh Token 过期）、1007（权限不足）、1008（账号封禁）
- 更新 `api_interceptors.dart` 对各错误码的处理逻辑
- **分页方式**：游标分页 `{list, next_cursor, has_more}`
- 检查现有分页 provider 是否适配此格式
- **软删除**：后端用 `deleted_at`，前端无需改动
- **OpenIM SDK**：升级至 ^3.8.3，检查 `im_service.dart` 接口兼容性
---
## 七、新增功能接入
### 7.1 Talker 日志系统（替换 print/debugPrint）
```dart
// main.dart
final talker = Talker();
FlutterError.onError = (details) => talker.handle(details.exception, details.stack);
// Dio 日志
dio.interceptors.add(TalkerDioLogger(talker: talker));
// Riverpod 日志
ProviderScope(observers: [TalkerRiverpodLogger(talker: talker)])
```
### 7.2 Envied 环境变量
```
// .env (gitignore)
API_BASE_URL=https://api.tongban.wang
OPENIM_API_ADDR=...
```
生成 `lib/core/config/env.dart`，不再硬编码敏感配置。
### 7.3 Freezed 数据模型
现有 `lib/core/models/*.dart` 逐步迁移为 freezed 不可变模型，支持 `copyWith`、`fromJson`、`toJson`。
### 7.4 Freerasp 安全防护
在 `main.dart` 初始化，检测越狱/root、调试器、模拟器，命中时上报后端并强制退出。
---
## 八、执行顺序建议
```
Week 1：Phase 1（核心框架）+ pubspec 升级 + Riverpod/go_router 迁移
Week 2：Phase 2（Settings）+ Phase 7（共享 Widget/Utils）
Week 3：Phase 3（用户/资料）+ Phase 4（Chat）
Week 4：Phase 5（Signal）+ Phase 6（其他页面）
Week 5：后端 API 对接验证 + 新功能接入（Talker/Envied/Freerasp）+ 回归测试
```
---
## 九、注意事项
1. **保留 `CupertinoTabBar`**：底部导航栏继续使用，颜色/背景需手动与 Material dark 主题一致。
2. **保留 `CupertinoSwitch`**：所有 `AdaptiveSwitch` 替换为 `CupertinoSwitch`，而非 `Switch`。
3. **不使用 `AdaptiveApp`**：改为纯 `MaterialApp`，Cupertino 路由过渡可通过 `PageTransitionsTheme` 单独配置。
4. **`packages/adaptive_platform_ui`**：整个目录可以保留但不引用，或直接删除（建议先注释 pubspec 依赖确认无报错后再删）。
5. **`plugins/aliyun_face_plugin`**：暂保留，但 pubspec 中移除后需同步删除对应 import。
6. **图标**：`AdaptiveNavigationDestination` 使用的是 SF Symbols 字符串（如 `'house.fill'`），替换后改用 `remixicon` 包的图标常量。