jasveerai88/gst-hst追蹤器

gst-hst追蹤器 — 代理技能

目的

加拿大自由工作者和獨資經營者常在試算表中追蹤GST/HST，並在超過CRA的$30,000小型供應商門檻後才發現。此工具讀取一份附日期的交易帳本，並產生：(a) 每季的GST/HST收款、ITC及淨應繳稅額，附帶T2125風格的收入/費用預覽區塊；(b) 門檻測試：計算最近4個日曆季的應稅收入總額，與$30,000限制比較，顯示剩餘空間或已超過的警報；(c) 按省份檢視相同帳本：各省的稅務系統類型、收款、ITC及淨稅額，僅在數據支援的範圍內顯示省級組成部分（記錄的QST作為備忘數字，加上對未記錄的QC銷售的估算；PST/RST以稅率×銷售額的暴露估算呈現）。 純Python標準庫；僅本地執行；讀取一個帳本檔案，不寫入任何內容。

此工具的核心誠信原則： 它是一個追蹤與計算輔助工具，非稅務建議，也非CRA申報。每份報告都帶有該免責聲明，您根據其輸出撰寫的任何內容也必須附加此聲明。它從不計算罰款或利息。

使用時機 / 不使用時機

在以下情況使用：

• 根據交易帳本準備某季度的GST/HST數字：收款、ITC、淨應繳稅額。
• 檢查自由工作者距離$30,000登記門檻還有多遠，或是否已超過。
• 整理收入和費用類別，為報稅季準備T2125風格的預覽檢視。
• 代理需要可信任的加拿大GST/HST數字（JSON格式）。

在以下情況不要使用：

• 使用者需要稅務建議、申報或關於其義務的裁決—此工具無法提供。請引導他們諮詢CRA或合格的會計師。
• 問題涉及罰款或利息—從不計算。
• 帳本是魁北克QST帳本：QST在此僅為備忘（請參閱限制）。BC PST / SK PST / MB RST僅在provinces檢視中作為暴露估算出現—從不作為應繳稅款或抵減。
• 帳本過時：門檻視窗錨定於最新交易，因此過時的帳本會給出過時的視窗。若日期看起來陳舊，請說明。

安裝

pipx install git+https://github.com/jasveerai88/gst-hst-tracker
# 或：pip install git+https://github.com/jasveerai88/gst-hst-tracker

（不在PyPI上—git+格式即安裝方式。）從原始碼目錄執行python3 src/gst_hst_tracker.py ...效果相同。

命令

# 季度報告（JSON或CSV輸入；成功時退出碼0）
gst-hst-tracker report LEDGER.json
gst-hst-tracker report LEDGER.csv --json

# 僅單一日曆季或一年
gst-hst-tracker report LEDGER.json --period 2026-Q1
gst-hst-tracker report LEDGER.json --period 2026

# 小型供應商警報（已超過時退出碼1，否則為0）
gst-hst-tracker threshold LEDGER.json [--limit 30000]

# 省份檢視（成功時退出碼0）
gst-hst-tracker provinces LEDGER.json
gst-hst-tracker provinces LEDGER.json --period 2026-Q1 --json

# 同時顯示等值印度盧比（INR）（匯率為1 CAD兌換）
gst-hst-tracker report LEDGER.json --cad-to-inr 67.97

# 覆蓋某個省的稅率（例如稅率變更時）
gst-hst-tracker report LEDGER.json --rate NS=15

輸入行（JSON列表、{"transactions": [...]}物件，或帶相同欄位的CSV）：date（YYYY-MM-DD，必填）、kind（income|expense，必填）、description（必填）、amount（稅前CAD，必填，≥ 0）、province（兩字母代碼，必填）；可選tax（已收取/支付的GST/HST—省略則從省份稅率計算；0表示零稅率並被尊重）、qst（僅QC行；單獨追蹤，從不納入淨額）、category（僅費用；T2125風格分組）。

模型（報告結果時請說明）

• 每季的淨應繳稅額 = 收入上收取的GST/HST − ITC（費用上支付的GST/HST）。負淨額 = ITC超過收款：屬於退稅狀況，非手頭現金。
• 門檻：截至最新交易所在季度的最近4個日曆季的應稅供應（僅收入行）。CRA的測試是超過$30,000—正好$30,000仍為小型供應商（status: "at"，退出碼0）。
• 截至2026年11月的預設稅率：GST 5%（AB BC MB NT NU SK YT），HST 13%（ON），HST 15%（NB/NL/PE），HST 14%（NS）（自2025年4月1日起從15%調降），QC = 僅聯邦部分的GST 5%。
• QST（9.975%）是魁北克省獨立的稅項：提供的qst金額僅作為備忘總額出現，從不進入淨額。
• 省份檢視（provinces）：相同的聯邦計算，按行的省份分組。編碼的省級稅率，標示「編碼稅率，檢查日期2026-11—申報前請與CRA/省級來源核實」：QST 9.975%（QC），PST 7%（BC），PST 6%（SK），RST 7%（MB）；HST省份沒有單獨的省級組成部分。QC顯示記錄的QST總額，加上對未記錄qst的QC收入行的估算；BC/SK/MB僅顯示稅率×銷售額的暴露估算，且無省級ITC（進項PST/RST通常視為成本）。捨入：各省數字四捨五入到分，總計是這些捨入數字的和，因此始終與各省區塊一致。

