WMS_MAIN/database/designs/store-express-binding-policy-design.md
liufumingren 0b781a7e70 feat: 店铺快递绑定策略模块 + 订单创建链路集成 + 运单号分配优化
【新增模块】
- app/model/store_express_binding_policy.js: 策略数据模型(17字段,JSON数组)
- app/service/systems/store_express_binding_policy.js: CRUD+列表(含名称批量解析)
- app/service/systems/express_policy.js: 缓存优先策略查询 + 6维漏斗匹配引擎
- app/service/systemMethods/store_express_binding_policy.js: method路由层
- database/designs/store-express-binding-policy-design.md: 设计文档

【策略漏斗匹配逻辑】
- 按priority DESC逐条匹配: store_ids→shop_name→prohibited→regions→exclude→weight
- NULL/空数组=不限, 未命中自动continue到下一条
- 地区/店铺匹配使用子串包含(省/市/区/详细地址均生效)
- 违禁品匹配使用数组交集
- 输出快递编码+重量类型, 未命中返回null

【订单创建链路集成】
- addOrder→addOrderLines后触发matchPolicy(weight可用)
- 命中: 写入logistics/sys_logistics 4字段+weight_type+操作日志
- 未命中: 降级到resolveExpressSnapshot默认值+兜底DEFAULT_STORE_SUBJECT_CONFIG(STO)
- 系统快递4字段一致, 自定义映射(express_setting)分流写入

【运单号分配优化】
- pickWaybillExpressInterface两步兜底:
  Step1: logistics_code仅匹配express_code(自定义编码精确)
  Step2: sys_logistics_code匹配全候选码(系统编码兜底)
- 新增weight_type过滤器(接口NULL=通配, 设限须精确匹配)
- groupedOrder.options新增sys_logistics_code/weight_type传递

【操作码翻译】
- ORDER_EXPRESS_POLICY_MATCH: '策略命中'
- ORDER_EXPRESS_FALLBACK: '快递降级'
- 无策略命中时写入快递降级日志

【API文档】
- methods/system.json: 策略模块4接口+响应字段(express_name/数组类型等)

【数据库迁移】
- 13个migration: 建表→字段迭代→TEXT改JSON→prohibited改数组(dev+prod均执行)
2026-08-04 08:18:43 +08:00

5.4 KiB
Raw Blame History

订单自定义店铺-快递绑定策略 设计方案

状态: 📋 设计中
设计日期: 2026-08-03
模块: 订单快递分配策略
表: 1 张 — wms_store_express_binding_policy


一、背景与目的

在 WMS 系统中,订单的快递分配目前依赖以下路径:

  1. store_warehouse.policy_config.auto_allocate_express 控制是否自动分配
  2. express_interface 表提供「仓库 + 店铺 + 平台 + 快递」的接口配置映射
  3. 货主 subject_config.default_express_code 提供默认快递

痛点:无法根据业务场景灵活配置"某个仓库下,某店铺(或某货主)强制使用/优先使用某快递"的策略。例如:

  • 仓库 A 的拼多多店铺「旗舰店」必须走中通(ZTO),而「奥莱店」走圆通(YTO)
  • 同一店铺在不同条件下(如收件省份、商品类型)使用不同快递
  • 多人同时管理时需要记录创建人、创建时间,方便追溯

解决方案:新增 wms_store_express_binding_policy 表,支持自定义店铺-快递绑定策略,按优先级匹配。


二、数据库表

wms_store_express_binding_policy

