# DriftLedger (浮记)

面向 [Beancount](https://beancount.github.io/) 用户的离线移动记账客户端。桌面账本只读，移动端仅追加写入 `main.bean`；支持 OCR、无障碍服务、通知监听、短信等多渠道自动记账。

**技术栈**：React Native + Expo (CNG) · TypeScript (strict) · Zustand · expo-sqlite · PP-OCRv6 (ONNX Runtime)

## 快速开始

```bash
npm install --legacy-peer-deps   # 安装依赖（必须带 --legacy-peer-deps）
npm run start                    # 启动 Metro 开发服务器
npm run android                  # 构建并运行 Android
npm test                         # 运行 Vitest 全量测试
npm run typecheck                # TypeScript 类型检查
```

> 本应用为侧载开源项目，不上架应用商店。Android 构建详见 [docs/android-build-guide.md](docs/android-build-guide.md)。

## 模块概览

| 目录 | 职责 |
|------|------|
| `src/domain/` | 纯业务逻辑：`.bean` 解析器、账单管道、去重、规则引擎、OCR 处理器 |
| `src/app/` | Expo Router 文件路由（`(tabs)/` 底部导航） |
| `src/components/` | React Native UI 组件与图表 |
| `src/store/` | Zustand 状态管理（ledger / import / settings / metadata / automation） |
| `src/services/` | 平台服务（同步、备份、安全、OCR 桥接） |
| `src/storage/` | SQLite 读缓存 + 版本化迁移 |
| `src/theme/` | Token 主题系统（浅色 / OLED 暗色） |
| `src/i18n/` | 中英文国际化 |
| `plugins/` | Expo Config Plugins 原生模块（OCR、无障碍、通知、短信、截图） |
| `tests/` | Vitest 单元测试（mock 后端，覆盖 domain 层） |

## 文档导航

| 文档 | 内容 |
|------|------|
| [docs/architecture.md](docs/architecture.md) | 系统架构与数据流 |
| [docs/development.md](docs/development.md) | 开发指南（环境、命令、规范、测试） |
| [docs/android-build-guide.md](docs/android-build-guide.md) | Android 打包与体积优化 |
| [docs/design/](docs/design/) | UI 重设计规格与分阶段实施计划 |
| [design-system/](design-system/beancount-mobile/MASTER.md) | 设计系统 Token 定义 |
| [AGENTS.md](AGENTS.md) | AI 编程助手贡献指南 |
| [plan.md](plan.md) | 设计决策与实施路线图（权威文档） |

## 账本约定

在桌面主账本中添加一次：

```beancount
include "main.bean"
```

应用不改写主账本或其他桌面维护文件；确认的交易只追加到 `main.bean`。