问题:店管家 /NewOrder/List 只支持按时间窗查询,不提供发货状态过滤, 原实现仅按 UpFxUserId 归属就整批入库,导致 sended/success/close 的订单 全部堆进「待审核」(实测店铺 19 近 7 天平台返回 385 单,真正待发货只有 11 单)。 - dgj 新增 isOrderFinished():ErpState∈sended/success/close(及各平台等价状态)、 有 OnlineSendTime、面单 IsSended=true、LogisticStatus>0 任一命中即视为已处理; PrintState/ExpressPrintTime 仅表示已打印面单,不作为判定依据 - listOrders 过滤未发货订单,返回 skipped 与 finished 列表 - externalPrintOrder.syncOrders 新增 voidFinishedOrders():本地仍处于待审核、 平台侧已发货的副本自动作废(写 void_at/void_reason + 操作日志),已审核订单不动 - orderStatus.voidOrder 支持 principalId(定时任务无登录态) - 手动/自动拉单消息、接口返回、接口契约、前端提示补充「跳过已发货 / 自动作废」统计 - 新增 scripts/cleanup-shipped-pending-orders.js(npm run orders:cleanup-shipped): 按同一口径清理历史脏单,默认 dry-run,--apply 才删除 - 新增 isOrderFinished 单测(7 项) 已清理历史脏单 103 条(备份见会话 files/backup-shipped-pending-orders.json), 清理后待审核仅剩 2 单真实的平台待发货订单。 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
228 lines
10 KiB
JavaScript
228 lines
10 KiB
JavaScript
'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_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 }],
|
||
* }] }
|
||
* 明细只保留平台商品快照,系统商品匹配由上层依据店铺商品绑定关系完成。
|
||
* @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 的平台必须实现),由各平台实现
|
||
* @param {Object} order 订单数据(字段口径由平台协议决定)
|
||
* @return {Promise<string[]>} 运单号列表
|
||
*/
|
||
async fetchWaybillNo(order) { // eslint-disable-line no-unused-vars
|
||
throw new Error(`外部打单平台 ${this.platformName} 未实现 fetchWaybillNo()`);
|
||
}
|
||
}
|
||
|
||
module.exports = PrintPlatformService;
|