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:
parent
1964021d50
commit
e99f8fad48
@ -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),
|
||||
|
||||
@ -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,
|
||||
},
|
||||
|
||||
@ -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,
|
||||
}));
|
||||
|
||||
@ -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" }
|
||||
|
||||
@ -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)`);
|
||||
},
|
||||
};
|
||||
@ -396,6 +396,8 @@ app_key=APP2024011514301234&method=entryorder.confirm×tamp=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` 整批判失败)
|
||||
|
||||
|
||||
@ -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",
|
||||
|
||||
@ -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",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user