SMB — Sutady Moneybook

SMB (Sutady Moneybook) 2.4.1 は、SQLite と MCP (Model Context Protocol) に基づくフルスタックの個人家計簿システムです。ローカル単独での実行とオフライン保存をネイティブにサポートし、Cloudflare Tunnel によるクロスネットワークの安全なアクセスも可能です。帳簿の唯一のデータソースはローカル SQLite であり、外部のクラウドデータベースに依存せず、データは完全に自己管理されます。

実装済み

• 収入/支出のクイック記帳。発生日のみを記録し、金額は整数の「分」で保存します。

• 完全にカスタマイズ可能なカテゴリ、無効化、移行、またはカテゴリの完全削除、月/年単位の請求書、検索フィルター、グローバルな30日間のゴミ箱、CSV/JSON エクスポート。

• 週、月、年のトレンド、カテゴリ別明細、カテゴリ構成、前の期間との同進捗比較。

• DeepSeek の消費概要、異常な増加、節約提案、カテゴリ構造、カスタム質問。プログラムが数値を担当し、モデルは説明のみを担当します。現在、外部モデルに帳簿のメモを送信することはありません。

• 標準の Streamable HTTP MCP。Web ページから「確認モード」と「直接接管モード」を切り替え可能。直接モードでは、帳簿、カテゴリ、借入、サブスクリプション、AI、バックアップ、タイムゾーンを管理でき、30日間の取り消し可能な操作記録を保持します。

• SQLite WAL＋synchronous=FULL、移行前のスナップショット、毎日の整合性/外部キーバックアップ、age 公開鍵暗号化、Google Drive へのアップロード。

• Cloudflare Access の二重保護、PWA インストール、Windows ログイン時の自動起動と失敗時の再起動ヘルパースクリプト。

• 4つのテーマ、4種類の内蔵ページ背景、および現在のデバイスにのみ保存される個人用背景画像。個人用画像はブラウザ内で圧縮されメタデータが除去され、内蔵背景に一時的に切り替えても削除されません。

• クエリ優先のインサイトホームページ：期間と収支タイプは URL に保存され、更新後やカテゴリ請求書から戻った後も元の表示位置が維持されます。

• モバイル端末では、コンパクトなサマリー、明細/構成の切り替え、下部固定ナビゲーション、請求書フィルタードロワーを採用。検索中は古いリストを保持し、コンテンツのちらつきを防ぎます。

• サイト全体の日付は設定の帳簿タイムゾーンに従います。コンピューターと Android のタイムゾーンが異なる場合でも、「今日」、デフォルトの月、AI 分析期間は一貫しています。

• 独立した「事項」モジュールで、他人からの借入金、分割返済、CNY/USD サブスクリプションを管理します。事項はデフォルトで消費統計に含まれません。積極的に関連付けるか同時に作成した通常の帳簿のみがグラフに影響します。

• 借入は、借入人の無効化、部分返済、自動精算、30日間のゴミ箱をサポート。サブスクリプションは、初回特典、月/年/カスタム期間、期限確認、支払い履歴、アプリ内リマインダーをサポートします。

• 毎月、人民元の総予算とカテゴリ予算を設定可能。予算は繰り越されず、記帳を妨げません。インサイトページには、使用済み、残り、予測、カテゴリリスクが表示されます。

• 「帳簿健康診断」は、決定的なルールで重複の疑い、高額支出、予算リスク、未確認の更新、関連異常を提示します。照合は自動的に帳簿を変更せず、AI はプログラムが発見した事実のみを説明します。

• Android/Windows インストール後のアプリメニューに「記帳」のクイックエントリを提供。OpenClaw は一度のアトミック書き込みで最大20件の帳簿を記録し、一括で取り消すことができます。

• 借入の記録には、検索可能な単一の借入人セレクターを使用。新しい借入人は借入と同一トランザクションで保存されます。同名のアクティブな記録は再利用され、無効化された記録は復元が必要です。

• OpenClaw の提案再試行では、未確認項目が重複作成されません。操作センターでは、必要に応じてフィールド変更と失敗ステータスを確認できます。帳簿健康診断は MCP の読み取り専用クエリでも実行でき、メモは返されません。

• オプションの「資金」モジュールは、人民元口座、残高の流れ、口座間送金、手数料、残高調整、全額返金を記録します。総資金には、未収の借入、投資、将来の収入は含まれません。

• 資金追跡を有効にする前の履歴帳簿は遡って追跡されません。有効化後の通常の収支は口座にバインドされ、残高は初期残高と追加型の資金フローから計算され、2番目の残高の真実は維持されません。

• OpenClaw は、口座、送金、調整、返金を正確にクエリおよび管理できます。すべての直接書き込みは引き続き冪等な requestId を使用し、曖昧な口座名は拒否されます。

「事項」の実際の操作、有効化前後の連動ルール、OpenClaw の権限については、借入とサブスクリプション利用ガイド を参照してください。口座の有効化、資金への影響、返金、健康診断のヒントについては、資金追跡の利用とメンテナンスガイド を参照してください。

Related MCP server: ExpenseTracker MCP Server

インサイトと請求書

• インサイトの「カテゴリ明細」は、カテゴリの順位、金額、前回からの変化を比較するために使用します。「カテゴリ構成」は、円グラフ、金額、割合を表示するために使用します。両方が同時に表示されることはありません。

