电子面单驱动扩展开发指南

概述

电子面单驱动扩展位于 driver/express/{Driver}/ 目录，负责对接各类电子面单打印服务（一号通、测试面单等），用于订单发货时自动打印快递面单。

系统通过 crmeb\services\driver\DriverRegistry 扫描各驱动包的 plugin.json 完成驱动注册。

已有驱动

驱动目录	驱动标识	说明
Yihaotong	`yihaotong`	一号通电子面单
TestExpress	`test_express`	测试电子面单

开发步骤

1. 创建驱动目录

mkdir -p driver/express/{DriverName}

2. 创建 plugin.json

{
    "key": "your_driver_key",
    "name": "驱动名称",
    "description": "驱动功能简述",
    "version": "1.0.0",
    "author": "CRMEB",
    "type": "driver",
    "path": "driver/express/YourDriver",
    "driver": {
        "name": "面单驱动名称",
        "driver_key": "your_driver_key",
        "class_name": "Driver",
        "icon": "icon-xxx",
        "is_builtin": true,
        "sort": 100,
        "config_fields": [
            {
                "field": "open",
                "label": "开启电子面单",
                "type": "switch",
                "group": "接口配置",
                "tip": "开启后可在订单发货时使用电子面单打印"
            },
            {
                "field": "api_key",
                "label": "应用Key",
                "type": "text",
                "required": true,
                "group": "基础配置"
            },
            {
                "field": "api_secret",
                "label": "应用密钥",
                "type": "password",
                "required": true,
                "group": "基础配置"
            }
        ],
        "help_doc": {
            "title": "使用说明",
            "steps": ["步骤1", "步骤2"],
            "link": "https://example.com"
        }
    }
}

plugin.json driver 子对象字段说明

字段	类型	必填	说明
`name`	string	✅	驱动显示名称
`driver_key`	string	✅	驱动唯一标识
`class_name`	string	❌	驱动类名，默认 `Driver`
`icon`	string	❌	图标类名
`is_builtin`	bool	❌	是否内置驱动
`sort`	int	❌	排序权重
`config_fields`	array	❌	配置字段定义（后台动态渲染表单；`open` 为 switch 开关字段，控制功能启用）
`help_doc`	object	❌	帮助文档（`{title, steps, link}`）

顶层字段（key/name/description/version/author/type/path/require）为各驱动类型通用结构，完整说明见短信驱动开发指南。

3. 创建 Driver.php

<?php
namespace driver\express\{DriverName};

use crmeb\services\express\BaseExpress;

/**
 * {DriverName} 电子面单
 */
class Driver extends BaseExpress
{
    protected function initialize(array $config = []): void
    {
        parent::initialize($config);
    }

    // 实现面单相关业务方法
}

4. 验证驱动

// 手动验证（通过驱动注册中心）
use crmeb\services\driver\DriverRegistry;

$drivers = DriverRegistry::scan('express');                              // 全部电子面单驱动
$class   = DriverRegistry::getDriverClass('express', 'your_driver_key'); // 完整类名 driver\express\YourDriver\Driver

接口规范

电子面单驱动继承自 BaseExpress，基类定义了面单打印所需的通用方法，子类可根据实际服务商 SDK 的能力选择性覆写。

BaseExpress 提供的通用方法

方法	说明	参数
`open()`	开通面单服务	—
`dump()`	数据导出	`$data`
`temp()`	获取面单模板	`$com`

驱动的核心职责

电子面单驱动的核心职责包括：

查询快递公司列表 — 获取支持的快递公司
获取面单模板 — 根据快递公司编码获取面单模板
打印面单 — 提交运单信息，获取面单图片/PDF 数据
面单状态管理 — 查询面单打印状态、取消面单等

配置存储

电子面单配置应存储在对应驱动表的 config_fields JSON 字段中。

配置字段设计建议

电子面单驱动通常需要以下配置：

字段	类型	说明
`open`	switch	功能开关
`type`	radio	接口类型（只读时标识服务商）
`api_key`	text	API密钥
`api_secret`	password	API密钥密码
`endpoint`	text	接口地址（可选）

参考实现

一号通电子面单 — 完整电子面单实现
测试电子面单 — 测试驱动实现

5.1 KiB Raw Permalink Blame History Unescape Escape