diff --git a/app/model/order_express_trace.js b/app/model/order_express_trace.js index b08dfeb..a9ba532 100644 --- a/app/model/order_express_trace.js +++ b/app/model/order_express_trace.js @@ -7,7 +7,7 @@ * @return {import('sequelize').ModelCtor} 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), diff --git a/app/service/systemMethods/waybill/warehouse.js b/app/service/systemMethods/waybill/warehouse.js index e0ed92a..11e5abc 100644 --- a/app/service/systemMethods/waybill/warehouse.js +++ b/app/service/systemMethods/waybill/warehouse.js @@ -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, }, diff --git a/app/service/systems/waybill.js b/app/service/systems/waybill.js index cf9a4f6..be53427 100644 --- a/app/service/systems/waybill.js +++ b/app/service/systems/waybill.js @@ -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, })); diff --git a/database/designs/waybill-module-design.md b/database/designs/waybill-module-design.md index 1b1d3d1..7ba3009 100644 --- a/database/designs/waybill-module-design.md +++ b/database/designs/waybill-module-design.md @@ -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" } diff --git a/database/migrations/20261111203500-change-trace-weight-to-decimal.js b/database/migrations/20261111203500-change-trace-weight-to-decimal.js new file mode 100644 index 0000000..327f34a --- /dev/null +++ b/database/migrations/20261111203500-change-trace-weight-to-decimal.js @@ -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)`); + }, +}; diff --git a/docs/openapi-callback-events.md b/docs/openapi-callback-events.md index 11be84e..c9078df 100644 --- a/docs/openapi-callback-events.md +++ b/docs/openapi-callback-events.md @@ -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` 整批判失败) diff --git a/methods/changes/system.json b/methods/changes/system.json index 137c0db..a693aa5 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -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", diff --git a/methods/system.json b/methods/system.json index c6af33f..3d548cd 100644 --- a/methods/system.json +++ b/methods/system.json @@ -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",