mcpField
B
bagisto-data-transfer

bagisto-data-transfer

github.com/bagistoデータ・データベース13121 回インストール2 週間前に更新
リポジトリ

bagisto-data-transfer について

Bagisto のファイル一括インポートを実装する開発スキルです。商品、顧客、税率向けに、インポーター契約や形式共通のソース、キューによるバッチ処理を解説します。

主な機能

  1. 01商品、顧客、税率のインポート
  2. 02インポーター契約と登録方法
  3. 03CSV、XLS、XLSX、XML ソース
  4. 04キューによる検証とバッチ処理
  5. 05関連付けとインデックス処理

活用シーン

  1. 01Bagisto にインポーターを追加
  2. 02停止したインポート処理の調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/bagisto/agent-skills --skill bagisto-data-transfer

インストール後、Claude Code で/bagisto-data-transferを入力して読み込まれたか確認します。

同梱ファイルimporters.mdpipeline.md

詳細

データ転送

packages/Webkul/DataTransfer は、ファイルから Bagisto に大量のレコードを取り込みます。 このパッケージには、商品、顧客、税率の 3 つのインポーターと、バッチ単位で検証、インポート、関連付け、インデックス作成を行うキュー処理のパイプラインが含まれています。

インポート専用です。 ここにはエクスポーターはありません。データのエクスポートには DataGrid 独自の機能を使用してください。詳しくは bagisto-datagrid-development スキルを参照してください。

参照ファイル

ファイル読み込むタイミング
importers.mdインポーターを作成または変更するとき — コントラクト、検証、バッチ
pipeline.mdステートマシン、キュージョブ、停止したインポートのデバッグ

レジストリ

インポーターは Config/importers.php に登録し、トップレベルの importers キーにマージします（data_transfer.importers ではありません）。

'tax_rates' => [
    'title'        => 'data_transfer::app.importers.tax-rates.title',
    'importer'     => 'Webkul\DataTransfer\Helpers\Importers\TaxRate\Importer',
    'sample_paths' => [
        'csv'  => 'bagisto-data-transfer/samples/csv/tax-rates.csv',
        'xls'  => 'bagisto-data-transfer/samples/xls/tax-rates.xls',
        'xlsx' => 'bagisto-data-transfer/samples/xlsx/tax-rates.xlsx',
        'xml'  => 'bagisto-data-transfer/samples/xml/tax-rates.xml',
    ],
],

管理画面の作成・編集画面は config('importers') を直接参照するため、新しいエントリーはビューを変更せずに形式のドロップダウンに表示されます。Import は config('importers.'.$type.'.importer') でクラスを解決します。配列キーはインポートレコードに保存される type なので、キーの名前を変更すると既存のインポートが孤立します。

4 つのサンプルパスをすべて指定してください。UI では形式ごとにサンプルをダウンロードできます。ファイルが見つからない場合は、適切なフォールバックではなくリンク切れになります。

インポーターのコントラクト

Helpers\Importers\AbstractImporter を継承し、次の 2 つのメソッドを正確に実装してください。

abstract public function validateRow(array $rowData, int $rowNumber): bool;
abstract public function importBatch(ImportBatchContract $importBatchContract): bool;

それ以外は、$validColumnNames、$masterAttributeCode、$permanentAttributes、$messages などのプロパティとして宣言するか、フックとしてオーバーライドします。importers.md を参照してください。

ソース

Helpers\Sources\ には CSV、XLS、XLSX、XML があり、いずれも AbstractSource を継承しています。AbstractSource は、行を反復処理するイテレーターであり、generateErrorReport(array $errors) を備えています。インポーターがファイルを直接開くことはありません。$this->source を読み取るため、同じインポーターですべての形式に対応できます。

必須事項

  • データを書き込む前に、行を検証します。 validateRow() は副作用のない処理にしてください。ファイル全体に対して実行され、stop-on-errors の場合はインポートが importBatch() に到達しないこともあります。
  • ファイル全体を行単位で処理せず、必ずバッチで処理してください。 AbstractImporter::BATCH_SIZE は 100 で、パイプラインはバッチごとに 1 つのジョブをディスパッチします。ファイル全体をメモリに読み込むインポーターは、この設計の利点を損ない、この機能が対応する対象のファイルサイズでは処理に失敗します。
  • Bagisto のほかの処理と同様に、書き込みにはリポジトリを使用してください。
  • すべてのメッセージで、23 のすべてのロケールにおいて、data_transfer:: 名前空間の trans() を使用してください。
  • isLinkingRequired() / isIndexingRequired() を実態に即して宣言してください。 true を返すと、バッチごとにキューのステージが追加されます。関連付けが必要なのに false を返すと、エラーが発生しないままレコードの関連付けが不完全な状態になります。
  • 検証後の処理にはキューが稼働している必要があります。QUEUE_CONNECTION=sync の場合、インポート全体がリクエスト内で同期実行されるため、実際のファイルではタイムアウトします。

必須サブスキル： 変更完了とする前に、bagisto-change-verification を使用してください。

コメント

Markdown 対応