liufumingren a4213bfd0d fix(external-print): 拉单只取平台未发货订单,已发货/已终结不再进待审核
问题:店管家 /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>
2026-11-03 04:14:02 +08:00

228 lines
10 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_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;