# SMB — Sutady Moneybook

SMB (Sutady Moneybook) 是一款基于 SQLite 和 MCP (Model Context Protocol) 的全栈个人记账系统。它原生支持本地单机运行与离线保存，也可通过 Cloudflare Tunnel 实现跨网安全访问；账本唯一数据源为本机 SQLite，浏览器不保存账目副本，不依赖外部云端数据库，数据完全自主掌控。当前版本以 `package.json` 为准。

## 已实现

- 快速收入/支出记账，只记录发生日期，金额以整数“分”保存。
- 完全自定义分类、停用、迁移或永久删除分类、月/年账单、搜索筛选、全局 30 天回收站、CSV/JSON 导出。
- 周、月、年趋势，分类明细、分类构成和上一周期同进度比较。进行中的月份对比上月同一段日期（例如 9 月 1 日对 8 月 1 日），不是上月整月；环比卡片和分类明细会写出对比窗口与上期金额。
- 标准 Streamable HTTP MCP；可由网页在“确认模式”和“直接接管模式”间切换。直接模式可管理账目、分类、借款、订阅、计划、备份和时区，并保留 30 天可撤销操作记录。想让 AI 解读账本时，直接问接入的 OpenClaw，它通过只读 MCP 工具读取同一套程序算出的数字。
- SQLite WAL＋`synchronous=FULL`、迁移前快照、每日完整性/外键备份、`age` 公钥加密和 Google Drive 上传。
- Cloudflare Access 双层保护、PWA 安装、Windows 登录自启动与失败重启辅助脚本。
- 温暖纸张、墨夜与跟随系统三种主题，四种内置页面背景，以及仅保存在当前设备的个人背景图片。个人图片会在浏览器内压缩并去除元数据，可暂时切换回内置背景而不会被删除。
- 查询优先的洞察首页：周期与收支类型保存在网址中，刷新或从分类账单返回后仍保持原来的查看位置。
- 手机端采用紧凑摘要、明细/构成切换、贴底导航和账单筛选抽屉；搜索期间保留旧列表，避免内容闪烁。
- 全站日期以账本时区为准（设置页只读显示，需要时让 OpenClaw 修改），电脑和 Android 所在时区不同时，“今天”与默认月份仍保持一致。洞察首页的期间、周/月/年与收支切换始终吸在顶部。
- 独立“事项”模块管理别人欠我的借款、分次还款、CNY/USD 订阅，以及一次性“计划”（预购尾款、某天要付的一笔、还没定日期的打算）。事项默认不进入消费统计；只有主动关联或同时创建的普通账目才会影响图表。
- 借款支持借款人停用、部分还款、自动结清和 30 天回收站；订阅支持首期优惠、月/年/自定义周期、到期确认、付款历史与应用内提醒。
- 计划录入不绑账户。无金额完成只改状态；有金额完成时才选分类和支付账户并记入账单，之后计划与账目不再同步。计划页用「未完成 / 已结束」分开，电脑上未完成左右分栏。完成无金额和移入回收站使用应用内确认。到期提醒出现在事项页签、底栏角标、洞察摘要和账本体检。
- 每月可设置人民币总预算和分类预算；预算不结转、不阻止记账，洞察页会显示已用、剩余、预测和分类风险。
- “账本体检”用确定性规则提示疑似重复、大额支出、预算风险、待确认续费、待完成计划和关联异常；核对不会自动改账。同一月同一档预算问题核对后，继续记账不会因金额变化再次弹出；已核对项不再占用体检列表。
- Android/Windows 安装后的应用菜单提供“记一笔”快捷入口；OpenClaw 支持一次原子写入最多 20 笔账目并整批撤销。
- 记录借款使用可搜索的单一借款人选择器；新借款人与借款同事务保存。同名活跃记录会复用，停用记录需先恢复。
- OpenClaw 提案重试不会重复创建待确认项；操作中心可按需查看字段变化和失败状态。账本体检也可由 MCP 只读查询，且不返回备注。
- 可选的“资金”模块记录账户、余额流水、账户间转账、手续费、余额校准和全额退款；总资金不包含待收借款、投资或未来收入。账本金额始终是人民币；账户可以是人民币、美元或 USDT，外币账户必须另填实际扣款或到账金额，不会查询或猜测汇率。最近资金流水按发生日从新到旧，在固定窗口内滚动加载。
- 资金追踪启用前的历史账目不会被追溯。启用瞬间会把当时已有账目记为历史基线，即使发生日期落在启用当天也不要求补账户。启用后新增的普通收支才绑定账户；余额由初始余额与追加式资金流水计算，不维护第二份余额真相。
- “账本体检”把缺少账户的启用后账目聚合成一条提示，可展开核对并批量指定人民币账户；已经计入启用余额的基线旧账不要补账户。
- OpenClaw 可精确查询和管理账户、转账、校准与退款；所有直接写入继续使用幂等 requestId，歧义账户名称会被拒绝。MCP 调错时返回 JSON-RPC 错误，而不是看起来像整站挂掉的通用 500。

“事项”的实际操作、启用资金前后的联动规则和 OpenClaw 权限见 [借款、订阅与计划使用指南](docs/MATTERS.md)。账户启用、资金影响、退款和体检提示见 [资金追踪使用与维护指南](docs/FUNDS.md)。

## 洞察与账单

