# Pickbank · 拾念记账

一句话记下日常开销，用预算看清生活，也让像素伙伴陪你养成记录习惯。

[English](README.en.md) · [工程架构](docs/open-source/ARCHITECTURE.md) · [当前状态](docs/open-source/PROJECT_STATUS.md) · [文件地图](docs/open-source/FILE_MAP.md)

项目理解、已完成优化和后续建议见[项目审阅记录](docs/open-source/PROJECT_REVIEW.md)。

Pickbank 是面向 Android 的本地记账应用，使用 Kotlin、Jetpack Compose 与 Room。手动记账和本地规则解析可以离线使用；大模型功能由用户自行配置服务商与 API Key。本仓库包含 Android 工程、开发工具和介绍网页。

## 功能

- **记录**：自然语言与手动录入、分类、备注、固定账单、账单文件导入。
- **预算与明细**：预算余量、分类限额、日期范围、关键词与收支筛选。
- **总结**：日 / 周 / 月 / 年 / 自定义区间统计、趋势、分类占比与账本导出。
- **可选 AI**：解析复杂输入、账单分析与问账，支持兼容聊天接口的服务商。
- **像素伙伴**：八种内置动物、昼夜家园、现实日历生命周期、互动与纪念档案；Android 支持用户导入自定义宠物媒体。
- **外观**：经典暖黑与 Hermes 蓝色主题，中文与英文界面。

Android 源码版本为 **1.9.2 / versionCode 24**，最低 Android 12（API 31）。2026-10-09 的开源准备属于源码维护，尚未发布新版本 APK。验证详情见[当前状态](docs/open-source/PROJECT_STATUS.md)。

## 构建 Android 应用

### 环境

| 工具 | 要求 |
|---|---|
| JDK | 21；Gradle daemon 配置指定 JetBrains JDK 21，Java / Kotlin 字节码目标为 17 |
| Android SDK | Platform 36；安装并接受对应 SDK 许可，Build Tools 按 Android Gradle Plugin 提示安装 |
| Gradle | 使用仓库 Wrapper 8.13 |
| Android Gradle Plugin / Kotlin | 8.13.2 / 2.1.0，版本在 `gradle/libs.versions.toml` |

用 Android Studio 打开仓库根目录，完成 SDK 设置。命令行使用者可以设置 `ANDROID_HOME`，或复制 `local.properties.example` 为 `local.properties` 并填写本机 SDK 路径。首次构建需要网络下载依赖；Wrapper 的 daemon 配置也可能下载 JDK。

Windows PowerShell：

```powershell
.\gradlew.bat :app:assembleUserDebug :app:assembleDeveloperDebug
```

macOS / Linux：

```sh
chmod +x gradlew
./gradlew :app:assembleUserDebug :app:assembleDeveloperDebug
```

输出在 `app/build/outputs/apk/user/debug/` 与 `app/build/outputs/apk/developer/debug/`。

| 变体 | 应用 ID | 用途 |
|---|---|---|
| `user` | `com.sum.ledger` | 日常使用 |
| `developer` | `com.sum.ledger.dev` | 日常功能加宠物场景、阶段等调试入口 |

两种变体可以同时安装，数据分别保存在各自沙箱。公共源码不包含八重神子测试素材，相关内置测试入口自动关闭；自定义宠物导入功能仍可使用。

**构建无需 API Key。** 首次使用 AI 时，在应用的 AI 配置界面填写服务商、模型与 Key。不要把 Key 放入源码或安装包。当前 `release` 构建仍使用 Android debug 签名，正式分发前需配置自己的生产签名，见[发布清单](docs/open-source/RELEASE_CHECKLIST.md)。

## 数据与隐私

账本保存在设备 Room 数据库；设置在 SharedPreferences；自定义宠物媒体在应用私有目录。应用没有实现账号或云端账本同步。

使用 AI 功能时，相关输入或账目摘要会发送给用户选择的服务商。API Key 保存在设备本地设置中。系统备份行为由 Android 和设备设置控制，本地保存不代表数据已加密或完全不会备份。清除应用数据、卸载或换机前，请先使用应用的导出功能保留账本。

漏洞报告请阅读 [SECURITY.md](SECURITY.md)，不要在公开 issue 附上私人账单、备份或 Key。

## 介绍网页

`website/` 是介绍 Android 应用的独立静态网页，无 npm 构建步骤：

```sh
python -m http.server 8766 --directory website
```

打开 <http://localhost:8766>。网页中的交互账本是说明性演示，使用示例金额，不是 Android 实机截图，也不会访问真实账本或调用 AI。

## 开发检查

```sh
python -m pip install -r requirements-dev.txt
python -m unittest discover -s scripts/tests -t .
```

Android 单元测试与 lint（Windows 将 `./gradlew` 替换为 `.\gradlew.bat`）：

```sh
./gradlew :app:testUserDebugUnitTest :app:testDeveloperDebugUnitTest :app:lintUserDebug
```

这些命令是检查入口，实际执行证据见[当前状态](docs/open-source/PROJECT_STATUS.md)。资源处理工具的输入要求见[文件地图](docs/open-source/FILE_MAP.md)。

网页自动检查需要另外安装 Playwright（`python -m pip install playwright`、`python -m playwright install chromium`），启动预览后运行 `python scripts/verify_website.py`。`.github/workflows/android.yml` 已准备对应源码检查，尚未在远端运行。

## 开源文件准备

在原开发工作区执行：

```sh
python scripts/export_open_source.py
```

脚本生成独立的 `open-source-prep/<run>/repository/`、文件哈希清单与私有审阅摘要。导出使用允许清单，排除旧 Git 历史、本机配置、私人备份、测试同人素材、构建缓存和历史产物。详细分类见[文件地图](docs/open-source/FILE_MAP.md)。

**上传前由项目所有者审阅导出包。** 原工作区曾跟踪私人配置和数据库，不应直接公开原仓库或推送原有历史。脚本只准备本地文件，不执行上传或 Git 推送。

## 贡献与许可

欢迎小范围修复与改进。请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，保留数据库迁移、整数金额与资源布局契约。

项目代码采用 [MIT License](LICENSE)。内置八物种、场景与应用图标的授权范围，以及字体和依赖的独立许可，见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。