Jafeng/bill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

初始化项目：添加 Git 版本控制、.gitignore 和 README

Browse Source 
- 建立基础的 Git 仓库结构
- 配置适用于 Vue.js + Node.js + Android 的 .gitignore
- 添加项目说明文档和开发计划
- 包含 Kiro IDE 规格文档和项目计划
This commit is contained in:
Jafeng
2025-08-14 15:22:45 +08:00
commit bc998c35c7
6 changed files with 1089 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
.gitignore vendored Normal file
View File

@@ -0,0 +1,121 @@
# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
# Production builds
dist/
build/
# Environment variables
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
# IDE and editor files
.vscode/
.idea/
*.swp
*.swo
*~
# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
# Logs
logs
*.log
# Runtime data
pids
*.pid
*.seed
*.pid.lock
# Coverage directory used by tools like istanbul
coverage/
*.lcov
# nyc test coverage
.nyc_output
# Dependency directories
jspm_packages/
# Optional npm cache directory
.npm
# Optional eslint cache
.eslintcache
# Optional REPL history
.node_repl_history
# Output of 'npm pack'
*.tgz
# Yarn Integrity file
.yarn-integrity
# parcel-bundler cache (https://parceljs.org/)
.cache
.parcel-cache
# next.js build output
.next
# nuxt.js build output
.nuxt
# vuepress build output
.vuepress/dist
# Serverless directories
.serverless
# FuseBox cache
.fusebox/
# DynamoDB Local files
.dynamodb/
# Android
*.apk
*.ap_
*.dex
*.class
bin/
gen/
out/
build/
local.properties
proguard/
# Capacitor
android/app/src/main/assets/public/
ios/App/App/public/
android/.idea/
ios/.idea/
# Capacitor plugins
android/capacitor-cordova-android-plugins/
ios/capacitor-cordova-ios-plugins/
# Local database files
*.db
*.sqlite
*.sqlite3
# Temporary files
tmp/
temp/

400
.kiro/specs/personal-billing-app/design.md Normal file
View 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 权限最小化原则
- 通知访问权限说明
- 用户授权确认机制

107
.kiro/specs/personal-billing-app/requirements.md Normal file
View File

