3PL 计费入门

计费链条——收费项目→费率表→Merchant 计费规则→对账单，以及当前缺口（用量手工传入、对账单暂无桌面页）。

计费链条#

链条：收费项目 → 费率表 → Merchant 计费规则 → 对账单/发票生成（wms_merchant_invoices + 明细行）。全部为桌面端操作，手机端无计费功能。

收费项目#

WMS → Billing → 收费项目（items）。新建：code（组织内唯一）/ name / category（8 类：storage、inbound、outbound、pick、pack、value_added、freight、other）/ pricing_method（6 种：per_pallet_day、per_unit、per_order、per_weight、per_cubic_ft、flat）/ unit_price / currency（默认 USD）/ uom / is_active。

费率表#

• WMS → Billing → 费率表（rate-sheet）：name + merchant_id（NULL = 全局，挂所有 merchant）+ version + effective_date/expiry_date + is_active。多版本支持。
• 明细行绑定一个收费项目；unit_price_override 为空 = 用项目原价；行也可设自己的 effective/expiry（为空 = 跟表走）。

Merchant 计费规则#

WMS → Billing → 计费规则（rules）：一 merchant 一条（组织×merchant 唯一），指向一个 rate_sheet_id；换版本 = 改 rate_sheet_id。

生成对账单#

调用 POST /api/wms/billing/invoices/generate 生成——当前无桌面生成页，对账单只能调 API 生成。

1. body：merchant_id、period_from、period_to（YYYY-MM-DD）、rate_sheet_id（可选）、quantities（用量，手工传入）、notes。
2. 费率表确定：显式传入优先；否则取该 merchant 的激活计费规则；无规则 → 400。
3. 防重：同一账期已有账单 → 拒绝（组织×merchant×账期唯一）。
4. 逐行计算（可手工复算）：unit_price = 覆盖价 ?? 项目原价；qty 从 quantities 取（flat 计价无数量时默认 1；qty=0 的行不落库）；amount = round(qty × unit_price, 2)。每行带 formula（qty × price = amount），可手工复算。
5. 取号：MINV-000001 起（原子取号）；落库头（status=draft，含费率表快照 rate_sheet_id+name+version）+ 行。

• 当前版本已知缺口：对账单生成后停在 draft；转 sent/paid 的流转 API 未实现；对账单无桌面列表/详情/生成页（GET 列表/详情接口存在，可调 API 查看）；与会计 AR（acc_invoices）无关联，对账单→AR 入账/核销链路未实现；币种只携带不换算（Phase 1）。