ネクストエンジン商品マスタ整形

概要

ネクストエンジン経由で楽天／Amazon／Yahoo!／Shopifyへ在庫・受注連携する前段で、商品マスタの主要項目（goods_id／daihyou_shouhin_code／stock_goods_id／zaiko_su／set_flg／jan／モール別SKU列）を整形し、(a) 表記ゆれ・重複・空欄、(b) 親子構造（バリエーション親子・セット親子）の設計破綻、(c) モール側SKUとの紐付け不整合、(d) 在庫加減算ロジックを踏まえた変更可否、を検出して修正方針と段階移行手順を提示する。

商品コードの正規化（半角統一・大文字統一・ハイフン統一）、バリエーション親が在庫を持たない設計の確認、セット商品の構成情報整合、stock_goods_idによる在庫共有設計までカバーする。

★最重要原則

「商品マスタCSVの zaiko_su 列をアップロードで上書きしようとしない」「商品コード（goods_id）の変更は最後の手段」の2つが最大の事故防止策。 ネクストエンジンの在庫操作は版・モード・設定で「加減算」「上書き」の挙動が変わるため、商品マスタ一括CSVで在庫を触ると意図しない値になる。在庫変更は 「在庫変更」「実数値登録」専用機能 or 在庫変更API を使う。goods_id の変更はモール側SKU・過去受注・WMS・出荷ラベルすべてに波及するため、表示用コードと内部IDを分離する／旧コード履歴を残す／段階移行する の代替策を必ず先に提示する。

知識ベース

詳細は references/ を参照：

• 商品マスタ主要項目（goods_id／daihyou_shouhin_code／stock_goods_id／zaiko_su／set_flg／jan／モール別SKU列）：references/master-fields.md
• 在庫加減算ロジックの詳細（zaiko_su の上書き／加減算挙動・専用機能・APIの使い分け）：references/inventory-logic.md
• 商品コード変更の影響範囲と代替策（表示用コード分離／旧コード履歴／段階移行）：references/code-change-impact.md
• モール別SKU紐付けマッピング（楽天項目選択肢／Amazon親子ASIN／Yahoo!option／Shopify Variant）：references/mall-sku-mapping.md
• 表記ゆれ検出パターン（goods_id／商品名／JAN／価格／カテゴリ／ブランド／不可視文字）：references/normalization-patterns.md
• セット商品・組商品・親子構造（バリエーション親子／セット親子／stock_goods_idによる在庫共有／循環参照）：references/set-bundle-structure.md
• 実例集（表記ゆれグループ／親子設計事故／在庫加減算事故）：references/examples.md

要点（本ファイルに残す）：

商品マスタ主要項目

項目	内容	主な制約
goods_id	商品コード（主キー）	30字以内、半角英数＋ハイフン推奨
goods_name	商品名	—
daihyou_shouhin_code	代表商品コード（バリエーション親）	goods_idへの参照
stock_goods_id	在庫減算先	goods_idへの参照（通常は自身）
zaiko_su	在庫数	加減算挙動に注意、CSVで触らない
set_flg	セット商品フラグ	0/1
jan	JANコード	チェックデジット検証は別スキル
rakuten_item_code / amazon_sku / yahoo_code / shopify_handle	モール別SKU	各モールの命名規則

在庫操作の鉄則

1. 商品マスタCSV経由で zaiko_su を触らない
2. 在庫変更は管理画面「在庫変更／実数値登録」または在庫変更API
3. アップロード前後で在庫スナップショットをバックアップ
4. テスト商品1件で挙動確認
5. セット親子・stock_goods_id共有による連動を把握

表記ゆれ正規化の標準ルール

対象	ルール
両端空白	strip
改行・ゼロ幅文字	削除（\r \n U+200B U+200C U+200D U+FEFF）
全角→半角	NFKC正規化
ハイフン類統一	U+002D - に統一（U+2010〜U+2015, U+2212, U+FF0D等を置換）
大文字小文字	upper() で統一（運用ポリシー次第）

親子設計の鉄則

• バリエーション親は在庫を持たない（zaiko_su=0、stock_goods_idは自身でなくダミーまたは未設定）
• セット親（set_flg=1）も独立在庫を持たない、子の在庫から min(子在庫/構成数量) で算出
• 循環参照（A→B→C→A）禁止
• daihyou_shouhin_codeは1段階で完結（孫まで階層化しない）

処理フロー

Step 1：入力CSVの確認と分類

ユーザーから受け取るデータ：

• ネクストエンジン商品マスタCSV
• 各モールのSKU一覧（楽天 normal-item.csv／Amazonレポート／Yahoo!商品CSV／Shopify products.csv）があれば
• 連携設定の概要（マッピングモードか SKU一致モードか）

不足は「仮定／不足情報／確認」に分け、急ぎなら主要前提仮定で暫定検査結果を出す。

