'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}} 归一化后的值与错误信息 */ 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, };