mirror of
https://github.com/crmeb/CRMEB.git
synced 2026-10-29 05:50:50 +00:00
162 lines
5.1 KiB
Markdown
162 lines
5.1 KiB
Markdown
# 电子面单驱动扩展开发指南
|
||
|
||
## 概述
|
||
|
||
电子面单驱动扩展位于 `driver/express/{Driver}/` 目录，负责对接各类电子面单打印服务（一号通、测试面单等），用于订单发货时自动打印快递面单。
|
||
|
||
系统通过 `crmeb\services\driver\DriverRegistry` 扫描各驱动包的 `plugin.json` 完成驱动注册。
|
||
|
||
## 已有驱动
|
||
|
||
| 驱动目录 | 驱动标识 | 说明 |
|
||
|---------|---------|------|
|
||
| [Yihaotong](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/express/Yihaotong/) | `yihaotong` | 一号通电子面单 |
|
||
| [TestExpress](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/express/TestExpress/) | `test_express` | 测试电子面单 |
|
||
|
||
## 开发步骤
|
||
|
||
### 1. 创建驱动目录
|
||
|
||
```bash
|
||
mkdir -p driver/express/{DriverName}
|
||
```
|
||
|
||
### 2. 创建 plugin.json
|
||
|
||
```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`）为各驱动类型通用结构，完整说明见[短信驱动开发指南](../sms/DEVELOPMENT.md#pluginjson-字段说明)。
|
||
|
||
### 3. 创建 Driver.php
|
||
|
||
```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. 验证驱动
|
||
|
||
```php
|
||
// 手动验证（通过驱动注册中心）
|
||
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` |
|
||
|
||
### 驱动的核心职责
|
||
|
||
电子面单驱动的核心职责包括：
|
||
|
||
1. **查询快递公司列表** — 获取支持的快递公司
|
||
2. **获取面单模板** — 根据快递公司编码获取面单模板
|
||
3. **打印面单** — 提交运单信息，获取面单图片/PDF 数据
|
||
4. **面单状态管理** — 查询面单打印状态、取消面单等
|
||
|
||
## 配置存储
|
||
|
||
电子面单配置应存储在对应驱动表的 `config_fields` JSON 字段中。
|
||
|
||
## 配置字段设计建议
|
||
|
||
电子面单驱动通常需要以下配置：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `open` | switch | 功能开关 |
|
||
| `type` | radio | 接口类型（只读时标识服务商） |
|
||
| `api_key` | text | API密钥 |
|
||
| `api_secret` | password | API密钥密码 |
|
||
| `endpoint` | text | 接口地址（可选） |
|
||
|
||
## 参考实现
|
||
|
||
- [一号通电子面单](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/express/Yihaotong/) — 完整电子面单实现
|
||
- [测试电子面单](file:///Users/xurongyao/web/crmeb_bz/crumb-bz-v6.0/crmebbz/backend/driver/express/TestExpress/) — 测试驱动实现
|