Step 2：goods_id 正規化と表記ゆれ検出

references/normalization-patterns.md に従い：

• 全goods_idを strip → 不可視文字除去 → NFKC → ハイフン統一 → upper で正規化
• 元データと正規化後の差分を「表記ゆれ候補」として抽出
• 同一正規化結果の元データを「表記ゆれグループ」化

Step 3：重複・空欄・桁数違反の検出

• goods_id 30字超過
• goods_id 空欄
• 完全重複（同一goods_idで複数行）
• 正規化後重複（表記ゆれ起因の見かけ重複）
• 必須項目（goods_name等）の空欄

Step 4：親子構造の検査

references/set-bundle-structure.md に従い：

• daihyou_shouhin_code が存在するgoods_idを指しているか（参照切れ検出）
• stock_goods_id が存在するgoods_idを指しているか
• set_flg=1 の商品に構成情報があるか
• 循環参照（A→B→A）の検出
• バリエーション親が在庫を持っていないか（zaiko_su>0で警告）
• セット親が独立在庫を持っていないか

Step 5：モール別SKUとの紐付け検査

references/mall-sku-mapping.md に従い、各モール側のSKU一覧と突合：

• ネクストエンジン goods_id がモール側SKUに存在するか
• モール側SKUがネクストエンジン側に存在するか
• 表記ゆれによる紐付け失敗の検出

特にAmazon item_sku は変更不可（新規SKU作成のみ）なので、紐付け不一致時はネクストエンジン側で調整する。

Step 6：在庫加減算リスクの確認

references/inventory-logic.md を参照：

• 商品マスタCSVに zaiko_su 列が含まれていないか（含まれていたら警告）
• アップロード前後のスナップショットバックアップ手順を案内
• セット親の販売可能数が min(子在庫/構成数量) で計算されているか

Step 7：商品コード変更が必要なケースの代替案提示

references/code-change-impact.md を参照し、変更動機別に代替案：

変更動機	推奨対応
表記ゆれの統合	SKU統合機能で履歴保持
命名規則の刷新	表示用コードと内部IDを分離
モール展開でコード統一	PIM側でマッピング保持
桁数超過（30字超）	早急に変更（影響範囲を慎重に）
OEM切替	仕入先別の品番に新コード採番

Step 8：修正方針と段階移行手順

優先度別の修正リストと、バックアップ → テスト商品 → 少量展開 → 全件適用 の段階移行手順を提示。

実例

例1：goods_id の表記ゆれグループ

表記ゆれグループ #001
  正規化後: TSH-001
  バリエーション:
    "TSH-001" (3件)
    "tsh-001" (1件)
    "TSH_001" (2件)
    "TSH−001"（U+2212混入）(1件)
  推奨統一先: TSH-001
  影響: 楽天SKU "TSH-001"（一致）、Amazon SKU "TSH-001"（一致）
  → ネクストエンジン側を統一すれば連携継続OK

その他の実例（バリエーション親に在庫が入っている事故／セット構成情報漏れ／循環参照）は references/examples.md 参照。

出力フォーマット（必須）

# ネクストエンジン商品マスタ整形 検査結果

## 0. 検査対象
- マスタ件数：N件
- 連携モール：<楽天／Amazon／Yahoo!／Shopify>
- CSVバックアップ：取得済 / 未取得

## 1. サマリ
| 区分 | 件数 |
|---|---|
| 表記ゆれ候補 |  |
| 完全重複 |  |
| 桁数違反（30字超） |  |
| 空欄（必須） |  |
| 親子参照切れ |  |
| 循環参照 |  |
| バリエーション親に在庫 |  |
| セット構成情報漏れ |  |
| モール側SKU不一致 |  |

## 2. 表記ゆれグループ（正規化後一致）
| 正規化後 | バリエーション | 件数 | 推奨統一先 | モール側影響 |
|---|---|---|---|---|

## 3. 親子構造の不整合
| goods_id | 種別 | 内容 | 修正案 |
|---|---|---|---|
|  | 参照切れ | daihyou_shouhin_code が存在しないコードを指す |  |
|  | バリエーション親在庫持ち | zaiko_su>0 | 親在庫を0に、stock_goods_id見直し |
|  | セット構成漏れ | set_flg=1 だが構成情報無 | 構成情報を登録 |
|  | 循環参照 | A→B→A |  |

## 4. モール別SKU紐付け
| ネクストエンジン goods_id | 楽天 | Amazon | Yahoo! | Shopify | 状態 |
|---|---|---|---|---|---|
|  |  |  |  |  | 完全一致／表記ゆれ／未紐付け |

## 5. 修正方針
| 種別 | 件数 | 対応 |
|---|---|---|
| 表記ゆれ統一 |  | NFKC＋ハイフン統一＋upper |
| 桁数違反 |  | 30字以内に短縮（影響範囲確認） |
| 親子修正 |  | 親在庫0／参照修正／構成情報登録 |
| 紐付け修正 |  | モール側SKU実態に合わせる |

