3PL課金の入門

課金チェーン——料金項目→料金表→マーチャント課金ルール→請求書、そして現状のギャップ（数量は手動入力、請求書画面は未提供）。

課金チェーン#

チェーン：料金項目→料金表→マーチャント課金ルール→請求書/インボイス生成（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＝グローバル、全マーチャント適用）＋version＋effective_date/expiry_date＋is_active。複数バージョン対応。
• 明細行は料金項目に1件ずつ紐付け、unit_price_overrideが空＝項目の原価を使用。行独自のeffective/expiryも可（空＝表に準拠）。

マーチャント課金ルール#

WMS → Billing → 課金ルール（rules）：マーチャントごとに1件（組織×マーチャントで一意）、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. 料金表の決定：明示指定が優先、なければ当該マーチャントの有効な課金ルールを使用。ルールなし→400。
3. 重複防止：同一期間の請求書が既存の場合は拒否（組織×マーチャント×期間で一意）。
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）。