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. 01为 Bagisto 添加导入器
  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 批量导入记录。 此包提供三个导入器——产品、客户和税率——以及一个队列 流水线，可分批验证、导入、关联和建立索引。

仅支持导入。 此处没有导出器；导出数据由 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，因此重命名键会导致现有导入记录失去关联。

请提供全部四种格式的示例文件路径。界面会为每种格式提供示例文件下载； 文件缺失时，链接会失效，而不是优雅地回退。

导入器契约

扩展 Helpers\Importers\AbstractImporter，并准确实现两个方法：

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。该类是一个行迭代器，并提供 generateErrorReport(array $errors)。导入器不会自行打开文件—— 它会读取 $this->source，因此同一个导入器可处理所有格式。

必须遵守的要求

  • 写入任何内容前，必须先验证各行。 validateRow() 必须 没有副作用：它会遍历整个文件，并且在 stop-on-errors 模式下，导入 可能永远不会执行到 importBatch()。
  • 必须分批处理，绝不能逐行处理整个文件。 AbstractImporter::BATCH_SIZE 为 100，流水线会为每个批次派发一个任务。 将整个文件载入内存的导入器违背了设计初衷，也无法处理此功能所针对的文件大小。
  • 写入必须通过存储库，与 Bagisto 中的其他写入操作一样。
  • 所有消息都必须通过 trans()，使用 data_transfer:: 命名空间，并覆盖全部 23 种语言环境。
  • 如实声明 isLinkingRequired() / isIndexingRequired()。 返回 true 会为每个批次增加一个队列阶段；如果需要关联却返回 false，记录就会处于关联不完整的状态，且不会报错。
  • 任何超出验证阶段的操作都要求队列正在运行。 使用 QUEUE_CONNECTION=sync 时，整个导入会在请求中内联执行，处理实际文件时会超时。

必需的子技能： 在宣布任何更改完成前，使用 bagisto-change-verification。

评论

支持 Markdown