初始化项目：添加 Git 版本控制、.gitignore 和 README
- 建立基础的 Git 仓库结构 - 配置适用于 Vue.js + Node.js + Android 的 .gitignore - 添加项目说明文档和开发计划 - 包含 Kiro IDE 规格文档和项目计划
This commit is contained in:
400
.kiro/specs/personal-billing-app/design.md
Normal file
400
.kiro/specs/personal-billing-app/design.md
Normal file
@@ -0,0 +1,400 @@
|
||||
# 个人账单应用设计文档
|
||||
|
||||
## 概述
|
||||
|
||||
个人账单应用是一个现代化的财务管理工具，采用 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 权限最小化原则
|
||||
- 通知访问权限说明
|
||||
- 用户授权确认机制
|
||||
Reference in New Issue
Block a user