# 平台对接标准模板

# 📋 概述

本文档记录了在 OMS 系统中对接新平台时需要的标准文件和配置。适用于所有新平台的集成工作。

# 🎯 标准文件结构

# 1. 店铺类型定义

文件: app/ome/lib/shop/type.php 位置: get_shop_type() 方法中的 $shop_type 数组模板:

'platform_code' => '平台显示名称',

示例:

'meituan4sg' => '美团闪购',

# 2. 平台矩阵目录结构

目录: app/erpapi/lib/shop/matrix/{platform_code}/ 标准结构:

{platform_code}/
├── response/
│   └── order.php
└── request/
    ├── order.php
    ├── delivery.php
    └── product.php

1
2
3
4
5
6
7

必需文件:

# response/order.php

<?php
/**
 * {平台名称}订单处理
 *
 * @category 
 * @package 
 * @author system
 * @version $Id: order.php
 */
class erpapi_shop_matrix_{platform_code}_response_order extends erpapi_shop_response_order
{
    protected $_update_accept_dead_order = true;

    protected function get_update_components()
    {
        $components = array('markmemo','marktype','custommemo');

        $rs = app::get('ome')->model('order_extend')->getList('extend_status',array('order_id'=>$this->_tgOrder['order_id']));
        // 如果ERP收货人信息未发生变动时，则更新{平台名称}收货人信息
        if ($rs[0]['extend_status'] != 'consignee_modified') {
            $components[] = 'consignee';
        }

        if (($this->_ordersdf['pay_status'] != $this->_tgOrder['pay_status']) || ($this->_ordersdf['shipping']['is_cod'] == 'true' && $this->_ordersdf['status'] == 'dead')) {
            $refundApply = app::get('ome')->model('refund_apply')->getList('apply_id', array('order_id' => $this->_tgOrder['order_id'], 'status|noequal' => '3'));
            // 如果没有退款申请单，以前端为主
            if (!$refundApply) {
                $components[] = 'master';
            }
        }

        return $components;
    }

