CSVインポート設計の実務｜バリデーション・差分更新・エラー返却を運用で詰まらせない

CSVインポートは「あると便利」ですが、運用に入ってから壊れやすい機能でもあります。
項目の増減で列がズレる、重複で二重登録される、上書きの範囲が曖昧で事故る、エラーが分からず担当者が詰む――この辺りを放置すると、結局は手入力に戻ります。
本記事では、CSVインポートを“運用で回る仕組み”として設計するための要点を整理します。

1. 最初に決める：CSVの“契約”を固定する（曖昧なCSVは必ず事故る）

CSVインポートは、入力フォームよりも厳密な仕様が必要です。最低限、次を固定します。

• 文字コード：UTF-8（BOM有無も方針化）
• 区切り：カンマ固定（タブ区切り等は別扱い）
• ヘッダ：ヘッダ行を必須にするか、列順固定にするか
• 必須列：何が欠けたら取り込まないか

「列順固定」で始めると簡単ですが、項目追加に弱いです。中長期で項目が増えそうなら、ヘッダ名でマッピングする設計が安全です。
製品カタログのような属性が増えがちな領域は、カテゴリ設計（カテゴリ構造）や検索項目（仕様項目設計）と同じで、後から増える前提で組む方が手戻りが減ります。

2. バリデーションは3段階に分ける（1回で全部やろうとしない）

2-1. 形式チェック（項目単体）

数値・日付・必須・桁数・禁則文字など。ここは即時に弾けます。
エラー表示の考え方は エラーメッセージ設計 と同じで、「何を直すべきか」が一読で分かる文言にします。

2-2. 行整合（行内の関係）

例：開始日が終了日より後、価格が負、数量が0、など。
「行内の複数項目で成立しているか」をここで見ます。

2-3. 参照整合（マスタとの整合）

拠点ID、カテゴリID、担当者IDなど、参照先が存在するか。ここで落とすと運用が止まりやすいので、
「不明な値は取り込まずエラーにする」か「仮登録に落とす」かを決めます。権限の絡みは 権限設計 と整合させると揉めません。

3. 差分更新の肝：ユニークキーを“業務のキー”で決める

差分更新（追加・更新・削除）をやるなら、ユニークキーが曖昧だと破綻します。
よくあるのは「商品コード」「拠点＋品番」「顧客ID」などの業務キーです。型番・品番系は 入力補助 と同じで表記ゆれが出るので、正規化ルールを決めてください。

削除は特に危険です。原則は「ソフトデリート」か「無効化フラグ」で運用し、復旧できる形にしておくと安全です。復旧の考え方は バックアップと復旧 に揃えると説明しやすいです。

4. プレビューとエラー返却：運用で一番効くのはここ

CSVインポートが嫌われる理由の多くは「何が悪いか分からない」です。
最低限、次を用意すると現場が回ります。

• プレビュー：取り込み結果（追加/更新/無視/エラー）を一覧で見せる
• エラー返却：行番号、列名、入力値、理由、修正例
• 部分取り込み：エラー行だけ除外して取り込むか、全体を止めるか選べる

部分取り込みは便利ですが、整合が壊れることがあります。問い合わせやステータス管理のように連動が多い領域では、運用ルールと同じく「途中状態が存在してよいか」を先に決めてください。

業種別でCSVが効く場面（例）

卸売・商社（BtoB）

商品マスタや価格条件、在庫（見込み含む）など、CSVの需要が大きいです。業務像は 卸売・商社向け を前提に、差分更新と無効化（廃番）をセットで設計すると現場が楽になります。

物流（拠点・料金表）

拠点やエリア、料金テーブルが定期的に変わる運用では、CSV更新がボトルネックになりがちです。料金系は 料金テーブル管理 の考え方に揃えて、適用日（いつから有効か）も一緒に持つと事故が減ります。

まとめ

CSVインポートは、形式チェックだけでは運用で壊れます。
契約（文字コード・ヘッダ・必須列）を固定し、バリデーションを3段階に分け、差分更新は業務キーで守る。
最後に、プレビューと「どの行の何が悪いか」が分かるエラー返却を用意する。
ここまで入れて初めて、CSVが“現場の武器”になります。