WMS_MAIN/database/migrations/20261111193000-create-wms-order-express-trace.js
liufumingren 89e4cd22c0 feat(waybill): 运单物流轨迹表与 waybill.getTrace 批量更新
- 新增 wms_order_express_trace(1 运单 : N 轨迹):express_id 关联主表,
  冗余 waybill_code / order_id,warehouse_id 隔离,raw_data 存原始报文;
  uk_express_op_scan(express_id, op_time, scan_type) 幂等;字符集与主表一致
- 新增出站回调 waybill.getTrace(注册到 callback_functions,管理端可勾选):
  入参与 waybill.getreceive 一致({ request: { waybill_codes: [...] } },单批 10 单,
  signMode=simple);响应 [{ waybillNo, trace: {...} }],兼容 trace 数组与 {code,data} 包装
- 新增 waybill.warehouse.updateTrace / updateTraceTaskProgress:
  复用导出任务的异步任务ID与进度模式(前缀 waybill_trace_),
  支持 waybillCodes 或与 waybill.warehouse.list 一致的 where 条件圈选(上限 5000);
  轨迹按 (express_id, op_time, scan_type) upsert,未匹配运单计入 not_found
- 文档:methods/system.json(0.3.325)、变更记录、设计文档 2.2.1/3.9、出站回调说明 3.7

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-11 19:53:29 +08:00

138 lines
4.7 KiB
JavaScript
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.

'use strict';
/**
* 创建运单物流轨迹表 wms_order_express_trace。
*
* 与 wms_order_express 关联:一个运单(express_id)对应多条轨迹(1:N),
* 轨迹由外部快递/轨迹接口回传(如奇门 taobao.qimen.trace.query 的 traces 节点)。
*
* 字段口径(与外部返回的轨迹行同名转下划线):
* op_time opTime 操作时间
* out_biz_code outBizCode 外部业务码(可能是拼接串,如 770358128188071_510180_1794262553000_210)
* memo memo 轨迹描述,如【广州市】快件已发往 山东济南转运中心
* op_org_city_name opOrgCityName 操作机构所在城市
* weight weight 重量(来源原值,单位以对接方为准)
* scan_type scanType 扫描类型,如 发件 / 到件 / 派件 / 签收
* raw_data 原始报文 JSON,便于后续新增字段时不改表结构
*
* 关联与隔离:
* express_id / waybill_code / order_id 冗余落库,便于「按运单」「按订单」直接查询;
* warehouse_id 做仓库隔离,避免跨仓串读。
*
* 幂等去重:uk_express_op_scan(express_id + op_time + scan_type)保证重复回传不落重复行。
*
* 索引:
* uk_express_op_scan(express_id, op_time, scan_type 唯一)
* idx_waybill_code(waybill_code, op_time)
* idx_order_id(order_id)
* idx_warehouse_op_time(warehouse_id, op_time)
*/
const TABLE_NAME = 'wms_order_express_trace';
module.exports = {
async up(queryInterface, Sequelize) {
const { BIGINT, STRING, INTEGER, DATE, JSON: JSON_TYPE } = Sequelize;
await queryInterface.createTable(TABLE_NAME, {
id: {
type: BIGINT(20).UNSIGNED,
primaryKey: true,
autoIncrement: true,
allowNull: false,
comment: '主键ID',
},
express_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '运单ID(wms_order_express.id)',
},
waybill_code: {
type: STRING(50),
allowNull: false,
comment: '运单号(冗余,便于按运单号直查)',
},
order_id: {
type: BIGINT(20).UNSIGNED,
allowNull: true,
comment: '订单ID(冗余,便于按订单查轨迹)',
},
warehouse_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '仓库ID(数据隔离维度)',
},
op_time: {
type: DATE,
allowNull: true,
comment: '操作时间(opTime)',
},
out_biz_code: {
type: STRING(191),
allowNull: true,
comment: '外部业务码(outBizCode)',
},
memo: {
type: STRING(500),
allowNull: true,
comment: '轨迹描述(memo),如【广州市】快件已发往 山东济南转运中心',
},
op_org_city_name: {
type: STRING(100),
allowNull: true,
comment: '操作机构所在城市(opOrgCityName)',
},
weight: {
type: INTEGER(11),
allowNull: true,
defaultValue: 0,
comment: '重量(weight,来源原值)',
},
scan_type: {
type: STRING(50),
allowNull: true,
comment: '扫描类型(scanType),如 发件/到件/派件/签收',
},
raw_data: {
type: JSON_TYPE,
allowNull: true,
comment: '原始轨迹报文(未落库字段的兜底存储)',
},
created_at: {
type: DATE,
allowNull: false,
defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
comment: '创建时间',
},
updated_at: {
type: DATE,
allowNull: false,
defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
comment: '更新时间',
},
deleted_at: {
type: DATE,
allowNull: true,
comment: '软删除时间',
},
}, {
// 与主表 wms_order_express 保持一致(utf8mb4_general_ci),避免轨迹描述含 4 字节字符时写入失败
charset: 'utf8mb4',
collate: 'utf8mb4_general_ci',
comment: '运单物流轨迹表(1 运单 : N 轨迹)',
});
await queryInterface.addIndex(TABLE_NAME, [ 'express_id', 'op_time', 'scan_type' ], {
unique: true,
name: 'uk_express_op_scan',
});
await queryInterface.addIndex(TABLE_NAME, [ 'waybill_code', 'op_time' ], { name: 'idx_waybill_code' });
await queryInterface.addIndex(TABLE_NAME, [ 'order_id' ], { name: 'idx_order_id' });
await queryInterface.addIndex(TABLE_NAME, [ 'warehouse_id', 'op_time' ], { name: 'idx_warehouse_op_time' });
},
async down(queryInterface) {
await queryInterface.dropTable(TABLE_NAME);
},
};