Skip to content

About

纯本地 Android 记账应用:不联网、无账号、金额以分存储。周期性账单、回收站、分类预算与预算节奏、消费日历、备份/恢复与 CSV 导出。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

亭宣记账 · TingLedger

一个纯本地的 Android 记账应用。没有账号、没有云同步、没有任何联网代码——数据只存在你自己手机上的 SQLite 里,界面按记账这件事本来的样子设计:先记下,再看懂,最后能守住预算。

  • 当前版本:v1.25.0(versionCode 38)
  • 最低系统:Android 8.0(minSdk 26),targetSdk / compileSdk 36
  • 包名:com.klocktx.moneyblocks
  • 许可证:MIT

目录


它不做什么

这些边界是刻意划的,不是"还没来得及做":

  • 不做多账户与转账。 记账的诉求就是"这笔钱进了哪个口袋、又从哪个口袋出去",加账户体系会让模型复杂度翻倍而收益为零。
  • 不做云同步、不做多设备。 一旦引入同步就要处理冲突、时间戳与服务端,而它是个人的账本。想带走数据请用备份与恢复。
  • 不做广告、不做统计上报、不联网。 见隐私与权限。
  • 不在每笔记录上选收支方向。 方向挂在账单上:「吃饭」永远是支出,「工资」永远是收入,记一笔时不必再选一次。

功能

记账

  • 自绘数字键盘,支持四则运算表达式(12.5*3+8 这种),中间量用 BigDecimal,只在最后落分时 HALF_UP 一次。
  • 金额全程以「分」为单位存储与运算(@JvmInline value class Cents),全链路禁止 Double 参与金额计算——这是"总开支对不上"这类问题的根因防线。
  • 记完一条可以立刻撤销;同一笔可以改成备注或金额。
  • 录入时会带上该账单最近用过的备注作为常用建议。

账单(分类)

  • 每个账单有自己的方向(支出 / 收入)、图标与颜色(8 色灰调色板:苔绿、赭石、雾蓝、陶红、藕紫、池青、石墨、玫灰)。
  • 图标从 Material Icons 预设库里选,不做自由绘制。
  • 拖动排序、归档(从首页收起但仍计入历史)、回收站(删除先标记,名下历史原地不动,30 天内可恢复;30 天后才真删,真删才会带走条目)。
  • 周期性账单:每月 / 每周到期自动落一笔固定金额,并带生成游标——被你删掉的那一期不会被下一轮补写回来。
  • 桌面长按图标快捷项:长按直接进某条账单的录入层,账单一变就自动刷新。

预算与节奏

  • 月度总预算:设一个数,超支时首页会转成提醒色。
  • 分类预算:每个支出账单再单独设一个月度上限,留空表示不设限;上限跟着备份走,账单真删时上限一起摘掉(避免 id 复用把上限串到下一个账单上)。
  • 预算节奏:日均可用 / 已超 X 元,并给出"照这个速度月末会怎样"的预测。数据还不够时它会明说——本月才过不到 7 天时,只显示"还看不出这个月的速度",不做看似精确的线性外推。

分析与日历

  • 支出占比(含每个账单的上限进度)、近 30 天逐日趋势、跨月对比、最大单笔、最贵的一天。
  • 消费日历热力图:按当月逐日着色,点某天弹出那天的全部流水。
  • 连续记账天数:只算真正记过账的日子,回看窗口 400 天。
  • 统计一律按资金方向取数,默认只看支出,避免把工资算进"本月花了多少"。

搜索

  • 按备注、账单名或精确金额搜索,可叠加筛选:方向 / 金额下限 / 时间范围。
  • 单次返回上限 400 条,界面上会明确告诉你结果被截断了——"共 N 笔 · 合计 ¥X"那行数字必须能诚实。

数据与可逆性

  • 备份 / 恢复:JSON 文本,格式版本 v1–v4 都能读,恢复前会校验格式与内容一致性;备份文件超过 30 天会提示"可能已过时"。
  • 导出 CSV:走系统的文件选择器(SAF),文件名带日期。
  • 删除账单是这款应用里唯一不可逆的操作,所以先做成"进回收站"。

外观

  • 6 套莫奈取色的配色(灰蓝晨雾、睡莲水光、日出橙雾、麦田赭金、竹舟池绿、教堂黄昏)× 浅色 / 深色 / 跟随系统。
  • 每套色板不是手挑的六个颜色:页面底、卡片、两条色带、正文墨色由一条派生规则算出来,能不能读清由 WCAG 对比度测试判定(明暗两套各有起算点)。
  • 圆角、尺寸阶、透明度、动效时长各自收敛成一套 token,并有一条会红的守卫测试拦住"随手写死一个 dp"。

