liufumingren c27ea5a789 feat(shop): 店管家接入「我的店铺」第二来源,支持拉取店铺并绑定货主
- 平台层新增 listShopSources() / resolveShopScope() 契约,来源由平台实现声明,控制器与前端不写死
- 店管家实现 my_shop 来源:POST /partner/LoadMyShopList 店铺列表(授权状态、平台、名称过滤)并归一化
- 新增 GET /api/external-print-accounts/:id/shop-sources;店铺列表接口支持 ?source=
- 店铺创建支持 source,写入 shops.external_source;编码 dgj-{账号ID}-{来源}-{ShopId},默认来源不加来源段
- 新增迁移 shops.external_source(默认 agent);刷新所在区只处理默认来源,避免自营店被误判解绑而自动禁用
- my_shop 的拉单/拉商品暂时明确拒绝,防止按账号 FxUserId 拉到上游其它数据(下一步接入)
- 前端「店铺列表」弹窗支持来源切换,展示平台、授权状态与服务到期时间
- 补充单元测试与文档(店管家取号-旧系统提取 §4.2.1.1)

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

261 lines
12 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()`);
}
/**
* 该平台支持的店铺来源清单(同一账号下可能有多种来源的店铺)。
*
* 通用层与前端只认这个清单:新增来源/新平台时只改平台实现,接口和页面都不用动。
* 默认实现为单一来源,老平台保持原行为。
* @return {Array<{code: string, name: string}>} 来源清单(第一个为默认来源)
*/
listShopSources() {
return [{ code: 'default', name: '店铺' }];
}
/**
* 解析店铺在平台侧的作用域(订单/商品/分区同步都按它取数)。
*
* 各平台把「用哪个字段定位店铺、去哪些域名查」这类平台知识收在自己实现里,
* 上层(控制器、定时任务、订单/商品同步)不再直接读 external_data 的平台字段。
* @param {Object} shop OMS 店铺记录(type=2)
* @return {{source: string, externalId: string, shopId: string, platformType: string, hosts: string[]}} 店铺作用域
*/
resolveShopScope(shop) { // eslint-disable-line no-unused-vars
const data = (shop && shop.external_data) || {};
const code = String((shop && shop.code) || '');
const tail = code.includes('-') ? code.slice(code.lastIndexOf('-') + 1) : code;
return {
source: String((shop && shop.external_source) || 'default'),
externalId: String(data.Id == null ? tail : data.Id),
shopId: data.ShopId == null ? '' : String(data.ShopId),
platformType: String(data.PlatformType || ''),
hosts: [],
};
}
/**
* 拉取平台侧的店铺/商家列表,由各平台实现。
* 需返回统一结构,避免上层直接依赖各平台字段:
* { total, list: [{
* source, external_id, name, contact_name, contact_phone, status, status_label,
* platform, platform_code, platform_name, remark, raw,
* }] }
* @param {Object} [options] 查询参数:source(默认取 listShopSources() 的第一项)/ pageIndex / pageSize / keyword / status / platformTypes
* @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()`);
}
/**
* 把订单推送到打单平台打印,由各平台实现
* @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;