輸出JSON架構（--json）

report：tool（"gst-hst-tracker"）、version、command（"report"）、file、currency（"CAD"）、rates（各省rate_pct + 標籤，標示as_of: "2026-11"，加上QST備註）、cad_to_inr（匯率或null）、period_filter（字串或null）、periods、totals、disclaimer。

每個期間：period（例如"2026-Q1"）、quarter（[2026, 1]）、income_total、expense_total、gst_hst_collected、itcs、net_tax_owing、qst_collected、qst_paid、transactions、t2125（gross_business_income、expenses_by_category、total_expenses）。totals對所顯示期間的相同欄位進行加總。搭配--cad-to-inr時，金錢欄位會增加*_inr同級欄位。

threshold：通用欄位加上latest_transaction、window_end_quarter、quarters（四個{quarter, income}條目，最舊者優先）、rolling_total、limit、headroom（已超過時為0）、over_by（未超過時為0）、crossed（布林值）、status（"under" | "at" | "crossed"）、rule、disclaimer。

provinces：通用欄位加上provincial_rates（stamp、qst_rate_pct、taxes—各省federal標籤和provincial_tax {name, rate_pct}或null）、rounding_rule、provinces、totals、disclaimer。provinces中的每個條目：province、tax_system（根據有效稅率建構，例如"GST 5% + PST 7%"）、income_total、expense_total、gst_hst_collected、itcs、net_tax_owing、transactions、以及provincial—對於純GST和HST省份為null；否則為{name, rate_pct, recorded_collected, recorded_paid, recorded_net}（QC為數字，BC/SK/MB為null—這些省份無記錄）、estimate_base、estimated_on_sales、note。totals增加qst_recorded_collected / qst_recorded_paid / qst_recorded_net以及provincial_estimated_on_sales。

出錯時，stdout輸出為單一物件：{"error": "<訊息>"}（驗證錯誤會標明行號："row 2: ..."）且退出碼為2—包括--json模式下的argparse使用錯誤。絕不輸出純文字，絕不輸出回溯。

退出碼

• report：0—報告已計算。2—錯誤。
• provinces：0—檢視已計算。2—錯誤。（無退出碼1狀態：檢視僅供參考；警報在threshold中。）
• threshold：0—滾動總額低於或正好等於限制：根據這些數字，仍為小型供應商。1—門檻已超過：滾動總額超過限制，需要註冊GST/HST。這是發現結果，非失敗：應顯著呈現。2—錯誤：未產生任何數字；請勿引用任何數字。
• 任一命令中的錯誤均退出碼2並附帶簡潔訊息（或在--json模式中輸出{"error": ...}物件）。

代理必須遵守的限制與誠信規則

• 非稅務建議，非申報。 絕不將此工具的輸出呈現為建議或已申報的報稅表。每個輸出中的免責聲明是關鍵性的：在您撰寫的任何摘要中都必須保留。
• 稅率是截至2026年11月的預設值，非即時事實。 請引用為「工具的2026年11月預設值」，並說明它們是可以覆蓋的。新斯科舍省為14%（直到2025年3月31日為15%）—如果用戶的數字是基於NS省15%計算的，這值得標註，而不是默默接受。
• 正好$30,000不算超過。 CRA的測試是「超過$30,000」。如果status為"at"，請報告「仍為小型供應商，零剩餘空間」—絕不要說「必須註冊」。
• threshold的退出碼1是工具正常運作。 這表示警報觸發。請報告滾動總額、超出金額，以及需要立即註冊—不要埋沒在細節中。
• QST絕不納入淨額。 如果您要總結QC行，請將QST作為單獨的備忘數字。不要將已收QST加入net_tax_owing，也不要將已付QST視為ITC。
• 省級估算僅為估算。 provinces檢視中的PST/RST數字以及對未記錄的魁北克銷售的QST數字，是基於編碼表格的稅率×銷售額估算—絕不要將它們呈現為已收取、應繳或已申報的金額，並且在引用稅率時始終附帶編碼稅率戳記（「檢查日期2026-11—申報前請與CRA/省級來源核實」）。在此工具中，進項支付的PST/RST絕非ITC。
• 負淨額是退稅狀況，非收入。 請勿將其描述為已收到的款項。
• 罰款和利息從不計算—如果用戶在較早的期間已超過門檻，那是與CRA/會計師的對話；請勿估算金額。
• 僅限本地：工具讀取您指定的檔案，不向任何地方發送任何內容。