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 端一致，后端无需改动