feat: 新增仪表盘页面与macOS多项优化

1. 新增TDashboard翻译类型与多语言文案 2. 完善macOS权限管理与Impeller渲染适配 3. 更新服务器部署配置与协议文件上传脚本 4. 修复翻译导入服务与根类型编译问题
2026-06-26 06:34:05 +08:00
parent bd937b02f3
commit 88a3f6d65f
39 changed files with 4257 additions and 302 deletions
--- a/iOS_macOS_Developer_Guide.md
+++ b/iOS_macOS_Developer_Guide.md
@@ -10,14 +10,12 @@

 | 日期 | 版本 | 变更内容 |
 |---|---|---|
+| 2026-06-26 | v14 | **macOS 权限动态申请**：①新建 `PermissionManager.swift` 原生权限管理器（AVFoundation/Photos/UserNotifications），通过 MethodChannel 暴露给 Flutter；②AppDelegate 新增 `checkPermission`/`requestPermission`/`openPermissionSettings` 三个 channel 方法；③MacosPlatformService 新增权限管理方法；④PermissionService macOS 分支改为调用原生 API，实现相机/麦克风/相册/通知权限的动态申请（替代 permission_handler_apple 无 macOS 实现的问题）；⑤AppPermission 枚举新增 `macosPermissionName` getter |
+| 2026-06-26 | v13 | **macOS Impeller 开关修复**：①修复「通用设置 → Impeller 渲染引擎」开关不生效的严重 bug（原 `setenv("FLUTTER_ENGINE_SWITCH_0")` 方式 macOS 桌面 embedder 不读取，改用 `FlutterDartProject.commandLineArguments` 传递 `--enable-impeller`/`--no-enable-impeller`）；②x86_64 端开启 Impeller 前增加二次确认警告对话框（说明 Intel Mac 上的 Metal 驱动渲染资源累积风险）；③Apple Silicon (arm64) 在重启对话框中显示「推荐开启」提示卡片；④新增 5 个翻译键（覆盖全部 14 种语言） |
+| 2026-06-26 | v12 | **macOS App Store 审核修复**：①flutter_webrtc 1.4.0→1.5.2（对齐 WebRTC-SDK 144.7559.09，解决 CocoaPods 版本冲突）；②新增 §2.8.9 flutter_webrtc 特殊包说明；③新增 §2.8.10 permission_handler_apple macOS 缺失实现说明（macOS 端权限改由 entitlement + Info.plist 自动管理）；④新增 §6.x macOS entitlement 与权限管理适配说明 |
 | 2026-06-15 | v11 | 同步三方库升级：删除custom_lint/riverpod_lint；新增analyzer/test_api/test/xml/pointycastle overrides；record降级到^6.2.1(7.0.0需Dart3.12+)；更新差异对照表和dependency_overrides行数 |
 | 2026-06-07 | v10 | 修正 §2.3 dependency_overrides 行数（4→5行/40+→46行）；修正 §2.6 补丁引用（§2.8→§2.9）；简化 §2.8.1 pro_image_editor 过时回退建议；删除 §5.4 pro_image_editor 本地包条目和 bitsdojo_window 废弃条目；简化 §3.3 pubspec.yaml 处理策略（git stash → 双模板脚本生成）；更新 §3.2/§3.5/§6 与双模板机制对齐 |
-| 2026-06-06 | v9 | 清理未使用依赖：移除 animations、animate_do、value_layout_builder、flutter_advanced_canvas_editor、flutter_blue_plus、http_cache_file_store、dartx、vector_math；删除差异对照表中 flutter_nfc_kit 过时条目 |
-| 2026-06-06 | v8 | 新增 `app_tracking_transparency` 差异对照条目；新增 `nearby_connections` 鸿蒙端本地stub包说明；新增 §2.10 nearby_connections鸿蒙适配说明 |
-| 2026-06-02 | v7 | **重大变更**：pubspec.yaml 拆分为双模板（pubspec.ohos.yaml + pubspec.macos.yaml），pubspec.yaml 不再提交到 Git；新增三方库变更通知机制；新增 setup_pubspec.ps1 脚本 |
-| 2026-06-02 | v6 | 鸿蒙端 pubspec.yaml 同步 bitsdojo_window → window_manager 迁移；更新 file_picker 本地包版本注释(v8.3.7→v11.0.0-ohos.1)；更新 speech_to_text(^7.0.0→^7.4.0)、live_activities(^2.0.0→^2.4.9) 远程版本号；补充 dependency_overrides 中 bitsdojo_window_windows 移除说明 |
-| 2026-06-01 | v5 | 新增 §2.6 pub cache 补丁说明；标记 bitsdojo_window 迁移完成；file_picker 升级到 12.x |
-| 2026-05-30 | v4 | 初版完整指南 |
+

 ---

@@ -168,7 +166,7 @@ Error: The getter 'ohos' isn't defined for the class 'TargetPlatform'
 | local_auth | `path: packages/local_auth` | `^3.0.1` |
 | battery_plus | `path: packages/battery_plus` | `^7.0.0` |
 | network_info_plus | `path: packages/network_info_plus` | `^8.1.0` |
-| flutter_webrtc | `path: packages/flutter_webrtc` | `^1.4.0` |
+| flutter_webrtc | `path: packages/flutter_webrtc` | `^1.5.2` |
 | mobile_scanner | `path: packages/mobile_scanner` | `^7.2.0` |
 | wifi_iot | `path: packages/wifi_iot` | `^0.3.19` |
 | nearby_service | `path: packages/nearby_service` | `^0.2.1` |
