From 58bc857325b566985864f2a7bcbb984f23c7b020 Mon Sep 17 00:00:00 2001 From: zimplexing Date: Fri, 11 Jul 2025 22:11:07 +0800 Subject: [PATCH] feat: Add Android 5.0 compatibility analysis report detailing risks, downgrade options, and implementation steps --- docs/ANDROID_5_COMPATIBILITY_ANALYSIS.md | 291 +++++++++++++++++++++++ 1 file changed, 291 insertions(+) create mode 100644 docs/ANDROID_5_COMPATIBILITY_ANALYSIS.md diff --git a/docs/ANDROID_5_COMPATIBILITY_ANALYSIS.md b/docs/ANDROID_5_COMPATIBILITY_ANALYSIS.md new file mode 100644 index 0000000..36a590d --- /dev/null +++ b/docs/ANDROID_5_COMPATIBILITY_ANALYSIS.md @@ -0,0 +1,291 @@ +# OrionTV Android 5.0 兼容性分析报告 + +## 项目概述 + +OrionTV是一个基于React Native TVOS和Expo SDK的电视端视频流媒体应用，专为Apple TV和Android TV平台设计。本文档分析了将项目降级到支持Android 5.0 (API Level 21)的兼容性风险和实施方案。 + +## 当前技术栈 + +### 核心框架版本 +- **React Native**: `npm:react-native-tvos@~0.74.2-0` +- **Expo SDK**: `~51.0.13` +- **React**: `18.2.0` +- **TypeScript**: `~5.3.3` +- **最小Android API级别**: 23 (Android 6.0) +- **目标Android API级别**: 34 (Android 14) + +### 关键依赖 +- `expo-av`: `~14.0.7` (视频播放) +- `expo-router`: `~3.5.16` (路由导航) +- `react-native-reanimated`: `~3.10.1` (动画) +- `react-native-tcp-socket`: `^6.0.6` (网络服务) +- `zustand`: `^5.0.6` (状态管理) + +## 兼容性限制分析 + +### React Native 0.74 限制 +根据官方文档，React Native 0.74已将最低Android API级别要求提升到23 (Android 6.0)，不再支持Android 5.0 (API Level 21)。 + +### Expo SDK 51 限制 +Expo SDK 51基于React Native 0.74，同样不支持Android 5.0。 + +## 降级方案 + +### 推荐的版本组合 + +#### 方案A: 保持TV功能的最新兼容版本 +```json +{ + "react-native": "npm:react-native-tvos@~0.73.8-0", + "expo": "~50.0.0", + "expo-av": "~13.10.x", + "expo-router": "~3.4.x", + "react-native-reanimated": "~3.8.x" +} +``` + +#### 方案B: 最大向后兼容版本 +```json +{ + "react-native": "npm:react-native-tvos@~0.72.12-0", + "expo": "~49.0.0" +} +``` + +### Android配置修改 +```gradle +// android/build.gradle +android { + minSdkVersion = 21 // 支持Android 5.0 + targetSdkVersion = 30 // 降级到Android 11 + compileSdkVersion = 33 // 对应的编译SDK版本 +} +``` + +## 风险评估 + +### 🔴 高风险组件 + +#### 1. 视频播放功能 (expo-av) +- **影响文件**: `hooks/usePlaybackManager.ts`, `app/play.tsx`, `stores/playerStore.ts` +- **风险**: API变化可能影响播放控制 +- **关键代码**: + ```typescript + import { Video, AVPlaybackStatus } from "expo-av"; + // 可能受影响的API调用 + videoRef?.current?.replayAsync(); + videoRef?.current?.pauseAsync(); + videoRef?.current?.playAsync(); + ``` + +#### 2. TV遥控器功能 (react-native-tvos) +- **影响文件**: `hooks/useTVRemoteHandler.ts` + 7个组件文件 +- **风险**: 遥控器事件处理可能有变化 +- **关键代码**: + ```typescript + import { useTVEventHandler, HWEvent } from "react-native"; + // 长按事件处理可能需要调整 + case "longRight": + case "longLeft": + ``` + +#### 3. 路由导航 (expo-router) +- **影响文件**: 9个页面文件 +- **风险**: 路由配置和参数传递可能有变化 +- **关键代码**: + ```typescript + import { useRouter, useLocalSearchParams } from "expo-router"; + ``` + +### 🟡 中等风险组件 + +#### 1. 远程控制服务 (react-native-tcp-socket) +- **影响文件**: `services/tcpHttpServer.ts` +- **风险**: 网络API兼容性问题 +- **关键代码**: + ```typescript + import TcpSocket from 'react-native-tcp-socket'; + this.server = TcpSocket.createServer((socket: TcpSocket.Socket) => {}); + ``` + +#### 2. 动画效果 (react-native-reanimated) +- **影响文件**: `components/VideoCard.tv.tsx` +- **风险**: 动画性能可能下降 +- **关键代码**: + ```typescript + import Animated, { useSharedValue, useAnimatedStyle, withSpring } from "react-native-reanimated"; + ``` + +### 🟢 低风险组件 + +#### 1. 状态管理 (zustand) +- **影响**: 与React Native版本无直接关系 +- **风险**: 极低 + +#### 2. 数据存储 (AsyncStorage) +- **影响文件**: `services/storage.ts` +- **风险**: 极低，API稳定 + +## 平台特定风险 + +### Android API 23 → 21 降级影响 + +#### 1. 运行时权限模型 +- **API 23+**: 需要运行时权限请求 +- **API 21-22**: 安装时权限模型 +- **影响**: 网络权限处理可能需要调整 + +#### 2. 网络安全配置 +- **风险**: HTTP cleartext流量处理 +- **当前配置**: `android.usesCleartextTraffic = true` +- **建议**: 保持当前配置确保向后兼容 + +#### 3. 后台服务限制 +- **API 23+**: 更严格的后台服务限制 +- **API 21-22**: 相对宽松的后台服务策略 +- **影响**: 远程控制服务可能表现不同 + +## 实施步骤 + +### 1. 准备阶段 +```bash +# 1. 备份当前项目 +git checkout -b android-5-compatibility + +# 2. 清理现有依赖 +rm -rf node_modules +rm yarn.lock +``` + +### 2. 版本降级 +```bash +# 3. 修改package.json依赖版本 +# 4. 重新安装依赖 +yarn install + +# 5. 清理原生代码 +yarn prebuild-tv --clean +``` + +### 3. 配置修改 +```bash +# 6. 修改android/build.gradle +# 7. 更新app.json配置 +# 8. 复制TV相关配置 +yarn copy-config +``` + +### 4. 测试构建 +```bash +# 9. 本地构建测试 +yarn build-local + +# 10. 运行测试 +yarn test +``` + +## 测试清单 + +### 核心功能测试 +- [ ] 视频播放、暂停、进度控制 +- [ ] 遥控器所有按键响应(上下左右、选择、菜单、返回) +- [ ] 长按快进/快退功能 +- [ ] 页面导航和参数传递 +- [ ] 焦点管理和视觉反馈 + +### TV特定功能测试 +- [ ] 控制条自动显示/隐藏 +- [ ] 剧集切换功能 +- [ ] 远程控制HTTP服务 +- [ ] 设置页面各项配置 +- [ ] 搜索功能 + +### 兼容性测试 +- [ ] Android 5.0真机测试 +- [ ] Android TV模拟器测试 +- [ ] Apple TV模拟器测试 +- [ ] 不同屏幕尺寸适配 +- [ ] 内存使用情况 +- [ ] 启动性能测试 + +## 依赖版本对照表 + +| 组件 | 当前版本 | 目标版本 | 风险等级 | 备注 | +|------|----------|----------|----------|------| +| react-native-tvos | ~0.74.2-0 | ~0.73.8-0 | 🔴 高 | TV功能核心 | +| expo | ~51.0.13 | ~50.0.0 | 🔴 高 | 框架基础 | +| expo-av | ~14.0.7 | ~13.10.x | 🔴 高 | 视频播放 | +| expo-router | ~3.5.16 | ~3.4.x | 🔴 高 | 路由导航 | +| react-native-reanimated | ~3.10.1 | ~3.8.x | 🟡 中 | 动画效果 | +| react-native-tcp-socket | ^6.0.6 | ^6.0.4 | 🟡 中 | 网络服务 | +| zustand | ^5.0.6 | ^5.0.6 | 🟢 低 | 状态管理 | +| @react-native-async-storage/async-storage | ^2.2.0 | ^2.1.x | 🟢 低 | 数据存储 | + +## 潜在问题和解决方案 + +### 1. 视频播放问题 +**问题**: expo-av版本降级可能导致某些视频格式不支持 +**解决方案**: +- 测试主要视频格式(MP4, M3U8) +- 必要时实现格式转换 +- 提供播放失败的友好提示 + +### 2. 遥控器响应问题 +**问题**: TV事件处理可能有差异 +**解决方案**: +- 仔细测试所有遥控器按键 +- 调整事件处理逻辑 +- 增加兼容性检查 + +### 3. 路由导航问题 +**问题**: 页面跳转参数传递可能有变化 +**解决方案**: +- 测试所有页面跳转 +- 验证参数正确传递 +- 必要时调整路由配置 + +### 4. 动画性能问题 +**问题**: 动画可能在低端设备上表现不佳 +**解决方案**: +- 简化动画效果 +- 增加性能检测 +- 提供动画开关选项 + +## 建议与结论 + +### 风险总结 +- **总体风险等级**: 🔴 **高等风险** +- **主要风险点**: 视频播放、遥控器功能、路由导航 +- **预计工作量**: 2-3周开发 + 1-2周测试 + +### 成本效益分析 +- **开发成本**: 高（需要大量测试和调试） +- **维护成本**: 高（使用较旧版本，安全更新有限） +- **用户覆盖**: 低（Android 5用户占比通常<2%） + +### 最终建议 +**不建议进行降级**，原因如下： +1. 技术风险高，可能影响核心功能稳定性 +2. 维护成本高，需要长期支持多个版本 +3. 用户收益有限，Android 5用户占比极低 +4. 与业界趋势不符，各大平台都在提升最低版本要求 + +### 替代方案 +1. **统计用户分布**: 收集实际用户设备数据，确认Android 5用户占比 +2. **渐进式升级**: 引导用户升级设备，提供升级指南 +3. **精简版本**: 为老设备提供功能精简的独立版本 +4. **Web版本**: 提供Web端访问方式作为补充 + +## 参考资料 + +- [React Native 0.74 Release Notes](https://reactnative.dev/blog/2024/04/22/release-0.74) +- [Expo SDK 51 Changelog](https://expo.dev/changelog/2024-05-07-sdk-51) +- [React Native TV OS Documentation](https://github.com/react-native-tvos/react-native-tvos) +- [Android API Level Distribution](https://developer.android.com/about/dashboards) + +--- + +**文档版本**: 1.0 +**最后更新**: 2025-01-11 +**作者**: Claude Code Assistant +**审核状态**: 待审核 \ No newline at end of file