3447nazmul/smb-bookkeeper-repo

SMB 請求書 + 簿記

1つの散らかったメッセージ → 請求書、経費ログ、次の督促状の下書き。 アカウント不要、サブスクリプション不要、ロックインなし — あなたのお金は、あなたが所有するファイルの中にあります。

小規模事業者は仕事で失敗するのではありません。待つことで失敗するのです。 北米のB2B請求書の約55％が期日後に支払われ（Atradius、Crestmont Capital経由、2026年更新）、米国の小規模事業者は2026年第2四半期に平均29.3日間支払いを待ち、期日から約9日超過しており（Xero Small Business Insights、Foundrly経由、2026年8月）、小規模事業者の倒産の82％はキャッシュフローの問題に起因します（米国商工会議所、Crestmont経由、2026年）。回収の確率は時間の経過とともに急速に低下します — 最初の30日間で積極的なフォローアップにより95％以上、120日を超えると20〜30％に低下します（Crestmont、2026年）。請求書作成は簡単な部分です。追跡こそが製品です — そして他のどこでも、追跡には料金がかかります。自動リマインダーはWave（月額19ドル）やInvoice Ninja（月額14ドル）ではPro専用です（ベンダーの価格ページ、2026年11月）。Waveは米国/カナダ国外への請求書送付ができず（Waveサポート、2026年9月8日）、Zoho Invoiceの無料枠は年間500件の請求書に制限され、180日間アイドル状態のデータは削除されます（zoho.com/invoice/pricing、2026年11月11日閲覧）。このスキルは、追跡を無料で下書きします。

バージョン 0.2.0。 v0.1.0のアドバーサリアルレビュー（20のギャップ、すべて修正またはMEASUREMENTS.md §11に記録済み）とディープリサーチによる修正（research-notes-v2.md §1）に基づき再構築されました。変更点はCHANGELOG.mdにあります。以下の数値は、バンドルされたサンプルデータでの実際の実行結果であり、見積もりではありません。

法律上、税務上、または財務上のアドバイスではありません。 このスキルは、請求書の作成と資金の追跡を支援します。税率、登録しきい値、請求書の要件は国によって異なり、時間の経過とともに変化します。ご自身で税率を設定し、お住まいの地域の管轄税務当局（バングラデシュの場合は歳入庁、nbr.gov.bd）または資格のある会計士に事業のルールを確認してください。この免責事項は、生成されるすべての請求書と領収書のフッターにも印刷されます — ベンガル語の文書ではベンガル語で表示されます。その背後にある記録保存ルール（何を保存するか、請求書のTIN/BIN、Mushakフォーム、保存期間）については、OpenAccountantsのbd-bookkeepingスキル（openaccountants/openaccountants、484★、2026年11月11日更新）を参照してください — 英語のリファレンスガイドであり、「特定の個人の事実についてレビューされたものではない…一般的な参考のみ」と明記されています。請求書は生成しません。このスキルは生成します。

実行方法

python3 scripts/bookkeeper.py <command>

Python 3.9以上、標準ライブラリのみ。インストール手順不要、依存関係なし、ネットワーク呼び出しなし、APIキー不要、アカウント不要。データは、開いて、コピーして、どこへでも持ち運べるプレーンなJSONファイルに保存されます。

金額ルール — 数値を信頼する前にお読みください

これらは、合計金額を信頼できるものにするルールであり、v0.1.0のレビューでこのスキルが破っていたと指摘されたルールです。

