決済フロー

位置づけ: 第1弾（催事＋アイテム＋商社）

概要

商社（卸）モジュールでは、卸案件（WholesaleCase）ごとに決済区分を1つ選択し、選択した区分に応じて工程列が確定する。工程は直列に進行し、直前工程が完了するまで発注・請求は行えない。発注可否・請求可否の判定、入金の分割消込、案件一覧・ダッシュボードのステータス集計は、いずれもこの工程列を単一のソースとして導出する。

決済区分は 前金 / 掛売 / 三社間 / カード / その他 の5値。元請案件（deals）とは別軸の案件（WholesaleCase）として管理し、案件作成時に決済区分を選択する。現行実装（wholesale.ts）は決済区分を変更する操作を持たず、案件作成時に選択した値をそのまま保持する。業務上決済区分の途中変更を許容するかどうかは未確定であり、後述「確認事項」を参照。

本ページはドメインロジック（crm_app/app/src/lib/wholesale.ts）を正として記述する。卸金額マスタ・販売店発注フォーム・パイプライン全体の仕様は features/wholesale を参照。

スコープ/対象

項目	内容
対象	卸案件（WholesaleCase）の決済区分・工程進行・発注ゲート・請求ゲート・入金消込
対象外	卸金額マスタ、販売店発注フォーム、タスク（features/wholesale を参照）
情報源	定例で確定した新要件（卸金額・発注管理・決済フロー・商社別軸）。正本は redesign/meeting-log
関連ページ	features/wholesale、glossary、redesign/valueos-gap

データ（エンティティ）

卸案件は1件の中に発注・請求・入金を複数保持する集約構造とする。

エンティティ	主キー	主なフィールド	役割
WholesaleCase	id（`W-0001`形式）	dealer, settlement, approvalNo, items[], 進捗フラグ, memo	卸案件の本体。工程進行の起点
WOrder	id	orderNo（`PO-0001`形式）, orderDate, supplier, amount, status, deliveredDate	発注の実体。1案件に複数保持可
WInvoice	id	invoiceNo（`INV-0001`形式）, invoiceDate, dueDate, amount, status	請求の実体。1案件に複数保持可
WPayment	id	paymentDate, amount, method	入金の実体。1案件に複数保持可（分割入金）

WholesaleCase は工程進行を判定するための進捗フラグを持つ。フラグとエンティティ登録（発注書・請求書の追加）は連動して更新する。

フラグ	意味	対応する工程
settlementConfirmed	決済条件の確定	settlement
paymentReceived	入金完了	prepay / payment（同一フラグを共有）
ordered	発注済	order
delivered	納品済	deliver
invoiced	請求済	invoice

決済区分と工程

決済区分ごとに工程数が異なる。前金は4工程、掛売・その他は5工程、三社間・カードは4工程とする。三社間とカードは工程列そのものが完全に一致する。

決済区分	工程数	特徴
前金	4	入金確認後に発注する。VE（当方）のリスクを最小にする区分
掛売	5	先に発注し、全納品後に請求する（売りかけ）
三社間	4	審査完了（承認番号）で先に発注し、工事後にローン会社から入金される
カード	4	カード会社の承認で先に発注し、カード会社から入金される
その他	5	掛売と同一の工程列を使用する

工程は7種類のキーで定義し、settlement（決済条件確定）と approval（承認番号確認）は排他、prepay（前金入金確認）は前金のみ、invoice（販売店へ請求）は掛売・その他のみに登場する。担当は経理（settlement/approval/prepay/invoice/payment）と発注担当（order/deliver）の2ロールに限定する。

工程キー	表示名	担当	完了条件	登場する決済区分
settlement	決済条件の確定	経理	settlementConfirmed = true	掛売・前金・その他
approval	審査OK（承認番号）の確認	経理	approvalNo が空文字でない	三社間・カード
prepay	前金の請求・入金確認	経理	paymentReceived = true	前金
order	商社/メーカーへ発注	発注担当	ordered = true	全区分
deliver	納品確認	発注担当	delivered = true	全区分
invoice	販売店へ請求	経理	invoiced = true	掛売・その他
payment	入金の消込	経理	paymentReceived = true	掛売・三社間・カード・その他

