コンテンツにスキップ

2026-03 SMILE得意先CSVの更新キーと再インポートルール

背景

  • SMILE 得意先マスタを正本とし、Vendure 側では SMILE 由来の顧客情報を再インポートで反映する運用を採る。
  • 同一顧客の再取り込み時に新規顧客が増殖すると、受注・配送先・請求先コードの整合が崩れる。
  • そのため、どのキーで既存顧客を再利用し、どこまで上書きするかを追加仕様として明文化する。

決定事項

1. 顧客の更新キー

  • SMILE 得意先CSVの Customer upsert キーは 得意先コード とする。
  • Vendure 上では Customer.customFields.customerCode を照合キーとし、同じ値の既存顧客が見つかった場合は新規作成せず更新する。
  • 判定基準は「同じ名称」「同じメールアドレス」ではなく、同じ得意先コードかどうかを優先する。

2. 再インポート時の上書き範囲

  • 得意先コード一致で既存顧客を再利用した場合、SMILE 由来の顧客項目（名称、メール、請求先コード、回収方法、住所関連 custom field、元行JSON など）は最新行で更新する。
  • 住所は Address.customFields.deliveryPointCode を upsert キーとして更新する。
  • deliveryPointCode が空または 0 の場合は、既存の defaultBillingAddress を更新対象として扱う。

3. 上書きの例外

  • customerStatus は SMILE importer では設定・補完しない。Vendure 側の custom field default または Dashboard / 運用側の明示設定を正本にする。
  • SMILE の 回収方法 は collectionMethod として保持し、顧客分類への変換は import 時に行わない。
  • collectionMethod に保存する値は SMILE の回収方法コードのみとする。 tokuisaki.csv の 回収方法,回収方法 は1列目がコード、2列目が表示名であり、 2列目の label (現金 / 口座引落 / 振込 / 振込(先入金)) や Vendure 内部値 (general など) は保存しない。

4. メールアドレスの扱い

  • 通常のメールアドレスは、顧客再利用の照合キーにしない。
  • したがって、得意先コードが異なるがメールアドレスだけ同じという理由では自動マージしない。
  • メールアドレスが未入力の行は仮ID運用とし、${customerCode}@ritsubi-platform.com 形式の仮メールアドレスを使用する。
  • 再インポート時、得意先コード一致の顧客が見つからなくても、同形式の仮メールアドレスを持つ顧客が存在する場合は、その顧客を再利用して更新する。
  • 仮パスワードは新規仮アカウント作成時に生成するが、Customer custom field や import log には保存しない。
  • 生成した仮パスワードは、SMILE 取込実行直後の Dashboard レスポンスでその場限りで表示 し、画面遷移後・再読込後・履歴画面からの再参照は不可とする。
  • 仮パスワードを忘れた場合は、顧客詳細の「パスワード設定」から新しい値を再発行する。

5. 同一ファイル内の重複行

  • 同一CSV内に同じ得意先コードの行が複数ある場合は、行順に処理する。
  • 先に出現した行で作成または更新した顧客に対し、後続行が上書きされる。
  • したがって、最終的な取り込み結果は最後に出現した同一得意先コードの行を正とする。

運用ルール

  • SMILE 由来の顧客情報を修正したい場合は、Vendure で直接メンテナンスせず SMILE 側を更新して再インポートする。
  • 既存顧客を更新したい場合は、同じ得意先コードで SMILE CSV を出力する。
  • 新規顧客として扱いたい場合は、SMILE 側で新しい得意先コードを発行する。
  • importer は SMILE の列値を Vendure の顧客分類や決済可否へ意味変換しない。 決済可否は PMCA、顧客分類は customerStatus、価格・販促条件は各ルールの責務として import 後の計算時に評価する。

既存データ修復

2026-05-28 に以下の migration で、過去の import 時意味変換による既存データを修復する。

  • StopSmileCollectionMethodCustomerStatusDerivation1779934399464
  • 回収方法 由来で自動設定された customerStatus を Vendure 側の default に戻す。
  • RepairSmileCustomerCollectionMethodCode1779936361554
  • collectionMethod に保存された label を SMILE コードへ戻す。
  • DB CHECK 制約 CHK_customer_collection_method_smile_code で、今後は null/空文字または numeric code 以外を拒否する。

関連ドキュメント

  • docs/03-implementation/vendure-plugins/smile-integration.md
  • docs/03-implementation/smile/smile-master-data-reference.md
  • docs/specifications/2026-03-smile-billing-linkage-ssot.md