## ファイルインポート (File Import)

「外部ファイルをイン力とする」データフローを定義するために使用されます: 形式、検証、解析、データベースへの永続化、レシート、およびエラー処理。

適用シナリオ:
- 一括作成/更新 (顧客、製品、クォータ、ホワイトリスト)
- 銀行取引明細書のインポート、履歴データの移行

推奨される情報:
- ファイル形式: CSV/XLSX/JSON、エンコーディング、区切り文字、ヘッダー
- フィールドマッピング: 列名 → ターゲットフィールド、必須/オプション、デフォルト値
- 検証ルール: タイプ、範囲、一意性、行間/テーブル間の検証
- 処理戦略: すべて成功するかすべて失敗するか / 部分的な成功、エラー行のフィードバック
- べき等性と重複排除: インポートバッチ番号、重複行の処理

ファイルとセキュリティ要件 (重複防止 / 上書き防止 / ウイルス対策 / 命名規則):
- 上書き防止: アップロードされたファイルは「追加のみ」のオブジェクトストレージパスに書き込まれる必要があり、元のファイル名で直接上書きすることは禁止されています。ビジネスデータの永続化は「新しいインポートバッチレコードの作成 → バッチによる挿入」である必要があり、履歴バッチファイルの直接上書きは禁止されています。
- 重複防止 (ファイルレベル): ファイルのハッシュ (SHA-256など) を計算し、`(tenant_id, uploader_id, file_hash)` をべき等性キーとして使用します。ヒットした場合は「既存のインポートバッチ番号」を返し、繰り返し永続化しないでください。
- 重複防止 (コンテンツレベル): 「ビジネスべき等性キー」 (例: `external_id` / `code` / `(org_id, code)`) を定義する必要があります。同じファイル内の重複行は、エラー行のフィードバックで識別可能である必要があります。バッチ間の重複は、スキップ / 上書き / エラー (明示的である必要があります) の戦略に従う必要があります。
- ウイルス対策: アップロード後に隔離領域に入り、ウイルススキャン/タイプスニッフィングが完了した後にのみ解析および永続化します。スキャンの失敗/タイムアウトは拒否され、監査される必要があります。
- ファイルタイプのホワイトリスト: 明示的にリストされた拡張子とMIMEタイプ (例: `.csv/.xlsx/.json`) のみを許可し、ファイルヘッダーのスニッフィングを実行し、「偽装された拡張子」を禁止します。
- サイズと行の制限: 最大サイズ (MB)、最大行数、最大列数を指定します。超過した場合は拒否してプロンプトを表示する必要があります。
- エンコーディングとフォーマット: CSVの場合は、エンコーディング (UTF-8推奨)、区切り文字、引用符のエスケープ、改行ルールを指定します。XLSXの場合は、シート名 (または最初のシート) とヘッダー行の位置を指定します。
- ファイル命名規則 (推奨): `<system>_<object>_<yyyymmdd>_<batch>.<ext>`; 表示と検索のみに使用され、べき等性には使用されません。バックエンドの最終的なストレージ名には、競合を避けるためにバッチ番号を含める必要があります。

ファイルの内容とデータマッピング (列/フィールドレベルまで明示的である必要があります):

マッピングテーブル (例):
| ソース列 (ヘッダー) | 例の値 | ターゲットフィールド (DB/API) | タイプ | 必須 | デフォルト | 変換ルール | 検証ルール | 備考 |
|---|---|---|---|---|---|---|---|---|
| customer_code | C001 | customer.code | string | Y | - | trim+upper | 一意; 長さ<=32 | ビジネスべき等性キー |
| customer_name | Alice | customer.name | string | Y | - | trim | 長さ<=128 | - |
| phone | 13800000000 | customer.phone | string | N | - | normalize_e164 | 有効な形式 | - |
| level | VIP | customer.level | enum | N | Normal | map: VIP->VIP | Enum検証 | - |

解析と永続化のガイドライン (明確にすることを推奨):
- ヘッダーの配置: ヘッダーのエイリアスを許可するか？ 列の欠落を許可するか？ 固定された列の順序？
- データ型: 空の値/空の文字列/NULLの判定。日付とタイムゾーン。小数の精度と丸め規則。
- エラーのフィードバック: エラー行には「行番号 + 元の値 + エラーコード + エラーメッセージ + ターゲットフィールド」が含まれている必要があり、ダウンロード (CSV/JSON) を提供する必要があります。
- 部分的な成功戦略: 「成功した行の永続化 + 失敗した行のフィードバック」と「バッチロールバック」を明確にします。部分的な成功がサポートされている場合、べき等性キーは、再アップロード時に重複して永続化されないことを保証する必要があります。