# Web 功能至 React Native TV 应用迁移计划

## 1. 项目目标

将现有 `web` 项目 (基于 Next.js) 的核心功能，包括视频浏览、搜索、详情查看、播放记录和收藏，完整地迁移到 React Native TV 应用中，并为电视遥控器交互进行深度优化。

## 2. 核心策略

我们将采用**前后端分离**的核心策略：

- **后端服务**: 将 `web/src/app/api/` 中的所有 API 逻辑剥离出来，封装成一个独立的、使用 **Express.js** 构建的 Node.js 服务。该服务将通过 **Docker** 进行容器化，部署在您的私有服务器上。
- **TV 应用 (前端)**: React Native TV 应用将作为纯前端，负责 UI 展示和用户交互。它将通过网络请求调用上述独立的后端服务来获取和提交数据。
- **数据持久化**: 用户数据（播放记录、收藏等）将从 `localStorage` 迁移到 React Native 的 **`AsyncStorage`**，实现应用内的本地持久化存储。

## 3. 架构设计

迁移后的系统架构如下所示：

```mermaid
graph TD
    subgraph "React Native TV 应用"
        A[用户] -->|遥控器交互| B(TV 应用界面)
        B -->|数据请求| C{数据服务层}
    end

    subgraph "本地存储"
        C -->|读/写| D[AsyncStorage (播放记录, 收藏)]
    end

    subgraph "后端服务 (Docker @ 您的服务器)"
        E[Express.js API 服务]
    end

    subgraph "第三方数据源"
        F[视频源 API]
        G[豆瓣 API]
    end

    C -->|API 请求| E
    E -->|代理请求| F
    E -->|代理请求| G
```

## 4. 分阶段实施计划

我们将迁移过程分为四个主要阶段，循序渐进，以确保每个环节都稳固可靠。

### 阶段一：后端服务搭建与部署 (Backend First)

**目标**: 优先保障数据接口的可用性，为后续所有前端工作提供数据基础。

- **任务 1**: 在项目根目录创建 `backend/` 文件夹，并初始化一个 Node.js (Express.js) 项目。
- **任务 2**: 将 `web/src/app/api/` 下的所有 API (search, detail, douban, login, playrecords) 的逻辑迁移到 Express 路由中。
- **任务 3**: 编写一个高效的 `Dockerfile`，用于构建后端服务的生产环境镜像。
- **任务 4**: 提供部署指南，说明如何在您的服务器上通过 Docker 启动服务，并配置必要的环境变量（如端口）。
- **交付物**: 可独立运行和测试的后端 API 服务。

### 阶段二：TV 应用基础建设与数据层迁移

**目标**: 在 TV 应用中搭建好基础框架，并完成数据存储逻辑的替换。

- **任务 1**: 安装必要的依赖库：`@react-native-async-storage/async-storage` (用于本地存储) 和 `react-navigation` (用于页面路由)。
- **任务 2**: 在 TV 应用中创建 `services/api.ts` 文件，封装所有对新后端服务的 `fetch` 请求。
- **任务 3**: 在 TV 应用中创建 `services/storage.ts` 文件，使用 `AsyncStorage` 重新实现 `web/src/lib/db.client.ts` 中的所有功能（播放记录、收藏的增删改查）。
- **交付物**: 一个可以与后端通信并能在本地存取数据的 TV 应用骨架。

### 阶段三：核心 UI 组件库迁移

**目标**: 自底向上，将 Web 组件重构为适用于 TV 平台的原生组件。

- **任务 1**: 识别 `web/src/components` 中的核心可复用组件，如 `VideoCard`、`ScrollableRow`、`AggregateCard` 等。
- **任务 2**: 在 TV 项目的 `components/` 目录下，创建对应的 TV 版本组件。
  - 将 HTML 标签 (`div`, `img`) 替换为 React Native 组件 (`View`, `Image`)。
  - 将 CSS 样式转换为 React Native 的 `StyleSheet` API。
  - **关键**: 为所有可交互组件添加 `onFocus`, `onBlur` 事件处理，并使用 `Touchable` 组件实现遥控器响应，确保良好的焦点管理和导航体验。
- **交付物**: 一套专为 TV 优化的、可复用的基础 UI 组件库。

### 阶段四：页面路由与功能整合

**目标**: 组装所有模块，将应用串联成一个完整、可用的产品。

- **任务 1**: 使用 `React Navigation` 库搭建 App 的整体路由结构，需要实现查看更多，详情页面，播放页等
- **任务 2**: 创建所有核心页面 (Screens)，例如 `MoreScreen`, `SearchScreen`, `DetailScreen`, `PlayerScreen`。
- **任务 3**: 在各个页面中，集成前几个阶段完成的 `services` 和 `components`，调用后端 API 获取数据，并渲染出最终界面。
- **任务 4**: 对整体应用进行联调测试，重点测试遥控器导航的流畅性和功能的完整性。
- **交付物**: 功能完整的 React Native TV 应用初版。

## 5. 技术栈清单

- **TV 应用**: React Native, TypeScript, React Navigation
- **后端服务**: Node.js, Express.js
- **数据存储**: @react-native-async-storage/async-storage
- **部署**: Docker

## 6. 风险与应对

- **风险**: 第三方 API 接口变更或失效。
  - **应对**: 后端服务已将 API 请求集中处理，若有变更，只需修改后端代码，无需更新客户端 App。
- **风险**: TV 平台（Android TV, tvOS）的 UI/UX 兼容性差异。
  - **应对**: 在开发过程中，优先使用 React Native 官方推荐的跨平台组件。对特定平台的差异，可以使用 `Platform.select()` 进行适配。

## 7. 下一步

我们已就此计划达成共识。下一步建议是：**切换到“代码”模式**，并开始着手执行**阶段一**的任务，即搭建和迁移独立的后端服务。