## 6. 在庫操作の注意（必読）
- 本検査結果には zaiko_su の修正を含めない
- 在庫変更は管理画面「在庫変更／実数値登録」または在庫変更APIで実施
- 商品マスタCSVに zaiko_su 列を含めない（含めるなら動作仕様を公式ヘルプで確認）

## 7. 商品コード変更（必要時のみ）
- 代替案を3つ検討したか
- 影響範囲（モール側SKU・過去受注・WMS・物流）を洗い出したか
- 新旧マッピング表を作成したか
- テスト商品1件で動作確認したか

## 8. 段階移行手順
1. バックアップ取得（商品マスタCSV・在庫データ・モール別SKU一覧）
2. テスト商品1件で正規化適用→連携確認
3. 少量（10件程度）で本番試行
4. 全件適用
5. 連携監視（1週間）

## 9. 確認チェックリスト
- [ ] CSVバックアップ取得済
- [ ] 表記ゆれ正規化後にモール側SKU実態と照合済
- [ ] バリエーション親の zaiko_su=0 を確認
- [ ] セット親の構成情報が完全
- [ ] 循環参照ゼロ
- [ ] goods_id 30字以内
- [ ] 在庫操作を商品マスタCSVで行っていない
- [ ] Amazon item_sku は変更しない方針

品質ゲート

• 正規化ルール（strip→不可視文字除去→NFKC→ハイフン統一→大小文字統一）を明示している
• goods_id の30字制限を検出している
• 親子構造（daihyou_shouhin_code／stock_goods_id／set_flg）の参照切れ・循環参照を検出している
• バリエーション親が在庫を持つ設計を「事故源」として警告している
• セット親の販売可能数を min(子在庫/構成数量) で計算するよう促している
• 商品マスタCSVで zaiko_su を上書きしないと明示している
• 商品コード変更時の影響範囲（モール側SKU・過去受注・WMS・物流）を必ず案内している
• Amazon item_sku 変更不可を明示している
• モール側SKU実態と照合せずに正規化「だけ」で完結させていない

エッジケース

• Excel経由の0落ち：goods_id 0001234 が 1234 に化ける。テキスト型インポートで防ぐ
• JANの指数表記化：4901234567894 が 4.90123E+12 に。同じくテキスト型推奨
• stock_goods_id で在庫共有：複数goods_idが同じ stock_goods_id を指すと、どれが売れても共通在庫が減る設計。意図か事故か要確認
• モール側だけ手動修正：ネクストエンジンを通さずモール側でSKU変更すると紐付けが切れる
• Amazon SKU変更不可：item_sku は変更できない。新規SKU作成しかない
• 同期間隔約10分：在庫変更後すぐにモール側を見ても反映前。10〜15分待つ
• 連休前の集中受注：表記ゆれや紐付けミスがあると事故が一気に出る。連休前に検査を回す

注意事項

• ネクストエンジンの仕様（CSV列名・在庫加減算挙動・API）は 更新される可能性がある。最新は公式ヘルプを確認
• 商品マスタの修正は 必ずバックアップ後 に実施。テスト商品1件 → 少量 → 全件の段階展開を守る
• 在庫は商品マスタCSVで触らず、専用機能を使う
• 商品コード変更は最後の手段。代替案（表示用コード分離・履歴保持・段階移行）を必ず検討
• 顧客情報・社内仕入先情報を出力に含めない
• 在庫整合の事故検出は別スキル crossmall-inventory-sync-checker と併用

references/ 一覧

• references/master-fields.md — 商品マスタ主要項目（goods_id／親子参照／モール別SKU列）
• references/inventory-logic.md — 在庫加減算ロジックと専用機能・APIの使い分け
• references/code-change-impact.md — 商品コード変更の影響範囲と代替策
• references/mall-sku-mapping.md — モール別SKU紐付け（楽天項目選択肢／Amazon親子／Yahoo!option／Shopify Variant）
• references/normalization-patterns.md — 表記ゆれ検出パターンと正規化スクリプト
• references/set-bundle-structure.md — セット商品・組商品・バリエーション親子の構造
• references/examples.md — 表記ゆれグループ／親子事故／在庫加減算事故の実例

参考公式情報源

• ネクストエンジン公式ヘルプ「商品マスタ仕様」「在庫連携設定」「モール連携設定」
• ネクストエンジンAPI「商品マスタAPI」「在庫変更API」
• 楽天RMS「商品データ仕様」（連携先側の確認用）
• Amazon Seller Central「SKU 仕様」「ASIN／SKUの違い」
• Yahoo!ショッピング「商品データ仕様」
• Shopify Admin API「Products・Variants」