Skip to content

新增平台连接器 ​

以接入一个新平台 FOO 为例。订单、库存、店铺、渠道接入页面都按连接器声明工作,不需要修改页面。

1. 登记平台 ​

  • 在 EcomPlatform 枚举中加入 FOO,在 sql/init.sql 的系统字典 ecom_platform 中加入取值(已有库另写升级脚本)。
  • 前端运行 npm run gen:enums 重新生成 constants/enums.js,在 locales/en-US/dict.js 中补英文名称。
  • 店铺列表、渠道接入中的平台徽标(颜色与缩写)在 views/ecom/store/health.js 中按平台登记。

2. 实现 ChannelConnector ​

java
@Component
public class FooConnector implements ChannelConnector {

    private static final ConnectorInfo INFO = new ConnectorInfo(EcomPlatform.FOO, AuthType.KEYS, List.of(
            CredentialField.text("appKey", "ecom.label.cred.fooAppKey", true),
            CredentialField.secret("appSecret", "ecom.label.cred.fooAppSecret"),
            CredentialField.cached("accessToken", true)),            // 缓存的访问令牌,不显示在表单中
            "https://api.foo.com", "https://sandbox.foo.com",
            EnumSet.of(ConnectorCapability.ORDERS, ConnectorCapability.SHIP_CONFIRM),
            "https://open.foo.com/docs");

    @Override
    public ConnectorInfo info() { return INFO; }

    @Override
    public void ensureToken(ConnectorContext ctx) {
        // 令牌过期时刷新,ctx.updateCredentials(Map.of("accessToken", token, ...)) 加密写回
    }

    @Override
    public List<OrderDraft> fetchOrders(ConnectorContext ctx, LocalDateTime since) {
        String base = ctx.baseUrl(INFO);          // 自定义地址 > 沙箱 / 正式地址
        StoreCredentials c = ctx.credentials();   // 解密后的授权
        // 分页拉取 since 之后更新的订单,转换为 OrderDraft(平台订单号、时间、状态、配送方式、收件人、币种、金额、行)
    }

    @Override
    public ShipmentResult confirmShipment(ConnectorContext ctx, EcomOrder order, List<EcomOrderItem> items) {
        // 回传运单号与承运商;平台物流托管的返回平台运单号
    }
}

要点:

  • 授权方式为 OAuth 时 AuthType.OAUTH,再实现 authorizeUrl 与 exchangeCode,回调地址固定为 {public-url}/ecom/oauth/callback/foo,见 OAuth 授权。
  • 每店域名不同时用 INFO.withPerStoreBaseUrl();拉单有时间窗限制时用 withOrderWindowNote(消息键),平台订单更新有延迟时用 withLookbackHours(n) 加长增量回看。
  • 支持按包裹部分发货时 partialShipment() 返回 true;回传库存实现 pushInventory,拉取在线商品实现 fetchListings,并在能力中声明。
  • HTTP 用 HttpJson,签名工具在 ConnectorSigns;平台返回业务错误时抛 ConnectorHttpException 或带消息键的 BizException,原文写进同步日志。
  • 连接器不写库、不开事务,同步、幂等、日志由 EcomSyncService 负责。

3. 授权字段的名称 ​

授权字段的显示名称写进 lemon-ecom/src/main/resources/i18n/ecom.properties 与 ecom_en.properties:

properties
ecom.label.cred.fooAppKey=App Key
ecom.label.cred.fooAppSecret=App Secret

运行 python3 scripts/check_i18n.py 检查中英文键一致。

4. 其他能力(可选) ​

能力接口位置
刊登、改价、类目属性、竞品价格PublishConnectorecom/publish/connector,复用店铺授权
买家消息、评价、请求评价MessageConnectorecom/cs/connector
广告结构、报告、竞价预算AdsConnectorecom/ads,授权字段名称写 ecom.label.ads.cred.*

注册为 Bean 后,对应页面自动出现该平台的选项和按钮。

5. 测试 ​

在 lemon-modules/lemon-ecom/src/test/.../connector 下用 JDK 自带的 HttpServer 模拟平台:把店铺的自定义地址指向本地服务,验证签名、授权、分页、报文转换和错误处理。集成层面的同步、回调、库存回传、令牌刷新可参考 EcomSyncHubTests(用测试连接器覆盖)。

正式接入前用真实开发者账号联调,把需要核对的点写进连接器的 javadoc。

6. 平台开发者后台 ​

  • 申请开发者账号与应用,获取应用密钥;
  • OAuth 平台登记回调地址 https://<你的域名>/api/ecom/oauth/callback/foo,并在后端配置 LEMON_ECOM_PUBLIC_URL;
  • 申请订单、发货、库存、商品等所需的接口权限。

面向跨境电商卖家的开源 ERP · 基于 GPL-3.0 协议
联系我们:电话 17701123202 · 微信 BG7LIF · 邮箱 zmissu@163.com