fix(waybill): 适配轨迹接口返回调整(空轨迹与小数重量)

- trace 为空数组(暂无轨迹)不再计为失败:只计入 result.empty,不落库,
  任务状态仍为 success;提示语补充「无轨迹 Z 单」
- weight 支持字符串小数(如 "0.99"):新增 parseTraceWeight 统一转数字保留 3 位小数
- wms_order_express_trace.weight 由 INT(11) 改为 DECIMAL(10,3)(迁移 20261111203500,
  已在开发库与生产库执行;MySQL 不支持 INT→DECIMAL 的 INPLACE,走 COPY 重建)
- 文档:methods/system.json(0.3.327)、变更记录、设计文档与出站回调说明同步

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-11 20:37:18 +08:00
parent 1964021d50
commit e99f8fad48
8 changed files with 150 additions and 15 deletions

View File

@ -7,7 +7,7 @@
* @return {import('sequelize').ModelCtor<import('sequelize').Model>} Sequelize 模型。
*/
module.exports = app => {
const { BIGINT, STRING, INTEGER, DATE, JSON: JSON_TYPE } = app.Sequelize;
const { BIGINT, STRING, DECIMAL, DATE, JSON: JSON_TYPE } = app.Sequelize;
const OrderExpressTrace = app.model.define('order_express_trace', {
id: {
@ -58,10 +58,10 @@ module.exports = app => {
comment: '操作机构所在城市(opOrgCityName)',
},
weight: {
type: INTEGER(11),
type: DECIMAL(10, 3),
allowNull: true,
defaultValue: 0,
comment: '重量(weight,来源原值)',
comment: '重量(weight,来源原值,支持小数如 0.99)',
},
scan_type: {
type: STRING(50),

View File

@ -715,18 +715,21 @@ class WaybillWarehouseService extends MainService {
}
const failedList = Array.isArray(result.failed) ? result.failed : [];
const emptyList = Array.isArray(result.empty) ? result.empty : [];
await this.setTraceTaskProgress(taskId, {
task_id: taskId,
status: 'success',
progress: 100,
current_count: waybillCodes.length,
total_count: waybillCodes.length,
message: `更新完成:新增 ${result.inserted} 条轨迹,更新 ${result.updated} 条,失败 ${failedList.length} 单`,
message: `更新完成:新增 ${result.inserted} 条轨迹,更新 ${result.updated} 条`
+ `,无轨迹 ${emptyList.length} 单,失败 ${failedList.length} 单`,
result: {
total: result.total,
matched: result.matched,
inserted: result.inserted,
updated: result.updated,
empty: emptyList,
not_found: Array.isArray(result.not_found) ? result.not_found : [],
failed: failedList,
},

View File

@ -1573,6 +1573,7 @@ class WaybillService extends MainService {
matched: 0,
inserted: 0,
updated: 0,
empty: [],
not_found: [],
failed: [],
};
@ -1600,6 +1601,7 @@ class WaybillService extends MainService {
}
const traceGroups = [];
const emptyWaybills = [];
const failed = [];
let processedCount = 0;
@ -1642,7 +1644,9 @@ class WaybillService extends MainService {
if (!waybillNo) continue;
const traceList = this.normalizeTraceList(row);
if (traceList.length === 0) {
failed.push({ waybill_code: waybillNo, reason: '轨迹内容为空' });
// 外部对「暂无轨迹」的运单返回 trace: [],属正常业务状态(如刚下单尚未揽收),
// 只计入 empty,不当作失败,避免整单任务被判失败
emptyWaybills.push(waybillNo);
continue;
}
traceGroups.push({ waybillNo, traces: traceList });
@ -1658,8 +1662,18 @@ class WaybillService extends MainService {
});
}
const empty = [ ...new Set(emptyWaybills) ];
if (traceGroups.length === 0) {
return { ...base, app_key: targetAppKey, failed };
// 全部为「暂无轨迹」或失败:无数据可落库,但只要没有硬失败(回调/业务码异常)就算执行成功
return {
...base,
success: failed.length === 0,
app_key: targetAppKey,
empty,
not_found: [ ...new Set(failed.map(item => item.waybill_code)) ],
failed,
...(failed.length === 0 && empty.length === 0 ? { reason: '未返回可用轨迹' } : {}),
};
}
const saveResult = await this.saveTraces({
@ -1677,6 +1691,7 @@ class WaybillService extends MainService {
matched: saveResult.matched,
inserted: saveResult.inserted,
updated: saveResult.updated,
empty: empty.length,
notFound: saveResult.notFound.length,
failed: failed.length,
});
@ -1688,6 +1703,7 @@ class WaybillService extends MainService {
matched: saveResult.matched,
inserted: saveResult.inserted,
updated: saveResult.updated,
empty,
not_found: notFound,
failed,
};
@ -1746,6 +1762,18 @@ class WaybillService extends MainService {
return list;
}
/**
* 解析轨迹重量:外部可能返回数字或字符串(如 "0.99"),统一转保留 3 位小数的数字。
* @param {*} value 外部返回值。
* @return {number} 重量,非法值返回 0。
*/
parseTraceWeight(value) {
if (value === undefined || value === null || value === '') return 0;
const num = Number(String(value).trim().replace(/,/g, ''));
if (!Number.isFinite(num)) return 0;
return Math.round(num * 1000) / 1000;
}
/**
* 解析轨迹操作时间:支持 'YYYY-MM-DD HH:mm:ss' 与 ISO 字符串,非法值返回 null。
* @param {*} value 外部返回值。
@ -1811,7 +1839,7 @@ class WaybillService extends MainService {
out_biz_code: String(trace.outBizCode || trace.out_biz_code || '').trim() || null,
memo: String(trace.memo || '').trim().slice(0, 500) || null,
op_org_city_name: String(trace.opOrgCityName || trace.op_org_city_name || '').trim() || null,
weight: Number(trace.weight) || 0,
weight: this.parseTraceWeight(trace.weight),
scan_type: String(trace.scanType || trace.scan_type || '').trim() || null,
raw_data: trace,
});
@ -1911,7 +1939,7 @@ class WaybillService extends MainService {
out_biz_code: row.out_biz_code || '',
memo: row.memo || '',
op_org_city_name: row.op_org_city_name || '',
weight: Number(row.weight) || 0,
weight: this.parseTraceWeight(row.weight),
scan_type: row.scan_type || '',
raw_data: row.raw_data || null,
}));

View File

@ -91,7 +91,7 @@
| `out_biz_code` | VARCHAR(191) NULL | `outBizCode` | 外部业务码 |
| `memo` | VARCHAR(500) NULL | `memo` | 轨迹描述 |
| `op_org_city_name` | VARCHAR(100) NULL | `opOrgCityName` | 操作机构城市 |
| `weight` | INT NULL DEFAULT 0 | `weight` | 重量(来源原值) |
| `weight` | DECIMAL(10,3) NULL DEFAULT 0 | `weight` | 重量(来源原值,支持小数如 `"0.99"`) |
| `scan_type` | VARCHAR(50) NULL | `scanType` | 扫描类型(发件/到件/派件/签收) |
| `raw_data` | JSON NULL | — | 原始轨迹报文兜底 |
@ -652,13 +652,15 @@ waybill.warehouse.updateTrace(入口层:参数校验 + 接口配置预检 +
```
- 兼容:`trace` 可为数组(一个运单多条轨迹)、`traces`/`traceList` 数组、`{ code, data: [...] }` 包装
- **暂无轨迹**:外部对未产生轨迹的运单返回 `"trace": []`,只计入任务 `result.empty`,不落库、不计失败,任务仍为 `success`
- **重量**:外部可能返回字符串小数(如 `"0.99"`),`parseTraceWeight` 统一转数字并保留 3 位小数(列类型 `DECIMAL(10,3)`)
- 落库映射:`opTime→op_time`、`outBizCode→out_biz_code`、`memo→memo`、`opOrgCityName→op_org_city_name`、`weight→weight`、`scanType→scan_type`,原始报文存 `raw_data`
- 幂等:唯一键 `(express_id, op_time, scan_type)`,重复回传只更新 `memo` / `op_org_city_name` / `weight` / `raw_data`
- 匹配不到运单的轨迹不落库,运单号写入任务 `result.not_found`
#### 任务进度
`task_id` 前缀 `waybill_trace_`,缓存键前缀 `waybill_trace_task_`(与 `waybill_export_`、`waybill_receive_` 隔离),`result` 返回 `{ total, matched, inserted, updated, not_found, failed }`。
`task_id` 前缀 `waybill_trace_`,缓存键前缀 `waybill_trace_task_`(与 `waybill_export_`、`waybill_receive_` 隔离),`result` 返回 `{ total, matched, inserted, updated, empty, not_found, failed }`;提示语形如「更新完成:新增 X 条轨迹,更新 Y 条,无轨迹 Z 单,失败 N 单」。
```json
{ "method": "waybill.warehouse.updateTraceTaskProgress", "task_id": "waybill_trace_1000028_1731190000000_ab12cd34" }

View File

@ -0,0 +1,75 @@
'use strict';
/**
* wms_order_express_trace.weight 由 INT 改为 DECIMAL(10,3)。
*
* 背景:外部轨迹接口返回的 weight 为带小数的字符串(如 "0.99"),
* 原 INT 列会把 0.99 四舍五入/截断为 1 或 0,丢失精度。
*
* 变更:INT(11) DEFAULT 0 → DECIMAL(10,3) DEFAULT 0(保留原可空性与注释)。
*
* 注意:MySQL 不支持 INT→DECIMAL 的 INPLACE 变更,只能 COPY(重建表)。
* 该表为 2026-11-11 新建(轨迹尚在接入期,数据量小),重建代价可接受。
* 幂等:已是 decimal 时跳过。
*/
const TABLE_NAME = 'wms_order_express_trace';
const COLUMN_NAME = 'weight';
module.exports = {
async up(queryInterface) {
const { sequelize } = queryInterface;
const [ rows ] = await sequelize.query(
'SELECT COLUMN_TYPE AS columnType, IS_NULLABLE AS isNullable, '
+ 'COLUMN_DEFAULT AS columnDefault, COLUMN_COMMENT AS columnComment '
+ 'FROM INFORMATION_SCHEMA.COLUMNS '
+ 'WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ?',
{ replacements: [ TABLE_NAME, COLUMN_NAME ] }
);
const column = (rows || [])[0];
if (!column) {
console.log(`[${COLUMN_NAME}] skip: ${TABLE_NAME}.${COLUMN_NAME} 列不存在`);
return;
}
if (String(column.columnType || '').toLowerCase().startsWith('decimal')) {
console.log(`[${COLUMN_NAME}] skip: 已是 DECIMAL(${column.columnType})`);
return;
}
const nullable = String(column.isNullable).toUpperCase() === 'YES' ? 'NULL' : 'NOT NULL';
const defaultValue = column.columnDefault === null || column.columnDefault === undefined
? ''
: ` DEFAULT ${Number(column.columnDefault) || 0}`;
const comment = String(column.columnComment || '').replace(/'/g, "''");
await sequelize.query(
`ALTER TABLE \`${TABLE_NAME}\` MODIFY COLUMN \`${COLUMN_NAME}\` `
+ `DECIMAL(10,3) ${nullable}${defaultValue} COMMENT '${comment}'`
);
console.log(`[${COLUMN_NAME}] changed to DECIMAL(10,3) on ${TABLE_NAME}`);
},
async down(queryInterface) {
const { sequelize } = queryInterface;
const [ rows ] = await sequelize.query(
'SELECT COLUMN_TYPE AS columnType, IS_NULLABLE AS isNullable, '
+ 'COLUMN_DEFAULT AS columnDefault, COLUMN_COMMENT AS columnComment '
+ 'FROM INFORMATION_SCHEMA.COLUMNS '
+ 'WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ?',
{ replacements: [ TABLE_NAME, COLUMN_NAME ] }
);
const column = (rows || [])[0];
if (!column) return;
if (!String(column.columnType || '').toLowerCase().startsWith('decimal')) return;
const nullable = String(column.isNullable).toUpperCase() === 'YES' ? 'NULL' : 'NOT NULL';
const comment = String(column.columnComment || '').replace(/'/g, "''");
await sequelize.query(
`ALTER TABLE \`${TABLE_NAME}\` MODIFY COLUMN \`${COLUMN_NAME}\` `
+ `INT(11) ${nullable} DEFAULT 0 COMMENT '${comment}'`
);
console.log(`[${COLUMN_NAME}] reverted to INT(11)`);
},
};

View File

@ -396,6 +396,8 @@ app_key=APP2024011514301234&method=entryorder.confirm&timestamp=1758047400&v=1.0
```
- 兼容:`trace` 可为数组(一个运单多条轨迹)、`traces` / `traceList` 数组、`{ code, data: [...] }` 包装
- **`trace: []`(暂无轨迹)**:属正常业务状态(如刚下单未揽收),只计入结果 `empty`,不落库、不计失败
- **`weight`**:可能返回字符串小数(如 `"0.99"`),WMS 统一转数字并按 `DECIMAL(10,3)` 落库
- 落库:`wms_order_express_trace`,唯一键 `(express_id, op_time, scan_type)` 幂等,命中时更新 `memo` / `op_org_city_name` / `weight` / `raw_data`
- 失败识别:与 3.6 相同(HTTP 200 但 `code` 非 `0/1/200` 整批判失败)

View File

@ -1,4 +1,22 @@
[
{
"version": "0.3.327",
"date": "2026-11-11",
"type": "updated",
"summary": "适配轨迹接口返回调整:trace 为空数组(暂无轨迹)不再计为失败,新增 result.empty;weight 支持字符串小数并改为 DECIMAL(10,3) 落库",
"methods": [
"waybill.warehouse.updateTrace",
"waybill.warehouse.updateTraceTaskProgress",
"waybill.warehouse.getTrace"
],
"notes": [
"背景:外部轨迹接口对暂无轨迹的运单返回 trace: [](如刚下单未揽收),原实现按「轨迹内容为空」计入 failed,导致整单任务被误判失败。",
"现口径:trace 为空数组 → 运单号写入 result.empty,不落库、不计 failed;任务状态仍为 success,提示语为「更新完成:新增 X 条轨迹,更新 Y 条,无轨迹 Z 单,失败 N 单」。",
"weight:外部返回可能是字符串小数(如 \"0.99\"),新增 parseTraceWeight 统一转数字并保留 3 位小数;非法值按 0 处理。",
"数据库:wms_order_express_trace.weight 由 INT(11) 改为 DECIMAL(10,3)(迁移 20261111203500,已执行开发库与生产库);MySQL 不支持 INT→DECIMAL 的 INPLACE 变更,该表为新建、数据量小,重建代价可接受。",
"getTrace 返回值不变,weight 现为小数(如 0.99)。"
]
},
{
"version": "0.3.326",
"date": "2026-11-11",

View File

@ -1,7 +1,7 @@
{
"module": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.3.326",
"version": "0.3.327",
"updatedAt": "2026-11-11",
"headers": [
{
@ -43367,14 +43367,15 @@
"notes": [
"链路:systemMethods/waybill/warehouse.js#updateTrace → systems/waybill.js#queryTraces → openapi/callback.js#sendByAppKey(event=waybill.getTrace)",
"请求与 waybill.getreceive 一致:{ request: { waybill_codes: [...] } },单批最多 10 个运单号,超出自动切批并在每批完成后更新任务进度",
"外部返回格式:[{ waybillNo, trace: { opTime, outBizCode, memo, opOrgCityName, weight, scanType } }];兼容 trace 为数组、traces 数组、{ code, data: [...] } 包装",
"落库:写 wms_order_express_trace,express_id 由 waybill_code + warehouse_id 匹配 wms_order_express 得到;按 (express_id, op_time, scan_type) 幂等,已存在则更新 memo/op_org_city_name/weight/raw_data",
"外部返回格式:[{ waybillNo, trace: {...} }],trace 可为对象或数组(空数组表示暂无轨迹);兼容 { code, data: [...] } 包装。weight 可能为字符串小数(如 \"0.99\"),统一转数字保留 3 位小数落库",
"落库:写 wms_order_express_trace,express_id 由 waybill_code + warehouse_id 匹配 wms_order_express 得到;按 (express_id, op_time, scan_type) 幂等,已存在则更新 memo/op_org_city_name/weight/raw_data;weight 列为 DECIMAL(10,3)",
"匹配不到运单的轨迹不计入落库,运单号写入任务 result.not_found",
"签名口径:与 waybill.getreceive 一致(signMode=simple,MD5(appSecret + timestamp + bodyJson))",
"签名字段映射:opTime→op_time、outBizCode→out_biz_code、memo→memo、opOrgCityName→op_org_city_name、weight→weight、scanType→scan_type,原始报文存 raw_data",
"where 圈选上限 5000 条(与 updateReceive 一致);运单号来源优先级 waybillCodes > where",
"任务进度:task_id 前缀 waybill_trace_,Redis 缓存键前缀 waybill_trace_task_,与导出(waybill_export_)、揽收(waybill_receive_)互相隔离",
"目标应用:仓库下 callback_functions 勾选了 waybill.getTrace 的首个启用应用(按 id 升序)"
"目标应用:仓库下 callback_functions 勾选了 waybill.getTrace 的首个启用应用(按 id 升序)",
"暂无轨迹(trace 为空数组):只计入结果 empty,不判失败、不落库;任务仍为 success"
]
},
{
@ -43491,6 +43492,12 @@
"required": false,
"description": "已存在并更新的轨迹条数"
},
{
"name": "empty",
"type": "array",
"required": false,
"description": "暂无轨迹的运单号列表(外部返回 trace: [],属正常业务状态,不计失败)"
},
{
"name": "not_found",
"type": "array",
@ -43647,7 +43654,7 @@
"name": "weight",
"type": "number",
"required": false,
"description": "重量(来源原值)"
"description": "重量(来源原值,支持小数如 0.99)"
},
{
"name": "scan_type",