WMS_MAIN/app/service/systems/sn_code_rule.js
liufumingren 9af7dcf8fb feat(storeWarehouse): 签约关系接口配置按货主开放接口落库且回调地址统一取配置
- storeWarehouse.store.saveApiConfig:新增 resolveContractApiInterfaceType,
  interface_type_id=3(OPEN_API_WAREHOUSE 仓库开放接口)自动映射为 2(OPEN_API 货主开放接口)落库,
  不再要求当前主体为仓库(货主可维护自身签约关系下的接口配置)
- callback_url 不再取入参(含 callbackUrl 别名),统一写入 config.openapi.defaultCallbackUrl(新增配置项,默认空)
- storeWarehouse.store.listApiConfig:interface_type_id 过滤同步映射(传 3 按 2 查询)
- 文档:methods/system.json 升级 0.3.350、methods/changes/system.json 变更记录、docs/openapi-callback-events.md 回调地址来源说明
- 测试:saveApiConfig 新增 4 条用例(3→2 落库、忽略入参回调地址、默认值未配置、货主主体可保存、缺失类型 404),listApiConfig 新增 1 条过滤映射用例

同时提交工作区其余在制品改动:
- waybill:移除 wms_order_express_trace 模型并新增 drop 迁移,轨迹查询/取号/打印链路调整
- order:订单 SN 编码(order_item_sn / order_item_sn_log / sn_code_rule、has_sn_item 回填迁移),pendingOrder/recheckOrder/wave/base 调整
- express_platform、order_async、order_export、order_storage_allocation、storage.report、stock_store 配套修复
- lib:新增 jd_client,调整 qimen_client、callback_functions 及配套测试

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-14 17:14:04 +08:00

