unopim-data-transfer

UnoPim 数据传输

导入/导出以排队、分批、跟踪状态的流水线形式运行于 packages/Webkul/DataTransfer。流水线通过配置实例化你的类——签名错误会在运行时导致致命错误，而臆造的方法则会被静默忽略。编写之前，请对照基类核实每个重写的方法。

必备背景： 使用 unopim-standards 遵循 Laravel 13 / PHP 8.4 的惯用写法、注释、本地化和规模规则。使用 unopim-exec 确定此工作区中的命令。声明任何更改已完成之前，请使用 unopim-verify。对于包脚手架、服务提供者、凭据和 cURL 客户端，请使用 unopim-plugin-development。

参考文件

文件	何时阅读
pipeline.md	作业流程、完整状态机、队列、模型，以及排查卡住或失败的作业
exporters.md	构建 Exporter、流式数据源，以及 exporters.php / quick_exporters.php 接线
importers.md	构建 Importer、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)
具有 validate(array $filters): array 方法的 AbstractValidator	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++。切勿混用——作业摘要会按名称报告这些计数。
• 异步四项（async、track_by、label_by、list_route）仅在由路由提供选项的选择字段中必需。固定列表使用静态内联 options 即可——核心代码在 packages/Webkul/DataTransfer/src/Config/exporters.php 中以这种方式提供了 file_format 和 date_format。
• 大型实体的导出源必须采用流式处理：重写 getResults()，使用基于 id 游标（键集）的数据源，例如 packages/Webkul/DataTransfer/src/Helpers/Sources/Export/ProductCursor.php。继承的默认实现会将 source->all() 完整载入内存——仅适用于小型实体（语言区域、货币、渠道）。
• 批次中的批量存在性查询使用 array_chunk($keys, 1000) + whereIn，绝不能每行执行一次查询——参见 packages/Webkul/DataTransfer/src/Helpers/Importers/Product/SKUStorage.php。
• 状态机除了 pending/validated/processing/completed/failed，还包括 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；仅当真实的 list_route 返回以 track_by/label_by 为键的对象时，才使用异步四项
• 依赖选择字段使用 depends_on
• 在服务提供者中合并配置文件（exporters、importers、quick_exporters 键）——示例：packages/Webkul/AiAgent/src/Providers/AiAgentServiceProvider.php
• 对应操作时递增计数器；在作业报告中核实摘要计数
• 新增的管理路由（例如 list_route 端点）须注册在 ['admin'] 中间件下并受 ACL 保护——按路由名称进行的强制执行采用失败放行策略