- 洞察中的“分类明细”用于比较分类名次、金额和相对上期同进度变化，并显示上期金额；“分类构成”用于查看环形图、金额和占比，两者不会同时显示。
- 分类构成会完整展示本期所有有金额的分类，不再合并为“其他”；每个扇区和图例都可下钻到对应账单。
- 账单页有四个平级入口：“最近录入”“月账单”“年账单”“回收站”。回收站跨全部日期按删除时间排列，不会继承上次查看的月份。
- 旧网址继续兼容：`/bills` 打开最近录入；`/bills?view=ledger&period=month&anchor=...` 打开月账单；将 `period` 改为 `year` 即打开年账单；`/bills?view=trash` 打开全局回收站。
- 普通删除会保留 30 天并允许恢复。回收站中的账目可永久删除；「分类」页面也可在展示影响范围并确认名称后，永久删除分类及其全部账目。永久删除不可撤销，但关联的借款、订阅或计划事项会保留并自动解除账本关联。

## 页面更新与个人背景

- 页面处于打开状态时，每 30 秒同步当前页面的账本数据；重新聚焦窗口或网络恢复时也会立即同步。
- PWA 每分钟检查一次前端新版本，发现后会在没有正在编辑的表单时自动更新。也可以在“设置 → 运行状态”点击“检查并刷新”。在用 `打开 SMB.cmd` 启动的生产服务里，它会先加载磁盘上已构建的最新本机程序（含新接口和迁移），再更新网页缓存。开发模式或未托管的 Node 仍只刷新网页。首次装上这一能力时，需要手动重启一次 SMB Service。
- Cloudflare 登录过期时使用页面上的“重新登录”，不要删除网站 Cookie 或清除网站数据。“重新登录”和“检查并刷新”保留登录 Cookie、外观偏好和 IndexedDB 中的个人背景；清除整个网站数据才会删除当前设备的个人图片。
- 选择“纯净、纸张、织纹、薄雾”会暂时停用个人图片，但图片仍保留在当前设备，可随时点击“使用图片”恢复。
- 每个浏览会话首次冷启动会短暂显示一次 SMB 品牌开屏；刷新数据和页面切换不会重播，系统开启“减少动画”时直接跳过。

## 快速上手与本地运行

需要 Node.js 22 或更高版本。

### 方式一：Windows 一键启动（最推荐）
直接双击项目根目录下的 **`打开 SMB.cmd`**。
- 首次运行会自动检查依赖、自动根据模板生成 `.env` 默认配置并完成编译打包；
- 随后会自动启动服务并在默认浏览器中打开记账首页（默认访问 `http://127.0.0.1:8788`，免登录单机模式）。
- 请保留标题为“SMB Service”的窗口，关闭该窗口即停止服务。代码更新并重新构建后，可在“设置 → 运行状态”点「检查并刷新」加载新的 `dist-server`，不必每次都关窗口。

### 方式二：命令行手动启动（跨平台通用：Windows / Linux / macOS）
在项目根目录打开终端：

```bash
# 1. 安装项目依赖
npm install

# 2. 初始化本地配置（默认开启免登录单机模式）
cp .env.example .env

# 3. 运行开发模式（推荐本地体验，支持代码热重载）
npm run dev
# 浏览器访问 http://127.0.0.1:5173

# 或者编译并启动正式生产服务：
npm run build
npm start
# 浏览器访问 http://127.0.0.1:8788
```

## 质量检查

```bash
npm test
npm run typecheck
npm run build
```

正式更新前可额外创建一份经过完整性检查的快照：

```powershell
npm.cmd run backup:snapshot -- manual-update
npm.cmd run backup:verify-restore
```

## 进阶功能与部署指南

如果你仅在个人电脑上单机记账，**无需配置任何外部服务，开箱即用**。

若需要以下进阶能力，可参考对应指南按需配置：
- **手机跨网远程记账**：通过 Cloudflare Tunnel 实现免公网 IP 穿透与 Access 身份验证，详见 [部署指南](docs/DEPLOYMENT.md)。
- **异地加密自动云备份**：用自己的 Google OAuth 客户端（双击 `配置Google Drive授权.cmd`）和 `age` 加密密钥，实现每日自动快照加密上传；本地快照可用 `BACKUP_LOCAL_DIR` 放到另一块硬盘。详见 [恢复指南](docs/RECOVERY.md)。
- **资金与账户管理**：多账户资产流水、转账与余额校准，详见 [资金追踪指南](docs/FUNDS.md)。
- **借款、订阅与计划**：跟进外部欠款、分次归还、周期订阅扣费和一次性计划，详见 [事项使用指南](docs/MATTERS.md)。

## 目录

- `src/`：手机与电脑共用的 React PWA。
- `server/`：Node API、MCP、资金、财务事项、备份与 OpenClaw 提醒服务。
- `db/`：SQLite 表结构与迁移。
- `tests/`：金额、日期、事项、界面和 MCP 测试。
- `scripts/`：初始化、自启动、备份密钥和恢复脚本。
- `deploy/`：Cloudflare 与 OpenClaw 的无密钥配置模板。

私密文件 `.env`、正式数据库、备份、日志和构建产物都已排除在版本控制之外。

版本号只在 `package.json` 中维护。修复和视觉精修递增补丁版本，向后兼容的新能力递增次版本，产品身份或不兼容契约变化递增大版本；发布记录见 [CHANGELOG.md](CHANGELOG.md)。Logo 规范与可编辑源稿见 [品牌指南](docs/BRAND.md)。

已明确延后的账单导入、第三方余额同步和更复杂账户能力见 [ROADMAP.md](ROADMAP.md)。