@@ -0,0 +1,107 @@
# Requirements Document
## Introduction
This document outlines the requirements for a personal billing application that automatically captures transaction data from Android notifications and provides comprehensive expense tracking with cloud synchronization. The app will be built using Vue.js frontend, Node.js backend, and Capacitor.js for Android integration, featuring a warm modern design with neumorphic elements.
## Requirements
### Requirement 1
**User Story:** As a user, I want the app to automatically read payment notifications from apps like Alipay and WeChat, so that I can capture transactions without manual entry.
#### Acceptance Criteria
1. WHEN a payment notification is received from supported apps THEN the system SHALL extract transaction details (amount, merchant, payment type)
2. WHEN transaction data is extracted THEN the system SHALL present a pre-filled confirmation dialog to the user
3. WHEN the user confirms the transaction THEN the system SHALL save it to the local database
4. IF the notification format is unrecognized THEN the system SHALL log the notification for future pattern analysis
5. WHEN the app starts THEN the system SHALL request notification access permissions from Android
### Requirement 2
**User Story:** As a user, I want to manually add, edit, and delete billing records, so that I can maintain complete control over my financial data.
#### Acceptance Criteria
1. WHEN the user taps the floating action button THEN the system SHALL display an add transaction form
2. WHEN creating a transaction THEN the system SHALL require amount, category, and date fields
3. WHEN editing a transaction THEN the system SHALL pre-populate the form with existing data
4. WHEN deleting a transaction THEN the system SHALL request confirmation before removal
5. WHEN saving a transaction THEN the system SHALL validate all required fields are completed
6. WHEN the amount field is focused THEN the system SHALL display a numeric keypad
7. WHEN selecting a category THEN the system SHALL display icon-based category selection
### Requirement 3
**User Story:** As a user, I want to search and filter my transactions, so that I can quickly find specific records.
#### Acceptance Criteria
1. WHEN the user enters text in the search bar THEN the system SHALL filter transactions by merchant name and notes
2. WHEN the user applies date filters THEN the system SHALL show only transactions within the selected date range
3. WHEN the user selects category filters THEN the system SHALL display only transactions from selected categories
4. WHEN the user selects account filters THEN the system SHALL show only transactions from selected payment methods
5. WHEN multiple filters are applied THEN the system SHALL combine them using AND logic
### Requirement 4
**User Story:** As a user, I want my data synchronized across devices, so that I can access my billing information anywhere.
#### Acceptance Criteria
1. WHEN the user registers THEN the system SHALL create a secure user account with JWT authentication
2. WHEN the user logs in THEN the system SHALL authenticate credentials and provide access token
3. WHEN network is available THEN the system SHALL automatically sync local changes to the server
4. WHEN network is unavailable THEN the system SHALL queue changes for later synchronization
5. WHEN conflicts occur during sync THEN the system SHALL prioritize server data and notify the user
6. WHEN the app starts THEN the system SHALL check for server updates and sync if needed
### Requirement 5
**User Story:** As a user, I want to view spending trends and analysis, so that I can understand my financial patterns.
#### Acceptance Criteria
1. WHEN viewing the analysis page THEN the system SHALL display spending by category in a pie chart
2. WHEN selecting a time period THEN the system SHALL show spending trends in a line chart
3. WHEN viewing monthly summary THEN the system SHALL display total income, expenses, and balance
4. WHEN viewing category breakdown THEN the system SHALL show percentage and amount for each category
5. WHEN no data exists for selected period THEN the system SHALL display an appropriate empty state message
### Requirement 6
**User Story:** As a user, I want an intuitive and visually appealing interface, so that managing my finances is enjoyable.
#### Acceptance Criteria
1. WHEN the app loads THEN the system SHALL display transactions in card format with category icons
2. WHEN interacting with buttons THEN the system SHALL provide smooth animations and visual feedback
3. WHEN viewing the interface THEN the system SHALL use the warm modern color scheme (orange primary, gray background)
4. WHEN using forms THEN the system SHALL apply neumorphic design elements to inputs and buttons
5. WHEN displaying amounts THEN the system SHALL use appropriate colors (red for expenses, green for income)
6. WHEN the interface loads THEN the system SHALL use proper typography hierarchy with Inter or Poppins font
### Requirement 7
**User Story:** As a user, I want the app to work offline, so that I can manage my finances without internet connectivity.
#### Acceptance Criteria
1. WHEN network is unavailable THEN the system SHALL continue to function with local data
2. WHEN adding transactions offline THEN the system SHALL save them to local SQLite database
3. WHEN network becomes available THEN the system SHALL automatically sync pending changes
4. WHEN viewing data offline THEN the system SHALL display the most recent synchronized data
5. WHEN sync fails THEN the system SHALL retry automatically with exponential backoff
### Requirement 8
**User Story:** As a user, I want to manage transaction categories and payment accounts, so that I can organize my finances according to my preferences.
#### Acceptance Criteria
1. WHEN setting up the app THEN the system SHALL provide default categories (food, transport, shopping, entertainment)
2. WHEN the user creates a custom category THEN the system SHALL allow icon and color selection
3. WHEN managing payment accounts THEN the system SHALL support cash, Alipay, WeChat, and bank cards
4. WHEN adding a new account THEN the system SHALL require a name and allow icon selection
5. WHEN deleting a category with existing transactions THEN the system SHALL require reassignment or confirmation

187
.kiro/specs/personal-billing-app/tasks.md Normal file
View File

