liufumingren 969c68f5f9 feat(external-print): 新增外部打单平台与账号管理(接入店管家登录)
- 新增 external_print_platforms(平台基础资料,开发者维护)与 external_print_accounts(账号/密码/cookie/token/登录状态)
- 新增平台账号 CRUD、登录态检查、登录接口;店铺管理下新增「外部打单平台」菜单
- 平台服务按 code 独立存放于 app/lib/printPlatform(dgj.js 实现店管家登录与 GetUserInfo 登录态检查)
- 平台接口 401 自动记录账号登录状态,前端展示状态并支持检查/登录

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

165 lines
6.2 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()`);
}
/**
* 把订单推送到打单平台打印,由各平台实现
* @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;