liufumingren ab630e7c01 feat(external-print): 订单拉取与定时同步,组合商品拆分为最小单位
后端能力:
- 接入店管家订单接口(/NewOrder/List),明细归一化后按店铺商品匹配系统商品/组合商品
- 新增 service/externalPrintOrder:手动与定时拉单共用入库逻辑,同时写入待审核状态分表
- 新增 schedule/fetchExternalShopOrders:按店铺配置的间隔自动拉单(最小 3 分钟,起点重叠 10 分钟)
- 新增 lib/orderItemExpand + service/orderItemResolve:平台行与最小单位行互转;
  绑定组合商品时按「数量 = 平台数量 x 组合内数量、单价取子商品零售价」拆成子商品行,解绑可还原
- 明细新增 platform_snapshot,保留平台原样(编码/名称/规格/图片/原行号/原数量/原单价)
- 店铺商品列表支持 has_unbound_order 筛选,订单列表支持 exclude_unbound(均已同步导出定义)
- 店铺商品只读化:移除新增/编辑/删除动作,仅保留查询与绑定;
  同步商品时平台已不存在的商品自动清理(未绑定且未被订单引用直接删除,已绑定或被引用仅下架)
- 新增 scripts/rebuild-order-items 存量明细重建脚本,新增 orderItemExpand 单测(8 项)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-03 03:29:09 +08:00

226 lines
9.6 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()`);
}
/**
* 拉取店铺订单(含明细),由各平台实现。
* 需返回统一结构,避免上层直接依赖各平台字段:
* { total, hosts: [命中来源], 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}>} 订单列表
*/
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;