MakeShop 商品CSV 検証

概要

MakeShop の商品データCSV／オプションデータCSV／在庫CSVは、列順序・文字コード・改行コード・BOM・ダブルクォートエスケープ・goods_id の整合 が原因でアップロード失敗や表示不全が頻発する。本スキルはCSV データを受け取り、エラー原因を特定し、修復コマンド（iconv／sed／awk）と検証手順を提示する。

加えて MakeShop 特有の 独自タグ（フリースペース1-10） によるHTML差込み破損も扱う。商品ページのテンプレに <!--MS:フリースペース1--> 等の擬似タグで差し込まれる仕組みのため、CSV側のHTML が壊れると商品ページのレイアウトごと崩壊する。

★最重要原則

「アップロード失敗の99%は (1) 文字コード／BOM／改行 (2) ダブルクォートのエスケープ (3) goods_id の不一致 のいずれか」。まず判定コマンド（file -I hexdump -C wc -l awk -F,）で物理的な構造を確認し、その後に意味的な検証（goods_id 重複・カテゴリ存在・価格数値型）に進む。

CSV を Excel で開いて保存しない。Shift_JIS化／先頭0落ち／改行コード変換／BOM付与など、Excel 経由で起きる事故が最多。VS Code 等のテキストエディタで開き、文字コード・改行コードを常時表示する運用に統一する。

知識ベース

トピック	references
商品データCSV の必須列／任意列／文字数目安／列順序固定 or ヘッダ識別／商品分類（カテゴリ）の指定方法（分類IDか分類パスか）／後から変更してはいけない列（goods_id・商品分類）	references/product-csv-columns.md
オプションデータCSV の主要列／オプションの2階層モデル（オプション項目／オプション値）／goods_id 紐付け／アップロード順序（商品先・オプション後）／重複・矛盾チェック／オプション数上限	references/option-csv-columns.md
文字コード（Shift_JIS／UTF-8 BOMなし／UTF-8 BOMあり）／改行コード（CRLF／LF）／BOM の判定（file -I / hexdump）／よくある事故5パターン／修正フロー／iconv・sed・awk コマンド	references/encoding-troubleshooting.md
独自タグ（フリースペース1-10）の典型形（<!--MS:フリースペース1-->）／用途例／HTMLエスケープ（"" 二重化・カンマ・改行）／典型破損パターン4種／更新運用フロー	references/free-space-tags.md
修復実例（列ずれ／goods_id 重複／フリースペース反映なし／文字化け／JAN先頭0落ち の5事例）	references/examples.md

仕様（列名・文字コード指定・改行コード指定・上限値）は MakeShop の管理画面のCSVインポート画面・公式ヘルプ で最新確認すること。プラン・時期により異なる。

処理フロー

Step 1：何のCSV か特定

• 商品データCSV（商品マスタ本体）
• オプションデータCSV（色・サイズ等のバリエーション、独立ファイル）
• 在庫数CSV（在庫差分／上書きの別運用）
• フリースペース1-10 に HTML を流し込む更新

ユーザーから「どのCSV か」が不明なら、ヘッダ行を見て判定する。

Step 2：物理構造の判定（修復の前提）

# 文字コード判定
file -I products.csv

# BOMの有無（先頭3バイトが ef bb bf なら UTF-8 BOMあり）
hexdump -C products.csv | head -1

# 行数
wc -l products.csv

# 列数（各行が同じ列数か）
awk -F, '{print NF}' products.csv | sort -u

判定結果に基づき、MakeShop の要求仕様（管理画面のCSVガイドの最新値）と突き合わせる。

Step 3：文字コード／改行コード／BOM の修正

references/encoding-troubleshooting.md の変換表に従う：

現状 → 要求	変換コマンド例
UTF-8 BOMあり → UTF-8	sed -i '1s/^\xEF\xBB\xBF//' file.csv
UTF-8 → UTF-8 BOMあり	printf '\xEF\xBB\xBF' > out.csv && cat in.csv >> out.csv
UTF-8 → Shift_JIS (CP932)	iconv -f UTF-8 -t CP932 in.csv -o out.csv
Shift_JIS → UTF-8	iconv -f CP932 -t UTF-8 in.csv -o out.csv
LF → CR+LF	awk 'sub("$", "\r")' in.csv > out.csv
CR+LF → LF	tr -d '\r' < in.csv > out.csv

変換後に再度 file -I と hexdump -C で確認、少数行（10件程度）でテストアップロード。

Step 4：CSV エスケープ（ダブルクォート・カンマ・改行）

ヘッダの後ろに \xEF\xBB\xBF が付いていない確認の次は、本文の構造チェック：

• 列値全体を " で囲んでいる場合、内部の " を "" に二重化

  OK：item-001,"<a href=""https://example.com"">詳細</a>" NG：item-001,"<a href="https://example.com">詳細</a>"

• カンマ , を含む値は " で囲む

• 改行を含む値は " で囲んだ中に収める（RFC 4180 準拠だが MakeShop パーサが対応しているか管理画面で確認、ダメなら <br> に置換）