• 金額は四捨五入します（ROUND_HALF_UP）、ちょうど店主が電卓で丸めるように — 銀行家丸めはしません。2.345タカは2.35タカになります。
• 数量は正確で、金額として丸めることはありません。 数量1.005は1.005のままです。明細合計のみが丸められます。数量は末尾のゼロなしで表示されます（3、決して3.00ではありません）。
• 税金は明細ごとに、割引後の明細金額に基づいて計算されます — 各明細の税金はその明細で四捨五入され、その後合計されます（Wave / Xero / FreshBooksの方法と同じ）。3行がそれぞれ0.35タカ、税率15％の場合、税金は0.15タカ（0.16タカではない）になります。
• 支払済みかどうかは、ステータス文字列ではなく、残高から判断されます。 「支払済み」とマークされた請求書にまだ4,000タカの未払いがある場合、4,000タカの未払いが報告され、レポートはステータスが間違っていると指摘します。ステータスはヒントです。期日超過状態は、期日と残高から導き出されます。
• 異なる通貨間で金額が合計されることはありません。 通貨混在の台帳は、通貨ごとの合計（5,000タカ + 100ドル）を報告し、マージされた合計とマージされた純額を拒否します — このスキルには為替レートがなく、その旨が明記されます。
• 台帳の問題は大きなエラーとなり、終了コード2で終了します。 overdue と cashflow は、行がスキップされた場合（データ無効）、番号が重複した場合、「支払済み」の請求書にまだ残高がある場合、支払いが過払いの場合、または支払いに paid_date がない場合に終了コード2で終了します。レポートは still 印刷されます。終了コードは、台帳を信頼する前に修正する必要があることを示します。
• 負の金額はマイナス記号を最初に表示します: −4,100タカ — どこでも同じ規則です。

ワークフロー: 1つの入力 → 請求書 → 領収書 → リマインダー → キャッシュフロー

1. 1つのJSON入力からの請求書、見積書、または領収書

python3 scripts/bookkeeper.py invoice --input samples/invoice-input.json --out out/invoice.html --config config/bd.json
python3 scripts/bookkeeper.py invoice --input samples/invoice-input-bn.json --out out/invoice-bn.html --config config/bd.json --lang bn
python3 scripts/bookkeeper.py invoice --input my-quote.json --out out/quote.html --format md
python3 scripts/bookkeeper.py receipt --input samples/invoice-input.json --out out/receipt.html --paid-date 2026-11-05 --amount-paid 4500

• 入力は1つの小さなJSONファイルです: 事業者 + 顧客 + 明細項目（説明、数量、単価）+ 請求書番号 + 発行日 + 期日。正確な形式は samples/invoice-input.json を参照してください。
• 見積書 → 請求書 → 領収書は1つのライフサイクル、1つのデータモデルです。 type: "quote" は期日の代わりに valid_until が必要です。請求書には「Net 30」だけでなく実際のカレンダー上の期日が必要です。領収書は --paid-date と --amount-paid を使用して支払済みの請求書から生成され、支払いが一部であった場合、残りの বাকি（残高） を表示します。金額が0の領収書は拒否されます — 領収書は受け取った金額を確認します。見積書には支払済み/残高の行は表示されません（提案に対しては何も支払われていません）。HTMLとMarkdownの両方で、番号は「請求書番号」ではなく「見積書番号」とラベル付けされます。
• 請求書には、すべての請求書に必要なフィールドが含まれます（調査ノート §3.1）：「請求書」という文言、一意の連番、発行日、期日、売り手の詳細、買い手の詳細、具体的な説明、明細項目、税（独立した行として）、支払い指示 + 支払総額。見積書番号が存在する場合は請求書に参照として記載されます。顧客の注文番号と売り手の**税金登録番号（tax_id — バングラデシュの場合は13桁のBIN）**は、指定された場合に請求書に印刷されます。
• 番号は連続しています（INV-2026-001、INV-2026-002、...）。番号をスキップしたり再利用したりしないでください — 欠番や重複は、確定申告時に収入の欠落や架空の経費のように見えます。台帳コマンドは、重複番号に対して警告を表示し、終了コード2で終了します。設定の numbering_prefix は請求書番号に対してチェックされます（警告でありエラーではありません）。default_terms は、入力に期間の記載がない場合に「支払条件」行を埋めます。
• 出力は、きれいで印刷可能なHTML（ブラウザで開き、PDFに印刷）またはMarkdown（--format md）です。HTMLには外部リソースが含まれていないため、表示されたとおりに正確に印刷されます。出荷されたサンプルは、ヘッドレスChromiumでレンダリングされ、PDFに一度印刷されました（MEASUREMENTS.md §11.6、スクリーンショットは docs/ を参照）。
• 金額は Decimal で計算され、floatは使用されません。割引は小計のパーセンテージで、明細ごとに適用されます。税金は割引後の金額に対して明細ごとに計算されます（「金額ルール」を参照）。
• 検証は厳格で、不正な入力があると終了コード2で終了します：期日がない、数量または価格が負、税率が0〜100％の範囲外、不正な日付、不正なJSON、ファイルがない、発行日より前の期日、発行日より前の支払日。項目がゼロの請求書は許可されます（合計0タカ）が、警告が印刷されます — これは下書きであり、隠すべき間違いではありません。文書の過払いは、文書コマンドの両方で警告を表示します（領収書に「残高: -825タカ」と表示されるべきではありません）。

