226 lines
10 KiB
Markdown
226 lines
10 KiB
Markdown
# app-android 迁移至 React Web 应用计划
|
||
|
||
> **目标**：将现有 Kotlin + Jetpack Compose 原生 Android 应用迁移为**纯 React Web 应用**，不再依赖任何原生 iOS/Android 代码，统一为浏览器端运行。
|
||
|
||
---
|
||
|
||
## 1. app-android 现状摘要
|
||
|
||
### 1.1 技术栈
|
||
|
||
| 层级 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 语言 | Kotlin 1.9+ | 主语言 |
|
||
| UI | Jetpack Compose | 声明式 UI |
|
||
| 架构 | MVVM | ViewModel + Compose |
|
||
| 网络 | Ktor | HTTP + WebSocket |
|
||
| 本地存储 | Room + DataStore | SQLite 数据库 + 键值存储 |
|
||
| 导航 | Navigation Compose | 声明式导航 |
|
||
| 图片 | Coil | 图片加载 |
|
||
| 主题 | Material 3 | 深色/浅色主题 |
|
||
| 支付 | 微信支付 / 支付宝 | 原生 SDK 集成 |
|
||
|
||
### 1.2 项目结构
|
||
|
||
```
|
||
app-android/
|
||
├── config/ # AppConfig (API 地址、BuildConfig)
|
||
├── data/ # 数据层
|
||
│ ├── auth/ # TokenManager (DataStore)
|
||
│ ├── database/ # Room (AppDatabase, Entity, DAO)
|
||
│ ├── preferences/ # TokenPreferences
|
||
│ └── repository/ # Conversation/Chapter/Message/Payment/Profile Repository
|
||
├── network/ # 网络层
|
||
│ ├── ApiService # REST API (Ktor + Bearer Auth)
|
||
│ ├── AuthService # 登录/注册/刷新 Token
|
||
│ ├── WebSocketClient
|
||
│ └── models/ # 请求/响应 DTO
|
||
├── ui/
|
||
│ ├── screens/ # 20+ 屏幕
|
||
│ ├── components/ # 可复用组件
|
||
│ ├── theme/ # Color, Theme, Type
|
||
│ ├── viewmodel/ # 7 个 ViewModel
|
||
│ └── settings/ # AppSettings (深色模式等)
|
||
├── navigation/ # Screen 路由 + AppNavigation
|
||
├── feature/ # VoiceRecorder 等
|
||
└── utils/ # 工具类
|
||
```
|
||
|
||
### 1.3 功能模块清单
|
||
|
||
| 模块 | screens / 组件 | ViewModel |
|
||
|------|-----------------|-----------|
|
||
| 认证 | Login, Register, NicknameSetup, ResetPassword, AccountManagement | AuthViewModel |
|
||
| 对话 | ConversationList, CreateMemory | ConversationListViewModel, CreateMemoryViewModel |
|
||
| 回忆录 | MyMemoir, ChapterReading, FullTextReading | MyMemoirViewModel |
|
||
| 个人中心 | Profile, PersonalInfo | ProfileViewModel |
|
||
| 套餐/支付 | UpgradePlan, PlanDetails, PlanBalance, MyOrders | PaymentViewModel |
|
||
| 设置/帮助 | FAQ, Feedback, About, ExportData, LegalDocument | - |
|
||
|
||
### 1.4 核心能力
|
||
|
||
- **认证**：手机号注册、登录、JWT Token 管理、刷新 Token、DataStore 持久化
|
||
- **对话**：WebSocket 实时语音对话、消息收发、TTS 播放
|
||
- **回忆录**：章节列表、阅读、全文、PDF 导出、对话整理为章节
|
||
- **支付**：微信支付、支付宝、套餐、订单、余额
|
||
- **本地数据**：Room 存储 Conversation/Chapter/Message，离线同步
|
||
- **主题**：深色模式、Material 3
|
||
|
||
---
|
||
|
||
## 2. 迁移策略
|
||
|
||
- 新建 **React Web 项目**（Vite + React 或 Create React App），不复用 app-ios
|
||
- 按 **模块/功能** 逐步迁移，优先核心流程（登录 → 对话 → 回忆录）
|
||
- 保留 API 契约不变，仅替换客户端实现
|
||
- **零原生代码**：纯 Web 技术栈，部署为静态站点或 SPA
|
||
|
||
---
|
||
|
||
## 3. 迁移步骤 TODO
|
||
|
||
### Phase 0：环境与基建（前置）
|
||
|
||
| # | 任务 | 说明 | 优先级 |
|
||
|---|------|------|--------|
|
||
| 0.1 | 初始化 React Web 项目 | `npm create vite@latest app-web -- --template react-ts` 或 CRA | P0 |
|
||
| 0.2 | 配置 API 环境 | 将 AppConfig.kt 中 BASE_URL / WS_BASE_URL 迁移为 env (VITE_*) | P0 |
|
||
| 0.3 | 搭建项目目录结构 | src/screens, components, services, store, hooks, themes | P1 |
|
||
| 0.4 | 配置路由 | React Router v6 | P0 |
|
||
|
||
### Phase 1：认证与 Token 管理
|
||
|
||
| # | 任务 | 对应 Android 实现 | 说明 | 优先级 |
|
||
|---|------|-------------------|------|--------|
|
||
| 1.1 | Auth API 封装 | AuthService.kt | 注册、登录、刷新 Token | P0 |
|
||
| 1.2 | Token 持久化 | TokenManager + DataStore | localStorage 或 sessionStorage | P0 |
|
||
| 1.3 | 401 自动刷新 + 登出 | ApiService Auth plugin | axios 拦截器实现 Bearer + 刷新 | P0 |
|
||
| 1.4 | LoginScreen | LoginScreen.kt | 手机号 + 密码登录 | P0 |
|
||
| 1.5 | RegisterScreen | RegisterScreen.kt | 手机号注册 | P0 |
|
||
| 1.6 | NicknameSetupScreen | NicknameSetupScreen.kt | 首次登录昵称设置 | P1 |
|
||
| 1.7 | ResetPasswordScreen | ResetPasswordScreen.kt | 重置密码 | P1 |
|
||
| 1.8 | AccountManagementScreen | AccountManagementScreen.kt | 账号管理、登出 | P1 |
|
||
|
||
### Phase 2：导航与主框架
|
||
|
||
| # | 任务 | 对应 Android 实现 | 说明 | 优先级 |
|
||
|---|------|-------------------|------|--------|
|
||
| 2.1 | 路由定义 | Screen sealed class | 定义所有 route 常量 / 路径 | P0 |
|
||
| 2.2 | 底部 Tab 导航 | MainActivity BottomNav | 聊天 / 回忆录 / 我的 三个 Tab | P0 |
|
||
| 2.3 | 栈式页面导航 | AppNavigation.kt | React Router `<Outlet>` / 嵌套路由 | P0 |
|
||
| 2.4 | 登录态路由守卫 | ProtectedRoute 组件 | 未登录 → 重定向 Login | P0 |
|
||
| 2.5 | 过渡动画 | NavigationTransitions | 视需求用 CSS transition 或 Framer Motion | P2 |
|
||
|
||
### Phase 3：REST API 与数据层
|
||
|
||
| # | 任务 | 对应 Android 实现 | 说明 | 优先级 |
|
||
|---|------|-------------------|------|--------|
|
||
| 3.1 | API Client 封装 | ApiService.kt | axios 实例、baseURL、timeout | P0 |
|
||
| 3.2 | 对话相关 API | ApiService 对话接口 | create/list/get conversation | P0 |
|
||
| 3.3 | 回忆录/章节 API | ApiService 章节/书籍接口 | books, chapters, PDF 等 | P0 |
|
||
| 3.4 | 支付/套餐 API | ApiService 支付接口 | plans, orders, balance | P1 |
|
||
| 3.5 | 用户/配置 API | ApiService Profile | 用户信息、FAQ、反馈 | P1 |
|
||
| 3.6 | 数据模型 (TypeScript) | network/models/*.kt | 定义请求/响应类型 | P0 |
|
||
|
||
### Phase 4：WebSocket 与对话功能
|
||
|
||
| # | 任务 | 对应 Android 实现 | 说明 | 优先级 |
|
||
|---|------|-------------------|------|--------|
|
||
| 4.1 | WebSocket Client | WebSocketClient.kt | 原生 `WebSocket` API，心跳、重连 | P0 |
|
||
| 4.2 | WebSocket 消息协议 | WebSocketMessage.kt | type / payload 解析 | P0 |
|
||
| 4.3 | 消息收发逻辑 | CreateMemoryViewModel | sendAudio/sendText、接收 TTS/文本 | P0 |
|
||
| 4.4 | 浏览器录音 | VoiceRecorder.kt | `MediaRecorder` API（getUserMedia） | P0 |
|
||
| 4.5 | ConversationListScreen | ConversationListScreen.kt | 对话列表 | P0 |
|
||
| 4.6 | CreateMemoryScreen | CreateMemoryScreen.kt | 聊天详情、语音输入 | P0 |
|
||
| 4.7 | MessageBubble / ChatInputField | 对应 Compose 组件 | 消息气泡、输入框 | P0 |
|
||
| 4.8 | 音频播放 (TTS) | CreateMemoryViewModel 中 TTS | `HTMLAudioElement` / `new Audio()` | P0 |
|
||
|
||
### Phase 5：回忆录模块
|
||
|
||
| # | 任务 | 对应 Android 实现 | 说明 | 优先级 |
|
||
|---|------|-------------------|------|--------|
|
||
| 5.1 | MyMemoirScreen | MyMemoirScreen.kt | 回忆录 Tab 主页 | P0 |
|
||
| 5.2 | 章节列表 | ChapterCard, BookInfoCard | 书籍/章节列表展示 | P0 |
|
||
| 5.3 | ChapterReadingView | 章节阅读 | 单章阅读 | P0 |
|
||
| 5.4 | FullTextReadingView | 全文阅读 | 完整回忆录阅读 | P1 |
|
||
| 5.5 | PDF 导出 | MyMemoirViewModel 导出逻辑 | 调用 API 获取 PDF，`blob` 下载或新窗口打开 | P1 |
|
||
| 5.6 | OrganizeConversationDialog | 对话整理为章节 | 弹窗 + API 调用 | P1 |
|
||
|
||
### Phase 6：个人中心与支付
|
||
|
||
| # | 任务 | 对应 Android 实现 | 说明 | 优先级 |
|
||
|---|------|-------------------|------|--------|
|
||
| 6.1 | ProfileScreen | ProfileScreen.kt | 我的 Tab、未登录/已登录 UI | P0 |
|
||
| 6.2 | PersonalInfoScreen | PersonalInfoScreen.kt | 个人信息、头像上传 | P1 |
|
||
| 6.3 | UpgradePlanScreen | UpgradePlanScreen.kt | 套餐选择 | P1 |
|
||
| 6.4 | PlanDetailsScreen / PlanBalanceScreen | 套餐详情、余额 | P1 |
|
||
| 6.5 | MyOrdersScreen | 订单列表 | P1 |
|
||
| 6.6 | 微信/支付宝支付 | PaymentUtils | 使用 H5 支付：微信 JSAPI / 支付宝网页支付 | P2 |
|
||
| 6.7 | FAQScreen / FeedbackScreen | 常见问题、反馈 | P1 |
|
||
| 6.8 | AboutScreen / LegalDocumentScreen | 关于、条款、隐私 | P1 |
|
||
| 6.9 | ExportDataScreen | 数据导出 | P2 |
|
||
|
||
### Phase 7：本地存储（可选）
|
||
|
||
| # | 任务 | 对应 Android 实现 | 说明 | 优先级 |
|
||
|---|------|-------------------|------|--------|
|
||
| 7.1 | 本地缓存 | Room + Repository | localStorage / IndexedDB（如 dexie.js）| P2 |
|
||
| 7.2 | 离线同步逻辑 | Repository 同步 | 视产品需求决定是否保留 | P2 |
|
||
|
||
### Phase 8：主题、设置与收尾
|
||
|
||
| # | 任务 | 对应 Android 实现 | 说明 | 优先级 |
|
||
|---|------|-------------------|------|--------|
|
||
| 8.1 | 主题系统 | LifeechoTheme, Color.kt | CSS 变量 + 深色/浅色 media/切换 | P1 |
|
||
| 8.2 | 主题持久化 | AppSettings.kt | localStorage 保存用户偏好 | P1 |
|
||
| 8.3 | 国际化 (i18n) | strings.xml | react-i18next 或类似 | P2 |
|
||
| 8.4 | 麦克风权限 | RECORD_AUDIO | 浏览器 `navigator.mediaDevices.getUserMedia` 需 HTTPS | P0 |
|
||
|
||
### Phase 9：构建与发布
|
||
|
||
| # | 任务 | 说明 | 优先级 |
|
||
|---|------|------|--------|
|
||
| 9.1 | 生产构建 | `npm run build`（Vite 输出 dist/）| P0 |
|
||
| 9.2 | 静态托管部署 | 部署至 Vercel / Netlify / Nginx 等 | P0 |
|
||
| 9.3 | 版本号与 CI | 对齐现有 GitHub Actions（若有）| P1 |
|
||
|
||
---
|
||
|
||
## 4. 技术映射速查
|
||
|
||
| Android (Kotlin) | React Web 对应 |
|
||
|------------------|-----------------|
|
||
| Jetpack Compose | React 组件 + CSS / Tailwind / styled-components |
|
||
| ViewModel + StateFlow | useState / useReducer / Zustand / React Query |
|
||
| Navigation Compose | React Router v6 |
|
||
| Ktor HttpClient | axios / fetch |
|
||
| Ktor WebSocket | 原生 `WebSocket` |
|
||
| Room | localStorage / IndexedDB（或仅网络）|
|
||
| DataStore | localStorage / sessionStorage |
|
||
| Coil | `<img>` / 原生加载 |
|
||
| Material 3 | 自定义主题 / MUI / shadcn/ui |
|
||
|
||
---
|
||
|
||
## 5. 风险与注意事项
|
||
|
||
1. **WebSocket + 语音**：浏览器端 WebSocket 稳定，录音需 `getUserMedia`，HTTPS 环境下可用。
|
||
2. **支付**：Web 端使用微信 H5 支付、支付宝网页支付，无需原生 SDK。
|
||
3. **本地数据**：Web 无 SQLite，可用 localStorage 简单缓存或 IndexedDB 做离线。
|
||
4. **性能**：长列表用虚拟滚动（react-window / react-virtuoso）。
|
||
5. **PWA**：可选做成 PWA，支持离线与「添加到主屏幕」。
|
||
|
||
---
|
||
|
||
## 6. 建议执行顺序
|
||
|
||
1. **Phase 0 + 1 + 2**：基建 + 认证 + 导航，打通「登录 → 主框架」。
|
||
2. **Phase 3 + 4**：API + WebSocket + 对话，实现核心对话流程。
|
||
3. **Phase 5**：回忆录浏览与阅读。
|
||
4. **Phase 6**：个人中心与基础套餐展示（支付可延后）。
|
||
5. **Phase 7 / 8 / 9**：按需推进本地存储、主题、构建发布。
|
||
|
||
---
|
||
|
||
*文档版本：1.0 | 更新日期：2025-02-15*
|