3447nazmul/smb-bookkeeper-repo

中小企業發票與記帳

一條雜亂訊息 → 發票、支出紀錄與下一封催款草稿。 無需帳戶、無需訂閱、無鎖定——你的錢，存在你擁有的檔案裡。

小型企業失敗的原因不在工作本身，而在等待： 北美約 55% 的 B2B 發票被逾期支付（Atradius，經由 Crestmont Capital，2026 年更新），美國小型企業在 2026 年第二季平均等待 29.3 天才收到付款，約超出到期日 9 天（Xero 小型企業洞察，經由 Foundrly，2026 年 8 月），而 82% 的小型企業倒閉可歸因於現金流問題（美國商會，經由 Crestmont，2026 年）。收款成功率隨著時間快速下降——在逾期 30 天內主動跟進，超過 95% 的成功率，超過 120 天則降至 20–30%（Crestmont，2026 年）。開立發票是簡單的部分。催款才是真正的產品——而在其他地方，催款功能都被付費牆擋住了：Wave 的自動提醒是 Pro 版功能（每月 $19）、Invoice Ninja 也是 Pro 版（每月 $14）（廠商定價頁面，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 結束。 當某一行被跳過（無效資料）、數字重複、「已付」發票仍有餘額、付款超額、或付款沒有 paid_date 時，overdue 和 cashflow 命令會以退出碼 2 結束。報告仍然會列印；退出碼表示在信任之前需先修正帳簿。
• 負數金額先顯示減號：−৳4,100——統一格式，到處一致。

工作流程：一個輸入 → 發票 → 收據 → 提醒 → 現金流

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

• 輸入是一個小型的 JSON 檔案：商家 + 客戶 + 明細項目（描述、數量、單價）+ 發票號碼 + 開立日期 + 到期日。請參閱 samples/invoice-input.json 了解確切格式。
• 報價單 → 發票 → 收據是同一個生命週期，同一個資料模型。 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 計算，絕不使用浮點數。折扣是基於小計的百分比，按行套用；稅金按行計算於折扣後金額（請參閱「金錢規則」）。
• 驗證嚴格，輸入錯誤時以退出碼 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，因為範例輸入中這樣指定——根據《增值稅與附加稅法 2012》（ArthiKalap，2026 年 7 月 25 日更新；TRW，2026-27 財政年度；TaxDo，2026 年；SDTT Academy，2026 年初），孟加拉的標準 VAT 稅率為 15%——但此技能不知道這一點，也絕對不能被引用為知道這一點。VAT 申報現在是每月一次（應在 15 天內申報）：2026 年財政法案原定從 2026 年 7 月 1 日起改為每季申報，但 2026 年 10 月 14 日 公告的修正命令恢復了每月申報（TRW「在孟加拉經商 2026」，截至 2026 年 10 月 24 日的法律；entrepreneurs.bd，2026 年）。舊筆記中的任何「每季」陳述現在都是錯誤的。
• 此技能中未硬編碼註冊門檻。 三份獨立於 2026 年 10 月至 11 月的指南現在匯聚到相同的數字——年營業額超過 Tk 50 萬 需強制註冊；年營業額 Tk 30–50 萬 可註冊，適用 4% 營業稅；某些活動無論營業額多少都必須註冊（TRW「孟加拉 VAT 2026」，2026 年 10 月 18 日立場；TRW「VAT 註冊」；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 "銅線，20 米"
python3 scripts/bookkeeper.py expense list --ledger expenses.json --month 2026-11
python3 scripts/bookkeeper.py expense export --ledger expenses.json --out expenses.csv

• 一筆支出 = 日期、類別、金額、備註。帳簿是 JSON 列表；export 寫出一個可在任何試算表中開啟的 CSV。
• 類別是簡單語言，非會計科目表：材料、運輸、工具、手機/網路、餐飲、租金、勞務、包裝、其他。未知類別會報錯，絕不會被默默接受。負數金額會被拒絕。--month 必須是真實的 YYYY-MM（2026-1 會被拒絕——原始前綴比對會默默合併十月和十一月）。
• 不是物件的帳簿行會大聲跳過並顯示警告，以退出碼 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 的 5 次接觸共識，2026 年 7 月驗證；InvoiceCub，2026 年 10 月 31 日；InvoiceFly，~2026 年 11 月；HeroThemes，~2026 年 8 月；FreelanceDesk，~2026 年 6 月——到期前、到期日、逾期 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——從提醒到最終通知各階段各有一張。請參閱 MEASUREMENTS.md §3。
• 草稿發票被排除在「欠您的款項」之外——未寄出的發票還不是應收款項。已付發票（餘額 0）也被排除。（對 100% 逾期發票進行跟進的企業，在一週內收到付款的可能性高出 76%——Chaser 2026 AR 報告，經由 Raoura，間接引用。）

5. 簡單的現金流檢視——業主真正檢查的數字

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

• 顯示此月至今的收入（已開立發票）、此月至今的支出、以及截至 --as-of 日期的應收款項（逾期 + 未到期）。全部按貨幣區分。
• 應收款項是基於負債的——您尚未收到錢的開立發票。已付發票不計入。（團隊已通過 MEASUREMENTS.md §4 中的樣本驗證了此數字：৳48,650 欠款，৳28,250 逾期，৳20,400 未到期。）
• 非預測性——它告訴您現在站在哪裡。 一些小型企業業主告訴我們，他們需要的是這個數字，而不是名為「現金流量表」的會計報表。它不預測未來現金流，也不包含銀行餘額。

6. 格式支援

格式	命令	輸出
HTML	invoice, receipt	可在瀏覽器中列印的 HTML 文件
Markdown	invoice, receipt（--format md）	可在終端機或編輯器中閱讀的 Markdown
JSON	overdue, cashflow（--json）	結構化資料，適用於自動化流程

設定檔

設定檔位於 config/ 目錄中。每個檔案定義：

• currency：貨幣符號（如 "৳"、"$"）
• currency_code：貨幣代碼（如 "BDT"、"USD"）
• locale：地區設定（如 "bn_BD"、"en_US"）
• tax_label：稅種的預設標籤（如 "VAT"、"Sales tax"）
• tax_rate_percent：設定為 null——您必須在輸入中指定
• default_terms：條款字串（如 "Net 30"）
• numbering_prefix：發票編號前綴（如 "INV-"）
• payment_methods：付款方式列表
• tax_id：您的稅籍編號（在孟加拉，BIN），用於填入發票
• language：設定為 "en" 或 "bn"

相關技能

• OpenAccountants/bd-bookkeeping（openaccountants/openaccountants，484★，2026-11-11 更新）：一份英文參考指南，涵蓋孟加拉 VAT 的記錄保存規則、Mushak 表格和 TIN/BIN 要求。明確標示為「僅供一般參考」。它不產生發票。此技能產生發票。