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

139 lines
5.4 KiB
Markdown
Raw 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.

# 订单自定义店铺-快递绑定策略 设计方案
> **状态**: 📋 设计中
> **设计日期**: 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,可选)
用于扩展匹配条件,可进一步按以下维度过滤:
```jsonc
{
"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:按自定义店铺标签绑定快递
```sql
INSERT INTO wms_store_express_binding_policy
(warehouse_id, custom_name, express_code, priority, creator_id)
VALUES
(1000000, '旗舰店-中通', 'ZTO', 10, 10001);
```
### 场景2:按自定义店铺标签+省份绑定快递(偏远地区走邮政)
```sql
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:全局默认快递
```sql
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` 支持定时策略(如大促期间切换快递)
- 策略复制:支持跨仓库复制策略配置