@@ -0,0 +1,187 @@
# 实施计划
## 项目约束条件
- **开发环境**: Windows 11
- **服务器环境**: 阿里云 Ubuntu 24.04
- **Git 服务器**: 阿里云自建 Git 服务
- **开发优先级**: 优先实现离线本地功能，云端登录功能可后置
- **版本管理**: 必须建立完整的 Git 版本控制
- [ ] 1. 建立项目版本管理和基础架构
- [-] 1.1 初始化 Git 版本控制
- 在阿里云自建 Git 服务器上创建项目仓库
- 配置 Windows 11 开发环境的 Git 客户端和 SSH 密钥
- 建立 .gitignore 文件和基础的分支管理策略
- _需求: 项目管理基础_
- [ ] 1.2 搭建前端项目基础架构
- 创建 Vue.js 前端项目，配置 Tailwind CSS 和基础路由
- 配置 Vite 构建工具和开发服务器
- 建立组件目录结构和基础样式系统
- _需求: 6.1, 6.6_
- [ ] 1.3 配置 Capacitor 和本地存储
- 将 Capacitor 添加到 Vue 项目，生成 Android 项目结构
- 集成 Capacitor SQLite 插件，配置本地数据库
- 创建本地数据访问层和基础 CRUD 操作
- _需求: 7.1, 7.2_
- [ ] 2. 实现本地数据模型和离线功能
- [ ] 2.1 创建本地数据模型
- 设计本地 SQLite 数据库表结构（交易、分类、账户）
- 实现本地数据模型的 TypeScript 接口定义
- 创建数据验证和格式化工具函数
- _需求: 2.1, 8.1, 8.3_
- [ ] 2.2 实现本地数据 CRUD 操作
- 开发本地交易数据的增删改查功能
- 实现分类和账户的本地管理功能
- 创建数据迁移和版本管理机制
- _需求: 2.2, 2.3, 2.4, 8.2, 8.4_
- [ ] 2.3 建立离线优先的数据架构
- 实现本地数据的状态管理（Pinia store）
- 创建离线模式的用户界面和提示
- 建立数据同步标记和冲突检测机制
- _需求: 7.1, 7.2, 7.4_
- [ ] 3. 开发核心交易管理界面
- [ ] 3.1 实现基础 UI 组件库
- 创建符合 neumorphic 设计风格的基础组件（按钮、输入框、卡片）
- 实现温暖现代主义色彩系统和字体层级
- 开发图标系统和分类图标组件
- _需求: 6.1, 6.3, 6.4, 6.6_
- [ ] 3.2 创建交易列表和卡片组件
- 设计实现 TransactionCard 组件，展示分类图标、商户名、金额和日期
- 开发交易列表页面，支持无限滚动和下拉刷新
- 实现空状态和加载状态的 UI 组件
- _需求: 6.1, 6.5_
- [ ] 3.3 开发交易添加和编辑表单
- 创建 AddTransactionPage 组件，包含金额输入、分类选择、日期选择器
- 实现 AmountInput 组件，支持数字键盘和金额格式化
- 开发 CategorySelector 组件，支持图标选择和自定义分类
- _需求: 2.1, 2.6, 2.7, 6.4_
- [ ] 3.4 实现搜索和筛选功能
- 创建 SearchFilter 组件，支持文本搜索和多维度筛选
- 实现前端搜索逻辑，支持按商户名、备注、分类、账户筛选
- 开发筛选结果的实时更新和状态管理
- _需求: 3.1, 3.2, 3.3, 3.4, 3.5_
- [ ] 4. 开发通知监听和自动记账功能
- [ ] 4.1 配置 Android 开发环境
- 在 Windows 11 上配置 Android Studio 和 SDK
- 设置 Android 模拟器和真机调试环境
- 创建基础的 Android 构建和调试流程
- _需求: 1.1_
- [ ] 4.2 开发通知监听 Capacitor 插件
- 创建自定义 Capacitor 插件，实现 NotificationListenerService
- 编写 Java/Kotlin 代码监听系统通知并解析支付信息
- 实现通知数据的正则表达式解析和格式化
- _需求: 1.1, 1.2, 1.4_
- [ ] 4.3 实现前端通知处理逻辑
- 集成通知监听插件到 Vue 应用中
- 创建通知确认对话框，支持用户确认和编辑自动捕获的交易
- 实现通知权限申请和状态管理
- _需求: 1.2, 1.3, 1.5_
- [ ] 5. 实现分类和账户管理功能
- [ ] 5.1 开发分类管理功能
- 创建分类管理界面，支持添加、编辑、删除分类
- 实现分类图标和颜色选择器
- 开发默认分类的初始化和管理逻辑
- _需求: 8.1, 8.2, 8.5_
- [ ] 5.2 实现账户管理功能
- 创建支付账户管理界面和 CRUD 操作
- 实现账户类型选择和图标配置
- 开发账户余额跟踪和统计功能
- _需求: 8.3, 8.4_
- [ ] 6. 创建数据分析和图表功能
- [ ] 6.1 实现本地数据分析逻辑
- 开发本地数据的汇总统计、趋势分析、分类统计功能
- 实现数据聚合查询和性能优化
- 创建分析数据的缓存机制
- _需求: 5.1, 5.2, 5.3, 5.4_
- [ ] 6.2 开发图表组件和分析页面
- 集成 ECharts，创建饼图、折线图、柱状图组件
- 实现 AnalyticsPage，展示支出构成、趋势分析和关键指标
- 开发交互式图表和时间段选择功能
- _需求: 5.1, 5.2, 5.3, 5.4, 5.5_
- [ ] 7. 完善用户体验和界面优化
- [ ] 7.1 添加动画和交互效果
- 实现页面转场动画和按钮交互效果
- 开发列表项的添加删除动画
- 创建加载状态和骨架屏组件
- _需求: 6.2_
- [ ] 7.2 优化用户体验细节
- 实现悬浮操作按钮和快速添加功能
- 开发手势操作和快捷键支持
- 创建用户引导和帮助系统
- _需求: 2.6, 6.1_
- [ ] 8. 搭建后端服务和云同步（后置功能）
- [ ] 8.1 在阿里云 Ubuntu 24.04 上搭建 Node.js 后端
- 配置阿里云服务器环境，安装 Node.js、MongoDB 和 Nginx
- 创建 Node.js 后端项目结构，配置 Express 和基础中间件
- 建立服务器端的 Git 部署流程和自动化脚本
- _需求: 4.1_
- [ ] 8.2 实现用户认证系统
- 创建 User 模型的 Mongoose Schema，包含邮箱、密码、偏好设置
- 开发注册、登录、刷新 token 的 API 端点
- 实现 JWT 中间件和前端认证状态管理
- _需求: 4.2_
- [ ] 8.3 开发云同步 API 和逻辑
- 创建数据同步的 API 端点，支持增量同步和冲突检测
- 实现自动同步机制，在网络可用时上传本地更改
- 开发同步冲突解决界面和错误重试逻辑
- _需求: 4.3, 4.4, 4.5, 4.6, 7.3_
- [ ] 9. 测试和质量保证
- [ ] 9.1 编写单元测试
- 为所有 Vue 组件编写单元测试，确保组件功能正确
- 创建本地数据操作的单元测试，覆盖所有 CRUD 操作
- 实现工具函数和数据验证的测试用例
- _需求: 所有需求的质量保证_
- [ ] 9.2 实现集成测试
- 开发通知解析功能的集成测试
- 创建本地数据存储和检索的集成测试
- 实现用户界面交互的端到端测试
- _需求: 所有需求的集成验证_
- [ ] 9.3 进行移动端测试
- 在多个 Android 设备上测试应用兼容性
- 验证通知权限申请和功能正确性
- 测试离线功能和本地数据存储的稳定性
- _需求: 1.5, 7.1, 7.2_
- [ ] 10. 性能优化和部署准备
- [ ] 10.1 前端性能优化
- 实现组件懒加载和代码分割
- 优化图片资源和静态资源加载
- 实现虚拟滚动和防抖搜索优化
- _需求: 性能相关的用户体验提升_
- [ ] 10.2 Android APK 构建和优化
- 配置 Android APK 的构建和签名流程
- 优化 APK 大小和启动性能
- 配置应用图标、启动画面和应用信息
- _需求: 整体系统的部署就绪_
- [ ] 10.3 生产环境部署配置（云端功能启用后）
- 在阿里云上配置 Nginx 反向代理和 SSL 证书
- 设置 MongoDB 数据库的备份和恢复机制
- 配置服务器监控和日志管理系统
- _需求: 4.3, 4.4 的性能保证_