236 lines
8.1 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';
const Service = require('egg').Service;
/** 单条 SN 码规则的匹配位置:前缀 */
const MATCH_TYPE_PREFIX = 'prefix';
/** 单条 SN 码规则的匹配位置:后缀 */
const MATCH_TYPE_SUFFIX = 'suffix';
/** 单条 SN 码规则的处理方式:整个扫码内容作为 SN 码 */
const KEEP_MODE_FULL = 'full';
/** 单条 SN 码规则的处理方式:去掉匹配到的前缀/后缀后作为 SN 码 */
const KEEP_MODE_STRIP = 'strip';
const MATCH_TYPE_SET = new Set([ MATCH_TYPE_PREFIX, MATCH_TYPE_SUFFIX ]);
const KEEP_MODE_SET = new Set([ KEEP_MODE_FULL, KEEP_MODE_STRIP ]);
/** 单个商品最多可配置的 SN 码规则条数 */
const MAX_RULE_COUNT = 20;
/** 前缀/后缀字符串最大长度 */
const MAX_MATCH_VALUE_LENGTH = 64;
/** 扫码内容(用于匹配校验)最大长度,与 wms_order_item_sn.sn_code 的 VARCHAR(512) 对齐 */
const MAX_SN_CODE_LENGTH = 512;
/**
* 商品 SN 码规则服务。
*
* 规则用于把「扫到的码」加工成真正入库的 SN 码,一条规则三步:
* 1. match_type:匹配位置,prefix=前缀 / suffix=后缀;
* 2. match_value:要匹配的前缀或后缀字符串;
* 3. keep_mode:full=整个扫码内容作为 SN 码 / strip=去掉匹配到的前缀或后缀后再作为 SN 码。
*
* 存储形如:
* [{ "match_type": "prefix", "match_value": "YGP", "keep_mode": "strip" }]
* 多条规则按数组顺序匹配,命中第一条即生效。
*/
class SnCodeRuleService extends Service {
/**
* 推断单条规则字段在其它调用处的可用性(供外部判断常量使用)。
* @return {Object} 规则常量。
*/
getConstants() {
return {
matchTypes: [ MATCH_TYPE_PREFIX, MATCH_TYPE_SUFFIX ],
keepModes: [ KEEP_MODE_FULL, KEEP_MODE_STRIP ],
maxRuleCount: MAX_RULE_COUNT,
maxMatchValueLength: MAX_MATCH_VALUE_LENGTH,
};
}
/**
* 把任意来源的规则内容解析为数组(不做元素合法性校验)。
* 兼容 JSON 字符串、数组、null/undefined;其它类型抛错。
*
* @param {*} rawRules 原始规则内容。
* @return {Object[]} 规则数组(未逐条校验)。
*/
parseRules(rawRules) {
if (rawRules === undefined || rawRules === null) {
return [];
}
if (Array.isArray(rawRules)) {
return rawRules;
}
if (typeof rawRules === 'string') {
const text = rawRules.trim();
if (!text) {
return [];
}
let parsed;
try {
parsed = JSON.parse(text);
} catch {
throw new Error('SN码规则格式不正确,必须是合法的 JSON 数组');
}
if (!Array.isArray(parsed)) {
throw new Error('SN码规则格式不正确,必须是数组');
}
return parsed;
}
throw new Error('SN码规则格式不正确,必须是数组');
}
/**
* 读取并校验规则;非法内容返回空数组,用于查询回显(不抛错)。
*
* @param {*} rawRules 原始规则内容(数据库列值)。
* @return {Object[]} 规范化后的规则数组。
*/
toRuleList(rawRules) {
try {
return this.normalizeRules(rawRules);
} catch {
return [];
}
}
/**
* 校验并规范化保存入参中的 SN 码规则。
*
* @param {*} rawRules 前端传入的规则(数组或 JSON 字符串),支持 match_type/matchType 等写法。
* @return {Object[]} 规范化后的规则数组:{ match_type, match_value, keep_mode }。
*/
normalizeRules(rawRules) {
const parsed = this.parseRules(rawRules);
if (parsed.length > MAX_RULE_COUNT) {
throw new Error(`SN码规则最多配置${MAX_RULE_COUNT}条`);
}
const normalized = [];
const seenKeys = new Set();
parsed.forEach((rawRule, index) => {
const position = index + 1;
const rule = this.isPlainObject(rawRule) ? rawRule : null;
if (!rule) {
throw new Error(`第${position}条SN码规则格式不正确,必须是对象`);
}
const matchType = this.normalizeMatchType(rule.match_type ?? rule.matchType ?? rule.type);
if (!matchType) {
throw new Error(`第${position}条SN码规则的匹配位置(match_type)只能是 prefix(前缀)或 suffix(后缀)`);
}
const matchValue = this.normalizeMatchValue(rule.match_value ?? rule.matchValue ?? rule.value);
if (!matchValue) {
throw new Error(`第${position}条SN码规则的匹配内容(match_value)不能为空`);
}
if (matchValue.length > MAX_MATCH_VALUE_LENGTH) {
throw new Error(`第${position}条SN码规则的匹配内容(match_value)长度不能超过${MAX_MATCH_VALUE_LENGTH}个字符`);
}
const keepMode = this.normalizeKeepMode(rule.keep_mode ?? rule.keepMode ?? rule.mode);
if (!keepMode) {
throw new Error(`第${position}条SN码规则的处理方式(keep_mode)只能是 full(全码)或 strip(去掉前缀/后缀)`);
}
const uniqueKey = `${matchType}|${matchValue}|${keepMode}`;
if (seenKeys.has(uniqueKey)) {
throw new Error(`第${position}条SN码规则与前面的规则重复:${matchType}「${matchValue}」${keepMode}`);
}
seenKeys.add(uniqueKey);
normalized.push({
match_type: matchType,
match_value: matchValue,
keep_mode: keepMode,
});
});
return normalized;
}
/**
* 按规则把扫码内容加工成 SN 码;未命中任何规则时返回原码。
*
* @param {string} rawCode 扫码内容。
* @param {Object[]} rules 已规范化的规则数组。
* @return {{ matched: boolean, rule: Object|null, sn_code: string, reason?: string }} 匹配结果。
*/
matchSnCode(rawCode, rules = []) {
const code = String(rawCode === undefined || rawCode === null ? '' : rawCode).trim();
if (!code) {
return { matched: false, rule: null, sn_code: '', reason: 'empty_code' };
}
if (code.length > MAX_SN_CODE_LENGTH) {
return { matched: false, rule: null, sn_code: code, reason: 'code_too_long' };
}
const ruleList = this.toRuleList(rules);
for (const rule of ruleList) {
if (rule.match_type === MATCH_TYPE_PREFIX && !code.startsWith(rule.match_value)) {
continue;
}
if (rule.match_type === MATCH_TYPE_SUFFIX && !code.endsWith(rule.match_value)) {
continue;
}
let snCode = code;
if (rule.keep_mode === KEEP_MODE_STRIP) {
const start = rule.match_type === MATCH_TYPE_PREFIX ? rule.match_value.length : 0;
const end = rule.match_type === MATCH_TYPE_SUFFIX ? code.length - rule.match_value.length : code.length;
snCode = code.slice(start, end);
}
if (!snCode) {
return { matched: true, rule, sn_code: '', reason: 'empty_after_strip' };
}
return { matched: true, rule, sn_code: snCode };
}
return { matched: false, rule: null, sn_code: code };
}
/**
* 规范化匹配位置。
* @param {*} rawValue 原始值。
* @return {string} 'prefix' / 'suffix',非法返回空串。
*/
normalizeMatchType(rawValue) {
const value = String(rawValue === undefined || rawValue === null ? '' : rawValue).trim().toLowerCase();
return MATCH_TYPE_SET.has(value) ? value : '';
}
/**
* 规范化处理方式。
* @param {*} rawValue 原始值。
* @return {string} 'full' / 'strip',非法返回空串。
*/
normalizeKeepMode(rawValue) {
const value = String(rawValue === undefined || rawValue === null ? '' : rawValue).trim().toLowerCase();
return KEEP_MODE_SET.has(value) ? value : '';
}
/**
* 清洗前缀/后缀字符串:去首尾空白,把 undefined/null 转空串。
* @param {*} rawValue 原始值。
* @return {string} 清洗后的字符串。
*/
normalizeMatchValue(rawValue) {
if (rawValue === undefined || rawValue === null) {
return '';
}
return String(rawValue).trim();
}
/**
* 判断是否普通对象。
* @param {*} value 待判断值。
* @return {boolean} 是否普通对象。
*/
isPlainObject(value) {
return Object.prototype.toString.call(value) === '[object Object]';
}
}
module.exports = SnCodeRuleService;