'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: 'business', label: '业务设置', description: '业务设置奇门配置帮助文档', }, ]; /** 开关类型字段的默认值:默认不启用 */ 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 = [ // 说明(2026-09-14 按用户要求逐轮核实后精简 —— 配置项是 WMS 后台的一套设置,OMS 侧只用得上其中两项): // - 「基础信息」分组已整体移除:customer_id 在 openapi 契约下恒为 null(奇门渠道才用于鉴权); // owner_alias / outsource_api_type 无任何引用;owner_code 在 openapi 的三个推送接口均 required=false, // 且 OMS 接收回传不看 ownerCode // - 「递交设置」(submit)与「回传设置」(callback)两组已整体移除:35 项里只有 item_name_with_spec 在用 // - 「业务设置」里同样未被读取的项也已移除:purchase_return_code_type / transfer_in_code_type / // transfer_out_code_type(出库/入库/退货类型编码已硬编码在 lib/wms/orderTypes.js 的枚举里)、 // sku_sync_key / barcode_sync_source(商品同步直接取 products.barcode/goods_code,不读配置) // - 现仅保留两项真正被读取的:api_version(请求 v 参数)、item_name_with_spec(商品同步名称拼规格) /* ---------- 业务设置 ---------- */ { 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' }, ], }, // 货品同步名称带规格:商品推送(singleitem.synchronize)时是否把 sku_property 拼到 itemName { key: 'item_name_with_spec', group: 'business', 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, };