商品・アイテムマスタ

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

アイテムマスタ（商品マスタ）は、型番を主キーとする Product と、メーカー・シリーズ・仕入先・施工店・ローン会社の周辺5マスタで構成する。Product は価格フィールドを持たない。価格は卸金額・価格表・販売価格・見積の4系統側で管理する（価格4系統との関係を参照）。

画面はマスタ画面の定型（一覧テーブル＋編集ドロワー＋変更履歴ペイン、サイドバー「マスタ」集約）に準拠する。定型仕様そのものは本ページでは扱わない。

スコープ

顧客・商談CRM本実装、見積本実装、KPI予実、AIエージェントは対象外（後続フェーズ）。本ページは商品マスタと周辺マスタの構造・業務ルールのみを扱う。段階分けは段階的スコープを参照。

データ

Product（商品）— 型番＝主キー

Product.model（型番）を主キーとし、重複登録はできない。型番が変わった場合は別レコード（別商品）として扱う。型番変更時、変更履歴は新規レコードに引き継がれず分断される。

フィールド	型・選択肢	必須	備考
`model`	文字列（型番）	必須・主キー	表記例: `CS-340B81`
`kind`	`PV / BT / EQ / IH / AC / 付帯`	必須	種別6区分を参照
`maker`	文字列（メーカー名）	必須	編集画面ではプルダウン。メーカーマスタの名称と商品側の既存値をマージして候補にする
`series`	文字列（シリーズ名）	任意	編集画面ではプルダウン。シリーズマスタと名称一致で対応付ける
`name`	文字列（商品名）	任意	例: 「蓄電池」等の一般名
`spec`	文字列（容量・枚数等）	任意	自由記述
`leadTimeDays`	数値（日）	任意	商品単位の納期目安
`stock`	`潤沢 / 少 / 欠品`	任意	数量在庫は持たない3状態管理
`note`	文字列（備考）	任意	自由記述

在庫は「潤沢/少/欠品」の3状態のみを持ち、数量在庫は管理しない。実在庫はメーカー・商社側にあり、CRM側で数量を保持しても実態と乖離するため、状態区分に限定する。

Product は価格フィールドを一切持たない。価格の実体は価格4系統との関係を参照。

型番の全角/半角・ハイフン・スペースなどの表記ゆれを正規化するルールは未定義である。階層構造と名称一致の課題と同根であり、確認事項に記載する。

種別6区分（kind）

kind は PV / BT / EQ / IH / AC / 付帯 の6区分で固定する。区分の追加はコード上の列挙値変更を伴うため、リリース後の変更管理対象として扱う。

区分コード	名称	想定商材
PV	太陽光パネル	太陽光モジュール一式
BT	蓄電池	蓄電システム一式
EQ	エコキュート	給湯システム一式
IH	IHクッキングヒーター	IH機器
AC	エアコン	空調機器
付帯	付帯部材	単体販売しない部材・工事付属品

「付帯」区分は境界事例（単体販売するかどうか判断が割れる部材）を含む。判断基準は運用側の判断に委ねる。

kind は商品マスタ画面のフィルタ軸であり、商社モジュールの WholesalePrice.itemKind（商品 / パッケージ）とは別概念である。名称が似ているため混同しやすいが、前者は商材カテゴリ、後者は卸金額行が単品かセットかの区分である。

周辺マスタ5種

いずれも一覧＋ドロワーの定型画面（マスタ画面）で構成する。

マスタ	主要フィールド	用途
`Manufacturer`（メーカー）	`name`	`Product.maker` の候補元。価格表の `manufacturerId` からも参照される
`Series`（シリーズ）	`name`, `maker`, `note`	商品を束ねる系列。商品検索の名寄せに使う
`Supplier`（仕入先）	`name`, `type: 商社 / メーカー直送`, `note`	仕入先の種別管理。卸金額の `supplier`（商社名）と名称で対応する
`Vendor`（施工店）	`name`, `type: 自社 / 他社`, `tool: CRMチャット / ANDPAD / LINE`, `area`	施工店の種別・連絡ツール・エリア管理
`LoanCompany`（ローン会社）	`name`, `daysDirect`（2社間営業日数）, `daysViaTrader`（3社間営業日数）	審査〜入金の営業日数管理

代理店マスタ（旧 Agency）は独立マスタとして廃止し、催事モジュールの会社マスタに統合済みである。催事会社と代理店を別マスタで分けない方針による。詳細は催事モジュール仕様を参照。

補足事項:

Supplier と商社モジュールの WholesalePrice.supplier（商社名・フリーテキスト）は名称一致で結びついており、ID参照ではない。
Vendor.tool（連絡ツール区分）は施工進捗の通知経路の出し分けに使う想定である。
LoanCompany.daysDirect / daysViaTrader は2社間・3社間で別々に営業日数を持つ。
Manufacturer.name と Product.maker の紐付けも名称一致である。

業務ルール

階層構造と名称一致

メーカー─シリーズ─商品の階層は、すべて名称の文字列一致で解決する。ID参照ではない。

flowchart LR
  M1["Manufacturer.name<br/>（文字列）"] -.文字列一致.-> P1["Product.maker<br/>（文字列）"]
  S1["Series.name<br/>（文字列）"] -.文字列一致.-> P1b["Product.series<br/>（文字列）"]

