jasveerai88/gst-hst-tracker

gst-hst-tracker — 代理技能

目的

加拿大自由职业者和个体经营者在电子表格中追踪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 − 费用支付的GST/HST（ITC）。负净额 = 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%）——如果用户的数据按新斯科舍省15%计算，值得指出，而非默默接受。
• 恰好$30,000未超过。 CRA的测试是“超过$30,000”。如果 status 为 "at"，则报告“仍为小供应商，零剩余空间”——绝不说“必须注册”。
• threshold 的退出码1表示工具正常工作。 这意味着告警已触发。报告滚动总额、超出金额以及需要注册——及时而非隐藏。
• QST从不进入净额。 如果您汇总魁北克行，请将QST保持为单独的备忘数字。不要将QST收取额添加到 net_tax_owing 中，也不要将QST支付额视为ITC。
• 省级估算是估算值。 provinces 视图中的PST/RST数字以及对未记录魁北克销售额的QST数字是来自编码表的税率×销售额估算值——切勿将其呈现为已收取、应缴纳或已申报的金额，并且在引用税率时始终附带编码税率的印章（“2026年11月检查—在申报前请与CRA/省级来源核实”）。本工具中，投入品支付的PST/RST绝不视为ITC。
• 负净额是退税状态，而非收入。 不要将其描述为已收到的款项。
• 从不计算罚款和利息 — 如果用户在较早的期间已超过门槛，那是与CRA/会计师的对话；不要估算金额。
• 仅本地运行：该工具读取您指向的文件，不向任何地方发送任何内容。