• カテゴリ構成は、今期の金額があるすべてのカテゴリを完全に表示し、「その他」に統合しません。各セクターと凡例は、対応する請求書にドリルダウンできます。

• 請求書ページには4つの同等のエントリがあります：「最近の入力」「月次請求書」「年次請求書」「ゴミ箱」。ゴミ箱はすべての日付にわたって削除時刻順に並び、前回表示した月を引き継ぎません。

• 古い URL は引き続き互換性があります：/bills は最近の入力を開き、/bills?view=ledger&period=month&anchor=... は月次請求書を開きます。period を year に変更すると年次請求書が開きます。/bills?view=trash はグローバルなゴミ箱を開きます。

• 通常の削除は30日間保持され、復元が可能です。ゴミ箱内の帳簿は完全に削除できます。設定のカテゴリ管理では、影響範囲を表示して名前を確認した後、カテゴリとそのすべての帳簿を完全に削除できます。完全な削除は取り消せませんが、関連する借入やサブスクリプションの事項は保持され、帳簿との関連付けは自動的に解除されます。

ページ更新と個人背景

• ページが開いている間、30秒ごとに現在のページの帳簿データを同期します。ウィンドウに再フォーカスするか、ネットワークが回復したときにも即座に同期します。

• PWA は毎分新しいバージョンをチェックし、新しいバージョンが見つかると、編集中のフォームがない場合に自動的に更新します。「設定 → 実行状態」で「チェックして更新」をクリックすることもできます。

• Cloudflare のログインが期限切れになった場合は、ページの「再ログイン」を使用してください。サイトの Cookie を削除したり、サイトデータをクリアしたりしないでください。「再ログイン」と「チェックして更新」は PWA プログラムキャッシュのみを置き換え、ログイン Cookie、外観設定、IndexedDB 内の個人背景は保持します。サイトデータ全体をクリアした場合のみ、現在のデバイスの個人画像が削除されます。

• 「クリーン、ペーパー、テクスチャ、ミスト」を選択すると、個人画像は一時的に無効になりますが、画像は現在のデバイスに保持され、いつでも「画像を使用」をクリックして復元できます。

• 各ブラウザセッションの最初のコールドスタート時に、SMB ブランドのスプラッシュスクリーンが一度だけ短く表示されます。データの更新やページ切り替えでは再生されず、システムで「アニメーションを減らす」が有効な場合はスキップされます。

クイックスタートとローカル実行

Node.js 22 以降が必要です。

方法1：Windows ワンクリック起動（最も推奨）

プロジェクトルートディレクトリの 打开 SMB.cmd をダブルクリックするだけです。

• 初回実行時には、依存関係を自動的にチェックし、テンプレートから .env のデフォルト設定を自動生成し、コンパイルとパッケージングを完了します。

• その後、サービスが自動的に起動し、デフォルトブラウザで家計簿のホームページが開きます（デフォルトでは http://127.0.0.1:8788 にアクセス、ログイン不要のシングルモード）。

方法2：コマンドラインでの手動起動（クロスプラットフォーム：Windows / Linux / macOS）

プロジェクトルートディレクトリでターミナルを開きます：

# 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

品質チェック

npm test
npm run typecheck
npm run build

正式な更新前に、整合性チェック済みのスナップショットを追加で作成できます：

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

高度な機能とデプロイガイド

個人のコンピューターで単独で家計簿を使用する場合、外部サービスを設定する必要はなく、すぐに使用できます。

以下の高度な機能が必要な場合は、対応するガイドを参照して必要に応じて設定してください：

• スマートフォンでのクロスネットワークリモート記帳：Cloudflare Tunnel によるパブリック IP 不要のトンネリングと Access 認証を実現します。詳細は デプロイガイド を参照してください。

• AI スマート消費分析：ルートディレクトリの 配置DeepSeek密钥.cmd をダブルクリックするか、.env に DeepSeek API キーを入力すると、消費インサイトと節約提案が有効になります。

• リモートでの暗号化自動クラウドバックアップ：Google Drive と age 暗号化キーを設定し、毎日の自動スナップショットアップロードを実現します。詳細は 復元ガイド を参照してください。

• 資金と口座管理：複数口座の資産フロー、送金、残高調整については、資金追跡ガイド を参照してください。

• 借入とサブスクリプション管理：外部の借入金、分割返済、定期的なサブスクリプションの引き落としについては、事項利用ガイド を参照してください。

ディレクトリ

• src/：スマートフォンとコンピューターで共有される React PWA。

• server/：Node API、MCP、DeepSeek、資金、財務事項、バックアップサービス。

• db/：SQLite のテーブル構造とマイグレーション。

• tests/：金額、日付、事項、UI、AI、MCP のテスト。

• scripts/：初期化、自動起動、バックアップキー、復元スクリプト。

• deploy/：Cloudflare と OpenClaw のキーレス設定テンプレート。

プライベートファイル .env、本番データベース、バックアップ、ログ、ビルド成果物はバージョン管理から除外されています。

バージョン番号は package.json でのみ管理されます。修正と視覚的な微調整はパッチバージョンを増やし、後方互換性のある新機能はマイナーバージョンを増やし、製品のアイデンティティや互換性のない契約の変更はメジャーバージョンを増やします。リリース記録は CHANGELOG.md を参照してください。ロゴの仕様と編集可能なソースは ブランドガイド を参照してください。

明確に延期された請求書のインポート、サードパーティの残高同期、より複雑な口座機能については、ROADMAP.md を参照してください。