# Kaching

**Repository Path**: TySpark/kaching

## Basic Information

- **Project Name**: Kaching
- **Description**: 记账
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Rust, Dioxus

## README

# Kaching 记账应用 — 开发设计（一款使用Rust+Dioxus[0.6]开发的桌面应用）

## 一、项目概述

课题组经费记账桌面应用，管理：

- 账户到账（外部经费入账）
- 成员资金往来（成员存钱入账户 / 账户向成员付款）
- 公用支出（办公用品、聚餐、个人支付等）
- 账户余额实时统计
- 数据导出为 Excel
- 暗色/亮色主题切换

## 二、数据模型

### 2.1 成员 (members)

| 字段       | 类型       | 说明            |
| ---------- | ---------- | --------------- |
| id         | INTEGER PK |                 |
| name       | TEXT       | 姓名            |
| note       | TEXT       | 备注            |
| active     | INTEGER    | 1=活跃 0=已毕业 |
| created_at | TEXT       | 创建时间        |

### 2.2 到账记录 (income_records)

外部经费到账（项目拨款等），资金流入账户。

| 字段       | 类型       | 说明                   |
| ---------- | ---------- | ---------------------- |
| id         | INTEGER PK |                        |
| amount     | REAL       | 金额（正数）           |
| date       | TEXT       | 到账日期               |
| source     | TEXT       | 来源（如：课题组经费） |
| note       | TEXT       | 备注                   |
| created_at | TEXT       |                        |

### 2.3 支出记录 (expense_records)

账户资金流出：购买办公用品、聚餐等。

| 字段        | 类型        | 说明                                 |
| ----------- | ----------- | ------------------------------------ |
| id          | INTEGER PK  |                                      |
| amount      | REAL        | 金额（正数）                         |
| date        | TEXT        | 支出日期                             |
| category_id | INTEGER FK  | 类别                                 |
| member_id   | INTEGER FK? | 关联成员（可空），成员垫付报销时关联 |
| description | TEXT        | 用途说明（如：购买A4纸一箱）         |
| note        | TEXT        | 备注                                 |
| created_at  | TEXT        |                                      |

### 2.4 支出类别 (categories)

| 字段 | 类型       | 说明     |
| ---- | ---------- | -------- |
| id   | INTEGER PK |          |
| name | TEXT       | 类别名称 |
| icon | TEXT       | 图标     |

预设数据：办公用品、聚餐、个人支付、交通、购物、快递费、其他

### 2.5 成员往来记录 (member_transactions)

记录账户与成员之间的资金流动。

| 字段        | 类型       | 说明                                           |
| ----------- | ---------- | ---------------------------------------------- |
| id          | INTEGER PK |                                                |
| member_id   | INTEGER FK | 成员                                           |
| amount      | REAL       | 金额（正数）                                   |
| tx_type     | TEXT       | `deposit`（成员存入） / `payout`（向成员付款） |
| date        | TEXT       | 日期                                           |
| description | TEXT       | 用途说明                                       |
| note        | TEXT       | 备注                                           |
| created_at  | TEXT       |                                                |

### 余额计算公式

```
余额 = Σ(到账金额) + Σ(成员存入金额) - Σ(支出金额) - Σ(向成员付款金额)
```

> 支出如果关联了成员（垫付报销），金额同样计入减项，不需要再单独记一笔成员付款。

## 三、UI 页面设计

### 页面列表

| 页面     | 说明                                                      |
| -------- | --------------------------------------------------------- |
| 仪表盘   | 余额概览、月度收支趋势（含hover提示）、支出分类、最近动态 |
| 到账记录 | 管理外部到账，支持搜索/筛选/排序/分页                     |
| 成员转账 | 成员转入/转给成员，Tab 切换，支持搜索/筛选/排序/分页      |
| 支出记录 | 管理支出，支持按类别筛选、搜索、排序、分页                |
| 成员管理 | 增删改成员，支持搜索/分页/排序                            |
| 设置     | 类别管理、数据库管理、深色模式切换                        |
| 成员详情 | 单个成员的资金往来明细                                    |
| 导出     | 多种 Excel 导出模式，支持打开文件夹                       |

### 仪表盘布局

```
┌─────────────────────────────────────┐
│  💰 当前余额: ¥12,580.00             │
├──────────┬──────────┬───────────────┤
│ 本月到账  │ 本月支出  │ 成员数        │
│ ¥5,000   │ ¥1,200   │ 6人           │
├──────────┴──────────┴───────────────┤
│  📈 月度收支趋势  │  🏷️ 支出分类    │
├──────────────────┴──────────────────┤
│  🕐 最近动态                         │
│  ├─ 01/15  到账     ¥5,000  课题组经费│
│  ├─ 01/14  支出     ¥200     A4纸    │
│  └─ ...                             │
└─────────────────────────────────────┘
```

