新增平台连接器
以接入一个新平台 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. 其他能力(可选)
| 能力 | 接口 | 位置 |
|---|---|---|
| 刊登、改价、类目属性、竞品价格 | PublishConnector | ecom/publish/connector,复用店铺授权 |
| 买家消息、评价、请求评价 | MessageConnector | ecom/cs/connector |
| 广告结构、报告、竞价预算 | AdsConnector | ecom/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; - 申请订单、发货、库存、商品等所需的接口权限。