2. 税金 — 入力する設定値であり、ハードコードされた税率ではありません

# 請求書入力（税率が存在する唯一の場所）:
"tax": {"name": "VAT", "rate_percent": 15}

• どのツールも税率をハードコードしていません。このスキルも同様です。 すべての請求書作成ツール（Zoho、FreshBooks、Wave、Xero — 調査ノート §5.1）は、ユーザーが名前付きの税金とパーセンテージを定義できるようにし、それを明細ごとに適用し、独立した行として表示します。このスキルはそれを正確にコピーしています：税金は、入力内の名前付きの税金 + 率％であり、デフォルトは0％ / 税なしです。
• config/ 内の国別プリセットは、税金のラベル、通貨、支払い方法、デフォルトの支払条件、番号プレフィックスを提供します — 税率は決して提供しません。config/bd.json（バングラデシュ: タカ、「VAT」、bKash / Nagad / Rocket / 銀行振込 / 現金）および config/us.json（米国: ドル、「Sales tax」、Net 30）。両方の設定ファイルの tax_rate_percent は意図的に null になっています。設定内の tax_id（あなたのBIN）は、入力にない場合に請求書を埋めます。
• サンプル請求書では15％のVATが使用されています。これはサンプル入力がそう指定しているからです — バングラデシュの標準VAT率は、2012年VAT及び付加義務税法（ArthiKalap、2026年7月25日更新；TRW、2026-27年度；TaxDo、2026年；SDTT Academy、2026年初頭）に基づき15％ですが、スキルはこれを認識しておらず、認識していると引用されてはなりません。VAT申告は再び月次になりました（15日以内に提出）：2026年財政法により2026年7月1日から四半期ごとになりましたが、2026年10月14日に官報公示された改正条例により月次申告が復活しました（TRW「Doing Business in Bangladesh 2026」、2026年10月24日時点の法律；entrepreneurs.bd、2026年）。古いノートにある「四半期ごと」の記述は現在は誤りです。
• 登録しきい値はこのスキルにハードコードされていません。 2026年10月から11月の3つの独立したガイドは現在、同じ数値に収束しています — 強制登録は年間売上高50ラークタカ以上、30〜50ラークタカの範囲は4％の売上税で登録、一部の活動は売上高に関係なく登録が必要です（TRW「VAT in Bangladesh 2026」、2026年10月18日時点；TRW「VAT Registration」；entrepreneurs.bd、2026年；Aniday、2026年9月確認）。しかし、NBR（歳入庁）に対する直接の確認は達成されていません：NBRのホームページ（2026年11月11日読み込み）にはしきい値のテキストはなく、vat.gov.bdはその日アクセスできませんでした。したがって、これらの数値はここでは収束する二次情報源であり、NBRが確認した事実ではないとして報告されています — スキルはしきい値を独自のものとして提示することは決してなく、ユーザーを nbr.gov.bd に誘導します。BINは13桁です（NBRホームページサービスリスト、2026年11月11日 — ラベルであり、官報ではありません。しきい値を確認する際に、NBR VAT登録ガイドで桁数を確認してください）。
• 税込み価格もサポートされています: "tax": {"name": "VAT", "rate_percent": 15, "inclusive": true} は、総額から税金を抽出します（VAT = 総額 × 15 ÷ 115）。MEASUREMENTS.md §5で計測済み: 総額1,150タカ → VAT 150タカ、合計は1,150タカのままです。