区分別の工程順序は次のとおり。

決済区分	STEP1	STEP2	STEP3	STEP4	STEP5
前金	settlement（経理）	prepay（経理）	order（発注担当）	deliver（発注担当）	—
掛売	settlement（経理）	order（発注担当）	deliver（発注担当）	invoice（経理）	payment（経理）
三社間	approval（経理）	order（発注担当）	deliver（発注担当）	payment（経理）	—
カード	approval（経理）	order（発注担当）	deliver（発注担当）	payment（経理）	—
その他	settlement（経理）	order（発注担当）	deliver（発注担当）	invoice（経理）	payment（経理）

工程は配列順に直列進行し、未完了の先頭工程を常に「現在の工程」として扱う。スキップ・並行実行は行わない。

前金は末尾に独立した payment 工程を持たず、prepay の入金確認をもって金銭処理を完結させる。三社間とカードは工程配列が完全に同一であり、両者を区別するのは決済区分の値と approvalNo フィールドの内容のみである。prepay と payment はいずれも paymentReceived という同一のブール値で完了判定する。前金だけが prepay を、他区分だけが payment を持つため、判定上の衝突は生じない。

発注ゲート・請求ゲート

発注可否（canOrder）と請求可否（canInvoice）は、工程配列上の位置関係から機械的に判定する。画面はこの判定結果を表示するレイヤーであり、判定ロジック自体は持たない。

発注ゲート: order より前の工程がすべて完了し、かつ未発注のときに true とする。
発注ブロック時のメッセージは、未完了の直前工程名を含む動的な文言（例:「決済条件の確定が未完了」）とする。
請求ゲート: invoice 工程を持つ区分（掛売・その他）でのみ判定し、invoice より前の工程がすべて完了し、かつ未請求のときに true とする。三社間・カード・前金は請求工程を持たないため、この判定自体が発生しない。
請求ブロック時のメッセージは「納品などの前工程が未完了」という固定文言とする。
画面では発注・請求ボタンにブロック理由をツールチップで表示し、ボタン文言を可否に応じて出し分ける。

決済区分	発注（order）解放条件	請求（invoice）解放条件	備考
前金	前金入金確認（prepay）完了後	該当なし	請求工程自体を持たない
掛売	決済条件確定（settlement）後	納品確認（deliver）完了後	標準フロー
三社間	承認番号確認（approval）後	該当なし	入金は payment 工程のみで判定
カード	承認番号確認（approval）後	該当なし	三社間と同一構造
その他	決済条件確定（settlement）後	納品確認（deliver）完了後	掛売と同一実装

入金管理（分割入金と残高消込）

1案件の payments[] に複数の入金を登録でき、残高消込方式で管理する。残高は保存された値ではなく、請求・入金の実額から都度計算する派生値とする。

関数	計算内容
wholesaleBilled	請求書（invoices）があればその合計、なければ品目合計（卸金額）を採用
wholesalePaid	入金（payments）の合計
wholesaleBalance	max(0, wholesaleBilled − wholesalePaid)

請求書のステータスは 請求済 / 一部入金 / 入金済 の3値とする。payment 工程の完了判定は残高計算ではなく、案件単位の paymentReceived フラグで行う。入金（WPayment）は案件単位の配列として保持し、特定の請求書（WInvoice）に紐付ける識別子は持たない。複数請求がある案件での入金対応関係は、案件のメモ欄で管理する運用とする。

与信枠・承認番号

掛売は与信枠の範囲内で先に発注する区分と位置づけるが、与信枠を表すデータ項目は現行仕様に存在しない。案件のメモ欄に自由記述で残す運用とする。与信枠のデータ構造化は次節「確認事項」を参照。

三社間・カードは工程列の先頭に approval（承認番号確認）を置き、WholesaleCase.approvalNo という単一の任意文字列フィールドを両区分で共用する。承認番号の発行元（三社間＝決済事業者、カード＝カード会社）を区別する専用フィールドは持たず、区別は決済区分の値と案件メモに委ねる。承認番号の形式（桁数・書式）に対するバリデーションは行わない。