    protected function _analysis()
    {
        parent::_analysis();

        // 平台特殊逻辑处理
        // 例如：闪购订单标记
        // $this->_ordersdf['is_xsdbc'] = true;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

# request/order.php

<?php
/**
 * {平台名称}订单处理
 *
 * @category 
 * @package 
 * @author system
 * @version $Id: order.php
 */
class erpapi_shop_matrix_{platform_code}_request_order extends erpapi_shop_request_order
{}

1
2
3
4
5
6
7
8
9
10
11

# request/delivery.php

<?php
/**
 * {平台名称}发货单处理
 *
 * @category 
 * @package 
 * @author system
 * @version $Id: delivery.php
 */
class erpapi_shop_matrix_{platform_code}_request_delivery extends erpapi_shop_request_delivery
{}

1
2
3
4
5
6
7
8
9
10
11

# request/product.php

<?php
/**
 * {平台名称}商品处理
 *
 * @category 
 * @package 
 * @author system
 * @version $Id: product.php
 */
class erpapi_shop_matrix_{platform_code}_request_product extends erpapi_shop_request_product
{}

1
2
3
4
5
6
7
8
9
10
11

# 3. 接口白名单配置

文件: app/erpapi/lib/shop/whitelist.php

# 构造函数映射

在 __construct() 方法的 $this->whiteList 数组中添加：

'{platform_code}' => $this->{platform_code},

# 接口数组定义

在文件末尾添加：

//{平台名称}
private ${platform_code} = array(
    SHOP_LOGISTICS_OFFLINE_SEND, //发货结果回传
    SHOP_UPDATE_ITEMS_QUANTITY_LIST_RPC, //更新库存
    SHOP_AGREE_RETURN_GOOD, //同意退货
    SHOP_REFUSE_RETURN_GOOD, //拒绝退货
    SHOP_CHECK_REFUND_GOOD,//确认退货
    SHOP_AGREE_REFUND, //同意退款
    SHOP_REFUSE_REFUND, //拒绝退款单
    SHOP_GET_ITEMS_LIST_RPC,
);

1
2
3
4
5
6
7
8
9
10
11

# 4. 发货回写运单号配置

目录: app/ome/lib/event/trigger/shop/data/delivery/

# 添加平台到回写列表

文件: app/ome/lib/event/trigger/shop/data/delivery/common.php 在 $syncShopTypes 数组中添加平台代码：

$syncShopTypes = array(
    // ... 其他平台
    'meituan4sg', // 添加新平台
    // ... 其他平台
);

1
2
3
4
5

# 创建平台配置文件

文件: app/ome/lib/event/trigger/shop/data/delivery/{platform_code}.php

<?php

class ome_event_trigger_shop_data_delivery_{platform_code} extends ome_event_trigger_shop_data_delivery_common
{
    /**
     * 支持拆单发货、多个订单合并发货
     * 
     * @param int $delivery_id
     * @return array
     */
    public function get_sdf($delivery_id)
    {
        //获取发货单主信息
        $this->__sdf = parent::get_sdf($delivery_id);
        if (!$this->__sdf) {
            return [];
        }
        
        //拆单逻辑
        $this->_get_split_sdf($delivery_id);
        
        //获取发货的商品明细
        $this->_get_delivery_items_sdf($delivery_id);
        //手工编辑替换过平台商品(需要加上被删除的平台oid子订单)
        if($this->__sdf['orderinfo']['is_modify'] == 'true' && $this->__sdf['is_split'] == 1){
            $this->_compatible_order_sync();
        }
        
        //过滤已经退款的oid子订单
        $this->_refund_split_sdf($delivery_id);
        
        return $this->__sdf;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 5. WMS 退货单 Service 配置（可选）

如果需要 WMS 退货单参数格式化功能：

# Service 注册

文件: app/miele/services.xml

<!-- Miele APP WMS 退货单参数格式化 Service -->
<service id="erpapi.service.wms.reship.params.format">
    <class>miele_service_erpapi_wms_reship</class>
</service>

1
2
3
4

# Service 实现

文件: app/miele/lib/service/erpapi/wms/reship.php

<?php
/**
 * Miele APP WMS 退货单参数格式化 Service
 * 
 * 用于处理 miele APP 的 reship_create 参数格式化差异
 * 
 * @category miele
 * @package miele.service.erpapi.wms
 * @author system
 * @version $Id: reship.php
 */
class miele_service_erpapi_wms_reship
{
    /**
     * 格式化退货单创建参数
     * 
     * @param array $sdf 退货单数据
     * @param array $params 已格式化的参数
     * @param object $channelObj 渠道对象
     * @return array 修改后的参数
     */
    public function format_reship_create_params($sdf, $params, $channelObj)
    {
        // 为 items 中的每个商品添加 inventoryType 字段
        if (isset($params['items']) && isset($sdf['storage_code'])) {
            $items = json_decode($params['items'], true);
            if (is_array($items) && isset($items['item'])) {
                foreach ($items['item'] as $key => $item) {
                    $items['item'][$key]['inventoryType'] = $sdf['storage_code'];
                }
                
                $params['items'] = json_encode($items);
            }
        }
        
        return $params;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# WMS 退货单 Service 埋点

文件: app/erpapi/lib/wms/request/reship.php 在 reship_create() 方法中添加：

$params = $this->_format_reship_create_params($sdf);

// 调用 service 进行参数扩展或修改
if ($service = kernel::servicelist('erpapi.service.wms.reship.params.format')) {
    foreach ($service as $object => $instance) {
        if (method_exists($instance, 'format_reship_create_params')) {
            $params = $instance->format_reship_create_params($sdf, $params, $this->__channelObj);
        }
    }
}

if (!$params) {
    return $this->error('参数为空,终止同步');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 🔧 特殊业务逻辑模板

# 1. 闪购订单处理

如果平台支持闪购业务，在 response/order.php 的 _analysis() 方法中添加：

protected function _analysis()
{
    parent::_analysis();

    // 闪购订单标记
    $this->_ordersdf['is_xsdbc'] = true;
}

1
2
3
4
5
6
7

# 2. 履约门店处理

如果需要处理履约门店信息，在 response/order.php 的 _analysis() 方法中添加：

protected function _analysis()
{
    parent::_analysis();

    // 履约门店处理
    if (isset($this->_ordersdf['cn_info']) 
        && isset($this->_ordersdf['cn_info']['trade_attr']) 
        && isset($this->_ordersdf['cn_info']['trade_attr']['xsdFulfillmentInfo']) 
        && isset($this->_ordersdf['cn_info']['trade_attr']['xsdFulfillmentInfo']['storeId'])) {
        
        $storeId = $this->_ordersdf['cn_info']['trade_attr']['xsdFulfillmentInfo']['storeId'];
        $this->_ordersdf['o2o_info']['o2o_store_bn'] = $storeId;
        
        // 设置所有订单商品的 store_code
        if (isset($this->_ordersdf['order_objects']) && is_array($this->_ordersdf['order_objects'])) {
            foreach ($this->_ordersdf['order_objects'] as &$order_object) {
                $order_object['store_code'] = $storeId;
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 📋 检查清单

# 基础配置

[ ] 在 app/ome/lib/shop/type.php 中添加店铺类型
[ ] 创建 app/erpapi/lib/shop/matrix/{platform_code}/ 目录结构
[ ] 创建 response/order.php 文件
[ ] 创建 request/order.php 文件
[ ] 创建 request/delivery.php 文件
[ ] 创建 request/product.php 文件
[ ] 在 app/erpapi/lib/shop/whitelist.php 中添加白名单配置
[ ] 在 app/ome/lib/event/trigger/shop/data/delivery/common.php 中添加平台到回写列表
[ ] 创建 app/ome/lib/event/trigger/shop/data/delivery/{platform_code}.php 文件

# 可选配置

[ ] 如果需要 WMS 退货单功能，添加 Service 配置
[ ] 如果需要闪购业务，添加闪购订单处理逻辑
[ ] 如果需要履约门店，添加门店信息处理逻辑

# 验证步骤

[ ] 验证所有 PHP 文件语法正确
[ ] 验证类名和命名空间正确
[ ] 验证白名单配置正确
[ ] 验证 Service 配置正确（如果适用）

# 🎯 示例：美团闪购集成

# 1. 店铺类型定义

'meituan4sg' => '美团闪购',

# 2. 目录结构

app/erpapi/lib/shop/matrix/meituan4sg/
├── response/
│   └── order.php
└── request/
    ├── order.php
    ├── delivery.php
    └── product.php

1
2
3
4
5
6
7

# 3. 白名单配置

'meituan4sg' => $this->meituan4sg,

//美团闪购
private $meituan4sg = array(
    SHOP_LOGISTICS_OFFLINE_SEND, //发货结果回传
    SHOP_UPDATE_ITEMS_QUANTITY_LIST_RPC, //更新库存
    SHOP_AGREE_RETURN_GOOD, //同意退货
    SHOP_REFUSE_RETURN_GOOD, //拒绝退货
    SHOP_CHECK_REFUND_GOOD,//确认退货
    SHOP_AGREE_REFUND, //同意退款
    SHOP_REFUSE_REFUND, //拒绝退款单
    SHOP_GET_ITEMS_LIST_RPC,
);

1
2
3
4
5
6
7
8
9
10
11
12
13

# 4. 闪购订单处理

protected function _analysis()
{
    parent::_analysis();

    // 美团闪购就是小时达，直接设置 is_xsdbc=1
    $this->_ordersdf['is_xsdbc'] = true;
}

1
2
3
4
5
6
7

# 5. 发货回写运单号配置

// 在 common.php 的 $syncShopTypes 数组中添加
'meituan4sg',

// 创建 meituan4sg.php 文件
class ome_event_trigger_shop_data_delivery_meituan4sg extends ome_event_trigger_shop_data_delivery_common
{
    public function get_sdf($delivery_id)
    {
        $this->__sdf = parent::get_sdf($delivery_id);
        if (!$this->__sdf) {
            return [];
        }
        
        $this->_get_split_sdf($delivery_id);
        $this->_get_delivery_items_sdf($delivery_id);
        
        if($this->__sdf['orderinfo']['is_modify'] == 'true' && $this->__sdf['is_split'] == 1){
            $this->_compatible_order_sync();
        }
        
        $this->_refund_split_sdf($delivery_id);
        
        return $this->__sdf;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 📝 注意事项

命名规范：平台代码使用小写字母和数字，避免特殊字符
类名规范：类名遵循 erpapi_shop_matrix_{platform_code}_{type}_{function} 格式
文件权限：确保创建的文件有正确的读写权限
版本控制：所有修改都应该提交到版本控制系统
测试验证：在正式环境部署前，在测试环境验证所有功能

最后更新：2024年 版本：1.0

← OpenAPI接口开发模板图片上传完整使用指南 →