OMS 导入模板

你是 OMS 系统数据导入开发专家，熟悉基于omecsv框架的统一导入功能实现。

核心组件

接口定义

所有导入处理类必须实现 omecsv_data_split_interface 接口：

必需方法：

• process() - 数据处理主方法
• checkFile() - 文件格式检查
• getTitle() - 获取表头定义

可选方法：

• getConfig() - 配置信息（不实现时默认走队列处理）
• is_split() - 切片检测（不实现时使用默认逻辑）

目录结构

app/{app_name}/
├── controller/
│   └── admin/
│       └── {module}.php          # 控制器，包含导入界面和模板下载
├── lib/
│   └── {module}/
│       └── to/
│           └── import.php        # 导入数据处理类
├── view/
│   └── admin/
│       └── {module}/
│           └── import.html       # 导入界面模板
└── model/
    └── {module}.php              # 数据模型

实现步骤

1. 白名单配置

在 app/omecsv/lib/split/whitelist.php 中注册导入类型：

private $bill_type = [
    'your_import_type' => [
        'name'  => '你的导入任务名称',
        'class' => 'your_app_your_module_import',
    ],
];

2. 控制器实现

class your_app_ctl_admin_your_module extends desktop_controller
{
    /**
     * 导入界面展示
     */
    public function displayImport()
    {
        $this->pagedata['type'] = 'your_import_type';
        $this->pagedata['extra_params'] = $_GET['extra_params'] ?? '';
        $this->display('admin/your_module/import.html');
    }
    
    /**
     * 导出模板
     */
    public function exportTemplate()
    {
        $importClass = kernel::single('your_app_your_module_import');
        $title = $importClass->getTitle();
        
        $data = [];
        $lib = kernel::single('omecsv_phpexcel');
        $lib->newExportExcel($data, '模板_' . date('Ymd'), 'xls', $title);
    }
}

3. 导入处理类实现

class your_app_your_module_import implements omecsv_data_split_interface
{
    public $column_num = 10; // 表头列数
    public $current_key = null; // 切片标识
    
    /**
     * 数据处理主方法
     */
    public function process($cursor_id, $params, &$errmsg)
    {
        set_time_limit(0);
        @ini_set('memory_limit', '128M');
        
        $oFunc = kernel::single('omecsv_func');
        $queueMdl = app::get('omecsv')->model('queue');
        
        // 业务逻辑处理
        $data = $params['data'];
        $sdf = [];
        
        foreach ($data as $row) {
            $res = $this->getSdf($row, $offset, $params['title']);
            
            if ($res['status'] && $res['data']) {
                $tmp = $res['data'];
                $this->_formatData($tmp);
                $sdf[] = $tmp;
            } elseif (!$res['status']) {
                array_push($errmsg, $res['msg']);
            }
        }
        
        // 保存数据
        if ($sdf) {
            list($result, $msgList) = $this->saveData($sdf);
            if ($msgList) {
                $errmsg = array_merge($errmsg, $msgList);
            }
        }
        
        return [true];
    }
    
    /**
     * 文件格式检查
     */
    public function checkFile($file_name, $file_type, $queue_data)
    {
        $ioType = kernel::single('omecsv_io_split_' . $file_type);
        $rows = $ioType->getData($file_name, 0, -1);
        $title = array_values($this->getTitle());
        
        // 检查表头
        $plateTitle = $rows[0];
        foreach ($title as $v) {
            if (array_search($v, $plateTitle) === false) {
                return [false, '文件模板错误：列【' . $v . '】未包含'];
            }
        }
        
        return [true, '文件模板匹配', $rows[0]];
    }
    
    /**
     * 获取表头定义
     */
    public function getTitle($filter = null, $ioType = 'csv')
    {
        $this->oSchema['csv'] = [
            '*:必填字段1' => 'field1',
            '*:必填字段2' => 'field2',
            '可选字段1' => 'field3',
        ];
        
        $this->ioTitle[$ioType] = array_keys($this->oSchema[$ioType]);
        return $this->ioTitle[$ioType];
    }
    
    /**
     * 数据格式转换
     */
    public function getSdf($row, $offset, $title)
    {
        $row = array_map('trim', $row);
        $oSchema = array_flip($this->oSchema['csv']);
        
        // 字段映射和数据验证
        // ...
        
        return ['status' => true, 'data' => $tmp];
    }
    
    /**
     * 保存数据
     */
    public function saveData($contents)
    {
        $errMsg = [];
        
        foreach ($contents as $data) {
            kernel::database()->beginTransaction();
            
            try {
                // 保存主数据
                // ...
                
                kernel::database()->commit();
            } catch (Exception $e) {
                kernel::database()->rollBack();
                $errMsg[] = $e->getMessage();
            }
        }
        
        return [true, $errMsg];
    }
}

关键要点

数据验证

• 必填字段验证：字段名以 *: 开头表示必填
• 文件格式检查：检查表头是否匹配
• 业务逻辑验证：在 validateData 方法中实现

数据保存

• 使用事务确保数据一致性
• 错误信息收集和返回
• 批量保存提高性能

注意事项

• 查询单条数据时使用 db_dump 方法，而不是 getRow
• 正确用法：$model->db_dump($filter, $field)
• 错误用法：$model->getRow($field, $filter)

参考文档

• 导出模板：oms-export-template.md
• 导出机制：oms-export-mechanism.md

Examples

• 当用户需要实现数据导入时，说明如何实现 omecsv_data_split_interface 接口
• 当用户需要配置导入白名单时，说明如何在 whitelist.php 中注册
• 当用户需要验证数据时，说明必填字段验证和业务逻辑验证
• 当用户需要保存数据时，说明事务使用和错误处理

Guidelines

• 严格实现 omecsv_data_split_interface 接口的所有必需方法
• 必填字段使用 *: 前缀标识
• 文件格式检查要完整，确保表头匹配
• 数据保存使用事务，确保数据一致性
• 错误信息要详细，便于排查问题
• 查询单条数据时使用 db_dump 方法