@@ -357,6 +355,77 @@ MacBook Pro 端使用 pub.dev 版本 `^0.9.3`，鸿蒙端的 `ohosName` 参数
  app_tracking_transparency: ^2.0.6
 ```

+#### 2.8.9 flutter_webrtc（macOS WebRTC-SDK 版本对齐）
+
+macOS 端 `flutter_webrtc` 已从 `^1.4.0` 升级为 `^1.5.2`，原因：
+
+1. **CocoaPods 版本冲突**：
+   - macOS `Podfile` 通过本地 podspec `macos/WebRTC-SDK.podspec.json` 声明 WebRTC 二进制库版本 `144.7559.09`（Intel Mac 渲染修复补丁，使用 ghfast.top 镜像下载）
+   - `flutter_webrtc 1.4.0` 的 macOS podspec 依赖 `WebRTC-SDK 144.7559.01`（`.01` 版本），与本地 podspec 的 `.09` 版本冲突，`pod install` 报错：`CocoaPods could not find compatible versions for pod "WebRTC-SDK"`
+   - `flutter_webrtc 1.5.2` 的 macOS podspec 已对齐声明 `s.dependency 'WebRTC-SDK', '144.7559.09'`，与本地 podspec 一致，冲突解决
+
+2. **API 兼容性**：
+   - 1.4.0 → 1.5.2 为兼容性升级，项目使用的 WebRTC API（`RTCPeerConnection` / `MediaStream` / `VideoRenderer`）均未变更
+   - 已通过 `flutter analyze` 验证：`screen_share_page.dart` / `webrtc_service.dart` / `screen_share_provider.dart` 无需修改
+
+3. **鸿蒙端注意**：
+   - 鸿蒙端使用本地包 `packages/flutter_webrtc`（v1.4.0-ohos.1），**无法直接升级到 1.5.2**
+   - 鸿蒙端本地包待后续同步升级到 `1.5.2-ohos` 版本
+   - 远程端升级不影响鸿蒙端编译（两端 pubspec 独立）
+
+```yaml
+# MacBook Pro 端（pubspec.macos.yaml）
+  flutter_webrtc: ^1.5.2  # WebRTC音视频通信（1.5.2 对齐 WebRTC-SDK 144.7559.09）
+
+# 鸿蒙端（pubspec.ohos.yaml）
+  flutter_webrtc:          # v1.4.0-ohos.1 | 本地化-鸿蒙适配；远程端已升至1.5.2，鸿蒙本地包待后续同步
+    path: packages/flutter_webrtc
+```
+
+> **macOS Podfile 本地 podspec 说明**：
+> ```ruby
+> # macos/Podfile 第 39 行
+> pod 'WebRTC-SDK', :podspec => 'WebRTC-SDK.podspec.json'
+> ```
+> 该 podspec 声明从 `ghfast.top` 镜像下载 `WebRTC.xcframework.zip`（v144.7559.09），
+> 避免直连 github.com 超时。升级 flutter_webrtc 时需确保其 podspec 声明的 WebRTC-SDK 版本与本地 podspec 一致。
+
+#### 2.8.10 permission_handler_apple（macOS 无实现 — 权限由 entitlement 管理）
+
+`permission_handler_apple` 是 `permission_handler` 在 iOS/macOS 平台的实现包，但 **9.4.9 版本仅支持 iOS，不支持 macOS**：
+
+```yaml
+# permission_handler_apple 9.4.9 的 pubspec.yaml
+flutter:
+  plugin:
+    implements: permission_handler
+    platforms:
+      ios:                                    # ⚠️ 仅声明 ios，无 macos
+        pluginClass: PermissionHandlerPlugin
+```
+
+**影响**：
+- macOS 端 `GeneratedPluginRegistrant.swift` 不会注册 `PermissionHandlerApplePlugin`
+- 调用 `Permission.camera.status` / `Permission.photos.request()` / `openAppSettings()` 等方法会抛出 `MissingPluginException(No implementation found for method checkPermissionStatus on channel flutter.baseflow.com/permissions/methods)`
+- 这是 macOS App Store 审核被拒 Guideline 2.1(a) 的直接原因（权限管理页点击相册/麦克风显示错误信息）
+
+**解决方案**：
+- macOS sandbox 下，权限由 **entitlement + Info.plist 用法说明** 自动管理
+- 系统在 App 首次访问受保护资源（相机/麦克风/相册）时弹出授权对话框（由 OS 触发，不由 App 调用）
+- `permission_service.dart` 中 `checkStatus()` / `requestPermission()` 已添加 macOS 早返回逻辑，直接返回 `granted`，避免调用未注册的方法通道
+- `openSettings()` 已添加 macOS 原生跳转：`Process.run('open', ['x-apple.systempreferences:com.apple.preference.security?Privacy'])`
+
+**macOS 必需的 entitlement 与 Info.plist 配置**：
+
+| 权限 | Entitlement | Info.plist Key | 说明 |
+|---|---|---|---|
+| 相机 | `com.apple.security.device.camera` | `NSCameraUsageDescription` | 扫码 / 拍照 / OCR |
+| 麦克风 | `com.apple.security.device.audio-input` | `NSMicrophoneUsageDescription` | 语音录制 / 语音转文字 |
+| 相册 | `com.apple.security.personal-information.photos-library` | （无需）| 保存图片/视频到相册 |
+| 本地服务器 | `com.apple.security.network.server` | （无需）| LocalSend 局域网文件传输 |
+
+> **注意**：`permission_handler_apple` 后续版本可能新增 macOS 支持，届时可移除 `permission_service.dart` 中的 macOS 早返回逻辑。检查方法：查看 `pub-cache/hosted/pub.dev/permission_handler_apple-X.Y.Z/` 是否存在 `macos/` 目录。
+
 ### 2.9 ⚠️ 鸿蒙端升级 Tips（2026-06-15，完成后删除本节）

 > **本节为鸿蒙端开发者提供升级指引，鸿蒙端完成适配后请删除此节。**