# personal-finance

**Repository Path**: amespaces/personal-finance

## Basic Information

- **Project Name**: personal-finance
- **Description**: 一个用rust 开发的个人记账项目， 全程使用AI， 部分接口存在bug待修改
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 个人记账 Web 项目 - 需求与设计说明书 (v1.0)

> **核心目标**：构建一个高性能、类型安全、用户体验优秀的个人记账 Web 应用。
> **后端技术**：Rust (Axum + SQLx + PostgreSQL)
> **前端技术**：React + Vite + TypeScript + Tailwind CSS + shadcn/ui

---

## 一、 技术栈架构

### 1.1 后端 (Backend)
| 层级 | 推荐方案 | 选型理由 |
|------|---------|----------|
| **Web 框架** | **Axum** + **Tokio** | 轻量、生态成熟、与 Tower 中间件无缝集成，适合高并发 API |
| **数据库/ORM** | **SQLx** + **PostgreSQL** | 编译期 SQL 检查（零运行时语法错误），全异步，高性能连接池 |
| **验证与序列化** | **serde** + **validator** | Rust 生态标准，JSON 解析与入参校验的一站式方案 |
| **鉴权** | **jsonwebtoken** (JWT) + **bcrypt** | 无状态认证，密码哈希存储，适合 RESTful API |
| **时间/金额** | **chrono** + **rust_decimal** | 统一 UTC 时间处理；避免浮点数精度丢失 |

### 1.2 前端 (Frontend)
| 层级 | 推荐方案 | 选型理由 |
|------|---------|----------|
| **框架** | **React** + **Vite** + **TypeScript** | 开发体验极佳，构建速度快，类型安全 |
| **样式** | **Tailwind CSS** | 原子化 CSS，开发效率高，支持 Dark Mode |
| **组件库** | **shadcn/ui** | 无头组件，高度可定制，UI 现代化且简洁 |
| **状态管理** | **Zustand** + **React Query** | 轻量全局状态 + 强大的服务端数据缓存/同步 |
| **图表库** | **Recharts** | 轻量级，基于 SVG，与 React 生态完美契合 |

---

## 二、 后端功能说明

### 2.1 核心模块划分
| 模块 | 功能描述 | 关键 API 路由 |
|------|---------|-------------|
| **用户认证** | 注册、登录、JWT 签发与校验 | `POST /api/v1/auth/register`<br>`POST /api/v1/auth/login` |
| **分类管理** | 预设分类、自定义增删改 | `GET /api/v1/categories`<br>`POST /api/v1/categories` |
| **账单管理** | 增删改查、软删除、多条件筛选 | `GET /api/v1/transactions`<br>`POST /api/v1/transactions`<br>`PUT /api/v1/transactions/:id` |
| **预算模块** | 月度预算设置、进度计算、预警 | `GET /api/v1/budgets`<br>`PUT /api/v1/budgets/:month` |
| **数据统计** | 收支汇总、分类占比、趋势分析 | `GET /api/v1/reports/summary`<br>`GET /api/v1/reports/trend` |

### 2.2 关键架构设计
- **统一错误响应**：
  ```json
  { "code": 400, "message": "业务错误描述", "data": null }
  ```
- **权限控制**：通过 JWT 中间件提取 `user_id`，所有 SQL 查询强制注入 `WHERE user_id = $1`，防止越权。
- **分页查询**：采用 `Offset` 或 `Cursor` 分页策略，避免大数据量下的性能瓶颈。

---

## 三、 前端页面与交互设计

### 3.1 整体布局
- **响应式设计**：桌面端左侧固定导航栏；移动端底部 Tab Bar 导航。
- **主题支持**：内置 Light/Dark 模式，支持跟随系统自动切换。
- **交互原则**：
  - **乐观更新 (Optimistic UI)**：列表操作（增删）即时反馈 UI，后台异步处理。
  - **加载状态**：首屏使用 Skeleton 骨架屏，避免页面闪烁。
  - **空状态**：无数据时展示插画与引导操作（如“开始记第一笔”）。

