- 外部打单平台快递接口:按账号同步平台模板、绑定快递编码、查看模板明细;打开列表只读库,仅「从平台同步数据」时拉取 - 系统管理新增自定义快递编码字典,订单改快递 / 物流下拉合并系统与自定义编码,推送奇门沿用订单上的编码 - 新增 OpenAPI deliveryorder.getwaybill:WMS 批量回取号(单次≤100、并发4、逐单结果),快递编码只取 WMS 报文,取消/作废/归档返回失败,已取号直接复用 - 新增 openapi_request_idempotency 请求级幂等:request_id 回放、报文摘要校验、30 分钟 stale 接管、7 天定时清理 - 外部打单平台订单按平台 fetch_waybill_no 下发 need_oms_waybill,推送时实时判定并回写单据 - 店铺、打单账号平台配置与「平台+编码→模板」绑定走 Redis 缓存,绑定/账号变更主动失效,避免批量推送与取号逐单查库 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
170 lines
5.8 KiB
JavaScript
170 lines
5.8 KiB
JavaScript
'use strict';
|
||
|
||
/**
|
||
* @controller ExternalPrintExpressInterfaceController 外部打单平台快递接口
|
||
* 归属打单账号:在「外部打单平台」页按账号查看 / 设置,前端不直连平台
|
||
*/
|
||
|
||
const { Controller } = require('egg');
|
||
const { buildPageResult } = require('../lib/pagination');
|
||
|
||
class ExternalPrintExpressInterfaceController extends Controller {
|
||
/**
|
||
* 取当前主体下的账号(需带平台配置)
|
||
* @param {number|string} id 账号ID
|
||
* @return {Promise<Object|null>} 账号实例
|
||
*/
|
||
async findAccount(id) {
|
||
const { ctx } = this;
|
||
const principalId = ctx.state.principalId;
|
||
if (principalId == null) return null;
|
||
return ctx.model.ExternalPrintAccount.findOne({
|
||
where: { id, principal_id: principalId },
|
||
include: [
|
||
{
|
||
model: ctx.model.ExternalPrintPlatform,
|
||
as: 'platform',
|
||
attributes: [ 'id', 'code', 'name', 'url', 'fetch_waybill_no' ],
|
||
},
|
||
],
|
||
});
|
||
}
|
||
|
||
/**
|
||
* @summary 快递接口列表
|
||
* @description 返回账号已落库的快递接口(含失效记录),支持按状态 / 平台 / 快递公司 / 关键词过滤
|
||
* @router get /api/external-print-accounts/{id}/express-interfaces
|
||
* @apikey
|
||
* @request path integer *id 账号主键ID
|
||
* @request query integer page 页码,默认 1
|
||
* @request query integer pageSize 每页条数,默认 20
|
||
* @request query integer status 状态:1有效 0已失效,不传返回全部
|
||
* @request query string platform_code OMS 平台编码(如 PDD)
|
||
* @request query string express_company_code 平台快递公司编码(如 YUNDA)
|
||
* @request query string keyword 关键词(模板名称 / 快递公司 / 店铺 / 自定义编码)
|
||
* @response 200 baseResponse success
|
||
*/
|
||
async index() {
|
||
const { ctx } = this;
|
||
const account = await this.findAccount(ctx.params.id);
|
||
if (!account) {
|
||
ctx.status = 404;
|
||
ctx.body = { code: 404, message: '打单账号不存在' };
|
||
return;
|
||
}
|
||
|
||
try {
|
||
const result = await ctx.service.externalPrintExpressInterface.list(account, ctx.query, ctx.state.principalId);
|
||
ctx.body = {
|
||
code: 0,
|
||
message: 'success',
|
||
data: buildPageResult(result.list, result.total, { page: result.page, pageSize: result.pageSize }),
|
||
};
|
||
} catch (err) {
|
||
this._fail(ctx, err, '查询快递接口失败');
|
||
}
|
||
}
|
||
|
||
/**
|
||
* @summary 从平台全量拉取快递接口
|
||
* @description 按账号下全部外部店铺的平台分区拉取面单模板;平台侧已不存在的模板保留并标记为失效
|
||
* @router post /api/external-print-accounts/{id}/sync-express-interfaces
|
||
* @apikey
|
||
* @request path integer *id 账号主键ID
|
||
* @response 200 baseResponse success
|
||
*/
|
||
async sync() {
|
||
const { ctx } = this;
|
||
const account = await this.findAccount(ctx.params.id);
|
||
if (!account) {
|
||
ctx.status = 404;
|
||
ctx.body = { code: 404, message: '打单账号不存在' };
|
||
return;
|
||
}
|
||
|
||
try {
|
||
const data = await ctx.service.externalPrintExpressInterface.sync(account, ctx.state.principalId);
|
||
ctx.body = { code: 0, message: 'success', data };
|
||
} catch (err) {
|
||
this._fail(ctx, err, '拉取快递接口失败');
|
||
}
|
||
}
|
||
|
||
/**
|
||
* @summary 保存快递接口设置
|
||
* @description 设置自定义编码(OMS 快递公司编码)与默认类型(none / platform / express);
|
||
* 默认类型为单选,同账号同平台或同快递只保留一个默认
|
||
* @router put /api/external-print-accounts/{id}/express-interfaces
|
||
* @apikey
|
||
* @request path integer *id 账号主键ID
|
||
* @request body saveExternalPrintExpressInterfacesRequest *body
|
||
* @response 200 baseResponse success
|
||
*/
|
||
async saveSettings() {
|
||
const { ctx } = this;
|
||
const account = await this.findAccount(ctx.params.id);
|
||
if (!account) {
|
||
ctx.status = 404;
|
||
ctx.body = { code: 404, message: '打单账号不存在' };
|
||
return;
|
||
}
|
||
|
||
try {
|
||
const data = await ctx.service.externalPrintExpressInterface.saveSettings(
|
||
account,
|
||
(ctx.request.body || {}).items,
|
||
ctx.state.principalId
|
||
);
|
||
ctx.body = { code: 0, message: 'success', data };
|
||
} catch (err) {
|
||
this._fail(ctx, err, '保存快递接口设置失败');
|
||
}
|
||
}
|
||
|
||
/**
|
||
* @summary 快递接口明细
|
||
* @description 实时请求平台的「面单账号明细」接口,返回网点 / 账号等信息(凭据字段已屏蔽)
|
||
* @router get /api/external-print-accounts/{id}/express-interfaces/{interfaceId}/detail
|
||
* @apikey
|
||
* @request path integer *id 账号主键ID
|
||
* @request path integer *interfaceId 快递接口记录ID
|
||
* @response 200 baseResponse success
|
||
*/
|
||
async detail() {
|
||
const { ctx } = this;
|
||
const account = await this.findAccount(ctx.params.id);
|
||
if (!account) {
|
||
ctx.status = 404;
|
||
ctx.body = { code: 404, message: '打单账号不存在' };
|
||
return;
|
||
}
|
||
|
||
try {
|
||
const data = await ctx.service.externalPrintExpressInterface.detail(
|
||
account,
|
||
ctx.params.interfaceId,
|
||
ctx.state.principalId
|
||
);
|
||
ctx.body = { code: 0, message: 'success', data };
|
||
} catch (err) {
|
||
this._fail(ctx, err, '查看快递接口明细失败');
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 统一错误响应
|
||
* @param {Object} ctx 上下文
|
||
* @param {Error} err 异常(可带 status)
|
||
* @param {string} fallbackMessage 兜底提示
|
||
* @return {void} 无
|
||
*/
|
||
_fail(ctx, err, fallbackMessage) {
|
||
const status = Number(err && err.status) || 500;
|
||
ctx.status = status;
|
||
ctx.body = { code: status, message: (err && err.message) || fallbackMessage };
|
||
if (status >= 500) ctx.logger.error('[externalPrintExpressInterface] %s', (err && err.message) || fallbackMessage, err);
|
||
}
|
||
}
|
||
|
||
module.exports = ExternalPrintExpressInterfaceController;
|