oms/backend/app/lib/warehouseApiFields.js
liufumingren cbd16752a5 feat(backend): 商品、店铺、组合商品、仓库与库存模块
- 商品/商品图片、店铺、店铺商品、组合商品及明细
- 仓库、仓库商品(WMS itemId 映射)、仓库接口配置与字段定义(warehouseApi/warehouseApiField)
- 库存:stock_items、product_stocks(ZC/CC 双维度)与库存重算工具(utils/recalcStock.js)
- 库存单据与对接日志:stock orders、api_outbound_logs
- 相关迁移:shops/shop_products/stock_orders/warehouses/warehouse_apis/warehouse_products/product_stocks/files-images 等表与字段
2026-09-13 02:23:39 +08:00

557 lines
16 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';
/**
* 仓库接口「配置项」定义(硬编码)
*
* 背景:接口配置(warehouse_apis)不再直接编辑自由 JSON 的扩展配置,
* 而是拆成两部分的接口共同维护:
* 1) 配置项定义(本文件,硬编码):GET /api/warehouse-api-fields 输出分组、字段清单与类型
* 2) 字段值:GET/PUT /api/warehouse-apis/:id/fields 单独读写,
* 以「字段名: 值」的 JSON 对象落库在 warehouse_apis.extra;
* 读取统一走 readFieldValues()(模型 WarehouseApi#getFieldValues 封装),
* 未配置的字段用本文件的硬编码 defaultValue 兜底
*
* 前端按 group 分组渲染小标题、按 type(字段类型枚举)渲染对应的表单控件,
* 因此新增/调整字段只改这里即可。
* 字段类型枚举:text 单行文本 / textarea 多行文本 / number 数字 / switch 开关 /
* select 下拉(需 options) / password 密码 / json JSON 对象
*/
/** 字段类型枚举(前端按此渲染表单控件,勿随意改名) */
const FIELD_TYPES = {
TEXT: 'text',
TEXTAREA: 'textarea',
NUMBER: 'number',
SWITCH: 'switch',
SELECT: 'select',
PASSWORD: 'password',
JSON: 'json',
};
/** 字段类型枚举列表(供接口输出给前端) */
const FIELD_TYPE_LIST = Object.values(FIELD_TYPES);
/**
* 字段分组(前端按 group 渲染小标题,字段通过 group 归属到分组)
* key:字段定义里的 group 取值
* label:分组标题
* description:分组说明(可放配置帮助文档链接)
*/
const FIELD_GROUPS = [
{
key: 'basic',
label: '基础信息',
description: '账号配置帮助文档:https://s.jkyun.biz/IMqcSIg',
},
{
key: 'business',
label: '业务设置',
description: '业务设置奇门配置帮助文档',
},
{ key: 'submit', label: '递交设置' },
{ key: 'callback', label: '回传设置' },
];
/** 开关类型字段的默认值:默认不启用 */
const SWITCH_OFF = false;
/**
* 类奇门JSON接口的配置项清单(硬编码,按奇门仓储实际配置项维护)
* key:落库(warehouse_apis.extra)时的字段名
* group:所属分组(FIELD_GROUPS.key)
* label:前端表单标签
* type:字段类型,决定前端表单控件与后端校验规则
* required:是否必填
* defaultValue:未填写时的默认值
* options:type=select 时的可选项
* min/max:type=number 时的取值范围
* description:字段说明(前端展示为提示文案)
*/
const WAREHOUSE_API_FIELDS = [
/* ---------- 基础信息 ---------- */
{
key: 'owner_alias',
group: 'basic',
label: '货主别名',
type: FIELD_TYPES.TEXT,
placeholder: '如 天豹云仓新WMS',
defaultValue: '天豹云仓新WMS',
description: '推送给外部系统的货主别名',
},
{
key: 'outsource_api_type',
group: 'basic',
label: '委外接口类型',
type: FIELD_TYPES.TEXT,
placeholder: '如 奇门-云谱WMS(appkey:23535631)',
description: '对接的委外仓接口类型',
},
{
key: 'customer_id',
group: 'basic',
label: '客户ID',
type: FIELD_TYPES.TEXT,
placeholder: '如 tbyc20260614',
defaultValue: 'tbyc20260614',
description: '外部系统分配的客户 ID',
},
{
key: 'owner_code',
group: 'basic',
label: '货主编码',
type: FIELD_TYPES.TEXT,
required: true,
placeholder: '如 tbyc20260614',
defaultValue: 'tbyc20260614',
description: '双方系统约定的货主(商家)编码',
},
/* ---------- 业务设置 ---------- */
{
key: 'purchase_return_code_type',
group: 'business',
label: '采购退货代码类型',
type: FIELD_TYPES.SELECT,
defaultValue: 'CGTH',
options: [{ label: '采购退货(CGTH)', value: 'CGTH' }],
},
{
key: 'transfer_in_code_type',
group: 'business',
label: '调拨入库代码类型',
type: FIELD_TYPES.TEXT,
placeholder: '如 DBRK',
defaultValue: 'DBRK',
},
{
key: 'transfer_out_code_type',
group: 'business',
label: '调拨出库代码类型',
type: FIELD_TYPES.TEXT,
placeholder: '如 DBCK',
defaultValue: 'DBCK',
},
{
key: 'sku_sync_key',
group: 'business',
label: '货品同步SKU选择',
type: FIELD_TYPES.SELECT,
defaultValue: 'barcode',
options: [{ label: '[条码]作为双方系统识别商品SKU(不推荐,改条码有风险)', value: 'barcode' }],
},
{
key: 'barcode_sync_source',
group: 'business',
label: '货品同步条码选择',
type: FIELD_TYPES.SELECT,
defaultValue: 'product_barcode',
options: [{ label: '货品档案条码', value: 'product_barcode' }],
},
{
key: 'api_version',
group: 'business',
label: '接口版本号',
type: FIELD_TYPES.SELECT,
defaultValue: 'V2.0',
options: [
{ label: 'V2.0', value: 'V2.0' },
{ label: 'V1.0', value: 'V1.0' },
],
},
/* ---------- 递交设置 ---------- */
{
key: 'item_name_with_spec',
group: 'submit',
label: '货品同步名称带规格',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'barcode_with_aux',
group: 'submit',
label: '货品同步条码带辅助条码',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'push_face_sheet',
group: 'submit',
label: '把物流面单数据传给WMS',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'order_info_not_push',
group: 'submit',
label: '递交订单时信息不传给仓库',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'shop_name_by_channel',
group: 'submit',
label: '销售单递交的店铺名称按渠道',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'price_shared_discount',
group: 'submit',
label: '递交使用分摊优惠后商品单价',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'platform_no_cut_length',
group: 'submit',
label: '截取电商平台订单号、支付单号长度',
type: FIELD_TYPES.NUMBER,
defaultValue: 0,
min: 0,
max: 50,
description: '截取长度,0 表示不截取;订单号与支付单号同时生效',
},
{
key: 'clear_logistics_no',
group: 'submit',
label: '已有物流单号的销售单,递交仓库发货时清空物流单号再进行递交',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'sync_order_custom_fields',
group: 'submit',
label: '订单级自定义字段同步递交给仓库',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'order_custom_fields_map',
group: 'submit',
label: '订单级自定义字段映射设置',
type: FIELD_TYPES.JSON,
description: '「设置」维护的映射,JSON 对象 { 订单字段: 仓库字段 }',
},
{
key: 'sync_item_custom_fields',
group: 'submit',
label: '货品级自定义字段同步递交给仓库',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'item_custom_fields_map',
group: 'submit',
label: '货品级自定义字段映射设置',
type: FIELD_TYPES.JSON,
description: '「设置」维护的映射,JSON 对象 { 货品字段: 仓库字段 }',
},
{
key: 'sender_company_use_shop',
group: 'submit',
label: '发件人公司使用店铺名称',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'consignment_doc_submit',
group: 'submit',
label: '寄售业务单据递交WMS,创建发货单或退货入库单',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'allow_invalid_item_order',
group: 'submit',
label: '允许无效货品订单递交仓库发货',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'order_flag_not_sync',
group: 'submit',
label: '订单标记无需同步递交给仓库',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'order_flag_setting',
group: 'submit',
label: '订单标记设置',
type: FIELD_TYPES.JSON,
description: '「设置」维护的订单标记规则,JSON 对象',
},
{
key: 'outsource_logistics_by_number',
group: 'submit',
label: '以取号返回的实际物流公司递交委外仓,回传不改订单的物流公司',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'wechat_dropship',
group: 'submit',
label: '使用微信代发模式',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'wechat_supplier_id',
group: 'submit',
label: '微店供应商ID',
type: FIELD_TYPES.TEXT,
placeholder: '使用微信代发模式时填写',
},
{
key: 'other_channel_flag_to_other',
group: 'submit',
label: '订单含指定标记时,递交委外仓的渠道为OTHER',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'other_channel_flag_setting',
group: 'submit',
label: '委外仓渠道为OTHER的设置',
type: FIELD_TYPES.JSON,
description: '「设置」维护需转为 OTHER 的订单标记,JSON 对象',
},
/* ---------- 回传设置 ---------- */
{
key: 'stock_change_type_mapping',
group: 'callback',
label: '库存异动回传单据类型映射',
type: FIELD_TYPES.JSON,
description: '「设置」维护的单据类型映射,JSON 对象',
},
{
key: 'stock_change_warehouse_strategy',
group: 'callback',
label: '库存异动仓库匹配策略',
type: FIELD_TYPES.JSON,
description: '「设置」维护的仓库匹配策略,JSON 对象',
},
{
key: 'salereturn_stock_in_type',
group: 'callback',
label: '销退入库类型库存异动',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'callback_by_actual_stock',
group: 'callback',
label: '按实际库存异动回传',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'aftersale_defect_callback',
group: 'callback',
label: '生成售后异常件回传',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'use_wms_warehouse_code',
group: 'callback',
label: '使用仓储方的仓库编码',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'forbid_stock_change_modify_erp',
group: 'callback',
label: '不允许仓库通过库存异动方式修改ERP库存',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'outbound_by_actual_qty',
group: 'callback',
label: '按实发数量生成出库单',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'allow_order_flow_write_logistics',
group: 'callback',
label: '允许订单流水通知写入物流单号',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'order_flow_abnormal_to_abnormal',
group: 'callback',
label: '订单流水通知回传“异常”时,销售单转入异常订单',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'order_flow_cancel_force_cancel',
group: 'callback',
label: '订单流水通知回传“取消”时,销售单强制取消发货单',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'outbound_time_use_current',
group: 'callback',
label: '仓库发货回传时,销售单“发货时间”使用当前时间',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
{
key: 'unique_code_allow_outsource',
group: 'callback',
label: '唯一码订单平台校验未通过时允许委外仓发货',
type: FIELD_TYPES.SWITCH,
defaultValue: SWITCH_OFF,
},
];
/** 字段 key 集合(用于校验入参) */
const FIELD_KEYS = WAREHOUSE_API_FIELDS.map(field => field.key);
/**
* 分组定义(深拷贝,避免调用方修改硬编码常量)
* @return {Array} 分组列表
*/
function listGroupDefs() {
return FIELD_GROUPS.map(group => ({ ...group }));
}
/**
* 字段定义(深拷贝,避免调用方修改硬编码常量)
* @return {Array} 字段定义列表
*/
function listFieldDefs() {
return WAREHOUSE_API_FIELDS.map(field => ({
...field,
options: field.options ? field.options.map(option => ({ ...option })) : undefined,
}));
}
/**
* 字段的硬编码默认值
* @param {Object} field 字段定义
* @return {*} 未声明 defaultValue 时返回 null
*/
function defaultValueOf(field) {
return field.defaultValue === undefined ? null : field.defaultValue;
}
/**
* 按类型把单个值归一化为可用的形态(读取用:容错,不抛错)
* 值为空或类型不合法时,一律回落到硬编码默认值
* @param {Object} field 字段定义
* @param {*} raw extra 中该字段的原始值
* @return {*} 归一化后的值
*/
function coerceFieldValue(field, raw) {
if (raw === undefined || raw === null || raw === '') return defaultValueOf(field);
switch (field.type) {
case FIELD_TYPES.NUMBER: {
const num = Number(raw);
return Number.isFinite(num) ? num : defaultValueOf(field);
}
case FIELD_TYPES.SWITCH:
return raw === true || raw === 1 || raw === '1' || raw === 'true';
case FIELD_TYPES.JSON: {
if (typeof raw !== 'string') return raw;
try {
return JSON.parse(raw);
} catch {
return defaultValueOf(field);
}
}
default:
return typeof raw === 'object' ? raw : String(raw);
}
}
/**
* 【统一读取方法】从 extra 读取「字段名: 值」的 JSON 对象
* - 存储即键值 JSON 对象(warehouse_apis.extra),此处是唯一读取出口,
* 接口返回与后续推送业务都应调用它,不要各自解析 extra
* - 未配置或值非法的字段,用硬编码 defaultValue 兜底(未声明默认值则为 null)
* @param {Object|null} extra warehouse_apis.extra
* @return {Object} { 字段key: 字段值 }
*/
function readFieldValues(extra) {
const source = extra && typeof extra === 'object' && !Array.isArray(extra) ? extra : {};
const values = {};
for (const field of WAREHOUSE_API_FIELDS) {
values[field.key] = coerceFieldValue(field, source[field.key]);
}
return values;
}
/**
* 校验并按类型归一化入参中的字段值
* @param {Object} input 请求体 values
* @return {{values: Object, errors: Array<String>}} 归一化后的值与错误信息
*/
function normalizeFieldValues(input) {
const source = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
const values = {};
const errors = [];
for (const key of Object.keys(source)) {
if (!FIELD_KEYS.includes(key)) errors.push(`未知字段:${key}`);
}
for (const field of WAREHOUSE_API_FIELDS) {
const raw = source[field.key];
if (raw === undefined || raw === null || raw === '') {
if (field.required) errors.push(`${field.label}为必填项`);
continue;
}
switch (field.type) {
case FIELD_TYPES.NUMBER: {
const num = Number(raw);
if (!Number.isFinite(num)) errors.push(`${field.label}需为数字`);
else if ((field.min !== undefined && num < field.min) || (field.max !== undefined && num > field.max)) {
errors.push(`${field.label}取值范围为 ${field.min} ~ ${field.max}`);
} else values[field.key] = num;
break;
}
case FIELD_TYPES.SWITCH:
values[field.key] = raw === true || raw === 1 || raw === '1' || raw === 'true';
break;
case FIELD_TYPES.SELECT: {
const allowed = (field.options || []).map(option => option.value);
if (!allowed.includes(raw)) errors.push(`${field.label}取值不在可选范围内`);
else values[field.key] = raw;
break;
}
case FIELD_TYPES.JSON: {
try {
const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
values[field.key] = parsed;
} catch {
errors.push(`${field.label}需为合法的 JSON`);
}
break;
}
default:
values[field.key] = String(raw);
}
}
return { values, errors };
}
module.exports = {
FIELD_TYPES,
FIELD_TYPE_LIST,
FIELD_GROUPS,
WAREHOUSE_API_FIELDS,
listGroupDefs,
listFieldDefs,
readFieldValues,
normalizeFieldValues,
};