unopim-data-transfer

UnoPim データ転送

インポート／エクスポートは、packages/Webkul/DataTransfer でキューに登録され、バッチ処理され、状態が追跡されるパイプラインとして実行されます。このパイプラインは設定を通じてクラスをインスタンス化するため、シグネチャを誤ると実行時に致命的なエラーになり、存在しないメソッドを追加しても呼び出されずに無視されます。実装する前に、オーバーライドするすべてのメソッドを基底クラスと照らし合わせて確認してください。

必須の事前知識： Laravel 13／PHP 8.4 の慣例、コメント、ローカライズ、スケールに関するルールには unopim-standards を使用してください。このワークスペースで使うコマンドの確認には unopim-exec を使用してください。変更が完了したと報告する前に、unopim-verify を使用してください。パッケージのひな型作成、プロバイダー、認証情報、cURL クライアントには unopim-plugin-development を使用してください。

参照ファイル

ファイル	読むタイミング
pipeline.md	ジョブの流れ、状態遷移の全容、キュー、モデル、停止または失敗したジョブのデバッグ
exporters.md	エクスポーターの作成、ソースのストリーミング、exporters.php ／ quick_exporters.php の配線
importers.md	インポーターの作成、importers.php の配線、チャンク単位の検索、エラーコード
validators.md	ジョブバリデーター — 宣言型ルール、命名、配線

存在しない API と実際の API

以前のドキュメントには、コードベースのどこにも存在しないメソッドが記載されていました。左の列にあるものは絶対に書かないでください。右の列がコアに実装されている API です。

存在しない API（致命的なエラーまたは呼び出されないコード）	実際の API
initializeExport()	initilize() — コアでスペルミスがあります。AbstractExporter では空のメソッドで、exportBatch() がバッチごとに一度呼び出します
$this->getFilterValue('credential')	$this->getFilters()['credential']
$this->initializeBatch($batch)	なし — exportBatch() は Event::dispatch に続いて $this->initilize() を呼び出して開始します
$this->saveBatchSummary($batch, $filePath)	$this->updateBatchState($batch->id, Export::STATE_PROCESSED)
AbstractValidator の validate(array $filters): array	Validators\JobInstances\Default\JobValidator の validate(array $data, array $options = []): void — ValidationException をスローします
importBatch(array $items): void	importBatch(JobTrackBatchContract $batch): bool と validateRow(array $rowData, int $rowNumber): bool — どちらも抽象メソッドで、どちらも実装が必要です
UNOPIM_ENTITY_NAME、ACTION_ADD、ACTION_UPDATE、CODE_ALREADY_EXIST、CODE_NOT_EXIST の各定数	参照する箇所はありません — 実際の慣例は ERROR_* 文字列コードと BATCH_SIZE です
フィルターキー 'dependent' => ['locale']	'depends_on' => ['field' => ..., 'as' => ...] — dependent は無視されます

コアでは initilize() と getSkippedtemsCount() のスペルミスがそのまま使われています。サブクラスでも同じスペルを使用してください。スペルを「修正」すると、コアが呼び出さない新しいメソッドが作られます。

厳守事項

• エクスポーターは Webkul\DataTransfer\Helpers\Exporters\AbstractExporter を継承します。インポーターは Webkul\DataTransfer\Helpers\Importers\AbstractImporter を継承し、JobTrackBatchRepository を parent::__construct() に必ず渡します。
• カウンター：作成後に $this->createdItemsCount++、更新後に $this->updatedItemsCount++、スキップ時に $this->skippedItemsCount++ を加算します。決して入れ替えないでください。ジョブのサマリーでは名前に基づいて報告されます。
• 非同期の4項目（async、track_by、label_by、list_route）が必要なのは、ルートに基づくセレクトオプションの場合のみです。固定リストには静的なインライン options が適切です。コアでは packages/Webkul/DataTransfer/src/Config/exporters.php の file_format と date_format がその方式を採用しています。
• 大規模なエンティティのエクスポートソースでは、必ずストリーミング処理を行います。packages/Webkul/DataTransfer/src/Helpers/Sources/Export/ProductCursor.php のような ID カーソル（キ​​ーセット）ソースで getResults() をオーバーライドしてください。継承したデフォルト実装は source->all() をハイドレートします。これはロケール、通貨、チャネルなど、小規模なエンティティに限り許容されます。
• バッチ内で一括存在確認を行う際は、array_chunk($keys, 1000) と whereIn を使います。行ごとにクエリを実行してはいけません。packages/Webkul/DataTransfer/src/Helpers/Importers/Product/SKUStorage.php を参照してください。
• ステートマシンには、保留中／検証済み／処理中／完了／失敗に加えて、validating（インポート）、paused、cancelled が含まれます。一時停止、再開、キャンセルは実際に動作するフローです。pipeline.md を参照してください。
• ジョブ設定の title 値と、ユーザーに表示するすべての文字列は翻訳キー（{package}::app...）にし、33すべてのロケールに反映します。
• ここで作成するコードでは、メソッド本体、配列リテラル、ルートグループ、Blade マークアップの中にコメントを記述しないでください。

チェックリスト

• エクスポーター：exportBatch(JobTrackBatchContract $batch, $filePath): bool を実装します。Event::dispatch と initilize() で開始し、updateBatchState(..., Export::STATE_PROCESSED) で終了します。
• インポーター：validateRow() と importBatch() の両方を、基底クラスと完全に一致するシグネチャで実装します。親コンストラクターを呼び出します。
• バリデーター：Default\JobValidator を継承し、{Entity}JobValidator という名前を付け、宣言的な $rules を使用します。
• getResults() は、大規模なエンティティでは ID カーソルを使ってストリーミング処理を行います。無制限の ->all()／->get() は使用しません。
• 外部 ID／SKU の照合データは、チャンク単位で事前読み込みします（array_chunk(..., 1000) と whereIn）。行ごとにクエリを実行しません。
• セレクトのフィルターフィールド：固定リストには静的な options を使用します。非同期の4項目は、track_by／label_by をキーとして持つオブジェクトを返す実際の list_route がある場合に限って使用します。
• 依存するセレクトには depends_on を使用します。
• 設定ファイルはプロバイダーでマージします（exporters、importers、quick_exporters キー）。例として packages/Webkul/AiAgent/src/Providers/AiAgentServiceProvider.php を参照してください。
• 対応するアクションでカウンターを加算します。ジョブレポートでサマリーの件数を確認します。
• 新しい管理者ルート（例：list_route エンドポイント）は ['admin'] ミドルウェア配下に登録し、ACL の対象にします。ルート名による適用制御はフェイルオープンです。