oms/backend/app/controller/externalPrintExpressInterface.js
liufumingren eaf957ed14 feat(express): 外部打单快递接口、自定义快递编码与回 OMS 取号
- 外部打单平台快递接口:按账号同步平台模板、绑定快递编码、查看模板明细;打开列表只读库,仅「从平台同步数据」时拉取
- 系统管理新增自定义快递编码字典,订单改快递 / 物流下拉合并系统与自定义编码,推送奇门沿用订单上的编码
- 新增 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>
2026-11-04 04:10:37 +08:00

170 lines
5.8 KiB
JavaScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'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;