87
README.md Normal file
View File

@@ -0,0 +1,87 @@
# 个人账单应用
一个现代化的个人财务管理应用，支持自动读取支付通知记账、手动记账、数据分析和云同步功能。
## 技术栈
- **前端**: Vue.js 3 + Tailwind CSS + TypeScript
- **移动端**: Capacitor.js (Android)
- **后端**: Node.js + Express.js + MongoDB
- **数据库**: SQLite (本地) + MongoDB (云端)
## 核心功能
- 🔔 自动读取支付宝、微信等支付通知进行记账
- 📝 手动添加、编辑、删除交易记录
- 🔍 强大的搜索和筛选功能
- 📊 数据分析和趋势图表
- ☁️ 云端同步和离线支持
- 🎨 现代化的 neumorphic 设计风格
## 开发环境
- **开发平台**: Windows 11
- **服务器**: 阿里云 Ubuntu 24.04
- **Git 服务器**: 阿里云自建
## 项目结构
```
bill/
├── frontend/ # Vue.js 前端应用
├── backend/ # Node.js 后端 API
├── .kiro/ # Kiro IDE 配置和规格文档
│ └── specs/ # 项目规格说明
├── android/ # Android 项目 (Capacitor 生成)
└── docs/ # 项目文档
```
## 开发计划
项目采用离线优先的开发策略：
1. ✅ 建立 Git 版本控制和基础架构
2. 🔄 实现本地数据模型和离线功能
3. 📱 开发核心交易管理界面
4. 🔔 集成通知监听和自动记账
5. 📊 添加数据分析和图表功能
6. ☁️ 后期添加云端同步功能
## 快速开始
### 前端开发
```bash
cd frontend
npm install
npm run dev
```
### 后端开发
```bash
cd backend
npm install
npm run dev
```
### Android 构建
```bash
cd frontend
npm run build
npx cap sync android
npx cap open android
```
## 贡献指南
1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request
## 许可证
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

