# LedgerApp

**Repository Path**: wonderful315/ledger-app

## Basic Information

- **Project Name**: LedgerApp
- **Description**: 一款离线的本地记账 Android 应用，Create By Kai & WordBuddy
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kledger（v1.5.4）

一款**离线**的本地记账 Android 应用，Create By Kai & WordBuddy

## 功能

### 记账（首页）
- **本月预算与支出**：iOS 蓝紫渐变卡片，展示本月支出、预算、剩余/超支金额及圆头进度条
  - **档位提醒**：进度 ≥50% 显示「已过半」，≥80% 进度条与文案变橙色，超支变黄色
- **常用分类快捷栏**（预算卡下方，横向滚动）
  - **点击分类**：打开完整记账弹窗并预选该分类
  - **长按分类秒记账**：直接弹出金额键盘（自动聚焦 + 快捷金额 10/15/20/50/100），两步完成记账
- **历史记录**：按日期分组的消费列表，每日为一张白色圆角卡片（分组间有分隔线）
  - **点击单条记录**：弹出详情（分类 / 金额 / 记账时间到小时 / 备注），可**编辑**或删除
  - 长按单条记录也可删除（带确认弹窗）
- **记一笔**：点击右下角 ➕ 打开**居中弹窗**（不覆盖全屏，圆角卡片底色与其他系统弹窗一致）
  - 输入金额（支持小数点，大号数字输入框）
  - **记账日期**：今天 / 昨天 两档分段控件点击切换；今天记录 = 当前小时，补记（昨天）= 固定 0 点
  - 选择消费分类（**两行一组横向滑动**：每列上下两个分类等宽，整组一起横滚，分类再多也不占弹窗高度；餐饮/交通/购物/其他 + 自定义分类）
  - 可填备注
  - 弹窗点击空白处即可关闭（无右上角 X）
  - **保存成功后弹窗内切换为 Face ID 风格对号动画**：绿色圆环扫描画满 → 对号一笔勾出（带渐隐尾迹与轻微弹跳），无按钮，动画完成后自动关闭
- **克制动效**：记账弹窗缩放淡入（iOS 弹窗感）、成功对号弹簧弹出、预算进度条平滑增长、列表增删过渡动画

### 统计
- 按月 / 按年切换（iOS 分段控件 + 左右箭头翻页）
- **环形饼图**：标准**正圆**（固定正方形画布），环宽收细，按消费分类显示占比
- **柱状图**：渐变圆角柱，按月 = 每日支出趋势，按年 = 每月支出趋势
- 分类明细列表（图标、金额、占比，分隔线内缩）

### 我的
- **外观**：深色模式开关（即时生效并记忆）
- **快速记账**：开关控制记账页顶部分类快捷栏显示 / 隐藏（点击记账 / 长按秒记）
- **数据存储位置**：账本数据固定保存在公共存储 `Documents/Kledger/ledger.db`，**卸载应用后账本文件不删除**（首次启动需授予「所有文件访问」权限）
- **清除历史数据**：删除公共目录下的账本文件与全部记账记录（弹窗二次确认，不可恢复）
- **设置本月预算**：为当月设置预算金额，首页卡片实时展示
- **下载导入模板**：生成 Excel（xlsx）导入模板（含示例与填写说明）
- **导入 Excel 数据**：选择模板格式的 xlsx 文件批量导入账单（日期/分类/金额/备注）
- **导出 Excel 数据**：按起止月份范围导出账单为 xlsx 文件
- **分类管理**：添加自定义分类（名称 + emoji 图标）、删除自定义分类（内置分类不可删）
- **更新日志**：页底默认折叠（点击展开 / 收起），展示最新版本更新内容，底部署名 Kai & WorkBuddy

## 技术栈