字段 类型 必填 默认值 说明
id BIGINT UNSIGNED ✅ AUTO 主键
warehouse_id BIGINT UNSIGNED ✅ — 仓库ID,策略所属仓库
custom_name VARCHAR(100) ✅ — 自定义店铺标签名称(自由文本,与系统店铺无关)
express_code VARCHAR(50) ✅ — 绑定的快递编码(关联 wms_express.code)
priority INT(11) ✅ 0 优先级,数值越大越优先匹配
is_enabled TINYINT(1) ✅ 1 是否启用:0=停用,1=启用
match_condition JSON — NULL 附加匹配条件(见下方说明)
remark VARCHAR(500) — NULL 备注说明
creator_id BIGINT UNSIGNED — NULL 创建人账户ID(关联 accounts 表)
created_at DATETIME ✅ CURRENT_TIMESTAMP 创建时间
updated_at DATETIME ✅ CURRENT_TIMESTAMP ON UPDATE 更新时间
deleted_at DATETIME — NULL 软删除时间

索引设计

索引名 字段 说明
PRIMARY id 主键
idx_warehouse_enabled warehouse_id, is_enabled, deleted_at 按仓库查询启用策略
idx_warehouse_express warehouse_id, express_code, deleted_at 按仓库+快递反查绑定

match_condition 字段说明(JSON,可选)

用于扩展匹配条件,可进一步按以下维度过滤:

{
  "platform_codes": ["PDD", "TB"],      // 限定平台编码
  "provinces": ["广东省", "浙江省"],       // 限定收件省份
  "cities": ["广州市", "杭州市"],          // 限定收件城市
  "item_codes": ["SKU001", "SKU002"],   // 限定商品编码
  "min_weight_g": 0,                    // 最小重量(g),NULL=不限制
  "max_weight_g": 5000,                 // 最大重量(g),NULL=不限制
  "min_amount": 0,                      // 最小金额(元),NULL=不限制
  "max_amount": 1000                    // 最大金额(元),NULL=不限制
}

三、匹配逻辑(伪代码)

1. 查询 wms_store_express_binding_policy
   WHERE warehouse_id = :warehouseId
     AND is_enabled = 1
     AND deleted_at IS NULL
   ORDER BY priority DESC, id ASC

2. 遍历结果集,对每条策略:
   a. 若 match_condition 为空 → 命中,返回 express_code
   b. 若 match_condition 不为空 → 逐条件判断:
      - platform_codes:订单平台编码是否在列表中
      - provinces / cities:收件地址省/市是否在列表中
      - item_codes:订单商品编码是否命中
      - min/max_weight_g:订单总重量是否在范围内
      - min/max_amount:订单总金额是否在范围内
   c. 所有条件 AND 全部满足 → 命中,返回 express_code

3. 若未命中任何策略 → 回退到原有默认逻辑
   (express_interface 匹配 → subject_config.default_express_code)

四、与现有表的关系

wms_store_express_binding_policy
  ├─ warehouse_id  → stores.id(逻辑关联,不做物理外键)
  ├─ express_code  → wms_express.code(逻辑关联)
  └─ creator_id    → accounts.id(逻辑关联)

五、典型使用场景

场景1:按自定义店铺标签绑定快递

INSERT INTO wms_store_express_binding_policy
  (warehouse_id, custom_name, express_code, priority, creator_id)
VALUES
  (1000000, '旗舰店-中通', 'ZTO', 10, 10001);

场景2:按自定义店铺标签+省份绑定快递(偏远地区走邮政)

INSERT INTO wms_store_express_binding_policy
  (warehouse_id, custom_name, express_code, priority, match_condition, creator_id)
VALUES
  (1000000, '偏远地区邮政', 'EMS', 20,
   '{"provinces":["新疆维吾尔自治区","西藏自治区","青海省"]}', 10001);

场景3:全局默认快递

INSERT INTO wms_store_express_binding_policy
  (warehouse_id, custom_name, express_code, priority, creator_id)
VALUES
  (1000000, '全局顺丰', 'SF', 5, 10001);

六、后续扩展

  • 策略命中日志:记录每次快递分配命中了哪条策略,便于分析调整
  • 策略生效时间段:增加 start_time / end_time 支持定时策略(如大促期间切换快递)
  • 策略复制:支持跨仓库复制策略配置