商社・卸
位置づけ: 第1弾（催事＋アイテム＋商社）
商社・卸モジュールは、商社（卸）を軸に販売店からの発注を管理する業務ドメインである。元請案件（販売店・エンドユーザー向け商談を扱う本体案件）とはエンティティを分離し、WholesaleCase を集約ルートとして発注・請求・入金を内包する独立したライフサイクルで運用する。
決済区分（前金／掛売／三社間／カード／その他）ごとに発注可否・請求可否を判定するワークフローエンジンを備え、案件は工程の進捗に応じてパイプライン列（WBucket）へ自動配置される。ワークフローエンジンで発注可否・請求可否を判定する構造は ValueOS の WorkflowEngine（canOrder / canInvoice）と同一の思想であり、case_settlements.settlement_type による決済区分管理にも対応する。決済区分の定義・審査観点・工程順序（FLOW）の詳細は /features/wholesale-settlement/ を正本とする。本ページでは、案件・卸金額マスタ・発注フォーム・受注〜入金・パイプライン・タスクを扱う。
スコープ/対象
Section titled “スコープ/対象”| 対象 | 内容 |
|---|---|
| 別軸案件 | WholesaleCase（商社軸の案件。orders[] / invoices[] / payments[] を内包） |
| 卸金額マスタ | WholesalePrice（アイテム × 商社の卸価格。反映日付き） |
| 販売店発注フォーム | DealerIntakeForm（送信で WholesaleCase を自動生成） |
| 受注〜入金 | WOrder / WInvoice / WPayment |
| パイプライン | WBucket（決済待ち／発注待ち／納品待ち／請求待ち／入金待ち／完了） |
| タスク | WholesaleTask（卸業務専用のタスクリスト） |
| 対象外（委譲） | 決済区分 WSettlement の定義・審査観点、工程 FLOW の全パターン → /features/wholesale-settlement/ |
アイテム（商品マスタ）は /features/item-master/、価格表・見積は /features/quote-pricing/ を参照。
データ（エンティティ表）
Section titled “データ（エンティティ表）”| エンティティ | 主なフィールド | 役割 | ValueOS対応 |
|---|---|---|---|
WholesaleCase | id（W-XXXX）, createdAt, dealer, settlement, approvalNo, items[], 進捗フラグ5種 | 商社軸の案件。発注・請求・入金の集約ルート | cases（決済関連は case_settlements） |
WholesalePrice | id, itemKind, itemName, supplier, purchasePrice, wholesalePrice, startDate, endDate, memo | アイテム×商社の卸価格。反映日により価格改定と履歴を表現 | dealer_sales_prices / supplier_purchase_prices に相当 |
WOrder | id, orderNo（PO-XXXX）, orderDate, supplier, amount, status, deliveredDate | 商社・メーカーへの発注記録 | orders |
WInvoice | id, invoiceNo（INV-XXXX）, invoiceDate, dueDate, amount, status | 販売店への請求記録 | invoices |
WPayment | id, paymentDate, amount, method | 分割入金レコード | payments |
WholesaleTask | id（WT-XXXX）, caseId, title, status, assignee, dueDate, priority, memo | 卸業務専用タスク。案件への任意接続 | ValueOSの tasks（case_id, title, status, due_date, assigned_user, priority） |
WholesaleCase は決済区分に応じたゲートフラグ（settlementConfirmed / paymentReceived / ordered / delivered / invoiced）を持ち、これらがワークフロー判定の入力になる。
| 画面 | 機能 | 備考 |
|---|---|---|
| 卸案件一覧（パイプライン） | 6バケットでの進捗表示。商社軸での絞り込みを既定にする | バケット間の手動移動は不可。工程完了に応じた自動導出のみ |
| 卸金額マスタ | アイテム×商社の卸価格の登録・改定 | startDate による価格予約・履歴を兼ねる |
販売店発注フォーム（DealerIntakeForm） | 販売店からの発注入力を受け付け、送信時に WholesaleCase を自動生成 | 手入力での案件直接作成も併存する |
| タスク一覧 | 卸業務専用タスクの一覧・期限管理 | 案件詳細内タブ表示と独立リスト表示のいずれを既定にするかは確認事項（下記） |
案件一覧の表示形式（かんばん列型かテーブル＋フィルタ型か）は、実装時に複数パターンを提示したうえで選定する。堅牢性要件として、ゼロ件バケットの表示、長い品名・販売店名の折返し、件数過多時のページングまたは仮想スクロールを満たす。
業務ルール/ワークフロー
Section titled “業務ルール/ワークフロー”卸金額マスタの価格引き当て
Section titled “卸金額マスタの価格引き当て”現在価格の引き当ては「startDate ≤ 基準日 かつ（endDate 未設定 または endDate ≥ 基準日）」を満たす行のうち、startDate が新しい順、同日なら卸価格が安い順で先頭を採用する。品名はフリーテキストの itemName で管理し、Product.model（型番）とは連結していない。
発注フォームからの案件起票
Section titled “発注フォームからの案件起票”DealerIntakeForm の送信時、進捗フラグ（settlementConfirmed / paymentReceived / ordered / delivered / invoiced）は全て未完了で初期化される。これによりワークフロー判定は自動的に先頭工程（決済区分に応じて「決済条件の確定」または「審査OK確認」）を指し、対応する WBucket（決済待ち）へ配置する。明細の品名を卸金額マスタから選択すると区分・卸単価を自動で引き当て、マスタに無い品名は単価を手入力する。
決済区分別の工程順（FLOW）
Section titled “決済区分別の工程順（FLOW）”| 決済区分 | 工程順 | 請求工程 | 入金確認の位置づけ |
|---|---|---|---|
| 前金 | 決済条件確定 → 前金入金確認 → 発注 → 納品 | 持たない | 発注より前（prepay 工程内） |
| 掛売 | 決済条件確定 → 発注 → 納品 → 請求 → 入金消込 | 持つ | 請求後（payment 工程） |
| 三社間 | 審査OK確認 → 発注 → 納品 → 入金消込 | 持たない | 納品後（payment 工程） |
| カード | 審査OK確認 → 発注 → 納品 → 入金消込 | 持たない | 納品後（payment 工程） |
| その他 | 決済条件確定 → 発注 → 納品 → 請求 → 入金消込 | 持つ | 請求後（payment 工程） |
工程の名称・担当・審査観点の詳細は /features/wholesale-settlement/ を正本とする。本ページは接続点（工程順とバケットの対応）のみを保持する。
パイプライン列（WBucket）の導出
Section titled “パイプライン列（WBucket）の導出”| バケット | 対応工程 | 決済区分による有無 | 導出条件 |
|---|---|---|---|
| 決済待ち | 決済条件確定／審査OK確認 | 全区分で通過 | 未完了の先頭工程がこの2つのいずれか |
| 発注待ち | 発注 | 全区分で通過 | 直前工程が完了かつ未発注 |
| 納品待ち | 納品確認 | 全区分で通過 | 発注済みかつ未納品 |
| 請求待ち | 請求 | 掛売・その他のみ（三社間／カード／前金は通らない） | 工程順に「請求」が含まれる場合のみ |
| 入金待ち | 前金入金確認／入金消込 | 前金は前者、他区分は後者 | 対応工程が未完了 |
| 完了 | — | 全区分共通 | 全工程が完了 |
発注可否（canOrder）は、工程順で「発注」より前の工程が全て完了し、かつ未発注のときに真となる。請求可否（canInvoice）は、工程順に「請求」が含まれ、それより前の工程が全て完了し、かつ未請求のときに真となる。この判定構造は ValueOS の WorkflowEngine（canOrder / canInvoice）と対応する。
受注から入金までの状態と金額
Section titled “受注から入金までの状態と金額”WOrder の状態は「発注済」「納品済」の2値、WInvoice の状態は「請求済」「一部入金」「入金済」の3値であり、いずれもフォーム操作による手動更新で遷移する。金額は次の式で自動算出する。
- 請求ベース金額（
wholesaleBilled）: 請求書があればその合計、無ければ明細の卸金額合計 - 入金済み合計（
wholesalePaid）: 入金レコードの合計 - 残高（
wholesaleBalance）:wholesaleBilled − wholesalePaid（下限0）
入金は複数レコードによる分割入金に対応する。入金をどの請求へ充当するかの按分ルールは定めておらず、入金レコードの単純合算で残高を算出する。
タスク（WholesaleTask）
Section titled “タスク（WholesaleTask）”タスクは title / status（未対応・対応中・完了）/ assignee / dueDate / priority（高・中・低）を持ち、卸案件（caseId）への任意接続に対応する。案件に紐付けない全社共通タスク（caseId = null）も登録できる。期限超過は「status ≠ 完了 かつ dueDate が基準日より前」で判定する。経理系工程（決済条件確定／審査OK確認／前金入金確認／請求／入金消込）と発注担当系工程（発注／納品確認）の担当分掌に沿って assignee を運用する。
現行実装は発注フォーム・案件操作の認証・権限ガードを持たず、入力主体が社内（VE）担当か販売店本人かを技術的に区別する手段を持たない。販売店による直接入力（ポータル化）と、その際の認証・権限モデルは確認事項とする。
- 元請案件（
deals）と卸案件（WholesaleCase）の紐付け方式（参照キー追加か疎結合突合か） WholesalePriceの価格改定時、旧行のendDateを必ず設定する運用とするかitemName（フリーテキスト）をProduct.model（型番）参照へ正規化する方式と時期DealerIntakeFormの入力主体（社内代行かポータル型か）と認証・権限モデルWOrder/WInvoiceのステータスを入金・納品実績から自動遷移させるか、手動更新のまま運用するか- 前金の工程順で「入金消込」を独立工程として持たず「前金入金確認」に統合している設計の妥当性
WholesaleTaskを案件詳細画面内タブとして表示するか、独立リストとして表示するか- 発注・請求明細のOCR/AI取込（明細スキャン）構想の採否と実装時期
- /features/wholesale-settlement/ — 決済区分・工程順序の正本
- /features/item-master/ — アイテム（商品）マスタ
- /features/quote-pricing/ — 価格表・見積
- /features/events/ — 催事モジュール（代理店権限モデルの先行事例）
- /redesign/valueos-gap/ — ValueOSとの対応・差分
- /valueos/data-model/ — ValueOSのテーブル定義
- /redesign/meeting-log/ — 7/29定例（卸の新要件確定回）