一款面向 Android 的本地优先账单管理应用，重点解决微信官方账单文件、微信账单截图和手工账单难以统一整理的问题。应用支持离线导入、截图 OCR 识别、导入批次汇总、账单编辑与批量管理、支出统计，以及高度可配置的 Excel 导出。
当前版本：
v0.5.0
Android：最低 Android 8.0（API 26），目标 API 36
数据策略：账单数据与 OCR 处理保留在本地，不上传金融数据
- 多种导入方式：支持微信官方 CSV/XLSX 文件、账单截图/图片和手工添加。
- 离线中文 OCR：使用 ML Kit 在设备端识别微信账单列表或交易详情截图，保存前可检查并修正草稿。
- 智能账单解析：兼容官方文件的说明行、BOM、Excel 数字日期、跨月份长截图、退款状态和常见 OCR 符号误识别。
- 批次化管理：同次导入或手工添加的账单合并成可展开的小汇总，显示导入时间、支出笔数、支出金额和总条数。
- 完整账单维护：支持修改账单字段、多选、全选、批量分类、分类重命名以及带确认的单条/批量删除。
- 可视化统计：按分类汇总总支出并显示扇形图；收入和退款不计入总支出。
- 自定义 Excel 导出：可选择记录、明细列、工作表和模板，并任意调整明细列与工作表顺序。
- 本地安全存储：Room + SQLCipher 加密账本，数据库密钥由 Android Keystore 包装保护。
从 GitHub Releases 下载与版本对应的 账单管家-<版本号>.apk，在 Android 8.0 或更高版本设备上安装。调试 APK 与正式商店签名版本的签名不同，覆盖安装前请确认设备上安装的是同一签名来源。
- 在微信中导出官方账单文件。
- 打开账单管家，选择
导入 CSV/XLSX，也可以从系统文件管理器将文件分享给应用。 - 检查解析出的有效、无效和疑似重复记录。
- 选择需要保存的记录并确认导入。
- 导入成功后，应用显示支出、收入、退款和总计数量；该提示需要主动点击关闭。
- 选择
识别截图，从系统图片选择器选择一张或多张账单图片。 - 等待设备端中文 OCR 完成识别。
- 检查交易时间、金额、收支方向、交易对方等字段，修正低置信度或不完整内容。
- 确认保存后，同一轮图片识别的记录会组成一个导入批次。
建议使用清晰、完整、未经强烈压缩的原始截图。当前识别重点针对微信账单列表、收支统计和交易详情，不承诺识别任意票据版式。
在首页选择 自定义添加，可一次添加一笔或多笔账单。每笔账单可设置时间、收支方向、金额、交易对方、分类、说明、交易类型、支付方式、状态和备注。同次保存的记录作为一个可展开的手工账单批次展示。
- 首页和账单页按导入/添加批次展示小汇总，点击可展开逐笔记录。
- 可通过搜索、收支方向和分类筛选账单；筛选同时作用于批次汇总与展开后的明细。
- 展开后可修改单笔账单，或选择多笔记录执行批量分类和批量删除。
- 删除操作需要确认，避免误删。
打开统计页查看按分类汇总的支出扇形图、金额和占比。图表统计实际支出，不将收入或退款计入总支出。
- 打开导出页并选择内置模板。
- 选择要导出的账单、明细列和工作表。
- 使用上移/下移调整列与工作表顺序。
- 选择保存位置，应用在本地生成标准 XLSX 工作簿。
模板会保存当前选择和排序，方便重复使用。
flowchart LR
A["CSV / XLSX 文件"] --> D["导入与标准化"]
B["截图 / 图片"] --> C["设备端中文 OCR"]
C --> D
E["手工添加"] --> D
D --> F["草稿检查与重复指纹"]
F --> G["Room + SQLCipher 本地账本"]
G --> H["批次汇总与账单管理"]
G --> I["分类统计与扇形图"]
G --> J["自定义 XLSX 导出"]
| 层次 | 主要技术与职责 |
|---|---|
| 界面 | Kotlin、Jetpack Compose、Material 3；首页、账单、统计、导入检查、导出与设置 |
| 状态与业务 | AppViewModel、协程、领域模型；导入协调、过滤、批次、手工账单、统计聚合 |
| 文件导入 | 自研 CSV 与轻量 XLSX 解析；表头归一化、Excel 日期转换、微信字段映射 |
| 图片识别 | Google ML Kit Chinese Text Recognition；OCR 结果的微信账单语义解释与纠错 |
| 本地数据 | Room、SQLCipher、Android Keystore；账单、分类、导入元数据与模板持久化 |
| 文件导出 | 本地生成标准 XLSX；支持工作表、列、记录范围、顺序与模板配置 |
| 质量保障 | JUnit、Room 测试、Compose UI/仪器测试、Android Lint、GitHub Actions、OpenSpec |
更完整的架构取舍、产品价值和限制请阅读 技术介绍与产品总结。
| 版本 | 类型 | 主要内容 |
|---|---|---|
v0.0.0 |
仓库基线 | 初始化 Git 仓库，建立可追溯的空白起点 |
v0.1.0 |
设计里程碑 | 完成 OpenSpec 提案、架构设计、需求规格和任务拆分 |
v0.2.0 |
MVP | Android Compose 应用、加密账本、微信文件/截图导入、筛选统计和 XLSX 导出 |
v0.2.1 |
导入修复 | 修复真实微信官方 XLSX 数字日期和复杂账单截图识别 |
v0.3.0 |
管理与导出 | 完整编辑、批量分类/删除、导出列与工作表任意排序、版本化 APK |
v0.4.0 |
批次汇总 | 持久化导入批次、导入结果统计弹窗、首页与账单页可展开批次卡片 |
v0.4.1 |
筛选修复 | 分类筛选正确作用于批次汇总、金额、数量和展开明细 |
v0.5.0 |
手工添加与图表 | 单笔/多笔手工账单、支出扇形图、新 Logo 和技术支持信息 |
完整的逐版本修改原因、实现内容和验证记录见 开发日志 与 CHANGELOG。仓库保留所有里程碑提交和 annotated semantic-version tags。
- JDK 17
- Android SDK（
compileSdk 36） - Windows PowerShell、macOS 或 Linux 终端
- 使用仓库内置 Gradle Wrapper，无需单独安装 Gradle
Windows：
.\gradlew.bat clean lintDebug testDebugUnitTest assembleDebugmacOS / Linux：
./gradlew clean lintDebug testDebugUnitTest assembleDebug构建完成后，版本化调试 APK 位于：
app/build/outputs/versioned-apk/debug/账单管家-<version>.apk
在连接模拟器或设备后运行仪器测试：
.\gradlew.bat connectedDebugAndroidTest验证 OpenSpec：
openspec validate build-android-bill-manager --strictapp/src/main/java/com/billmanagement/app/
├── MainActivity.kt # Compose 页面与交互入口
├── AppViewModel.kt # 应用状态和业务编排
├── data/
│ ├── db/ # Room / SQLCipher 数据层
│ ├── importer/ # CSV / XLSX 导入解析
│ ├── ocr/ # ML Kit OCR 与微信账单解释
│ ├── export/ # XLSX 导出和模板
│ └── security/ # Android Keystore 密钥管理
└── domain/ # 领域模型、批次、过滤、统计和账单操作
docs/ # 用户指南、隐私、测试、发布和开发日志
openspec/changes/ # 产品提案、设计、规格和实施任务
- OCR 在 Android 设备本地执行，应用不把账单或图片上传到云端。
- 账单数据库使用 SQLCipher 加密，密钥由 Android Keystore 保护。
- 系统文件与图片选择器只授予用户主动选择内容的读取权限。
- 仓库不包含真实账单、未脱敏截图、密钥、密码或发布签名文件。
- 用户可在设置页删除全部本地账单、分类、导入元数据、草稿和临时数据。
更多信息见 隐私说明。
- 当前仅支持 Android，尚无 iOS、桌面或 Web 版本。
- 当前主要适配微信账单，不读取微信私有目录，也不自动操作微信。
- OCR 会受截图清晰度、裁剪、字体缩放和界面版本影响，重要账目应在保存前复核。
- 趋势统计（日/周/月/年）、分页组合筛选和疑似重复账单处理界面仍在后续路线中。
- 当前仓库提供的是调试构建流程；正式发布需要独立的安全签名配置。
提交代码前请运行测试和 OpenSpec 严格校验。测试数据必须是虚构或彻底脱敏内容，禁止提交真实金融数据。详细约定见 CONTRIBUTING.md。
项目使用 MIT License，第三方依赖声明见 THIRD_PARTY_NOTICES.md。
技术支持：云洋科技技术支持