安装

到 Releases 下载 TingLedger-v1.25.0-release-signed.apk,允许"安装未知来源应用"即可。

  • 已装过旧版本可以直接覆盖安装,数据保留。
  • 发布版签名证书 SHA-256 指纹(用来核对是不是同一个密钥): fc86dddfac1fa60f3adbe4a1ef6c36de6d5f606f07d409d4331b958bff50906c,证书主体 CN=TingLedger。
  • 自己构建:./gradlew assembleDebug 出的包用 debug 证书签名,不能覆盖安装正式包,请先卸载。

隐私与权限

AndroidManifest.xml 里没有一条 <uses-permission>,源码里搜不到任何网络相关符号(java.net、Http*、OkHttp、Retrofit、Socket、WebView……全部为 0 命中)。也就是说:

  • 记账数据不会离开手机,除非你自己用备份/导出功能把它带出去。
  • 应用没有后台同步、没有埋点、没有广告 SDK。

一条需要如实说明的:manifest 里 android:allowBackup="true",这意味着系统级的应用数据备份(例如你迁移到新手机时)可能会带上本地数据库。如果你不希望账本进入系统备份,请在构建时把它改成 false。

构建

项 值
JDK 21(build.cmd 里显式钉住;JVM target 仍是 17)
Gradle 9.1.0(用仓库自带的 wrapper,不必本机安装)
AGP / KSP 8.13.0 / 2.3.12
Kotlin 2.4.0
compileSdk / targetSdk / minSdk 36 / 36 / 26
# 1. 告诉 Gradle 你的 Android SDK 位置(这个文件不会进版本库)
echo "sdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk" > local.properties

# 2. debug 包
./gradlew assembleDebug      # Windows: build.cmd assembleDebug

关于签名密钥: release 构建读取 keystore/keystore.properties(含 storeFile / storePassword / keyAlias / keyPassword)与 keystore/tjz-release.jks。这两个文件不在仓库里,构建脚本对它们做了存在性判断——没有密钥时 release 会退化产出未签名包,而不是把你构建失败卡住。要出可安装的正式包,自己 keytool 生成一对即可。

关于依赖仓库: settings.gradle.kts 里把阿里云 / 腾讯云镜像放在前面,google() 与 mavenCentral() 作为后备。在境外网络环境下会直接走后两个源,不需要改配置。

跑测试

./gradlew test

当前状态(v1.25.0 实测):debug 变体 258 条 / 27 个类,release 变体 233 条 / 23 个类,0 失败。

