400 lines
9.4 KiB
Markdown
400 lines
9.4 KiB
Markdown
|
# 个人账单应用设计文档
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
个人账单应用是一个现代化的财务管理工具，采用 Vue.js + Node.js + Capacitor.js 技术栈构建。应用的核心特性是通过读取 Android 通知自动捕获交易信息，结合手动记账、云同步和数据分析功能，为用户提供完整的个人财务管理解决方案。
|
|||
|
|
|
|||
|
|
## 架构
|
|||
|
|
|
|||
|
|
### 整体架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|||
|
|
│ Vue.js 前端 │ │ Node.js 后端 │ │ MongoDB 数据库 │
|
|||
|
|
│ │ │ │ │ │
|
|||
|
|
│ - 用户界面 │◄──►│ - RESTful API │◄──►│ - 用户数据 │
|
|||
|
|
│ - 状态管理 │ │ - JWT 认证 │ │ - 交易记录 │
|
|||
|
|
│ - 本地存储 │ │ - 数据验证 │ │ - 分类配置 │
|
|||
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────┐
|
|||
|
|
│ Capacitor.js │
|
|||
|
|
│ │
|
|||
|
|
│ - Android 桥接 │
|
|||
|
|
│ - 通知监听服务 │
|
|||
|
|
│ - 原生功能调用 │
|
|||
|
|
└─────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 技术栈详细说明
|
|||
|
|
|
|||
|
|
**前端层 (Vue.js)**
|
|||
|
|
- Vue 3 with Composition API
|
|||
|
|
- Pinia 状态管理
|
|||
|
|
- Vue Router 路由管理
|
|||
|
|
- Tailwind CSS 样式框架
|
|||
|
|
- ECharts 图表库
|
|||
|
|
- SQLite (通过 Capacitor) 本地数据库
|
|||
|
|
|
|||
|
|
**后端层 (Node.js)**
|
|||
|
|
- Express.js 框架
|
|||
|
|
- MongoDB + Mongoose ODM
|
|||
|
|
- JWT 身份认证
|
|||
|
|
- bcrypt 密码加密
|
|||
|
|
- express-validator 数据验证
|
|||
|
|
|
|||
|
|
**移动端桥接 (Capacitor.js)**
|
|||
|
|
- 自定义通知监听插件
|
|||
|
|
- 本地存储插件
|
|||
|
|
- 网络状态检测
|
|||
|
|
|
|||
|
|
## 组件和接口
|
|||
|
|
|
|||
|
|
### 前端组件架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
App.vue
|
|||
|
|
├── Layout/
|
|||
|
|
│ ├── AppHeader.vue
|
|||
|
|
│ ├── AppNavigation.vue
|
|||
|
|
│ └── AppFooter.vue
|
|||
|
|
├── Pages/
|
|||
|
|
│ ├── HomePage.vue
|
|||
|
|
│ ├── AddTransactionPage.vue
|
|||
|
|
│ ├── AnalyticsPage.vue
|
|||
|
|
│ ├── SettingsPage.vue
|
|||
|
|
│ └── AuthPage.vue
|
|||
|
|
├── Components/
|
|||
|
|
│ ├── TransactionCard.vue
|
|||
|
|
│ ├── CategorySelector.vue
|
|||
|
|
│ ├── AmountInput.vue
|
|||
|
|
│ ├── DatePicker.vue
|
|||
|
|
│ ├── SearchFilter.vue
|
|||
|
|
│ ├── ChartComponents/
|
|||
|
|
│ │ ├── PieChart.vue
|
|||
|
|
│ │ ├── LineChart.vue
|
|||
|
|
│ │ └── BarChart.vue
|
|||
|
|
│ └── Common/
|
|||
|
|
│ ├── LoadingSpinner.vue
|
|||
|
|
│ ├── EmptyState.vue
|
|||
|
|
│ └── ConfirmDialog.vue
|
|||
|
|
└── Plugins/
|
|||
|
|
└── NotificationListener.js
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 后端 API 接口
|
|||
|
|
|
|||
|
|
**认证接口**
|
|||
|
|
```
|
|||
|
|
POST /api/auth/register
|
|||
|
|
POST /api/auth/login
|
|||
|
|
POST /api/auth/refresh
|
|||
|
|
POST /api/auth/logout
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**交易管理接口**
|
|||
|
|
```
|
|||
|
|
GET /api/transactions # 获取交易列表（支持分页和筛选）
|
|||
|
|
POST /api/transactions # 创建新交易
|
|||
|
|
GET /api/transactions/:id # 获取单个交易详情
|
|||
|
|
PUT /api/transactions/:id # 更新交易
|
|||
|
|
DELETE /api/transactions/:id # 删除交易
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**分类和账户管理**
|
|||
|
|
```
|
|||
|
|
GET /api/categories # 获取分类列表
|
|||
|
|
POST /api/categories # 创建分类
|
|||
|
|
PUT /api/categories/:id # 更新分类
|
|||
|
|
DELETE /api/categories/:id # 删除分类
|
|||
|
|
|
|||
|
|
GET /api/accounts # 获取账户列表
|
|||
|
|
POST /api/accounts # 创建账户
|
|||
|
|
PUT /api/accounts/:id # 更新账户
|
|||
|
|
DELETE /api/accounts/:id # 删除账户
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**数据分析接口**
|
|||
|
|
```
|
|||
|
|
GET /api/analytics/summary # 获取汇总数据
|
|||
|
|
GET /api/analytics/trends # 获取趋势数据
|
|||
|
|
GET /api/analytics/categories # 获取分类统计
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**同步接口**
|
|||
|
|
```
|
|||
|
|
POST /api/sync/upload # 上传本地更改
|
|||
|
|
GET /api/sync/download # 下载服务器更新
|
|||
|
|
GET /api/sync/status # 获取同步状态
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Capacitor 插件接口
|
|||
|
|
|
|||
|
|
**通知监听插件**
|
|||
|
|
```typescript
|
|||
|
|
interface NotificationListenerPlugin {
|
|||
|
|
requestPermission(): Promise<{ granted: boolean }>;
|
|||
|
|
startListening(): Promise<void>;
|
|||
|
|
stopListening(): Promise<void>;
|
|||
|
|
addListener(
|
|||
|
|
eventName: 'notificationReceived',
|
|||
|
|
listenerFunc: (notification: ParsedNotification) => void
|
|||
|
|
): Promise<PluginListenerHandle>;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
interface ParsedNotification {
|
|||
|
|
amount: number;
|
|||
|
|
type: 'income' | 'expense';
|
|||
|
|
source: string;
|
|||
|
|
merchant?: string;
|
|||
|
|
timestamp: string;
|
|||
|
|
rawContent: string;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 数据模型
|
|||
|
|
|
|||
|
|
### 用户模型 (User)
|
|||
|
|
```javascript
|
|||
|
|
{
|
|||
|
|
_id: ObjectId,
|
|||
|
|
email: String,
|
|||
|
|
password: String, // bcrypt 加密
|
|||
|
|
name: String,
|
|||
|
|
createdAt: Date,
|
|||
|
|
updatedAt: Date,
|
|||
|
|
preferences: {
|
|||
|
|
currency: String,
|
|||
|
|
language: String,
|
|||
|
|
theme: String
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 交易模型 (Transaction)
|
|||
|
|
```javascript
|
|||
|
|
{
|
|||
|
|
_id: ObjectId,
|
|||
|
|
userId: ObjectId,
|
|||
|
|
amount: Number,
|
|||
|
|
type: String, // 'income' | 'expense'
|
|||
|
|
category: ObjectId,
|
|||
|
|
account: ObjectId,
|
|||
|
|
merchant: String,
|
|||
|
|
description: String,
|
|||
|
|
date: Date,
|
|||
|
|
createdAt: Date,
|
|||
|
|
updatedAt: Date,
|
|||
|
|
syncStatus: String, // 'synced' | 'pending' | 'conflict'
|
|||
|
|
source: String, // 'manual' | 'notification'
|
|||
|
|
rawNotification: String // 原始通知内容（如果来自通知）
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 分类模型 (Category)
|
|||
|
|
```javascript
|
|||
|
|
{
|
|||
|
|
_id: ObjectId,
|
|||
|
|
userId: ObjectId,
|
|||
|
|
name: String,
|
|||
|
|
icon: String,
|
|||
|
|
color: String,
|
|||
|
|
type: String, // 'income' | 'expense' | 'both'
|
|||
|
|
isDefault: Boolean,
|
|||
|
|
createdAt: Date,
|
|||
|
|
updatedAt: Date
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 账户模型 (Account)
|
|||
|
|
```javascript
|
|||
|
|
{
|
|||
|
|
_id: ObjectId,
|
|||
|
|
userId: ObjectId,
|
|||
|
|
name: String,
|
|||
|
|
type: String, // 'cash' | 'alipay' | 'wechat' | 'bank'
|
|||
|
|
icon: String,
|
|||
|
|
color: String,
|
|||
|
|
isDefault: Boolean,
|
|||
|
|
createdAt: Date,
|
|||
|
|
updatedAt: Date
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 错误处理
|
|||
|
|
|
|||
|
|
### 前端错误处理策略
|
|||
|
|
|
|||
|
|
**网络错误**
|
|||
|
|
- 自动重试机制（指数退避）
|
|||
|
|
- 离线模式切换
|
|||
|
|
- 用户友好的错误提示
|
|||
|
|
|
|||
|
|
**数据验证错误**
|
|||
|
|
- 实时表单验证
|
|||
|
|
- 清晰的错误信息显示
|
|||
|
|
- 防止无效数据提交
|
|||
|
|
|
|||
|
|
**通知解析错误**
|
|||
|
|
- 记录未识别的通知格式
|
|||
|
|
- 提供手动确认选项
|
|||
|
|
- 持续改进解析规则
|
|||
|
|
|
|||
|
|
### 后端错误处理
|
|||
|
|
|
|||
|
|
**API 错误响应格式**
|
|||
|
|
```javascript
|
|||
|
|
{
|
|||
|
|
success: false,
|
|||
|
|
error: {
|
|||
|
|
code: 'VALIDATION_ERROR',
|
|||
|
|
message: '数据验证失败',
|
|||
|
|
details: {
|
|||
|
|
field: 'amount',
|
|||
|
|
message: '金额必须大于0'
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**错误类型定义**
|
|||
|
|
- `VALIDATION_ERROR`: 数据验证错误
|
|||
|
|
- `AUTHENTICATION_ERROR`: 认证失败
|
|||
|
|
- `AUTHORIZATION_ERROR`: 权限不足
|
|||
|
|
- `NOT_FOUND_ERROR`: 资源不存在
|
|||
|
|
- `CONFLICT_ERROR`: 数据冲突
|
|||
|
|
- `INTERNAL_ERROR`: 服务器内部错误
|
|||
|
|
|
|||
|
|
### 同步冲突处理
|
|||
|
|
|
|||
|
|
**冲突解决策略**
|
|||
|
|
1. 服务器优先：默认采用服务器数据
|
|||
|
|
2. 用户选择：对于重要冲突，让用户选择
|
|||
|
|
3. 合并策略：对于非冲突字段进行合并
|
|||
|
|
4. 备份本地：冲突数据备份到本地
|
|||
|
|
|
|||
|
|
## 测试策略
|
|||
|
|
|
|||
|
|
### 单元测试
|
|||
|
|
- Vue 组件测试（Vue Test Utils + Jest）
|
|||
|
|
- API 端点测试（Supertest + Jest）
|
|||
|
|
- 工具函数测试
|
|||
|
|
- 数据模型验证测试
|
|||
|
|
|
|||
|
|
### 集成测试
|
|||
|
|
- 前后端 API 集成测试
|
|||
|
|
- 数据库操作测试
|
|||
|
|
- 通知解析功能测试
|
|||
|
|
- 同步机制测试
|
|||
|
|
|
|||
|
|
### 端到端测试
|
|||
|
|
- 用户注册登录流程
|
|||
|
|
- 交易添加编辑删除流程
|
|||
|
|
- 通知自动记账流程
|
|||
|
|
- 数据同步流程
|
|||
|
|
|
|||
|
|
### 移动端测试
|
|||
|
|
- Android 设备兼容性测试
|
|||
|
|
- 通知权限申请测试
|
|||
|
|
- 离线功能测试
|
|||
|
|
- 性能测试
|
|||
|
|
|
|||
|
|
## UI/UX 设计规范
|
|||
|
|
|
|||
|
|
### 色彩系统
|
|||
|
|
```css
|
|||
|
|
/* 主色调 */
|
|||
|
|
--primary: #F97316; /* 橙色 - 主要交互元素 */
|
|||
|
|
--primary-light: #FB923C; /* 浅橙色 - 悬停状态 */
|
|||
|
|
--primary-dark: #EA580C; /* 深橙色 - 按下状态 */
|
|||
|
|
|
|||
|
|
/* 辅助色 */
|
|||
|
|
--accent-blue: #3B82F6; /* 蓝色 - 收入相关 */
|
|||
|
|
--accent-green: #22C55E; /* 绿色 - 成功状态 */
|
|||
|
|
--accent-red: #EF4444; /* 红色 - 支出相关 */
|
|||
|
|
|
|||
|
|
/* 中性色 */
|
|||
|
|
--background: #F5F5F4; /* 背景色 */
|
|||
|
|
--surface: #FFFFFF; /* 卡片背景 */
|
|||
|
|
--text-primary: #333333; /* 主要文本 */
|
|||
|
|
--text-secondary: #666666; /* 次要文本 */
|
|||
|
|
--border: #E5E5E5; /* 边框色 */
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 组件设计原则
|
|||
|
|
|
|||
|
|
**卡片设计**
|
|||
|
|
- 大圆角 (16px)
|
|||
|
|
- 微妙阴影 (0 2px 8px rgba(0,0,0,0.1))
|
|||
|
|
- 充足的内边距 (16px)
|
|||
|
|
|
|||
|
|
**按钮设计**
|
|||
|
|
- 主按钮：橙色背景，白色文字
|
|||
|
|
- 次要按钮：透明背景，橙色边框
|
|||
|
|
- 悬浮按钮：圆形，橙色，右下角固定
|
|||
|
|
|
|||
|
|
**表单设计**
|
|||
|
|
- 圆角输入框 (8px)
|
|||
|
|
- 聚焦时橙色边框
|
|||
|
|
- 清晰的标签和占位符
|
|||
|
|
|
|||
|
|
**图标系统**
|
|||
|
|
- 使用 Lucide 图标库
|
|||
|
|
- 统一的线条粗细 (2px)
|
|||
|
|
- 分类图标支持自定义颜色
|
|||
|
|
|
|||
|
|
### 动画和交互
|
|||
|
|
|
|||
|
|
**页面转场**
|
|||
|
|
- 滑动动画 (300ms ease-out)
|
|||
|
|
- 淡入淡出效果
|
|||
|
|
|
|||
|
|
**按钮交互**
|
|||
|
|
- 点击时轻微缩放 (0.95)
|
|||
|
|
- 悬停时颜色变化
|
|||
|
|
- 加载状态显示
|
|||
|
|
|
|||
|
|
**列表动画**
|
|||
|
|
- 项目添加/删除的滑动动画
|
|||
|
|
- 搜索结果的淡入效果
|
|||
|
|
|
|||
|
|
## 性能优化
|
|||
|
|
|
|||
|
|
### 前端优化
|
|||
|
|
- 组件懒加载
|
|||
|
|
- 图片懒加载
|
|||
|
|
- 虚拟滚动（大量数据）
|
|||
|
|
- 防抖搜索
|
|||
|
|
- 缓存策略
|
|||
|
|
|
|||
|
|
### 后端优化
|
|||
|
|
- 数据库索引优化
|
|||
|
|
- API 响应缓存
|
|||
|
|
- 分页查询
|
|||
|
|
- 数据压缩
|
|||
|
|
|
|||
|
|
### 移动端优化
|
|||
|
|
- 本地数据缓存
|
|||
|
|
- 增量同步
|
|||
|
|
- 后台任务优化
|
|||
|
|
- 内存管理
|
|||
|
|
|
|||
|
|
## 安全考虑
|
|||
|
|
|
|||
|
|
### 数据安全
|
|||
|
|
- JWT Token 安全存储
|
|||
|
|
- API 请求加密 (HTTPS)
|
|||
|
|
- 敏感数据加密存储
|
|||
|
|
- 定期 Token 刷新
|
|||
|
|
|
|||
|
|
### 隐私保护
|
|||
|
|
- 通知数据本地处理
|
|||
|
|
- 用户数据最小化收集
|
|||
|
|
- 数据删除机制
|
|||
|
|
- 隐私政策合规
|
|||
|
|
|
|||
|
|
### 权限管理
|
|||
|
|
- Android 权限最小化原则
|
|||
|
|
- 通知访问权限说明
|
|||
|
|
- 用户授权确认机制
|