| 项 | 选型 |
|---|---|
| 语言 | Kotlin 2.0.21 |
| UI | Jetpack Compose（Material 3，iOS 风格主题） |
| 数据库 | Room 2.6.1（本地 SQLite，`ledger.db`，已升级至 v3：记录含记账小时） |
| 架构 | MVVM（ViewModel + StateFlow + Repository） |
| 图表 | Compose Canvas 自绘（无第三方图表库，饼图为正圆） |
| Excel | Apache POI 5.2.5（xlsx 读写，纯本地） |
| 最低系统 | Android 8.0（API 26） |
| 目标系统 | Android 16（API 36，兼容小米澎湃 OS 3） |

## 构建与安装

### 方法一：Android Studio（推荐）

1. 使用较新的 Android Studio（建议 Ladybug 及以上版本）
2. `File → Open` 选择本目录（`LedgerApp` 文件夹）
3. 等待 Gradle Sync 完成（首次会自动下载依赖，需联网一次）
4. 连接小米手机（开启开发者选项 + USB 调试），点击绿色 ▶ 运行
   - 手机弹窗选择「允许 USB 调试」即可安装运行

### 方法二：命令行构建 APK

```bash
# 在项目根目录执行（需要本机有 JDK 17+）
gradle assembleDebug
# 产物：app/build/outputs/apk/debug/Kledger-v1.5.4.apk
```

将 `Kledger-v1.5.4.apk` 传到小米手机上直接安装（需允许"安装未知来源应用"）。

## Excel 导入格式说明

统一列结构（模板中已含说明）：

| 日期 | 分类 | 金额 | 备注 |
|---|---|---|---|
| 2026-08-31 | 餐饮 | 12.5 | 午餐 |

- 日期格式 `yyyy-MM-dd`（也兼容 `yyyy/M/d` 等常见格式）
- 分类需与 App 内已有分类名称一致，匹配不到的行自动归入「其他」
- 金额为正数；备注可选
- 日期、金额无法解析的行会被跳过，并在导入结果中提示跳行数

## 工程结构

```
LedgerApp/
├── app/src/main/java/com/example/ledgerapp/
│   ├── MainActivity.kt              # 入口 Activity
│   ├── data/
│   │   ├── entity/Entities.kt       # Record(账单) / Category(分类) / Budget(预算) 实体
│   │   ├── dao/Daos.kt              # Room DAO
│   │   ├── AppDatabase.kt           # 数据库 + 默认分类 + 配色 + 迁移
│   │   ├── LedgerRepository.kt      # 仓库层
│   │   └── ExcelUtils.kt            # xlsx 导出 / 导入 / 模板生成（POI）
│   ├── viewmodel/LedgerViewModel.kt # 状态管理 + 统计计算 + 导入导出 + 深色模式 + 清除历史数据
│   └── ui/
│       ├── LedgerApp.kt             # 底部导航框架（记账 / 统计 / 我的，iOS Tab 风格）
│       ├── theme/Theme.kt           # iOS 风格主题（浅色 + 深色）
│       ├── charts/Charts.kt         # 正圆饼图 / 渐变柱状图（Canvas 自绘）
│       ├── record/                  # 记账首页 + 快捷分类栏 + 记一笔/秒记账/编辑弹窗
│       ├── settings/SettingsScreen.kt  # 我的页（外观 / 清除历史数据 / 预算 / Excel / 分类管理）
│       └── stats/StatsScreen.kt     # 统计页（分段控件 + 卡片图表）
└── app/src/main/res/                # 资源（图标/主题/字符串）
```

## 隐私说明

- 应用**不申请网络权限**，记账数据不出手机
- 账本数据保存在公共存储目录 `Documents/Kledger/ledger.db`（`/storage/emulated/0/Documents/Kledger/`），**卸载应用后数据仍保留**
- 写入公共目录需「所有文件访问」权限（Android 11+）或「读写外部存储」权限（Android 8~9），首次启动会引导授权
- Excel 导入 / 导出通过系统文件选择器完成，文件由用户自行保存到本地
- 「清除历史数据」会删除上述目录下的账本文件，操作前会二次确认