名称一致が切れる代表的なシナリオ:

メーカーが社名変更・ブランド統合した際、Manufacturer.name を更新しても Product.maker の既存レコードが旧名のまま残り、名称一致が切れる。
シリーズ名がリブランドされた場合、旧シリーズ名で登録済みの商品が新シリーズ名の Series レコードから外れて見えなくなる。
全角/半角・スペース・中黒（・）などの表記ゆれにより、同一のメーカー・シリーズが別名称として扱われ、名寄せが漏れる。

seriesId/makerId へのID参照化は、確認事項に記載する未決の論点である。

商品マスタと価格の分離

商品マスタ（Product、型番＝主キー）は型番・種別・納期・在庫などの識別情報のみを保持する。価格・仕切りは価格・見積ドメイン（PriceBook/Part/PackageSet/SalesPrice）側で保持し、商品マスタからは参照しない。

廃番管理

現行の Product に廃番（生産終了）の概念はない。レコードは「ある/ない」の二値でしか表現できず、既存参照（卸金額・過去案件）を保ったまま販売終了扱いにする手段がない。廃番ステータスの導入は確認事項に記載する。

変更履歴

マスタ画面定型の履歴ペインで、フィールド単位の before/after（変更者・日時付き）を記録・閲覧できる。

対象エンティティ	履歴記録	粒度
`Product`（商品）	あり	フィールド単位 before/after
`Supplier`（仕入先）	あり	フィールド単位 before/after
`Vendor`（施工店）	あり	フィールド単位 before/after
`LoanCompany`（ローン会社）	あり	フィールド単位 before/after
`Series`（シリーズ）	なし	詳細ページが専用UIで、定型の履歴経路（マスタ画面のドロワー編集）を通らないため
`EventStore`（催事店舗）・`EventCompany`（代理店）	あり	MasterScreen経由でフィールド単位 before/after。記録・閲覧は催事モジュール仕様側
催事シフト等（MasterScreenを使わない催事内データ）	なし	催事モジュール仕様の管轄範囲であり対象外

Product の型番変更は別レコード扱いのため、旧型番側の変更履歴は新レコードに引き継がれない。

価格4系統との関係

Product は価格フィールドを持たない。価格は次の4系統で管理する。

flowchart LR
  Product["Product<br/>（型番・種別・在庫等）"]
  WP["① 卸金額<br/>WholesalePrice"]
  PB["② 価格表<br/>PriceBook / Part / PackageSet"]
  SP["③ 販売価格<br/>SalesPrice"]
  QT["④ 見積<br/>Quote"]
  Product -.名称一致（型番/itemName）.-> WP
  Product -.名称一致（productNo等）.-> PB
  Product -.名称一致（productNo）.-> SP
  Product -.名称一致.-> QT

価格系統	保持モジュール	アイテムとの紐付け方法	改定管理
卸金額	商社モジュール（`WholesalePrice`）	`itemName`（フリーテキスト）＋ `supplier`（商社名）で保持。型番との直接参照はない	`startDate`（反映日）で最新を導出
価格表	価格・見積ドメイン（`PriceBook`/`Part`/`PackageSet`）	`Part.productNo` 等の名称的な参照	`effectiveDate`（反映日）で最新を導出
販売価格	価格・見積ドメイン（`SalesPrice`）	`productNo`（型番）＋ `channel`（商流/代理店）で保持	`startDate`（反映日）で最新を導出
見積	価格・見積ドメイン（`Quote`）	明細行（`QuoteItem`）に型番・数量・金額を都度入力	見積単位で個別

卸金額（WholesalePrice）は itemKind（商品 / パッケージ）・itemName（フリーテキスト）・supplier（商社名）・purchasePrice（仕入）・wholesalePrice（卸）・startDate（反映日）を持ち、反映日で改定を管理する。ただし itemName は型番との突合が名称頼みであり、階層構造と名称一致と同じ課題を抱える。

価格表・販売価格・見積の3データは価格・見積ドメイン内で保持し、商品マスタとは名称的な参照（型番文字列の一致）で結びつく。ID参照ではない。

価格改定（各系統の反映日）と、アイテム側の leadTimeDays（納期）・stock（在庫3状態）は独立した概念であり連動しない。価格が変わっても在庫・納期の表示は自動更新されない。

確認事項

seriesId/makerId によるID参照化の要否・移行手順（既存レコードの名称→ID変換方法、価格表・卸金額など他モジュールへの波及範囲を含む）。
型番の表記ゆれ（全角/半角・ハイフン・スペース）を正規化するルールの要否。
卸金額 itemName を型番参照に寄せるかどうか（上記のID正規化と同根）。
Product への廃番ステータス（status: 販売中 / 廃番）追加の要否。追加する場合、廃番時は新規選択候補から除外しつつ卸金額・過去案件など既存参照は保持する設計とする。
廃番（恒久的な状態）と stock の「欠品」（一時的な状態）の使い分け運用ルールの要否。
廃番品から後継型番への案内リンク機能の要否。
変更履歴の保存期間・CSV等へのエクスポート要否。