Summary
この文書の要点
- 行番号、列名、入力値、修正理由をセットで返す。
- エラーと警告を分け、取り込み可否を明確にする。
- 行番号、列名、エラー種別、修正例、重大度を構造化して返す。
- 構文エラー、型変換エラー、業務ルール違反、重複を別カテゴリにする。
どこが設計の難所か
CSV取り込みで「validation failed」とだけ表示されても、利用者は何を直せばよいか分かりません。技術者がログを見ないと解決できない取り込みは、日常業務に乗りません。
CSVには複数のエラーが同時に含まれます。最初の1件で止めると修正と再取り込みを何度も繰り返すことになります。一方で、大量エラーをそのまま表示しても読めません。
CSV取り込みで「エラーがあります」とだけ表示しても、利用者はどこを直せばよいか分かりません。開発者向けの例外メッセージをそのまま出すと、情報としても安全性としても不十分です。
境界をどう切るか
取り込み処理では、構造エラー、行エラー、警告を分けます。構造エラーは処理を止め、行エラーは一覧化し、警告は取り込み可能だが確認が必要なものとして扱います。
設計では、パース、ヘッダー検証、型変換、業務検証、登録を段階化し、それぞれの失敗を同じエラーレポート形式へ変換します。画面はこのレポートを使って、行ごとの修正導線を提供します。
実装で効く細部
エラーレポートには、行番号、列名、入力値、期待形式、修正例、エラーコードを含めます。React画面ではエラー行を絞り込み、CSVとしてダウンロードできるようにします。テンプレート版をヘッダーやメタデータで確認します。
エラーレポートは`row_number`、`column_key`、`column_label`、`code`、`message`、`severity`、`suggestion`を持つ配列にします。React側ではCSVの該当行をハイライトし、エラーのみのダウンロードや修正後再アップロードを支援します。
- ファイル全体エラーと行単位エラーを分ける。
- 警告は登録可能、エラーは登録不可など、重大度ごとの扱いを明確にする。
- 内部の例外名やSQLエラーを利用者向けメッセージへ直接出さない。
壊れ方を観測する
検証では、複数行エラー、テンプレート違い、重複キー、警告のみのファイル、エラー修正後の再取り込みを確認します。文言が業務担当者に伝わるかもレビュー対象にします。
検証では、文字コード違い、列不足、空値、数値形式、日付形式、重複、参照先なしをサンプル化します。エラー件数が多い場合の表示、ダウンロード、ページングも確認します。
捨てた選択肢とトレードオフ
親切なエラーを作るには実装コストがかかります。ただし、取り込み業務ではエラー対応が運用時間の大半になることがあります。最初からレポート設計に投資する価値があります。
詳細なエラーを返すほど修正しやすくなりますが、実装とメッセージ管理の負荷は増えます。最初は登録を止める重大エラーから始め、警告や修正候補は利用頻度に応じて追加するのが現実的です。
現場に残す判断軸
CSV取り込みは、成功時より失敗時の体験が重要です。利用者が自分で直せるエラーレポートを返すことで、システム運用の負担を大きく減らせます。
CSV取り込みのエラーは、失敗の通知ではなく修正作業のUIです。エラーを構造化すると、取り込み機能そのものの信頼性が上がります。