### 3.2 页面路由结构
| 路由路径 | 页面名称 | 核心组件与功能 |
|----------|---------|----------------|
| `/dashboard` | **概览页** | 卡片（本月结余/收支）、环形图（分类占比）、快速记账 FAB 按钮 |
| `/transactions` | **账单列表** | 顶部过滤栏（日期/类型/分类）、流水列表（无限滚动）、编辑/删除抽屉 |
| `/reports` | **报表页** | 时间轴选择器、折线图（收支趋势）、柱状图（分类对比）、CSV 导出 |
| `/budget` | **预算管理** | 预算进度条（绿/黄/红三色阈值）、按月/分类设置 |
| `/settings` | **设置** | 偏好设置（货币/主题）、数据管理（导入导出）、账户安全 |

---

## 四、 核心数据模型 (SQLx / PostgreSQL)

```sql
-- 1. 用户表 (Users)
CREATE TABLE users (
    id VARCHAR(36) PRIMARY KEY DEFAULT (UUID()),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 2. 分类表 (Categories)
CREATE TABLE categories (
    id VARCHAR(36) PRIMARY KEY DEFAULT (UUID()),
    user_id VARCHAR(36) NOT NULL,
    name VARCHAR(50) NOT NULL,
    type ENUM('income', 'expense') NOT NULL,
    icon VARCHAR(50),  -- 图标标识
    color VARCHAR(7),  -- Hex 颜色
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- 3. 账单表 (Transactions)
CREATE TABLE transactions (
    id VARCHAR(36) PRIMARY KEY DEFAULT (UUID()),
    user_id VARCHAR(36) NOT NULL,
    category_id VARCHAR(36) DEFAULT NULL,
    amount DECIMAL(12,2) NOT NULL CHECK (amount > 0),
    type ENUM('income', 'expense') NOT NULL,
    date DATE NOT NULL,
    note TEXT,
    tags JSON,         -- JSON 类型
    is_deleted BOOLEAN DEFAULT FALSE, -- MySQL 中 BOOLEAN 是 TINYINT(1) 的别名
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id),
    FOREIGN KEY (category_id) REFERENCES categories(id) ON DELETE SET NULL
);

-- 4. 预算表 (Budgets)
CREATE TABLE budgets (
    id VARCHAR(36) PRIMARY KEY DEFAULT (UUID()),
    user_id VARCHAR(36) NOT NULL,
    category_id VARCHAR(36) DEFAULT NULL,
    month VARCHAR(7) NOT NULL, -- 格式: YYYY-MM
    limit_amount DECIMAL(12,2) NOT NULL,
    FOREIGN KEY (user_id) REFERENCES users(id),
    FOREIGN KEY (category_id) REFERENCES categories(id) ON DELETE CASCADE,
    UNIQUE KEY unique_user_category_month (user_id, category_id, month)
);
```

---

## 五、 开发里程碑 (Milestones)

| 阶段 | 目标内容 | 预计工时 |
|------|---------|----------|
| **Phase 1 (MVP)** | 用户鉴权 + 账单 CRUD + 分类管理 + 基础列表页 | 1 - 2 周 |
| **Phase 2** | 概览数据聚合 + 图表集成 + 预算模块开发 | 1 周 |
| **Phase 3** | 报表导出 + 高级筛选 + 响应式适配 + PWA 支持 | 1 周 |
| **Phase 4 (Opt)** | 性能优化 (Redis 缓存) + 批量导入 + 单元测试覆盖 | 持续 |

---

## 六、 Rust 开发特别提示 (避坑指南)

1.  **精度问题**：金额字段务必使用 `rust_decimal`，严禁使用 `f64`。
2.  **SQLx 编译检查**：本地开发开启离线模式 `SQLX_OFFLINE=true`，避免 CI/CD 环境无数据库导致编译失败。
3.  **时间处理**：
    *   数据库存储 `TIMESTAMPTZ` (带时区)。
    *   后端统一转为 `chrono::Utc`。
    *   前端展示时再转换为用户本地时区。
4.  **错误处理**：使用 `thiserror` 定义底层错误，`anyhow` 处理应用层错误链。
5.  **结构体设计**：数据库实体 (`Model`) 与 API 响应 (`DTO`) 必须分离，避免敏感字段泄露。