oms/backend/app/lib/warehouseApiFields.js
liufumingren 489563a4b2 feat(backend): 仪表盘报表接口、配置裁剪、单号 5 位与账号名称/头像
- 仪表盘报表:新增 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>
2026-09-14 16:09:35 +08:00

238 lines
8.4 KiB
JavaScript
Raw Permalink 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: '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,
};