界面不需要真机也能验:单测用 Robolectric 4.16 + Compose UI Test 在 JVM 里真的把屏幕组合一次。这个闸门是踩过坑之后加的——曾连发两个"进账单页闪退"的包,因为只做了编译和纯逻辑单测,而崩溃发生在组合期,编译器看不见。仓库里还有两类不常见的测试,值得单独提:

  • 查询计数测试(AnalyticsQueryCountTest):断言的是"打开这个页面、记一笔、翻个月,到底扫了几遍库",用注入的假仓储数调用次数。性能优化不该靠"我觉得会快一点"。
  • 样式守卫测试(StyleAuditTest):扫源码,非 theme 目录里出现裸 dp、裸 RoundedCornerShape(、alpha = 0.Nf、tween(N) 就让构建失败。找不到源码根就硬失败——一道不可能报错的检查等于没有检查。

两条写测试时会踩到的实测前提:runTest 不会替换 Dispatchers.Main,不 setMain 的话 viewModelScope 一条都不跑,所有计数停在 0,看起来特别像"代码没问题";Robolectric 下 DataStore 文件在同一个测试类内是共享的,断言别依赖"干净起点"。

项目结构与技术选型

app/src/main/java/com/klocktx/moneyblocks/
├── core/       Cents、时间工具、AppContainer(手写依赖容器)
├── data/       Room:实体 / DAO / 数据库 / 显式迁移;DataStore;Repository 实现
├── domain/     model(Bill / Entry / Stats …)、usecase(求值器、排期、预算节奏、备份 …)、repo 接口
└── ui/         theme、home、analytics、bill、keypad、day、search、settings、common
  • 分层是包级而非 Gradle 多模块。 规模不大,拆模块的收益过剩。
  • DI 用手写 AppContainer,没引 Hilt。 依赖关系一眼可见,不需要注解处理器再猜一次。
  • 图表是 Canvas 手绘的,没引图表库。 要的就是"这一格深一点浅一点"完全由我控制。
  • 唯一的交互库依赖是 sh.calvin.reorderable。 拖动排序自己写过两版都被否掉——连续拖动加边缘自动滚动的细节太多。结论:交互原语用库,视觉与计算自己写。
  • Room SCHEMA_VERSION = 4,所有变更都配显式 Migration。 已装设备上有真实流水,fallbackToDestructiveMigration() 等于清空用户的账本。迁移测试的做法是让 Room 自己跑迁移(它会校验 room_master_table 里的 identity hash),而不是手工执行 SQL。
  • 设置类偏好走 DataStore(月度预算、分类上限、主题选择)。

设计上较真的几件事

  • 金额不用 Double。 见上;Cents 是内联值类,运行时没有包装对象。
  • 不确定就说不确定。 月初前几天不做速度预测;搜索结果被截断就明说截断;备份过期就提示可能过时。
  • 删除默认可逆。 删账单先进回收站,恢复只是清标记,不需要重放任何数据,也就不会对不上账。
  • 动效克制。 页面切换只淡入淡出不做水平位移——顶栏已经对齐,再滑一下反而像没对齐。互斥的两套控件用 AnimatedVisibility 而不是 Crossfade,因为 Crossfade 的淡出内容一直挂在语义树里,看不见的按钮仍能被点、被读屏念到。
  • 无障碍不是附加项。 图标有 contentDescription,拖动把手有业务化标签,读屏能念出每一行是什么。
  • 每个结论带数字。 README 里所有版本、体积、测试条数都来自构建产物与测试 XML,不是估计。

开发史与设计文档

DESIGN.md 是这个项目的规格文档,共 51 节,从最初的需求评审一路记到 v1.25.0。它记的不只是"做了什么",还包括为什么这么做和哪些判断是我做错的:

  • §34–§40:两次配色返工,以及"为什么企业感的饱和橙不能当主色"。
  • §45:记账弹层顶到全屏,我凭推断改了四轮,最后一条把真实高度打印出来的测试 10 秒定位(内容 754dp > 屏幕 740dp)。
  • §51:把逐日聚合下推到 SQL 的优化,被一条时区对照测试否决(expected:<[2026-02-28]> but was:<[2026-03-01]>,TimeZone.setDefault 传不进 native SQLite),因为无法在真机上验证,宁可不采纳。

已知限制与未验证项

诚实列在这里,欢迎帮忙验证:

  • v3 → v4 的 schema 迁移没有在真机上验证过。 有单测覆盖迁移逻辑,但没有装旧版本的真实设备,这是目前风险最高的一项。
  • 界面观感与性能手感需要装机确认。 开发机上没有任何真机与模拟器镜像,所有"看起来更好"的判断都只做到"像素与尺寸可测",没法替你做审美判断。
  • 性能还有一轮没做:分析页/首页目前是顶层一次收集 14–17 条流,任意一条变化就整片重组,按 section 拆分会更省;逐日聚合下推到 SQL 也被推迟(见上一条的否决理由)。
  • 备份格式升到 v4,读 v1–v3 旧文件是兼容的,但 v1 时期的一些字段语义在恢复时会走默认值。

参与贡献

改代码之前请注意两条这个项目已经付过学费的规矩:

  1. 改完至少跑 ./gradlew test,别只验主源码编译——测试源里的错误只有跑到它才知道。新加的组合冒烟测试类记得同时加进 app/build.gradle.kts 里 testReleaseUnitTest 的排除名单(ui-test-manifest 只能挂 debug)。
  2. 动 schema 必须写显式 Migration,并且补一条让 Room 自己跑迁移的测试。

Pull Request 请说清楚改动动机;涉及界面或性能的改动,请带上可复现的数字(组合是否变多、查询少了几次),不要写"感觉更流畅"。

许可证

MIT — 见 LICENSE。

致谢

  • 配色取名的灵感来自莫奈的睡莲、日出、麦垛与鲁昂教堂系列。
  • reorderable 提供了可用的拖动排序原语。
  • Android Jetpack Compose、Room、DataStore 与 Material Icons。

About

纯本地 Android 记账应用:不联网、无账号、金额以分存储。周期性账单、回收站、分类预算与预算节奏、消费日历、备份/恢复与 CSV 导出。

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages