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

238 lines
11 KiB
JavaScript
Raw 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';
/**
* 外部打单平台服务基类。
*
* 约定:一个平台一个 service 类,放在 app/lib/printPlatform/ 目录下,文件名与平台标识(code)保持一致;
* 类上声明 static code(须与 external_print_platforms.code 相同),由 ./index.js 统一注册与实例化。
*
* 平台基础资料(链接地址、是否回平台取号)来自 external_print_platforms,由开发者维护;
* 账号密码来自 external_print_accounts,仅供服务端调用平台使用,切勿写入日志或返回给前端。
*/
class PrintPlatformService {
/**
* @param {Object} options 构造参数
* @param {Object} options.platform 平台配置(external_print_platforms 记录)
* @param {Object} [options.account] 打单账号(external_print_accounts 记录,含 account / password / cookie / token)
* @param {Function} [options.saveCookie] 会话 cookie 落库回调,签名 (cookie) => Promise<void>
* @param {Function} [options.saveToken] 登录 token 落库回调,签名 (token) => Promise<void>
* @param {Function} [options.saveLoginStatus] 登录状态落库回调,签名 (status) => Promise<void>,1已登录 0未登录/失效
*/
constructor({ platform, account, saveCookie, saveToken, saveLoginStatus } = {}) {
if (!platform || !platform.code) {
throw new Error('创建外部打单平台服务需要平台配置(platform.code)');
}
this.platform = platform;
this.account = account || null;
this._saveCookie = typeof saveCookie === 'function' ? saveCookie : null;
this._saveToken = typeof saveToken === 'function' ? saveToken : null;
this._saveLoginStatus = typeof saveLoginStatus === 'function' ? saveLoginStatus : null;
}
/**
* 平台标识,必须与 external_print_platforms.code 一致
* @return {string|null} 平台标识,基类未声明时为 null(注册时会因缺少 code 报错)
*/
static get code() {
return null;
}
/** 平台标识(与平台配置的 code 对应) */
get platformCode() {
return this.constructor.code;
}
/** 平台名称 */
get platformName() {
return this.platform.name;
}
/** 平台链接地址:仅服务端请求使用,前端不展示 */
get baseUrl() {
return this.platform.url;
}
/** 是否回打单平台取号:1 是 0 否(固化在平台基础资料中) */
get needFetchWaybillNo() {
return Number(this.platform.fetch_waybill_no) === 1;
}
/**
* 读取打单账号密码,未配置时抛错,避免各实现重复判空
* @return {{account: string, password: string}} 平台登录凭据
*/
getCredentials() {
const account = this.account || {};
if (!account.account || !account.password) {
throw new Error(`外部打单平台 ${this.platformName} 未配置账号密码`);
}
return { account: account.account, password: account.password };
}
/**
* 该账号已保存的会话 cookie(未登录过时为空字符串)
* @return {string} 会话 cookie
*/
get cookie() {
return (this.account && this.account.cookie) || '';
}
/**
* 保存会话 cookie:更新内存中的账号记录,并通过构造时传入的 saveCookie 回调落库,
* 避免登录态散落在临时变量、文件或缓存里
* @param {string} cookie 平台返回的会话 cookie
* @return {Promise<void>} 无返回值
*/
async saveCookie(cookie) {
const value = String(cookie || '');
if (this.account) this.account.cookie = value;
if (!this._saveCookie) {
throw new Error(`外部打单平台 ${this.platformName} 未提供 cookie 保存回调,无法持久化会话`);
}
await this._saveCookie(value);
}
/**
* 该账号已保存的登录 token(未登录过时为空字符串)
* @return {string} 登录 token
*/
get token() {
return (this.account && this.account.token) || '';
}
/**
* 保存登录 token:更新内存中的账号记录,并通过构造时传入的 saveToken 回调落库
* @param {string} token 平台返回的登录 token
* @return {Promise<void>} 无返回值
*/
async saveToken(token) {
const value = String(token || '');
if (this.account) this.account.token = value;
if (!this._saveToken) {
throw new Error(`外部打单平台 ${this.platformName} 未提供 token 保存回调,无法持久化登录态`);
}
await this._saveToken(value);
}
/**
* 记录登录状态(1 已登录 / 0 未登录或已失效)。
* 状态是辅助信息,未提供落库回调时只更新内存,不抛错。
* @param {number|boolean} status 登录状态
* @return {Promise<void>} 无返回值
*/
async saveLoginStatus(status) {
const value = status === true || Number(status) === 1 ? 1 : 0;
if (this.account) this.account.login_status = value;
if (this._saveLoginStatus) await this._saveLoginStatus(value);
}
/**
* 登录外部打单平台(获取会话/令牌),由各平台实现
* @return {Promise<Object>} 登录结果(会话、令牌等,由各实现定义)
*/
async login() {
throw new Error(`外部打单平台 ${this.platformName} 未实现 login()`);
}
/**
* 检查当前账号的登录态(不触发登录),由各平台实现
* @return {Promise<{loggedIn: boolean, message?: string, url?: string}>} 登录态检查结果
*/
async checkSession() {
throw new Error(`外部打单平台 ${this.platformName} 未实现 checkSession()`);
}
/**
* 拉取平台侧的店铺/商家列表,由各平台实现。
* 需返回统一结构,避免上层直接依赖各平台字段:
* { total, list: [{ external_id, name, contact_name, contact_phone, status, remark, raw }] }
* @param {Object} [options] 查询参数:pageIndex / pageSize / keyword
* @return {Promise<{total: number, list: Array}>} 平台店铺列表
*/
async listShops(options) { // eslint-disable-line no-unused-vars
throw new Error(`外部打单平台 ${this.platformName} 未实现 listShops()`);
}
/**
* 拉取平台侧的店铺商品(全量快照),由各平台实现。
* 需返回统一结构,避免上层直接依赖各平台字段:
* {
* total, verified,
* hosts: [{ host, total, verified, pages, areas: [{ dbname, name, total, verified, pages }] }],
* list: [{
* outer_item_id, outer_sku_id, title, outer_code, spec, image,
* price, stock, status, platform_type, external_shop_id, raw,
* }],
* }
* verified 表示快照完整(去重后的商品数 = 平台返回的 Total),上层可据此清理已下架商品。
* @param {Object} shop OMS 店铺记录(type=2,external_data 为平台返回的商家原始结构)
* @return {Promise<{total: number, verified: boolean, hosts: Array, list: Array}>} 商品快照
*/
async listProducts(shop) { // eslint-disable-line no-unused-vars
throw new Error(`外部打单平台 ${this.platformName} 未实现 listProducts()`);
}
/**
* 拉取店铺订单(含明细),由各平台实现。
* 必须是「仍需要本系统处理」的订单:平台侧已发货 / 已终结(完成、关闭、退款完成…)的订单要过滤掉,
* 否则会写进待审核形成脏单。被过滤掉的订单号通过 finished 返回,上层据此作废本地未处理的副本。
* 需返回统一结构,避免上层直接依赖各平台字段:
* { total, hosts: [命中来源], skipped, finished: [{ external_order_id, platform_status }], list: [{
* external_order_id, external_shop_id, external_shop_name, platform_type, platform_code, platform_name,
* platform_status,
* order_no, total_amount, pay_amount, receiver, remark,
* external_created_at, external_updated_at, raw,
* items: [{ external_item_id, outer_item_id, outer_sku_id, sku_code, name, spec, image,
* quantity, price, total_amount, relation_base_product, base_product, raw }],
* }] }
* platform_code / platform_name 必须是 app/lib/platformCode.js 里的系统预设平台编码(PDD / DYXD / SPH…),
* platform_type 保留平台原始标识仅作留痕。
* 明细只保留平台商品快照,系统商品匹配由上层依据店铺商品绑定关系完成。
* @param {Object} shop OMS 店铺记录(type=2,external_data 为平台返回的商家原始结构)
* @param {Object} [options] 查询参数(startTime / endTime)
* @return {Promise<{total: number, list: Array, hosts: Array, skipped: number, finished: Array}>} 订单列表
*/
async listOrders(shop, options) { // eslint-disable-line no-unused-vars
throw new Error(`外部打单平台 ${this.platformName} 未实现 listOrders()`);
}
/**
* 按平台商品ID(可选规格ID)单独拉取商品,用于订单明细匹配不到店铺商品时按需补拉,由各平台实现。
* 需返回统一结构:
* { list: [与 listProducts().list 同结构], missing: [{ outer_item_id, outer_sku_id, reason }], hosts: [命中来源说明] }
* @param {Object} shop OMS 店铺记录(type=2,external_data 为平台返回的商家原始结构)
* @param {Array<{outer_item_id: string, outer_sku_id?: string}>} items 待补拉的商品
* @return {Promise<{list: Array, missing: Array, hosts: Array}>} 命中与未命中的商品
*/
async listProductsByIds(shop, items) { // eslint-disable-line no-unused-vars
throw new Error(`外部打单平台 ${this.platformName} 未实现 listProductsByIds()`);
}
/**
* 把订单推送到打单平台打印,由各平台实现
* @param {Object} order 订单数据(字段口径由平台协议决定)
* @return {Promise<Object>} 平台响应
*/
async print(order) { // eslint-disable-line no-unused-vars
throw new Error(`外部打单平台 ${this.platformName} 未实现 print()`);
}
/**
* 回打单平台取运单号(fetch_waybill_no=1 的平台必须实现),由各平台实现
*
* 调用方为 WMS 取号回调(deliveryorder.getwaybill):订单信息由 OMS 回读,
* 快递编码来自 WMS 报文,所选快递接口按「账号 + 平台 + 编码」匹配后传入。
* @param {Object} order 订单数据(字段口径由平台协议决定)
* @param {Object} [options] 取号上下文
* @param {Object} [options.template] 命中的快递接口(external_print_express_interfaces 记录)
* @param {string} [options.expressCode] WMS 传入的快递编码
* @param {string} [options.platformCode] 订单平台编码(如 TB)
* @return {Promise<string|string[]|Object>} 运单号(字符串 / 数组 / 平台原始结果,由上层归一化)
*/
async fetchWaybillNo(order, options = {}) { // eslint-disable-line no-unused-vars
throw new Error(`外部打单平台 ${this.platformName} 未实现 fetchWaybillNo()`);
}
}
module.exports = PrintPlatformService;