63 lines
5.3 KiB
Markdown
63 lines
5.3 KiB
Markdown
|
||
# Beancount 移动端：复式记账与账单自动记账方案
|
||
|
||
## 摘要
|
||
|
||
面向已有 Beancount 账本的个人用户，开发 iOS/Android 应用。账本文件是唯一权威来源：应用读取现有 `.bean` 文件，并将手机确认的新交易追加到独立的 `mobile.bean`。自动记账采用“导入账单 → 规则生成复式分录草稿 → 用户确认入账”，不申请短信权限、不自动提交未确认交易。
|
||
|
||
首版不做实时 Git/WebDAV 双向同步、OCR、AI 直接记账、投资 lot 完整计算或团队协作。
|
||
|
||
## 核心实现
|
||
|
||
- 使用 React Native + TypeScript + Expo CNG（自定义开发构建），支持 iOS 与 Android；本地以加密 SQLite 保存账本索引、导入记录、规则和草稿缓存，原始 `.bean` 文件仍为唯一权威数据。
|
||
- 首次打开时导入账本包（主文件及其 `include` 引用的文件）；应用解析账户、交易、商品、价格和余额断言，建立只读查询索引。
|
||
- 要求用户在主账本中一次性加入 `include "mobile.bean"`。应用只创建、编辑或删除 `mobile.bean` 内的分录，绝不改写桌面维护的源文件。
|
||
- 导出时输出完整账本包及更新后的 `mobile.bean`；用户可通过 Files/iCloud/Android 文件选择器交回其原有同步方式。首版不做后台文件监听或并发合并。
|
||
- 使用 Tree-sitter 提供 Beancount 语法树解析；复式规则由独立账务层执行：
|
||
- 交易必须至少有两条 posting；
|
||
- 同币种显式金额 posting 必须平衡；
|
||
- 账户必须已 `open`；
|
||
- 金额采用 Decimal/字符串定点表示，禁止浮点计算；
|
||
- 不支持或无法安全解释的高级指令、插件与复杂库存交易保留原文并标记为“只读兼容”，不允许移动端修改。
|
||
- 应用公开的领域接口固定为：
|
||
- `parseLedger(files) -> LedgerIndex | ParseDiagnostics`
|
||
- `validateTransaction(draft, ledger) -> ValidationResult`
|
||
- `importStatement(file, adapter) -> ImportedEvent[]`
|
||
- `classify(event, rules, ledger) -> TransactionDraft`
|
||
- `commitMobileTransaction(draft) -> mobile.bean diff`
|
||
- `exportLedgerBundle() -> zip`
|
||
|
||
## 自动记账流程
|
||
|
||
- 首版支持可版本化的账单适配器：支付宝 CSV、微信支付 CSV、银行卡 CSV；Excel 仅在格式等同 CSV 时支持。PDF 账单不纳入首版。
|
||
- 每个适配器统一输出 `ImportedEvent`：交易时间、金额、币种、收付款方向、渠道账户、交易对手、备注、外部流水号和原始字段。
|
||
- 导入后按“渠道 + 外部流水号”去重；缺少流水号时，以日期时间、金额、方向、对手方和备注生成指纹，并提示可能重复项。
|
||
- 规则按优先级匹配：渠道账户、收付款方向、对手方关键词、备注关键词、金额区间、币种。规则输出目标账户、对方账户或分类、标签、摘要和置信度。
|
||
- 未匹配规则时，生成含 `Expenses:Uncategorized` 或 `Income:Uncategorized` 的草稿；用户必须选择或确认分类后才能写入。
|
||
- 转账识别仅在金额、币种一致且时间差在 3 天内的两条相反流水之间执行；生成 `Assets:* ↔ Assets:*` 分录，并要求用户确认。
|
||
- 确认交易写入 `mobile.bean`，并保留导入事件与生成交易的关联；用户可从一笔已确认交易反查源账单及命中规则。
|
||
- 用户在确认页手工修正账户、金额、日期、摘要或分录后，可选择“保存为规则”；规则只对之后导入的账单生效，不回写历史交易。
|
||
|
||
## 页面与交互
|
||
|
||
- `账本`：导入账本、解析状态、`mobile.bean` 写入状态、导出账本包。
|
||
- `记账`：支出、收入、转账、手工复式分录；默认提供借贷平衡提示。
|
||
- `导入`：选择账单文件、选择适配器、字段预览、重复项处理、草稿确认队列和导入结果。
|
||
- `规则`：按优先级管理自动分类规则，展示最近命中次数与示例。
|
||
- `账户与报表`：账户树、账户明细、未分类交易、月度收支和净资产；仅基于已解析且有效的分录计算。
|
||
- `诊断`：展示 Beancount 文件语法/账务错误、未识别指令与无法写回的原因；错误不阻断阅读，但阻断受影响账本的写入。
|
||
|
||
## 测试与验收
|
||
|
||
- 账务单测覆盖：平衡/不平衡分录、Decimal 精度、多币种隔离、关闭账户、未知账户、转账、编辑和删除 `mobile.bean` 内交易。
|
||
- 解析兼容测试使用公开 Beancount 示例及中文账户名；要求未支持内容不丢失、导出后仍保留原始文本。
|
||
- 每个账单适配器使用脱敏固定样本，覆盖收入、支出、退款、手续费、转账、重复流水和字段缺失。
|
||
- 端到端测试覆盖：导入账本 → 导入支付宝账单 → 命中规则 → 修改草稿 → 确认 → 导出 → 桌面端 Beancount 校验通过。
|
||
- 上架前在 iOS/Android 真机验证离线记账、数据库加密、文件导入导出、应用锁和崩溃恢复；不申请 SMS、全盘存储或后台读取权限。
|
||
|
||
## 默认假设
|
||
|
||
- 默认主币种为 CNY，但账本可含其他货币；首版只对同币种交易做自动平衡校验，不自动推导汇率、成本或库存。
|
||
- `mobile.bean` 是仅由移动端维护的追加文件；桌面端交易在首版只读。
|
||
- 用户负责将导出的账本包同步回 Git、WebDAV、iCloud 或其他已有方案；实时多端同步属于下一阶段。
|