3. 経費ログ — プレーンな言語、プレーンなファイル

python3 scripts/bookkeeper.py expense add --ledger expenses.json --date 2026-11-11 --category Materials --amount 1200 --note "copper wire, 20 m"
python3 scripts/bookkeeper.py expense list --ledger expenses.json --month 2026-11
python3 scripts/bookkeeper.py expense export --ledger expenses.json --out expenses.csv

• 1つの経費 = 日付、カテゴリ、金額、メモ。台帳はJSONリストです。export は、任意のスプレッドシートで開くことができるCSVを書き出します。
• カテゴリはプレーンな言語であり、勘定科目コードではありません：Materials（材料）、Transport（運送）、Tools（工具）、Mobile/internet（モバイル/インターネット）、Meals（食事）、Rent（家賃）、Labour（人件費）、Packaging（梱包）、Other（その他）。未知のカテゴリはエラーとなり、黙って受け入れられることはありません。負の金額は拒否されます。--month は実際の YYYY-MM でなければなりません（2026-1 は拒否されます — 生のプレフィックス一致は、10月と11月を黙ってマージする可能性があります）。
• オブジェクトではない台帳行は、警告とともにスキップされ、終了コード2で終了します — トレースバックは表示されず、黙ってスキップされることもありません。expense add は、壊れた行を含む台帳の書き換えを拒否します（まず修正してください）。

4. 期日超過トラッカー + 督促状の下書き — スキルの中心

python3 scripts/bookkeeper.py overdue --invoices samples/invoices.json --as-of 2026-11-11
python3 scripts/bookkeeper.py overdue --invoices samples/invoices.json --as-of 2026-11-11 --lang bn --json

• 請求書台帳をスキャンし、期日経過期間（現在 / 1〜30日 / 31〜60日 / 61〜90日 / 90日以上）ごとにすべての未払い請求書を一覧表示し、それぞれに対して適切な段階の次の督促状を下書きします。
• 6段階シーケンス（Raoura、2026年7月確認；InvoiceCub、2026年10月31日；InvoiceFly、〜2026年11月；HeroThemes、〜2026年8月；FreelanceDesk、〜2026年6月にわたる5タッチコンセンサス — 期日前、期日、7日、14日、30日 — さらに、7タッチバージョンからの期日超過1〜6日間の早期フレンドリーナッジを追加。7タッチバージョンの追加の21日タッチは独立した段階ではなく、14日ドラフトの次のタッチ（30日）でカバーされます）：期日の3日前、期日当日、期日超過7日目、期日超過14日目、期日超過30日目の最終通知、さらに期日超過1〜6日間のナッジ。段階的なエスカレーションであり、決して最初から非難しません：初期段階では善意を想定します（忘れた / 埋もれた / 承認待ち）。約款で延滞料が規定されており、請求書が約2週間超過している場合にのみ延滞料に言及します。すべての下書きは、請求書番号、金額、元の期日、および実際の延滞日数（8日間延滞の請求書には「8日間延滞」と表示され、段階番号は表示されません）を再記載します。
• 下書きのみ — スキルは決して送信しません。 ユーザーがリマインダーを送信します。レポートは次のタッチ日も印刷するため、エスカレーションを覚えておく必要はありません。すでに過ぎた次のタッチ日は、「今すぐ送信（期日は…でした）」と印刷され、単なる過去の日付として表示されることはありません。最終通知は、最短で今日から7日後の期限を設定します（max(due + 37日, as-of + 7日)）— すでに期限切れの支払督促は、督促がないよりも悪いです。
• サンプルで測定済み（2026年11月11日現在）：6件の未払い請求書、48,650タカの未収金（বাকি）、4件が期日超過で合計28,250タカ — ナッジから最終通知まで各段階に1件ずつ。MEASUREMENTS.md §3を参照。
• 下書きの請求書は「未収金」から除外されます — 未送信の請求書はまだ未収金ではありません。支払済みの請求書（残高0）も除外されます。（期日超過請求書の100％をフォローアップする企業は、1週間以内に支払われる可能性が76％高い — Chaser 2026 AR Report、Raoura経由、間接情報。）

