# SMB — Sutady Moneybook

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

## 已实现

- 快速收入/支出记账，只记录发生日期，金额以整数“分”保存。
- 完全自定义分类、停用、迁移或永久删除分类、月/年账单、搜索筛选、全局 30 天回收站、CSV/JSON 导出。
- 周、月、年趋势，分类明细、分类构成和上一周期同进度比较。
- DeepSeek 消费概览、异常增长、节省建议、分类结构和自定义问题；程序负责数字，模型只负责解释，当前不会向外部模型发送账目备注。
- 标准 Streamable HTTP MCP；可由网页在“确认模式”和“直接接管模式”间切换。直接模式可管理账目、分类、借款、订阅、AI、备份和时区，并保留 30 天可撤销操作记录。
- SQLite WAL＋`synchronous=FULL`、迁移前快照、每日完整性/外键备份、`age` 公钥加密和 Google Drive 上传。
- Cloudflare Access 双层保护、PWA 安装、Windows 登录自启动与失败重启辅助脚本。
- 四套主题、四种内置页面背景，以及仅保存在当前设备的个人背景图片。个人图片会在浏览器内压缩并去除元数据，可暂时切换回内置背景而不会被删除。
- 查询优先的洞察首页：周期与收支类型保存在网址中，刷新或从分类账单返回后仍保持原来的查看位置。
- 手机端采用紧凑摘要、明细/构成切换、贴底导航和账单筛选抽屉；搜索期间保留旧列表，避免内容闪烁。
- 全站日期以设置中的账本时区为准，电脑和 Android 所在时区不同时，“今天”、默认月份与 AI 分析周期仍保持一致。
- 独立“事项”模块管理别人欠我的借款、分次还款和 CNY/USD 订阅。事项默认不进入消费统计；只有主动关联或同时创建的普通账目才会影响图表。
- 借款支持借款人停用、部分还款、自动结清和 30 天回收站；订阅支持首期优惠、月/年/自定义周期、到期确认、付款历史与应用内提醒。
- 每月可设置人民币总预算和分类预算；预算不结转、不阻止记账，洞察页会显示已用、剩余、预测和分类风险。
- “账本体检”用确定性规则提示疑似重复、大额支出、预算风险、待确认续费和关联异常；核对不会自动改账，AI 只解释程序发现的事实。
- Android/Windows 安装后的应用菜单提供“记一笔”快捷入口；OpenClaw 支持一次原子写入最多 20 笔账目并整批撤销。
- 记录借款使用可搜索的单一借款人选择器；新借款人与借款同事务保存。同名活跃记录会复用，停用记录需先恢复。
- OpenClaw 提案重试不会重复创建待确认项；操作中心可按需查看字段变化和失败状态。账本体检也可由 MCP 只读查询，且不返回备注。
- 可选的“资金”模块记录人民币账户、余额流水、账户间转账、手续费、余额校准和全额退款；总资金不包含待收借款、投资或未来收入。
- 资金追踪启用前的历史账目不会被追溯；启用后的普通收支绑定账户，余额由初始余额与追加式资金流水计算，不维护第二份余额真相。
- OpenClaw 可精确查询和管理账户、转账、校准与退款；所有直接写入继续使用幂等 requestId，歧义账户名称会被拒绝。

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

## 洞察与账单

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

## 页面更新与个人背景

- 页面处于打开状态时，每 30 秒同步当前页面的账本数据；重新聚焦窗口或网络恢复时也会立即同步。
- PWA 每分钟检查一次新版本，发现新版本后会在没有正在编辑的表单时自动更新。也可以在“设置 → 运行状态”点击“检查并刷新”。
- Cloudflare 登录过期时使用页面上的“重新登录”，不要删除网站 Cookie 或清除网站数据。“重新登录”和“检查并刷新”只替换 PWA 程序缓存，保留登录 Cookie、外观偏好和 IndexedDB 中的个人背景；清除整个网站数据才会删除当前设备的个人图片。
- 选择“纯净、纸张、织纹、薄雾”会暂时停用个人图片，但图片仍保留在当前设备，可随时点击“使用图片”恢复。
- 每个浏览会话首次冷启动会短暂显示一次 SMB 品牌开屏；刷新数据和页面切换不会重播，系统开启“减少动画”时直接跳过。

## 快速上手与本地运行

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

### 方式一：Windows 一键启动（最推荐）
直接双击项目根目录下的 **`打开 SMB.cmd`**。
- 首次运行会自动检查依赖、自动根据模板生成 `.env` 默认配置并完成编译打包；
- 随后会自动启动服务并在默认浏览器中打开记账首页（默认访问 `http://127.0.0.1:8788`，免登录单机模式）。

### 方式二：命令行手动启动（跨平台通用：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)。
- **AI 智能消费分析**：双击根目录 `配置DeepSeek密钥.cmd` 或在 `.env` 中填入 DeepSeek API Key 即可启用消费洞察与节省建议。
- **异地加密自动云备份**：配置 Google Drive 与 `age` 加密密钥，实现每日自动快照上传，详见 [恢复指南](docs/RECOVERY.md)。
- **资金与账户管理**：多账户资产流水、转账与余额校准，详见 [资金追踪指南](docs/FUNDS.md)。
- **借款与订阅管理**：跟进外部欠款、分次归还与周期订阅扣费，详见 [事项使用指南](docs/MATTERS.md)。

## 目录

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

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

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

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