### 交互功能

- **搜索**：到账、支出、成员、转账页面均支持关键词搜索
- **日期筛选**：支持日期范围筛选
- **排序**：表格列头可点击排序（升序/降序）
- **分页**：数据量大时自动分页，每页 20 条
- **表单校验**：必填字段为空时显示红色错误提示
- **图表交互**：月度收支趋势图支持 hover 显示具体金额
- **键盘快捷键**：Esc 关闭弹窗
- **暗色模式**：设置页可切换深色/浅色主题

## 四、技术栈

| 层次       | 技术                        |
| ---------- | --------------------------- |
| UI         | Dioxus 0.6 + dioxus-desktop |
| 状态管理   | Dioxus Signals              |
| 数据库     | SQLite (rusqlite)           |
| Excel 导出 | rust_xlsxwriter             |
| 日期处理   | chrono                      |
| 文件对话框 | rfd                         |

## 五、项目结构

```
kaching/
├── Cargo.toml
└── src/
    ├── main.rs           # 入口
    ├── app.rs            # 根组件 + 路由 + 暗色模式 + CSS 变量
    ├── config.rs         # 配置管理 + 自动备份
    ├── db.rs             # 数据库初始化 + CRUD
    ├── models.rs         # 数据模型
    ├── export.rs         # Excel 导出
    └── pages/
        ├── mod.rs
        ├── dashboard.rs      # 仪表盘（余额、趋势图、分类图、最近动态）
        ├── income.rs         # 到账记录管理
        ├── members.rs        # 成员管理
        ├── member_detail.rs  # 成员详情（转账 + 垫付报销）
        ├── member_transfers.rs # 成员转账（转入/转出 Tab）
        ├── expenses.rs       # 支出记录管理
        ├── settings.rs       # 设置（类别、数据库、备份、深色模式）
        └── export_page.rs    # Excel 导出
    └── components/
        ├── mod.rs
        ├── layout.rs         # DataTable（支持排序）+ Modal
        ├── form_fields.rs    # Toast / SearchBar / DateRangeFilter / PaginationBar / 表单组件
        └── chart.rs          # SVG 柱状图
```

## 六、共享组件 (`components/form_fields.rs`)

| 组件/函数          | 说明                                       |
| ------------------ | ------------------------------------------ |
| `use_toast()`      | 创建 Toast 状态，支持 `success/error/info` |
| `ToastMessage`     | Toast 通知渲染                             |
| `SearchBar`        | 搜索输入框                                 |
| `DateRangeFilter`  | 日期范围筛选（从/到）                      |
| `FilterBar`        | 组合搜索 + 日期 + 自定义筛选               |
| `use_pagination()` | 分页状态管理                               |
| `PaginationBar`    | 分页控件                                   |
| `FormField`        | 文本输入（支持 `error` 校验提示）          |
| `NumberField`      | 金额输入（文本模式，保留小数输入）         |
| `SelectField`      | 下拉选择（支持 `error` 校验提示）          |
| `Card`             | 卡片容器                                   |
| `PageHeader`       | 页面标题 + 操作按钮                        |
| `fmt_amount()`     | 格式化金额为 ¥1,234.56                     |
| `today()`          | 获取当天日期 YYYY-MM-DD                    |

## 七、暗色模式

使用 CSS 自定义属性实现主题切换：

| 变量               | 亮色值    | 暗色值    |
| ------------------ | --------- | --------- |
| `--bg`             | `#f8f9fa` | `#0f0f1a` |
| `--bg-card`        | `#fff`    | `#1a1a2e` |
| `--bg-hover`       | `#f1f5f9` | `#252539` |
| `--text`           | `#333`    | `#e0e0e0` |
| `--text-secondary` | `#64748b` | `#a0a0b0` |
| `--text-muted`     | `#888`    | `#777`    |
| `--border`         | `#e5e7eb` | `#2a2a3e` |
| `--primary`        | `#4f6ef7` | `#6366f1` |
| `--danger`         | `#ef4444` | `#f87171` |

在设置页通过 `.theme-dark` / `.theme-light` 类切换。

## 八、Excel 导出内容

- Sheet 1: **总账** — 所有交易的合并流水（日期、类型、金额、说明）
- Sheet 2: **到账明细**
- Sheet 3: **支出明细**（含类别）
- Sheet 4: **成员往来**（按成员汇总：存入总额、付款总额、净额）
- Sheet 5: **成员往来明细**

导出后支持一键打开文件夹或文件。