ステータスバケット（進捗ビュー）

案件一覧・ダッシュボードは、現在の工程から自動導出する6バケットで集計・絞り込みを行う。バケットは手動変更の対象にしない。

バケット	対応する工程
決済待ち	settlement, approval
発注待ち	order
納品待ち	deliver
請求待ち	invoice
入金待ち	prepay, payment
完了	全工程完了

区分ごとに通過するバケットの並びが異なる点に注意する。前金は「決済待ち → 入金待ち（prepay） → 発注待ち → 納品待ち → 完了」の順で、入金待ちを発注待ちより前に通過する。掛売・その他・三社間・カードは入金に相当する工程が末尾に来るため、この4区分と前金とではバケットの通過順が逆になる。三社間・カードは請求待ちを経由しない。

マイルストーン（発注・請求/入金の予定日）

案件作成日（createdAt）を起点に、決済区分ごとのリードタイムで発注予定日・請求/入金予定日を投影し、タイムライン表示に用いる。実績（ordered・invoiced・paymentReceived が完了）が入るとマイルストーンは完了表示に切り替わる。

区分	発注までのリードタイム	金銭マイルストーンの種別
前金	5日（ただし入金確認が発注より先に到来する）	入金 → 発注の順
掛売	1日	発注 → 請求の順
三社間	2日	発注 → 入金の順
カード	2日	発注 → 入金の順
その他	3日	発注 → 請求の順

前金以外は「発注」の10日後に納品、その3日後に請求または入金が到来する想定でマイルストーンを算出する。前金のみ、入金確認マイルストーンを発注マイルストーンより前に置く。

ValueOSとの対応

ValueOSは決済区分を case_settlements.settlement_type で保持し、区分ごとに fee_rate / fee_amount（三社間の手数料）、deposit_rate / deposit_amount（頭金）、payment_terms（掛売の支払条件）、card_brand / card_status（カード）、finance_company / approval_number / loan_status（三社間）を専用カラムとして分離する。当方は同じ「承認番号確認」の情報を WholesaleCase.approvalNo という単一フィールドに集約しており、三社間とカードで発行元を区別する専用カラムは持たない。

発注可否・請求可否の判定は、ValueOSでは WorkflowEngine（canOrder / canInvoice）が担い、画面は表示レイヤーに徹する設計である。当方の wholesaleFlow（canOrder / canInvoice の判定と工程進行）はこの設計思想に沿っており、判定ロジックを工程配列から機械的に導出する点で対応する。

観点	当方（WholesaleCase）	ValueOS
決済区分	settlement（5値）	case_settlements.settlement_type
発注可否判定	wholesaleFlow.canOrder	WorkflowEngine.canOrder
請求可否判定	wholesaleFlow.canInvoice	WorkflowEngine.canInvoice
発注実体	orders[]（WOrder）	orders テーブル
請求実体	invoices[]（WInvoice）	invoices テーブル
入金実体	payments[]（WPayment）	payments テーブル
三社間・カードの専用項目	approvalNo（単一・共用）	finance_company / approval_number / loan_status（三社間）、card_brand / card_status（カード）

差分の全体像は redesign/valueos-gap を参照（同ページの発注・請求・入金に関する記述は、本ページで示すWOrder/WInvoice/WPaymentのエンティティ化が実装された後の内容に更新する必要がある）。

確認事項

与信枠（掛売）のデータ構造と、超過時の挙動（発注ブロック／警告のみ／前金への切替提案）
承認番号の発行元区別（三社間／カード）を専用フィールドとして分離する要否
前金における一部入金時の発注可否（現行は入金の有無のみを判定し、金額の充足は判定しない）
決済区分の途中変更、および工程完了の取り消し（差し戻し）を許容する運用の要否
請求ステータス（請求済／一部入金／入金済）の自動遷移の要否と実装位置
同一バケット滞在日数の閾値超過を検知する滞留アラートの自動化要否
担当ロール単位ではなく担当者個人単位で「自分の待ち」に絞るビューの要否