各行の列数が一致しない場合は、エスケープ漏れの可能性が最も高い。

Step 5：goods_id の検証（商品データCSV）

• すべて埋まっているか
• 半角英数・記号のみ（全角混入なし）
• 重複がないか
• 大文字小文字に揺れがないか

# goods_id 列（仮に1列目）の重複検出
awk -F, 'NR>1 {print $1}' products.csv | sort | uniq -d

Step 6：他カラムの意味検証

• 商品名がすべて埋まっている
• 商品分類が 既存カテゴリと一致（事前に管理画面で分類を作成済か）。CSV側で新規指定しても作成されない場合あり
• 販売価格が数値（カンマ「,」や「円」が混入していない）
• 在庫管理区分「する」の場合、在庫数が数値で埋まっている
• 公開／非公開フラグが店舗仕様の指定値
• JANコード列：13桁文字列（先頭0落ちなし、jan-code-checker 併用でチェックデジット検証推奨）

Step 7：オプションデータCSV の検証（該当時）

references/option-csv-columns.md に従う：

• goods_id が商品データCSV と完全一致（大文字小文字・前後スペースの違いも別物扱い）
• アップロード順序：商品データCSV → オプションデータCSV（逆順だと「該当商品なし」エラー）
• 同一goods_id 内でオプション値の重複なし
• 価格差列：数値のみ（「+500円」「500.5」等の混入NG、整数指定の場合）
• 在庫数と在庫管理区分の矛盾なし
• オプション数上限（項目5〜10／値30〜50／組合せ100〜200程度、店舗プランで異なる）

# goods_id の差分検出
diff <(awk -F, 'NR>1 {print $1}' products.csv | sort -u) \
     <(awk -F, 'NR>1 {print $1}' options.csv | sort -u)

Step 8：フリースペース1-10 の検証（HTML差込み）

references/free-space-tags.md の破損パターン：

• パターンA「列数不一致」：エスケープ漏れ
• パターンB「アップロード成功なのに反映されない」：管理画面で対象列が空 or 文字化け → Step 2-3に戻る
• パターンC「商品ページレイアウト崩壊」：HTMLタグの閉じ忘れ／CSSの暴発／改行残骸
• パターンD「特殊文字表示不可」：< > & の実体参照エスケープが必要かをテンプレ側と合わせる

HTML を入れる場合は、テンプレ側のクラス名・構造を確認したうえで CSV化する。

Step 9：修復後の検証とテストアップロード

• file -I hexdump -C wc -l awk -F, の判定を再実行
• 少数行（10件程度）でテストアップロード
• 商品ページの公開プレビューで実機表示確認（フリースペース差込み位置・レイアウト）
• 全件アップロード前にバックアップ（Git or 日付付与）

代表例：「アップロード成功なのにフリースペース1が反映されない」

現象：CSV はアップロード成功表示、商品マスタ管理画面で確認すると フリースペース1の値が空欄。

判定手順：

$ file -I products.csv
products.csv: text/csv; charset=utf-8

$ hexdump -C products.csv | head -1
00000000  ef bb bf 67 6f 6f 64 73  5f 69 64 2c e5 95 86 e5

→ UTF-8 BOMあり。MakeShop が UTF-8 BOMなしを要求しているなら、先頭3バイトの EF BB BF のせいで列名 goods_id が ?goods_id と認識され、マッピング失敗 → 列値も無視されている。

修復：

$ sed -i '1s/^\xEF\xBB\xBF//' products.csv
$ hexdump -C products.csv | head -1
00000000  67 6f 6f 64 73 5f 69 64  2c e5 95 86 e5 93 81 e5

→ BOM除去後、ヘッダ先頭が goods_id で始まることを確認、テストアップロードで反映確認。

他4事例（列ずれ／goods_id 重複／文字化け／JAN先頭0落ち）の完全版は references/examples.md。

出力フォーマット

# MakeShop CSV 検証：[ファイル名]

## 0. 前提
- CSV種別：商品データ / オプションデータ / 在庫 / フリースペース更新
- 想定操作：新規登録 / 全件更新 / 差分更新
- 管理画面の要求仕様：文字コード___ / 改行___ / BOM___（最新確認した値）

## 1. 物理構造の判定
```
file -I [file]
→ [結果]

hexdump -C [file] | head -1
→ [結果]

wc -l [file]
→ [結果]

awk -F, '{print NF}' [file] | sort -u
→ [結果]
```

## 2. 検出された問題
| # | レベル | 行／列 | 内容 | 修復案 |
|---|---|---|---|---|
| 1 | 致命 |  |  |  |
| 2 | 警告 |  |  |  |
| 3 | 注意 |  |  |  |

## 3. 修復コマンド（実行順）
```sh
# 1. バックアップ
cp [file] [file].bak

# 2. 修復
[コマンド]

# 3. 検証
file -I [file]
hexdump -C [file] | head -1
```

