- 仪表盘报表:新增 app/service/dashboard.js + app/controller/dashboard.js + app/lib/billStatus.js,注册 GET /api/dashboard/report(jwtAuth + principalCheck), 一次聚合返回概览指标、发货单/入库单/出库单状态分布与待办、近 N 天单据量与 出入库数量趋势、库存 Top 商品、最近出入库流水;warehouse_id 只过滤单据与流水 (product_stocks 无仓库维度);契约 dashboard* 同步到 swagger - 接口配置裁剪:仓库接口配置只保留 api_version 与 item_name_with_spec; 历史 warehouse_apis.extra 冗余键、owner_code 配置、递交/回传设置一并清理 (迁移 20260915002400~02800) - 入库/出库/发货单报文与字段对齐 WMS 标准:去掉 ownerCode、operatorCode 等多余字段, 入库明细补 itemId;发货单明细去掉无意义的 owner_code(迁移 20260915002600) - 单号 5 位起:四张单据表 AUTO_INCREMENT 提到 10000(迁移 20260915002900) - 账号名称/头像按主体维护:principal_users 增 name/avatar 并回填(迁移 20260915003000/03100), 新增 app/lib/accountProfile.js(关联表名称/头像 → users 兜底);审核人写入 operator/operator_name; register 不再写 nickname、updateProfile 仅接受邮箱/手机号 - 出库单推送/锁库存链路的配套调整(outboundOrderPush、订单与发货单控制器) Co-Authored-By: GitHub Copilot <noreply@github.com>
238 lines
8.4 KiB
JavaScript
238 lines
8.4 KiB
JavaScript
'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<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,
|
||
};
|