Novault-Frontend-app/implementation_plan.md

# NoVault App - React Native 移动端实施计划

## 📋 项目概述

将现有的 Web 端记账应用（frontend/）迁移到 React Native 原生应用（app/）。

### 技术栈对比

| 维度 | Web 端 (frontend/) | 移动端 (app/) |
| :--- | :--- | :--- |
| 框架 | React 19 + Vite | React Native 0.83 |
| 路由 | react-router-dom | @react-navigation/native |
| 状态 | Context + Hooks | Context + Hooks (复用) |
| 样式 | CSS 文件 | StyleSheet (需重写) |
| HTTP | fetch | fetch (可复用) |
| 图表 | ECharts | react-native-svg-charts 或 WebView |
| 图标 | @iconify/react | react-native-vector-icons |
| 动画 | framer-motion | react-native-reanimated |

---

## 🎯 核心功能模块

基于 Web 端的 pages 结构，移动端需要实现以下模块：

### 第一阶段：基础架构 (P0)

1. **项目结构搭建**
   - src/ 目录结构
   - 导航配置
   - 主题系统
   - API 服务层

2. **认证模块**
   - 登录页面
   - Token 存储 (AsyncStorage)
   - 自动刷新机制

3. **首页 (Home)**
   - 资产概览卡片
   - 快捷记账入口
   - 最近交易列表

### 第二阶段：核心功能 (P1)

1. **交易模块 (Transactions)**
   - 交易列表 (虚拟滚动)
   - 新增/编辑交易
   - 交易详情

2. **账户模块 (Accounts)**
   - 账户列表
   - 账户详情
   - 新增/编辑账户

3. **分类管理**
   - 分类选择器
   - 图标选择

### 第三阶段：增强功能 (P2)

1. **预算模块 (Budget)**
2. **报表模块 (Reports)**
3. **设置模块 (Settings)**
4. **工具模块 (Tools)**

---

## 📁 目录结构设计

```
app/
├── src/
│   ├── components/          # 可复用组件
│   │   ├── common/          # 通用组件 (Button, Card, Input...)
│   │   ├── transaction/     # 交易相关组件
│   │   └── account/         # 账户相关组件
│   │
│   ├── screens/             # 页面组件 (对应 Web 的 pages)
│   │   ├── Auth/            # 登录/注册
│   │   ├── Home/            # 首页
│   │   ├── Transactions/    # 交易
│   │   ├── Accounts/        # 账户
│   │   ├── Budget/          # 预算
│   │   ├── Reports/         # 报表
│   │   └── Settings/        # 设置
│   │
│   ├── navigation/          # 导航配置
│   │   ├── index.tsx        # 根导航
│   │   ├── MainTab.tsx      # 底部 Tab 导航
│   │   └── types.ts         # 导航类型定义
│   │
│   ├── services/            # API 服务 (从 Web 端移植)
│   │   ├── api.ts           # 基础 HTTP 客户端
│   │   ├── authService.ts
│   │   ├── transactionService.ts
│   │   └── accountService.ts
│   │
│   ├── hooks/               # 自定义 Hooks (从 Web 端移植)
│   │   ├── useTheme.tsx
│   │   └── useAuth.tsx
│   │
│   ├── contexts/            # Context Providers
│   │   ├── ThemeContext.tsx
│   │   └── AuthContext.tsx
│   │
│   ├── types/               # TypeScript 类型 (直接复用 Web 端)
│   │   └── index.ts
│   │
│   ├── theme/               # 主题配置
│   │   ├── colors.ts
│   │   ├── spacing.ts
│   │   └── typography.ts
│   │
│   └── utils/               # 工具函数 (从 Web 端移植)
│       ├── format.ts
│       └── date.ts
│
├── App.tsx                  # 应用入口
└── index.js                 # 注册入口
```

---

## 🔄 代码复用策略

### 可直接复用 (90%+)

| 模块 | 说明 |
| :--- | :--- |
| `types/index.ts` | 类型定义完全相同 |
| `services/*.ts` | API 调用逻辑，需微调 storage 方式 |
| `utils/*.ts` | 工具函数（日期格式化、金额计算等） |

### 需要适配 (50%)

| 模块 | 说明 |
| :--- | :--- |
| `hooks/*.tsx` | 核心逻辑复用，UI 相关部分需调整 |
| 状态管理 | Context 逻辑复用，Provider 包装调整 |

### 需要重写 (100%)

| 模块 | 说明 |
| :--- | :--- |
| 所有 UI 组件 | `<div>` → `<View>`, CSS → StyleSheet |
| 导航系统 | react-router → react-navigation |
| 样式系统 | CSS 文件 → RN StyleSheet |

---

## ✅ 任务清单

### Phase 1: 基础架构

- [ ] 1.1 创建 src/ 目录结构
- [ ] 1.2 安装核心依赖 (react-navigation, async-storage, vector-icons)
- [ ] 1.3 配置主题系统 (colors, typography, spacing)
- [ ] 1.4 移植 types/index.ts
- [ ] 1.5 创建 API 服务层 (适配 AsyncStorage)
- [ ] 1.6 配置导航结构 (Stack + Tab)
- [ ] 1.7 创建 AuthContext 和 ThemeContext

### Phase 2: 核心页面

- [ ] 2.1 登录页面
- [ ] 2.2 首页 (资产概览 + 快捷入口)
- [ ] 2.3 交易列表页
- [ ] 2.4 新增交易页
- [ ] 2.5 账户列表页

### Phase 3: 完善功能

- [ ] 3.1 交易详情和编辑
- [ ] 3.2 账户详情和编辑
- [ ] 3.3 分类选择器组件
- [ ] 3.4 预算模块
- [ ] 3.5 设置页面

---

## 📝 备注

- 优先保证核心记账流程可用
- 图表功能暂时使用 WebView 嵌入 ECharts，后期可替换为原生方案
- 保持 API 接口与 Web 端一致，后端无需改动