5. シンプルなキャッシュフロー表示 — 経営者が実際に確認する数字

python3 scripts/bookkeeper.py cashflow --invoices samples/invoices.json --ledger samples/expenses.json --as-of 2026-11-11

• 1つの画面に、当月の「入金（回収済み）」と「出金（経費）」、そして「未収金（遅延）」を表示します。その他の形式はありません。新しい情報はありません。--month で過去の月を表示できます。
• 当月（または指定された月）に入金が予定されている請求書は「入金」にカウントされます。期日を過ぎても支払われていない請求書は「未収金」にカウントされます。同じ月に支払われた期日超過の請求書は、最初に「入金」にカウントされ、次に「未収金の解決」として表示されます。経費は支払日からカウントされます。
• 月が指定されていない場合、デフォルトは --as-of の月です。--month は YYYY-MM 形式でなければなりません。無効な月はエラーになります。
• 測定済み（サンプル、2026年11月）：入金 45,000タカ、経費 19,230タカ、キャッシュフロー 25,770タカ、未収金 48,650タカ（内 28,250タカが期日超過）。MEASUREMENTS.md §4を参照。

設定リファレンス

すべての設定ファイルは config/ にあります（例：config/bd.json、config/us.json）。ユーザーはこれらをコピーして編集します。以下はその内容です（tax_rate_percent は null であることに注意）：

• currency_symbol（例："৳"、"$"）
• currency_code（例："BDT"、"USD"）
• locale（例："bn_BD"、"en_US"）
• tax_label（例："VAT"、"Sales tax"）
• tax_rate_percent：常に null — 入力ファイルで設定します。
• tax_id：あなたの税金登録番号（例：バングラデシュのBIN）。入力にない場合に請求書に記載されます。
• numbering_prefix（例："INV-2026-"）
• default_terms（例："Net 30"）
• payment_methods：支払い方法のリスト（例：["bKash", "Nagad", "Rocket", "Bank Transfer", "Cash"]）
• business_details：あなたの事業の詳細（名前、住所、電話、メール）

開発者向け情報

# テストの実行
python3 -m unittest discover -s tests

# カバレッジ（インストールされている場合）
coverage run -m unittest discover -s tests && coverage report -m

Python 3.9以降が必要です。サードパーティの依存関係はありません。

アーキテクチャ

• scripts/bookkeeper.py：メインのCLIエントリポイント
• lib/：コアロジック（金額、台帳、テンプレート）
• config/：国別設定（JSON）
• samples/：サンプル入力ファイル
• tests/：単体テスト
• docs/：ドキュメントとスクリーンショット
• MEASUREMENTS.md：パフォーマンスと正確性の測定
• CHANGELOG.md：変更履歴

貢献

バグレポート、機能リクエスト、プルリクエストを歓迎します。行動規範を尊重し、MEASUREMENTS.md に記載されたベンチマークを壊さないでください。

ロードマップ（v0.3.0以降）

• 複数通貨のサポート（現在は拒否されます）
• バングラデシュのMushakフォームのエクスポート
• 支払いリマインダーのメールテンプレート
• より多くの国別設定
• Web UI（任意）

ライセンス

MIT — あなたのデータ、あなたのお金、あなたのビジネス。