187
plan.md Normal file
View File

@@ -0,0 +1,187 @@
个人账单 App 项目规划书
这是一个为你量身定制的安卓账单 App 项目规划，旨在将你的想法转化为一个具体、可执行的开发蓝图。
1. 项目概述与技术栈解析
我们将构建一个现代化的个人账单应用，核心技术栈为 Vue.js (前端) + Node.js (后端)，并通过 Capacitor.js 框架将 Web 应用打包成一个功能完整的安卓 App。
前端 (Vue.js):
框架: Vue 3 (Composition API)
UI 库: 可以选用 Element Plus 或 Vant 进行快速开发，但为了实现你想要的独特设计风格，我们更推荐使用 Tailwind CSS，它可以提供原子级的 CSS 工具，让你自由地构建任何设计。
图表库: ECharts 或 Chart.js 用于数据可视化（趋势分析）。
后端 (Node.js):
框架: Express.js 或 Koa.js，用于构建 RESTful API。
数据库: MongoDB (配合 Mongoose) 或 PostgreSQL。MongoDB 的文档型结构非常适合存储账单这类灵活的数据。
认证: JWT (JSON Web Tokens)，即使是自用，也建议建立简单的用户认证体系，便于未来扩展。
移动端桥接 (Capacitor.js):
这是连接你的 Vue 应用和安卓原生功能的关键。它能让你用 JavaScript 调用原生 API，比如我们需要的“读取通知”功能。
2. 功能需求详解
a. 核心功能：读取 App 通知自动记账
这是项目的亮点，也是技术难点。实现思路如下：
安卓原生插件:
你需要使用 Android Studio 创建一个 Capacitor 插件。
这个插件的核心是实现安卓的 NotificationListenerService 服务。这是一个系统服务，当获取用户授权后，可以监听设备上所有新发出的通知。
数据捕获与筛选:
在服务中，当收到一个新的通知时，判断其来源 App (例如：支付宝、微信、银行 App)。
使用正则表达式或关键词（如“收款”、“支付”、“消费”、“-”、“+”）从通知的标题和内容中提取关键信息：金额、商户名、支付类型。
数据通信:
原生插件将解析好的数据（如 { "amount": 12.5, "type": "expense", "source": "支付宝" }）通过 Capacitor 的桥接机制，发送给你的 Vue 应用。
Vue 应用处理:
Vue 应用接收到数据后，可以弹出一个预填好信息的对话框，让用户确认或补充信息（如消费分类），然后保存到账单中。这比完全自动记录的体验更好，避免了误记。
b. 基础功能：账单增删改查 (CRUD)
这是 App 的基本盘，UI/UX 设计至关重要。
主界面: 以卡片列表形式展示近期的账单流水，每张卡片清晰地显示 分类图标、名称、金额 和 日期。
添加/修改:
通过一个悬浮操作按钮 (FAB) 触发。
表单应包含：
金额输入: 显眼的数字键盘。
分类选择: 一组设计精美的图标（餐饮、交通、购物、娱乐等），支持自定义添加分类。
日期选择: 默认为当天，但可修改。
账户选择: （现金、支付宝、微信、银行卡）。
备注: 可选的文本输入框。
查询: 提供顶部的搜索栏，可以按备注、商户名进行模糊搜索，并提供按日期、分类、账户的筛选功能。
c. 核心功能：云同步
后端 API 需要设计的端点 (Endpoints) 如下：
POST /api/auth/register: 用户注册
POST /api/auth/login: 用户登录
POST /api/bills: 新增一条账单
GET /api/bills: 获取所有账单（支持分页和筛选）
PUT /api/bills/:id: 更新指定账单
DELETE /api/bills/:id: 删除指定账单
GET /api/sync: 一个用于检查数据版本和同步的端点。
同步逻辑:
本地数据库 (如 SQLite) 作为缓存，保证离线可用。
当网络连接可用时，将本地未同步的更改（新增、修改、删除）推送到服务器。
从服务器拉取最新的数据更新到本地。
d. 增值功能：趋势分析
消费构成: 使用 饼图 或 环形图 展示指定时间段内（如月度、年度）各个消费分类的占比。
消费趋势: 使用 折线图 或 柱状图 展示每天或每月的支出/收入变化。
数据看板: 在一个专门的“分析”页面，展示多个维度的图表和关键数据（如月度总支出、总收入、结余等）。
3. 设计风格与 UI/UX 构想
根据你的要求，我们来构思一种 “温暖现代主义” 风格，它融合了扁平化的简洁和拟物化的质感。
色彩方案:
背景色 (Base): #F5F5F4 (米灰色/暖灰色) - 提供一个柔和、不刺眼的画布。
主题色 (Primary): #F97316 (鲜活的橙色) - 用于按钮、图标、当前选中的状态等交互元素，引人注目。
辅助色 (Accent):
#3B82F6 (柔和的蓝色) - 可用于表示“收入”或积极信息。
#22C55E (清新的绿色) - 也可作为补充色，或用于成功提示。
文本色 (Text): #333333 (深灰色) - 保证最佳的可读性，而不是纯黑。
设计语言:
卡片 (Cards): 每个账单项都是一个卡片。使用大的圆角 (rounded-xl)，并添加非常微妙的、柔和的阴影 (shadow-sm)，让它看起来像是轻轻浮在背景之上。
拟物感 (Neumorphism Touch): 主要用在按钮和输入框上。可以给按钮添加一个同色系的内阴影和外阴影，模拟出轻微凹陷或凸起的效果，但要非常克制，避免过度设计。
图标 (Icons): 使用线条流畅、风格统一的图标库，如 Lucide 或 Heroicons。分类图标可以设计得更有趣、更多彩一些。
字体 (Typography): 选择一款现代且易读的无衬线字体，如 "Inter" 或 "Poppins"。通过字重 (Bold, Medium, Regular) 来区分信息的层级。
留白 (White Space): 充分利用留白，让界面看起来干净、不拥挤，引导用户的视线。
示例组件构想：
悬浮操作按钮 (FAB): 一个橙色的圆形按钮，右下角固定。按钮上有一个白色的 + 号，点击时可以有一个流畅的放大和旋转动画。
账单卡片: 左侧是一个圆形的分类图标，中间是商户名和备注，右侧是支出金额（用深灰色或主题橙色表示）和日期。
4. 简易开发路线图
第一阶段：后端先行
[ ] 设计数据库模型 (Schema)。
[ ] 初始化 Node.js + Express 项目。
[ ] 实现用户认证 API。
[ ] 实现账单的 CRUD API。
[ ] 使用 Postman 或 Insomnia 等工具测试所有 API。
第二阶段：Web 应用核心功能
[ ] 初始化 Vue 3 + Tailwind CSS 项目。
[ ] 搭建主要页面路由 (首页、分析页、设置页)。
[ ] 设计并实现账单列表和卡片组件。
[ ] 开发账单的添加、编辑、删除表单和逻辑。
[ ] 对接后端的 CRUD API，实现前后端数据交互。
第三阶段：安卓集成与原生功能
[ ] 将 Capacitor 添加到 Vue 项目中。
[ ] 构建并生成安卓项目。
[ ] 在 Android Studio 中，创建用于读取通知的 Capacitor 插件。
[ ] 编写原生 Java/Kotlin 代码实现 NotificationListenerService。
[ ] 在 Vue 中调用插件，并处理从原生端传来的数据。
第四阶段：完善与优化
[ ] 开发趋势分析页面，使用 ECharts 渲染图表。
[ ] 实现完整的云同步逻辑。
[ ] 优化 UI 细节和动画效果。
[ ] 进行全面的测试和 Bug 修复。
希望这份详细的规划能给你提供一个清晰的起点和方向！祝你开发顺利！