## 4. 意味検証（goods_id・カテゴリ・価格）
- [ ] goods_id：すべて埋まっている／半角英数のみ／重複なし
- [ ] 商品名：すべて埋まっている
- [ ] 商品分類：既存カテゴリと一致
- [ ] 販売価格：数値型（「円」「,」混入なし）
- [ ] 在庫数：在庫管理「する」なら数値で埋まっている

## 5. オプションCSV（該当時）
- [ ] goods_id が商品データCSV と完全一致
- [ ] アップロード順序：商品 → オプションの順
- [ ] 同一goods_id 内でオプション値の重複なし
- [ ] 価格差列：数値のみ
- [ ] 組合せ数：店舗プランの上限以内

## 6. フリースペース1-10（HTML差込み・該当時）
- [ ] ダブルクォート `"` を内部で使う箇所は `""` に二重化
- [ ] カンマを含む値は `"` で囲み
- [ ] HTML タグの開閉対応
- [ ] テンプレ側の差込み位置とクラス名を確認済
- [ ] 改行は `"` 囲み内 or `<br>` に置換

## 7. テストアップロード手順
1. バックアップ取得
2. 10件程度の縮小CSV作成
3. 管理画面でテストアップロード
4. 公開プレビューで実機表示確認
5. 問題なければ全件アップロード

## 8. 再発防止
- CSV編集は VS Code 等で（Excel は最終確認のみ）
- 文字コード・改行コードを常時表示
- Git or 日付フォルダで世代管理

品質ゲート

• file -I と hexdump -C で物理構造を実測した
• MakeShop 管理画面の最新要求仕様（文字コード／改行／BOM）を確認した
• 各行の列数が一致している（awk -F, '{print NF}' の出力が単一値）
• goods_id：半角英数のみ、重複なし、全角混入なし
• 商品分類が事前に管理画面で作成済（CSV側で新規指定しても作成されない場合あり）
• 価格・在庫数が数値型（カンマ・「円」混入なし）
• オプションCSV の goods_id が商品データCSV と完全一致
• アップロード順序：商品 → オプション の順（逆順は失敗）
• フリースペースに HTML を入れる場合、エスケープ規則とテンプレ側構造を確認済
• バックアップ（Git or 日付付与）を取得済
• 修復後に10件規模のテストアップロード→公開プレビュー確認を経た

エッジケース

• goods_id を後から変更したい：URL・過去注文履歴・SEO評価に影響。原則変更しない。やむを得ない場合は旧URLからの301リダイレクト計画とSearch Consoleの再クロール申請をセット
• 商品分類を変更したい：パンくず・URL構造変更。SEO評価が一旦リセットされる前提で計画
• JAN先頭0落ち（Excel 由来）：列の書式を「文字列」に、VS Code で編集。CSV内 ="0490123456789" の書式強制は MakeShop が受けるかを確認
• 機種依存文字（①㈱㊤）：Shift_JIS／UTF-8 のやりとりで化ける。商品名では (1) 株式会社 に置換する運用
• 改行コード混在（CRLFとLFが混在）：複数人編集で発生。VS Code 右下で統一、または awk 'sub("$", "\r")' で CRLF統一
• オプション組合せ数が上限超え：上限を超えると一部のオプションが表示されない。プラン依存（項目5〜10／値30〜50／組合せ100〜200程度）

注意事項

• MakeShop の CSV列名・文字コード指定・改行コード指定・上限値 はプラン・時期で変動する。本ファイルの記述は2026年5月時点の整理であり、最終的に管理画面のCSVインポート画面とCSVガイドで最新確認すること
• CSVは Excel で開いて保存しない。Shift_JIS化・先頭0落ち・BOM付与・改行コード変換の事故が起きる。VS Code 等のテキストエディタを標準に
• 本番アップロード前のバックアップは必須。Git or 日付フォルダで世代管理
• 在庫数CSVは「差分」と「全件上書き」を区別。商品データCSVは通常「上書き」だが、店舗仕様で挙動が異なる場合あり
• goods_id・商品分類は後から変更すると影響大。SEO・受注運用への影響を確認してから実施

references/ 一覧

• references/product-csv-columns.md — 商品データCSV の必須／任意列・文字数目安・列順序・カテゴリ指定方法・変更不可列
• references/option-csv-columns.md — オプションデータCSV の主要列・2階層モデル・goods_id 紐付け・アップロード順序・上限
• references/encoding-troubleshooting.md — 文字コード・改行・BOM の判定と修正（iconv／sed／awk・5パターンの事故と対策）
• references/free-space-tags.md — フリースペース1-10 と擬似タグ（<!--MS:フリースペース1-->）・HTMLエスケープ・破損パターン4種
• references/examples.md — 修復実例（列ずれ／goods_id 重複／フリースペース反映なし／文字化け／JAN先頭0落ち）

参考公式情報源

• MakeShop 公式ヘルプ／CSVインポートガイド（商品データ／オプションデータ／在庫CSV）
• RFC 4180「Common Format and MIME Type for Comma-Separated Values (CSV) Files」
• Unicode Consortium「UTF-8, UTF-16, UTF-32 & BOM」