Summary
この文書の要点
- シートの見た目ではなく、取り込み契約として列定義を持つ。
- 型変換と業務検証を分け、エラー位置を行番号と列名で返す。
- 列名、型、必須、正規化、重複、参照整合性を段階的に検証する。
- エラーは開発者向けではなく、行番号と修正方法が分かる形で返す。
どこが設計の難所か
シート取り込みは最初の成功体験が早い反面、運用が始まると列名の変更、日付形式の揺れ、数値に混ざる文字、非表示列、メモ行などで失敗します。失敗理由が技術者にしか読めないと、現場で修正できません。
業務担当者が直接編集するシートでは、完全な入力制御はできません。また、Google Sheets APIの取得結果は文字列中心になるため、アプリ側で型変換と検証を明示する必要があります。
Google Sheetsは業務担当者が扱いやすい一方で、空白、全角半角、日付形式、結合セル、見出し変更、数式結果など、取り込み側から見ると揺れが多い入力です。きれいなCSVを前提にすると、運用で必ず壊れます。
境界をどう切るか
取り込み処理では、列マッピング、型変換、必須チェック、業務ルール検証、差分検出を段階に分けます。Zodなどのスキーマは型変換後のデータに使い、変換できなかった値は行番号と列名つきで返します。
設計では、読み取り、正規化、構文検証、業務検証、登録の段階を分けます。Zodなどのschemaは構文検証には向きますが、既存DBとの重複や参照チェックは別の層で扱う方が責務が明確になります。
実装で効く細部
列定義には、表示名、内部キー、必須有無、変換関数、説明を持たせます。取り込み前にヘッダーを検証し、想定外の列や不足列を報告します。差分検出には外部IDや自然キーを使い、作成、更新、無視、削除候補を分けます。
取り込み処理では、ヘッダーを内部フィールドへマッピングし、値はtrim、空文字のnull化、日付のISO化、数値の桁区切り除去を行ってから検証します。エラーは`row_number`、`column_name`、`code`、`message`、`suggested_value`を持つ配列として返すと、画面側で修正支援しやすくなります。
- シートの列順に依存せず、ヘッダー名と許容別名でマッピングする。
- 警告とエラーを分け、登録不可と要確認を同じ扱いにしない。
- インポート結果には入力ファイルのハッシュと検証バージョンを残す。
壊れ方を観測する
検証では、空白行、列順変更、日付形式違い、重複キー、必須欠落、古いテンプレートをテストデータに含めます。エラー出力はJSONだけでなく、担当者が読めるCSVや画面表示でも確認します。
検証では、正常な表だけでなく、列名違い、空行、重複、数式エラー、日付形式の混在、権限不足をサンプルとして持ちます。実データに近い汚れ方をテストに入れるほど、運用時の問い合わせが減ります。
捨てた選択肢とトレードオフ
厳しく検証すると取り込みは止まりやすくなります。緩くすると誤データが入ります。重要データはエラーで止め、軽微な表記揺れは警告として取り込むなど、業務影響でレベルを分けると運用しやすくなります。
厳密にしすぎると取り込み前の修正負担が増え、緩くしすぎると後工程で壊れます。最初の取り込みでは警告として受け入れ、登録確定時に厳しくするなど、業務フローに合わせた段階検証が有効です。
現場に残す判断軸
Google Sheets連携の品質はAPI呼び出しではなく、検証とフィードバックで決まります。現場が直せるエラーを返す設計が、シート運用をシステムに組み込む前提になります。
Google Sheets取り込みの品質は、API連携の成功ではなく、入力の揺れをどう説明し、どう直してもらえるかで決まります。検証結果をデータとして設計することが、壊れにくさにつながります。
