From 6c8a96de3b9bd71ceb192fe6ee5b464f13e67c0b Mon Sep 17 00:00:00 2001 From: liufumingren Date: Wed, 30 Sep 2026 03:08:59 +0800 Subject: [PATCH] =?UTF-8?q?docs(methods):=20=E5=90=8C=E6=AD=A5=E7=9B=98?= =?UTF-8?q?=E7=82=B9/=E5=9B=9E=E8=B0=83=E6=B3=A8=E5=86=8C=E8=A1=A8/?= =?UTF-8?q?=E6=89=8B=E5=B7=A5=E8=BF=90=E5=8D=95=E5=8F=B7/=E6=94=B6?= =?UTF-8?q?=E8=B4=A7=E7=BB=91=E5=AE=9A=E6=8E=A5=E5=8F=A3=E6=96=87=E6=A1=A3?= =?UTF-8?q?=EF=BC=880.3.205=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- methods/changes/system.json | 153 ++++ methods/system.json | 1345 ++++++++++++++++++++++++++++++++++- 2 files changed, 1492 insertions(+), 6 deletions(-) diff --git a/methods/changes/system.json b/methods/changes/system.json index 1bd5764..14027d8 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,157 @@ [ + { + "version": "2026.09.30-manual-waybill-express-code", + "date": "2026-09-30", + "type": "updated", + "summary": "order.pendingOrder.manualWaybill 新增可选参数 express_code:传入时同步修改订单的快递编码,行为参考 updateOrderExpress", + "methods": [ + "order.pendingOrder.manualWaybill" + ], + "notes": [ + "代码依据:app/service/systemMethods/order/pendingOrder.js#manualWaybill 新增可选入参 express_code(string,选填,trim 后为空视为未传);传入时参考 updateOrderExpress 的解析口径——从当前仓库快递列表(带缓存 getExpressList)中查找对应项,不存在则抛『快递编码 不存在』;自定义映射(is_system_setting=true)时订单 sys_logistics_code/name 写系统快递编码和名称、logistics_code/name 写自定义编码和名称,系统快递(is_system_setting=false)时四个字段均写系统快递的 code/name;不传时保持原行为(运单记录沿用订单当前 sys_logistics_code/name)。", + "写入范围:传入 express_code 时,订单表同步更新 sys_logistics_code/sys_logistics_name/logistics_code/logistics_name 四字段(与 print_status/post_status='fin' 同一次 update),运单记录(wms_order_express)的 logistics_code/logistics_name 写入解析后的新值;不传时运单记录沿用订单原系统快递字段。", + "操作日志:extras 新增 expressCode/sysLogisticsCode/sysLogisticsName/logisticsCode/logisticsName 字段,message 在传入 express_code 时补充快递信息。", + "响应:传入 express_code 时额外返回 express_code、sys_logistics_code、sys_logistics_name、logistics_code、logistics_name;不传时响应结构与原版本一致(向后兼容)。", + "文档变更范围:methods/system.json 的 order.pendingOrder.manualWaybill 更新 description、params 新增 express_code、response 新增 5 个可选字段、errors 新增 404 快递编码不存在;根版本 0.3.204 → 0.3.205、updatedAt 更新为 2026-09-30;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。" + ] + }, + { + "version": "2026.09.29-stock-check-no-global-sequence", + "date": "2026-09-29", + "type": "updated", + "summary": "盘点单号改为全局递增:generateCheckNo 移除按仓库隔离(uk_check_no 全局唯一索引下按仓从 1 起会跨仓撞号),create 撞唯一键自动重取重试最多 5 次,口径与收货单 receiving_number 一致", + "methods": [ + "stock.check.create" + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js#generateCheckNo 移除 warehouse_id 隔离条件,改为查询全局最大 PD+YYYYMMDD 前缀单号取末尾 6 位序号 +1;新增 isCheckNoDuplicateError()(parent.code==='ER_DUP_ENTRY' 且 sqlMessage 命中 uk_check_no/check_no,参照收货单 isReceivingNumberDuplicateError 口径);create() 撞唯一键自动重取单号重试最多 5 次(与收货单 create 重试口径一致),超过重试次数或非单号冲突错误原样抛出。", + "原因说明:uk_check_no 为全局唯一索引(不区分仓库),原按仓库隔离序号各自从 1 起会跨仓撞号;改为全局递增后并发创建仍有极小概率撞号,由唯一键重试兜底。", + "收货单参照口径:与收货单 receiving_number 一致——按全局最大序号 +1 生成 + 撞唯一键自动重取重试。", + "并发重试说明:每次重试都重新调用 generateCheckNo() 取最新全局最大序号;仅 ER_DUP_ENTRY 且命中 uk_check_no 才重试,其它错误直接抛出。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create 的 description 与 notes;根版本 0.3.203 → 0.3.204、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致。" + ] + }, + { + "version": "2026.09.29-stock-check-detail-delete", + "date": "2026-09-29", + "type": "added", + "summary": "新增 stock.check.detailDelete:删除盘点明细(从任务移除商品),仅 created/rejected 状态允许,删除时防御性清理作业记录并重算 total_items", + "methods": [ + "stock.check.detailDelete" + ], + "notes": [ + "代码依据:app/service/systemMethods/stock/check.js(ALL_METHOD_NAMES 扩为 14 个含 detailDelete;detailDelete 从登录上下文注入 warehouseId,入参 id + detail_id(兼容 detailId 驼峰,detail_id 优先),走统一 _call 捕获业务错误码;为写操作,不在免日志清单 list/detail/recordList/export/exportTaskProgress 中)、app/service/systems/stock_check.js(detailDelete:id/detail_id 非法抛 400『盘点任务ID不能为空/盘点明细ID不能为空』,任务不存在/明细不存在分别抛 400;仅 ADD_DETAIL_ALLOWED_STATUSES(created/rejected)允许删除,否则 400『当前状态(xxx)不允许删除明细』;删除明细后防御性清理 wms_stock_check_record 并重算主表 total_items;返回 { detail_id, deleted:true, total_items })。", + "状态限制口径:仅主表 created/rejected 允许删除明细(与 addDetail 口径一致,共用 ADD_DETAIL_ALLOWED_STATUSES);其它状态返回 400。", + "防御清理说明:正常流程 created/rejected 状态不应存在作业记录,但为兜底,删除明细时按 { detail_id, check_id, warehouse_id } 一并删除 wms_stock_check_record 中的关联记录,避免残留孤儿记录;删除后重算主表 total_items。", + "权限口径:随 ALL_METHOD_NAMES 免 API 权限(isNeedAuth=false)、免仓库有效期鉴权(免鉴权清单)、必须登录(isNeedLogin=true,免登录清单为空);detailDelete 为写操作,记录操作日志。", + "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.detailDelete(放在 addDetail 之后,与代码 ALL_METHOD_NAMES 顺序一致);根版本 0.3.202 → 0.3.203、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次先按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON,随后同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致。" + ] + }, + { + "version": "2026.09.29-stock-check-record-unique-index", + "date": "2026-09-29", + "type": "updated", + "summary": "盘点作业记录表加固:location_code 空串归一 + 历史重复合并 + 唯一索引 uk_detail_location(detail_id, location_code),从数据库层保证 report 覆盖式上报并发安全;接口返回口径不变(空库位 location_code 仍为 null)", + "methods": [ + "stock.check.report", + "stock.check.recordList" + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js(report 未传库位归一存空串 '';查重条件统一 { detail_id, location_code };依赖数据库层唯一索引 uk_detail_location 保证并发安全;recordList 返回 location_code 空串归一为 null;detail 的 locations/location_codes 输出口径不变,空库位组 location_code=null)、app/model/stock_check_record.js(location_code allowNull=false defaultValue='')。", + "迁移:database/migrations/20260929130000-unique-stock-check-record-detail-location.js——location_code 归一 NULL→''、合并历史重复记录(同 detail_id+location_code 保留 id 最大一条)、列改 NOT NULL DEFAULT ''、新增唯一索引 uk_detail_location(detail_id, location_code);本地与生产均已执行。", + "口径变化:report 未传库位不再存 NULL 而是存空串 ''(\"无库位\"分组),覆盖式查重条件不变({ detail_id, location_code },含空串分组),并发下由唯一索引兜底不产生重复记录。", + "接口兼容性:对外返回口径不变——recordList 将空串归一为 null、detail 的 locations/location_codes 空库位组 location_code 仍为 null,客户端无需调整。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.report 的 description/notes 与 location 入参描述、stock.check.recordList 的 rows response 描述与 notes(空串归一 null 口径);根版本 0.3.201 → 0.3.202、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" + ] + }, + { + "version": "2026.09.29-stock-check-work-adjust", + "date": "2026-09-29", + "type": "updated", + "summary": "盘点作业接口 5 项调整:report 改为覆盖式(同明细+同库位重复上报更新已有记录)、新增 recordDelete(删作业记录重算汇总)与 recordList(分页查作业记录)、detail rows 增加按库位聚合 locations、finish 放宽未盘校验(未盘按实盘 0 计盘亏并返回 unchecked_items)", + "methods": [ + "stock.check.report", + "stock.check.detail", + "stock.check.finish", + "stock.check.recordDelete", + "stock.check.recordList" + ], + "notes": [ + "代码依据:app/service/systemMethods/stock/check.js(ALL_METHOD_NAMES 扩为 13 个含 recordList/recordDelete;免权限/免鉴权清单共用全部方法,免日志清单为 list/detail/recordList/export/exportTaskProgress;recordDelete 入参兼容 record_id/recordId 写法)、app/service/systems/stock_check.js(report 覆盖式上报:同 detail_id + 同 location_code(含同为空库位 location_code 为 NULL)更新已有记录 quantity/checker_id/checker_name/checked_at 并保留/回填 location_id,否则新增,返回 mode=created|updated;recordList 按 id DESC 分页返回记录全字段 + item_code/item_name;recordDelete 仅 approved/checking 状态、删除后重算汇总且主表状态不回退;detail rows 增加 locations 按库位聚合;finish 未盘明细按实盘 0 计盘亏并返回 unchecked_items)。", + "行为口径变化明细:①stock.check.report 从每次新增一条记录改为覆盖式——同 detail_id + 同 location_code(含同为空库位)重复上报更新已有记录(quantity/checker/checked_at),首次上报才新增,返回 mode=created|updated;②新增 stock.check.recordDelete:入参 id + record_id(兼容 recordId),仅 approved/checking 状态允许,删除后重算 total_items/checked_items/diff_items/detail_status(明细记录删光后回到未盘),主表状态不回退,返回 { record_id, deleted:true, ...summary };③新增 stock.check.recordList:入参 id(可选)+ detail_id(可选)+ pagination 至少传其一,返回 { rows, total, page, pageSize },rows=记录全字段 + item_code/item_name,按 id DESC;④stock.check.detail rows 每条新增 locations 数组(按库位聚合 [{ location_id, location_code, quantity }],空库位归 location_code=null 组),records 与既有聚合字段不变;⑤stock.check.finish 不再拦截未盘明细,未盘按实盘 0 处理(diff=-账面快照,计盘亏与 diff_items),返回新增 unchecked_items 字段。", + "无 schema 变更:本次仅业务行为调整,wms_stock_check / wms_stock_check_detail / wms_stock_check_record 表结构未变,无需数据库迁移。", + "权限口径:recordList/recordDelete 与同分组其它方法一致——免 API 权限(isNeedAuth=false)、免仓库有效期鉴权、必须登录(isNeedLogin=true);recordList 为查询类免操作日志,recordDelete 为写操作记录操作日志。", + "文档变更范围:methods/system.json 的 module=stock.check 分组新增 stock.check.recordList、stock.check.recordDelete 两条 method,更新 stock.check.report/detail/finish 三条 description 与 response(report 增加 mode 字段、detail rows 增加 locations 聚合、finish 增加 unchecked_items 并移除未盘拦截错误);根版本 0.3.200 → 0.3.201、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" + ] + }, + { + "version": "2026.09.29-storage-entry-bindReceiving-soft-deleted-restore", + "date": "2026-09-29", + "type": "fixed", + "summary": "storage.entry.bindReceiving 修复解绑后重新绑定失败:CREATED 分支改用三态幂等(已存在跳过/软删除恢复/新建),不再因软删除残留行撞唯一索引报 BINDING_WRITE_FAILED(Validation error)", + "methods": [ + "storage.entry.bindReceiving" + ], + "notes": [ + "根因:findOrCreate 查询默认排除软删除行(paranoid),解绑(unbindReceiving 软删除主表绑定行)后再次绑定同一 (entry_order_id, receiving_id) 时,create 撞唯一索引 uk_entry_order_receiving 抛 SequelizeUniqueConstraintError(message 为 \"Validation error\"),被捕获计入 skipped 并返回 BINDING_WRITE_FAILED。生产现场:绑定行 id=793(入库单 1280 RK202609290005 ↔ 收货单 4686 R20725003)于 2026-09-28 19:02 解绑软删除,2026-09-29 重新绑定即失败。", + "修复:app/service/systems/receiving_entry_match.js 的 bindEntryOrderReceiving CREATED 分支改为 paranoid:false 查询三态处理——未删除已存在跳过(created=false)、已软删除则 allocated_quantity 重置为 {} 并 restore(restored=true)、不存在新建(create 唯一索引冲突视为并发已建立,created=false);bound 项统一返回 created/restored 两字段。", + "同类加固:_commitBinding(PDA 上架确保主表绑定)的 findOrCreate 同步改为三态;_bindEntryOrderReceiving(自动匹配)与 _bindOneReceivingAndSyncStorage(COMPLETED)恢复软删除行时显式 allocated_quantity={} 兜底、软删除判断兼容 deletedAt/deleted_at 两种属性名。", + "文档变更范围:methods/system.json storage.entry.bindReceiving 的 bound.created/restored 描述更新、restored required 改为 true;根版本 0.3.199 → 0.3.200、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" + ] + }, + { + "version": "2026.09.29-stock-check-detail-split", + "date": "2026-09-29", + "type": "updated", + "summary": "盘点明细表拆分:wms_stock_check_detail 仅保留盘点商品(stock_id+快照),库位/数量信息下沉到新建 wms_stock_check_record(盘点作业记录表);report 改为写入记录(同明细可多库位多次上报),已盘口径=存在记录,差异=记录数量合计-账面快照;detail 返回 records 与聚合字段;导出明细行含库位合并/盘点人合并。", + "methods": [ + "stock.check.report", + "stock.check.detail", + "stock.check.finish", + "stock.check.export", + "stock.check.exportTaskProgress" + ], + "notes": [ + "代码依据:app/model/stock_check_detail.js(明细表仅存盘点商品:stock_id+商品快照,移除 location_id/location_code/check_quantity/diff_quantity/is_diff/status/checker_id/checker_name/checked_at)、app/model/stock_check_record.js(新建盘点作业记录表:check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark,一个明细可在多库位多次上报)、app/service/systems/stock_check.js(report 写入记录不再更新明细;detail 返回 records 与聚合字段;finish 未盘=无记录明细、差异按记录聚合;export Sheet2 商品级聚合+库位/盘点人合并)、app/service/systemMethods/stock/check.js(report 从登录上下文注入 checkerId/checkerName)。", + "迁移:database/migrations/20260929120000-split-stock-check-detail-create-record.js(明细表移除 9 个作业字段 + 新建 wms_stock_check_record 及 4 个索引 idx_check_id/idx_detail_id/idx_stock_id/idx_warehouse_location),本地与生产均已执行。", + "口径变化明细:report 每次上报新增一条作业记录(同明细可在多库位多次上报),明细已盘数量=记录 quantity 合计;已盘口径=存在记录(DISTINCT detail_id);差异=记录数量合计-账面快照 system_quantity;detail.rows 返回 checked_quantity/diff_quantity/is_diff/status/location_codes[]/checkers[]/last_checked_at + records[];finish 未盘明细=无记录明细;export Sheet2 明细行(商品级聚合)列为 盘点单号/商品编码/商品名称/规格/账面数量/已盘数量/差异数量/是否有差异/库位编码(顿号合并)/盘点人(合并)/最近盘点时间。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.report/detail/finish/export 共 4 条 method 的 description 与 response;根版本 0.3.198 → 0.3.199、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" + ] + }, + { + "version": "2026.09.29-stock-check-apis", + "date": "2026-09-29", + "type": "added", + "summary": "新增库存盘点模块 11 个 method(创建空任务/列表/添加明细/拉取明细/盘点作业上报/完成盘点/提交审核/取消/审核/导出/导出进度),完整状态机 created→submitted→approved/rejected→checking→completed/cancelled", + "methods": [ + "stock.check.create", + "stock.check.list", + "stock.check.addDetail", + "stock.check.detail", + "stock.check.report", + "stock.check.finish", + "stock.check.submit", + "stock.check.cancel", + "stock.check.audit", + "stock.check.export", + "stock.check.exportTaskProgress" + ], + "notes": [ + "代码依据:app/service/systemMethods/stock/check.js(11 个 method 包装层,统一 _call 包装 400/500)与 app/service/systems/stock_check.js(状态机、单号生成 PD+YYYYMMDD+6位序号、汇总重算、Excel 导出 + COS 上传)。", + "表结构:wms_stock_check(盘点主表,仓库隔离 warehouse_id、盘点单号 check_no 唯一、状态 status、明细进度 detail_status、汇总 total_items/checked_items/diff_items)与 wms_stock_check_detail(盘点明细表,商品/库位快照、账面数量 system_quantity、实盘数量 check_quantity、差异数量 diff_quantity=实盘-账面)。", + "迁移:database/migrations/20260929100000-create-wms-stock-check.js、20260929101000-create-wms-stock-check-detail.js、20260929110000-align-stock-check-status-machine.js(主表 status 默认值 pending → created、注释对齐新状态机),本地与生产均已执行。", + "权限口径:11 个 method 全部免权限/免鉴权(仓库有效期检查)/需登录;list/detail/export/exportTaskProgress 免操作日志;不产生 wms_permission 权限记录,无需执行 permission:sync:system-api。", + "导出任务口径:Redis 进度缓存 key stock_check_export_task_{taskId}、TTL 1800 秒;每任务一个 Sheet(Sheet 名=盘点单号 check_no);单次最多 50 个盘点任务。", + "文档变更范围:methods/system.json 新增分组 module=stock.check(库存盘点模块)共 11 条 method;根版本 0.3.196 → 0.3.197、updatedAt 2026-09-28 → 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。" + ] + }, { "version": "2026.09.28-weigh-pack-padding-message", "date": "2026-09-28", diff --git a/methods/system.json b/methods/system.json index 9b7b96b..2a78687 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.196", - "updatedAt": "2026-09-28", + "version": "0.3.205", + "updatedAt": "2026-09-30", "headers": [ { "name": "platform", @@ -25106,13 +25106,13 @@ "name": "created", "type": "boolean", "required": true, - "description": "本次是否新建绑定(CREATED 为 findOrCreate 结果;COMPLETED 新建或恢复均为 true)" + "description": "本次是否新建绑定行;绑定已存在(未删除)或由软删除行恢复时为 false" }, { "name": "restored", "type": "boolean", - "required": false, - "description": "仅 COMPLETED:是否由已软删除的绑定关系恢复(恢复后按归一化目标执行进度同步)" + "required": true, + "description": "是否由已软删除(解绑产生)的绑定行恢复;CREATED 恢复后台账重置为 {} 不重算进度,COMPLETED 恢复后按归一化目标执行进度同步" }, { "name": "storage_sync", @@ -31883,7 +31883,7 @@ }, { "method": "order.pendingOrder.manualWaybill", - "description": "手工录入运单号。为指定待处理订单创建一条运单记录(wms_order_express 表),仅允许 step 在 [1,2,3] 且 outbound_status 不为 'padding' 的订单操作。完成后自动更新订单表的 print_status 与 post_status 为 'fin',表示外部已打印。", + "description": "手工录入运单号。为指定待处理订单创建一条运单记录(wms_order_express 表),仅允许 step 在 [1,2,3] 且 outbound_status 不为 'padding' 的订单操作。完成后自动更新订单表的 print_status 与 post_status 为 'fin',表示外部已打印。可选传入 express_code,行为参考 updateOrderExpress:从当前仓库快递列表(带缓存)中查找对应项,若为自定义映射(is_system_setting=true),订单 sys_logistics_code/name 写系统快递编码和名称、logistics_code/name 写自定义编码和名称;若为系统快递(is_system_setting=false),四个字段均写系统快递的 code/name;未找到则报错;不传则运单记录沿用订单当前系统快递信息。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -31915,6 +31915,13 @@ "required": false, "source": "body", "description": "物流接口名称(选填),手工填入的值,trim 后为空则传 null" + }, + { + "name": "express_code", + "type": "string", + "required": false, + "source": "body", + "description": "快递编码(选填),可为系统编码或仓库自定义编码。传入时同步修改订单的快递信息,行为参考 updateOrderExpress;不传时运单记录沿用订单当前系统快递信息" } ], "response": [ @@ -31953,6 +31960,36 @@ "type": "string", "required": true, "description": "创建时间" + }, + { + "name": "express_code", + "type": "string", + "required": false, + "description": "传入的快递编码,未传时不返回" + }, + { + "name": "sys_logistics_code", + "type": "string", + "required": false, + "description": "写入订单的系统快递编码,仅在传入 express_code 时返回" + }, + { + "name": "sys_logistics_name", + "type": "string", + "required": false, + "description": "写入订单的系统快递名称,仅在传入 express_code 时返回" + }, + { + "name": "logistics_code", + "type": "string", + "required": false, + "description": "写入订单与运单记录的快递编码(自定义或系统),仅在传入 express_code 时返回" + }, + { + "name": "logistics_name", + "type": "string", + "required": false, + "description": "写入订单与运单记录的快递名称(自定义或系统),仅在传入 express_code 时返回" } ], "errors": [ @@ -31976,6 +32013,10 @@ "code": 400, "message": "订单已标记待出库,不允许手工录入运单号" }, + { + "code": 404, + "message": "快递编码 不存在" + }, { "code": 500, "message": "内部错误:OrderExpress 模型未加载或数据库写入失败" @@ -37737,6 +37778,1181 @@ } ] }, + { + "groupName": "库存盘点模块", + "module": "stock.check", + "list": [ + { + "method": "stock.check.create", + "description": "创建盘点任务(空任务):生成盘点单号(PD+YYYYMMDD+6位序号,序号全局递增(不按仓库隔离),并发下撞 uk_check_no 唯一键自动重取重试(最多 5 次),口径与收货单 receiving_number 一致),初始状态 created、明细进度 none_checked;warehouse_id 由服务端从当前登录上下文(ctx.user.store_id)自动注入,前端无需传递。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "title", + "type": "string", + "required": false, + "source": "body", + "description": "盘点名称/主题(非必填)" + }, + { + "name": "type", + "type": "string", + "required": false, + "source": "body", + "description": "盘点范围类型,缺省 all:all=全盘 / store=按货主 / goods=按商品 / location=按库位" + }, + { + "name": "mode", + "type": "string", + "required": false, + "source": "body", + "description": "盘点方式,缺省 open:open=明盘(可见账面数量)/ blind=盲盘(不可见账面数量)" + }, + { + "name": "store_id", + "type": "number", + "required": false, + "source": "body", + "description": "货主ID(type=store 按货主盘点时必填)" + }, + { + "name": "check_date", + "type": "string", + "required": true, + "source": "body", + "description": "盘点日期(必填,格式必须可被 Date 解析)" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "盘点任务ID" + }, + { + "name": "check_no", + "type": "string", + "required": true, + "description": "盘点单号(PD+YYYYMMDD+6位序号)" + }, + { + "name": "title", + "type": "string", + "required": true, + "description": "盘点名称/主题" + }, + { + "name": "type", + "type": "string", + "required": true, + "description": "盘点范围类型:all/store/goods/location" + }, + { + "name": "mode", + "type": "string", + "required": true, + "description": "盘点方式:open/blind" + }, + { + "name": "store_id", + "type": "number", + "required": false, + "description": "货主ID(按货主盘点时有值)" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "主表状态(新建为 created)" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "明细盘点进度:none_checked/partial_checked/all_checked(新建为 none_checked)" + }, + { + "name": "check_date", + "type": "string", + "required": false, + "description": "盘点日期" + }, + { + "name": "start_time", + "type": "string", + "required": false, + "description": "实际开始时间(开始盘点作业后回填)" + }, + { + "name": "end_time", + "type": "string", + "required": false, + "description": "实际结束时间(完成盘点后回填)" + }, + { + "name": "creator_id", + "type": "number", + "required": true, + "description": "创建人账户ID" + }, + { + "name": "creator_name", + "type": "string", + "required": true, + "description": "创建人名称快照" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细行数" + }, + { + "name": "checked_items", + "type": "number", + "required": true, + "description": "已盘行数" + }, + { + "name": "diff_items", + "type": "number", + "required": true, + "description": "差异行数" + }, + { + "name": "remark", + "type": "string", + "required": true, + "description": "备注" + }, + { + "name": "created_at", + "type": "string", + "required": false, + "description": "创建时间" + }, + { + "name": "updated_at", + "type": "string", + "required": false, + "description": "更新时间" + } + ], + "errors": [ + { + "code": 400, + "message": "无法获取当前仓库上下文 / 盘点范围类型不合法 / 盘点方式不合法 / 按货主盘点时必须指定货主 / 盘点日期不能为空且格式必须合法" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ], + "notes": [ + "代码依据:app/service/systems/stock_check.js#generateCheckNo 移除 warehouse_id 隔离条件,改为查询全局最大 PD+YYYYMMDD 前缀单号并取末尾 6 位序号 +1(不按仓库隔离);新增 isCheckNoDuplicateError()(parent.code === 'ER_DUP_ENTRY' 且 sqlMessage 命中 uk_check_no/check_no,参照收货单 isReceivingNumberDuplicateError 口径);create() 创建撞唯一键时自动重取单号重试,最多 5 次(maxCreateRetries=5,与收货单 create 重试口径一致);超过重试次数或非单号冲突错误原样抛出。", + "原因说明:uk_check_no 为全局唯一索引(不区分仓库),原按仓库隔离序号各自从 1 起会跨仓撞号;改为全局递增后并发创建仍有极小概率撞号,由唯一键重试兜底。", + "收货单参照口径:与收货单 receiving_number 一致——按全局最大序号 +1 生成 + 撞唯一键自动重取重试。", + "并发重试说明:每次重试都重新调用 generateCheckNo() 取最新全局最大序号;仅 ER_DUP_ENTRY 且命中 uk_check_no 的错误才重试,其它错误不重试直接抛出。", + "文档变更范围:methods/system.json 的 module=stock.check 分组更新 stock.check.create 的 description 与 notes;根版本 0.3.203 → 0.3.204、updatedAt 保持 2026-09-29;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。", + "库表维护源说明:维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 写入 JSON 后,同步回填开发库与生产库(import 当前 system.json → export 回写往返校验),保持库与文件一致。" + ] + }, + { + "method": "stock.check.list", + "description": "拉取盘点任务列表:按当前用户仓库(ctx.user.store_id)限定数据范围,支持 status 状态筛选(单值或数组)、store_id 货主筛选、keyword 关键字(盘点单号/标题模糊)与分页。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数 { page, pageSize },默认 page=1、pageSize=20,pageSize 上限 200" + }, + { + "name": "where.status", + "type": "string", + "required": false, + "source": "body", + "description": "状态筛选(单值或数组):created/submitted/rejected/approved/checking/completed/cancelled" + }, + { + "name": "where.store_id", + "type": "number", + "required": false, + "source": "body", + "description": "货主筛选" + }, + { + "name": "where.keyword", + "type": "string", + "required": false, + "source": "body", + "description": "关键字,对盘点单号(check_no)/标题(title)模糊匹配" + } + ], + "response": [ + { + "name": "rows", + "type": "array", + "required": true, + "description": "盘点任务行列表(主表全字段,含 check_no/title/type/mode/store_id/status/detail_status/check_date/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at)" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "总条数" + }, + { + "name": "page", + "type": "number", + "required": true, + "description": "当前页码" + }, + { + "name": "pageSize", + "type": "number", + "required": true, + "description": "每页条数" + } + ], + "errors": [ + { + "code": 500, + "message": "服务器内部错误" + } + ] + }, + { + "method": "stock.check.addDetail", + "description": "添加盘点明细:按 stock_ids 查询 wms_stock_warehouse 生成明细快照行(商品编码/名称/规格/账面数量等);仅 created/rejected 状态允许;已存在同 stock_id 的明细自动跳过(幂等),完成后重算主表 total_items。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID" + }, + { + "name": "stock_ids", + "type": "array", + "required": true, + "source": "body", + "description": "商品库存ID列表(wms_stock_warehouse.id)" + } + ], + "response": [ + { + "name": "added", + "type": "number", + "required": true, + "description": "本次新增明细数" + }, + { + "name": "skipped", + "type": "number", + "required": true, + "description": "已存在被跳过(幂等)的 stock_id 数" + }, + { + "name": "invalid_stock_ids", + "type": "array", + "required": true, + "description": "无效商品库存ID列表(不存在或不属于当前仓库)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "重算后的明细总行数" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 created/rejected)不允许添加明细 / 请至少选择一个商品" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ] + }, + { + "method": "stock.check.detailDelete", + "description": "删除盘点明细(从任务中移除某个商品):入参 id(盘点任务ID)+ detail_id(盘点明细ID,兼容 detailId 驼峰写法,detail_id 优先);仅主表状态 created/rejected 允许删除;明细存在作业记录(wms_stock_check_record)时防御性一并删除(正常流程该状态不应有记录);删除后重算主表 total_items,返回 { detail_id, deleted, total_items }。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID" + }, + { + "name": "detail_id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点明细ID(与 detailId 二选一,detail_id 优先)" + }, + { + "name": "detailId", + "type": "number", + "required": false, + "source": "body", + "description": "盘点明细ID(驼峰别名,兼容写法)" + } + ], + "response": [ + { + "name": "detail_id", + "type": "number", + "required": true, + "description": "被删除的盘点明细ID" + }, + { + "name": "deleted", + "type": "boolean", + "required": true, + "description": "是否删除成功(true)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "删除后重算的主表明细总行数" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空 / 盘点明细ID不能为空 / 盘点任务不存在 / 当前状态(非 created/rejected)不允许删除明细 / 盘点明细不存在" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ], + "notes": [ + "写操作,记录操作日志(不在免日志清单 list/detail/recordList/export/exportTaskProgress 中)。", + "detail_id 与 detailId 兼容:detail_id 非空时优先,否则取 detailId。", + "删除后对 wms_stock_check_record 按 { detail_id, check_id, warehouse_id } 防御性清理作业记录,并重算主表 total_items。" + ] + }, + { + "method": "stock.check.detail", + "description": "拉取盘点任务的全部明细行(商品清单)与盘点作业记录:返回主表信息(check)与全部明细(rows);rows 每条含商品快照(id/check_id/warehouse_id/stock_id/item_code/item_name/spec/batch_no/system_quantity/remark/created_at/updated_at)+ 已盘聚合字段(checked_quantity=作业记录数量合计、diff_quantity=实盘-账面、is_diff、status=checked|unchecked、location_codes、checkers、last_checked_at)+ records(该明细在 wms_stock_check_record 的全部作业记录:库位+数量+盘点人)+ locations(按库位聚合 [{ location_id, location_code, quantity }],空库位归 location_code=null 组)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID" + } + ], + "response": [ + { + "name": "check", + "type": "object", + "required": true, + "description": "盘点主表信息(id/check_no/title/type/mode/store_id/status/detail_status/check_date/start_time/end_time/creator_id/creator_name/total_items/checked_items/diff_items/remark/created_at/updated_at)" + }, + { + "name": "rows", + "type": "array", + "required": true, + "description": "明细行列表:每条含商品快照(id/check_id/warehouse_id/stock_id/item_code/item_name/spec/batch_no/system_quantity 账面快照/remark/created_at/updated_at)+ 已盘聚合(checked_quantity 已盘数量=作业记录 quantity 合计、diff_quantity 差异数量=已盘-账面、is_diff 是否有差异 0|1、status=checked|unchecked、location_codes 库位编码数组去重、checkers 盘点人数组去重、last_checked_at 最近上报时间)+ records(该明细全部盘点作业记录,每条含 id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/created_at/updated_at)+ locations(按库位聚合数组,每项含 location_id/location_code/quantity,quantity 为该库位下作业记录数量合计;空库位记录归 location_code=null 组;按首条记录 id 升序);无作业记录时 records/locations 为空数组、聚合字段为 null" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "明细总条数" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空 / 盘点任务不存在" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ] + }, + { + "method": "stock.check.report", + "description": "盘点作业上报(覆盖式):同明细 + 同库位编码重复上报时更新已有记录(quantity/checker_id/checker_name/checked_at,保留原 location_id,若本次新匹配到 location_id 则回填),不再新增;未传库位归入\"无库位\"分组(location_code 存空串 ''),同分组重复上报同样覆盖更新;仅 approved/checking 状态允许;库位编码匹配 wms_location_space.space_code 时回填 location_id;主表 approved 首次上报自动转 checking;完成后重算 checked_items/diff_items/detail_status(已盘口径=存在记录的明细数,差异=记录数量合计-账面快照);数据库层由唯一索引 uk_detail_location(detail_id, location_code) 保证覆盖式上报并发安全(并发下不产生重复记录)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID" + }, + { + "name": "detail_id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点明细ID" + }, + { + "name": "location", + "type": "string", + "required": false, + "source": "body", + "description": "库位编码(可空;写入作业记录 location_code,匹配 space_code 时回填 location_id;未传或为空归入无库位分组(存空串 ''))" + }, + { + "name": "quantity", + "type": "number", + "required": true, + "source": "body", + "description": "实盘数量(不小于 0 的整数)" + } + ], + "response": [ + { + "name": "record", + "type": "object", + "required": true, + "description": "新增或更新的盘点作业记录(wms_stock_check_record 行:id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/created_at/updated_at)" + }, + { + "name": "detail_id", + "type": "number", + "required": true, + "description": "盘点明细ID" + }, + { + "name": "mode", + "type": "string", + "required": true, + "description": "本次上报模式:created=首次上报新增记录 / updated=同明细+同库位重复上报更新已有记录" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "checked_items", + "type": "number", + "required": true, + "description": "已盘行数(存在作业记录的明细数)" + }, + { + "name": "diff_items", + "type": "number", + "required": true, + "description": "差异行数(实盘合计与账面快照不一致的明细数)" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "明细盘点进度:none_checked/partial_checked/all_checked" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空 / 盘点明细ID不能为空 / 盘点任务不存在 / 当前状态(非 approved/checking)不允许盘点作业 / 实盘数量必须为不小于0的整数 / 盘点明细不存在" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ], + "notes": [ + "覆盖口径:同 detail_id + 同 location_code(未传库位存储空串 '',即\"无库位\"分组)视为同一作业记录,重复上报只更新不新增。", + "并发保证:数据库层唯一索引 uk_detail_location(detail_id, location_code) 兜底,并发上报同一明细+库位时不产生重复记录(模型 location_code allowNull=false 默认空串)。" + ] + }, + { + "method": "stock.check.recordList", + "description": "拉取盘点作业记录列表:至少传 id(盘点任务ID)或 detail_id(明细ID)之一(可同时传,detail_id 生效时只查该明细的作业记录);按当前用户仓库(ctx.user.store_id)限定数据范围;rows 每条为作业记录(wms_stock_check_record)全字段 + 商品快照列(item_code/item_name,从明细表补齐);按记录 id 倒序,分页返回。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": false, + "source": "body", + "description": "盘点任务ID(可选;与 detail_id 至少传一个)" + }, + { + "name": "detail_id", + "type": "number", + "required": false, + "source": "body", + "description": "盘点明细ID(可选;传了只查该明细的作业记录;与 id 至少传一个)" + }, + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数 { page, pageSize },默认 page=1、pageSize=20,pageSize 上限 200(最小 1)" + } + ], + "response": [ + { + "name": "rows", + "type": "array", + "required": true, + "description": "作业记录行列表:每条为 wms_stock_check_record 全字段(id/check_id/warehouse_id/detail_id/stock_id/location_id/location_code/quantity/checker_id/checker_name/checked_at/remark/created_at/updated_at)+ 商品快照列 item_code/item_name;location_code 口径:库中空串(\"无库位\"分组)返回时归一为 null(接口返回口径不变)" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "总条数" + }, + { + "name": "page", + "type": "number", + "required": true, + "description": "当前页码" + }, + { + "name": "pageSize", + "type": "number", + "required": true, + "description": "每页条数" + } + ], + "errors": [ + { + "code": 400, + "message": "请至少提供盘点任务ID或明细ID" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ], + "notes": [ + "查询类方法,不记录操作日志(免日志清单:list/detail/recordList/export/exportTaskProgress)。", + "rows 按记录 id 倒序返回。", + "location_code 返回口径:库中空串(无库位分组)归一为 null,接口返回口径不变(与 detail 的 locations/location_codes 空库位组 location_code=null 一致)。" + ] + }, + { + "method": "stock.check.recordDelete", + "description": "删除盘点作业记录:仅主表状态 approved/checking 允许删除;记录必须属于该盘点任务与当前仓库,删除后重算 checked_items/diff_items/detail_status(该明细作业记录删光后回到未盘口径),主表状态不回退。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID" + }, + { + "name": "record_id", + "type": "number", + "required": true, + "source": "body", + "description": "作业记录ID(wms_stock_check_record.id)" + }, + { + "name": "recordId", + "type": "number", + "required": false, + "source": "body", + "description": "作业记录ID(驼峰别名,兼容写法;record_id 优先)" + } + ], + "response": [ + { + "name": "record_id", + "type": "number", + "required": true, + "description": "被删除的作业记录ID" + }, + { + "name": "deleted", + "type": "boolean", + "required": true, + "description": "是否删除成功(true)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "checked_items", + "type": "number", + "required": true, + "description": "重算后的已盘行数(存在作业记录的明细数)" + }, + { + "name": "diff_items", + "type": "number", + "required": true, + "description": "重算后的差异行数(实盘合计与账面快照不一致的明细数)" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "重算后的明细盘点进度:none_checked/partial_checked/all_checked" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空 / 作业记录ID不能为空 / 盘点任务不存在 / 当前状态(非 approved/checking)不允许删除作业记录 / 作业记录不存在或不属于该盘点任务" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ], + "notes": [ + "删除为写操作,记录操作日志(不在免日志清单)。", + "删除后仅重算盘点进度汇总(checked_items/diff_items/detail_status),主表状态不回退。" + ] + }, + { + "method": "stock.check.finish", + "description": "完成盘点作业(允许部分未盘完成):仅 approved/checking 状态允许;未盘明细=无作业记录(wms_stock_check_record)的明细,按实盘 0 处理(差异=-账面快照,计入盘亏与差异行数);已盘明细按作业记录数量合计与账面快照(system_quantity)对比聚合(盘盈=正差异合计、盘亏=负差异绝对值合计);完成后主表置 completed、回填 end_time、detail_status=all_checked,返回差异汇总(盘盈/盘亏合计)与未盘明细数(unchecked_items)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "盘点任务ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "完成后的主表状态(completed)" + }, + { + "name": "total_items", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "checked_items", + "type": "number", + "required": true, + "description": "已盘行数(存在作业记录的明细数)" + }, + { + "name": "unchecked_items", + "type": "number", + "required": true, + "description": "未盘明细数(无作业记录的明细数,完成时按实盘 0 处理计为盘亏)" + }, + { + "name": "diff_items", + "type": "number", + "required": true, + "description": "差异行数(实盘合计与账面快照不一致的明细数,未盘明细按实盘 0 计入)" + }, + { + "name": "profit_total", + "type": "number", + "required": true, + "description": "盘盈合计(作业记录数量合计大于账面快照的差异合计)" + }, + { + "name": "loss_total", + "type": "number", + "required": true, + "description": "盘亏合计(实盘小于账面快照的差异绝对值合计,含未盘明细的账面快照数)" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 approved/checking)不允许完成盘点" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ] + }, + { + "method": "stock.check.submit", + "description": "完成盘点任务(提交审核):仅 created/rejected 状态允许;校验 total_items>0(无明细行时拒绝)后主表置 submitted(待审核)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "盘点任务ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "提交后的主表状态(submitted)" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 created/rejected)不允许提交审核 / 盘点任务还没有明细行,无法提交审核" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ] + }, + { + "method": "stock.check.cancel", + "description": "取消盘点任务:仅 created/submitted/rejected 状态允许;取消后主表置 cancelled(终态)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "盘点任务ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "取消后的主表状态(cancelled)" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空 / 盘点任务不存在 / 当前状态(非 created/submitted/rejected)不允许取消" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ] + }, + { + "method": "stock.check.audit", + "description": "审核盘点任务:仅 submitted 状态允许;action=approve → 主表置 approved(审核完成,待盘点作业);action=reject → 主表置 rejected(驳回,可重新添加明细再提交),reason 可选(缺省保留原备注)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "盘点任务ID" + }, + { + "name": "action", + "type": "string", + "required": true, + "source": "body", + "description": "审核动作:approve=通过 / reject=驳回" + }, + { + "name": "reason", + "type": "string", + "required": false, + "source": "body", + "description": "驳回原因(写入备注,可选;缺省保留原备注)" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "盘点任务ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "审核后的主表状态:approved(通过)/ rejected(驳回)" + } + ], + "errors": [ + { + "code": 400, + "message": "盘点任务ID不能为空 / 审核动作仅支持 approve/reject / 盘点任务不存在 / 当前状态(非 submitted)不允许审核" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ] + }, + { + "method": "stock.check.export", + "description": "提交盘点任务导出任务(异步):Excel 分两个 Sheet 生成——Sheet1「盘点单」一行一个盘点任务(单号/名称/范围/方式/状态/进度/货主/创建人/汇总数/起止时间/备注),Sheet2「盘点明细」一行一条明细(商品级聚合,首列盘点单号:商品编码/商品名称/规格/账面数量/已盘数量(作业记录数量合计)/差异数量/是否有差异/库位编码(多个库位顿号「、」合并)/盘点人(合并)/最近盘点时间);ExcelJS 流式生成后上传 COS;进度通过 Redis 缓存(key stock_check_export_task_*,TTL 1800 秒)追踪,立即返回任务ID;单次最多 50 个盘点任务。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "ids", + "type": "array", + "required": false, + "source": "body", + "description": "盘点任务ID数组(兼容单值;与 task_ids 二选一,优先级高于 task_ids)" + }, + { + "name": "task_ids", + "type": "array", + "required": false, + "source": "body", + "description": "盘点任务ID数组(兼容别名)" + } + ], + "response": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "导出任务ID(格式 stock_check_export_{warehouseId}_{时间戳}_{随机串})" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted/running/success/failed/not_found" + }, + { + "name": "progress", + "type": "number", + "required": true, + "description": "进度百分比(0-100)" + }, + { + "name": "current_count", + "type": "number", + "required": true, + "description": "当前已处理明细数" + }, + { + "name": "total_count", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "任务提示信息" + }, + { + "name": "result", + "type": "object", + "required": false, + "description": "任务成功时的结果对象(含 filename/fileKey/url/cdnUrl/cosUrl)" + }, + { + "name": "error", + "type": "string", + "required": true, + "description": "失败时的错误信息(可选)" + }, + { + "name": "update_time", + "type": "number", + "required": true, + "description": "最近一次状态更新时间戳(毫秒)" + } + ], + "errors": [ + { + "code": 400, + "message": "请至少选择一个盘点任务 / 单次最多导出 50 个盘点任务" + }, + { + "code": 500, + "message": "服务器内部错误" + } + ], + "notes": [ + "兼容 ids / task_ids 两种入参写法,ids 优先;自动去重并过滤非正整数。", + "异步执行:查询任务与明细(按盘点作业记录聚合已盘数量/差异/库位/盘点人)→ ExcelJS 流式写入(Sheet1「盘点单」一行一个盘点任务,Sheet2「盘点明细」一行一条明细,首列盘点单号)→ COS 上传。", + "进度缓存 Redis key stock_check_export_task_{taskId},TTL 1800 秒。" + ] + }, + { + "method": "stock.check.exportTaskProgress", + "description": "查询盘点任务导出进度:按 task_id(兼容 taskId 驼峰写法)读取 Redis 任务缓存;任务不存在时正常返回(status=not_found),不视为错误;任务成功时 download_url 从 result 兜底提取(url/cdnUrl/cosUrl/fileKey)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(正常登录 token,携带仓库上下文)" + } + ], + "params": [ + { + "name": "task_id", + "type": "string", + "required": false, + "source": "body", + "description": "任务ID(下划线写法)" + }, + { + "name": "taskId", + "type": "string", + "required": false, + "source": "body", + "description": "任务ID(驼峰写法)" + } + ], + "response": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "任务ID(未传任务ID时为空字符串)" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted/running/success/failed/not_found" + }, + { + "name": "progress", + "type": "number", + "required": true, + "description": "进度百分比(0-100)" + }, + { + "name": "current_count", + "type": "number", + "required": true, + "description": "当前已处理明细数" + }, + { + "name": "total_count", + "type": "number", + "required": true, + "description": "明细总行数" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "任务提示信息" + }, + { + "name": "result", + "type": "object", + "required": false, + "description": "任务成功时的结果对象(含 filename/fileKey/url/cdnUrl/cosUrl)" + }, + { + "name": "error", + "type": "string", + "required": true, + "description": "失败时的错误信息(可选)" + }, + { + "name": "download_url", + "type": "string", + "required": true, + "description": "任务完成后可直接下载的文件地址(从 result 兜底提取,未完成或未找到时为空字符串)" + }, + { + "name": "update_time", + "type": "number", + "required": true, + "description": "最近一次状态更新时间戳(毫秒)" + } + ], + "errors": [ + { + "code": 500, + "message": "服务器内部错误" + } + ], + "notes": [ + "任务不存在为正常响应(status=not_found),非业务错误。", + "进度缓存 Redis key stock_check_export_task_{taskId},TTL 1800 秒。" + ] + } + ] + }, { "groupName": "运单模块(仓库侧)", "module": "waybill.warehouse", @@ -39096,6 +40312,20 @@ "required": false, "description": "回调通知 URL" }, + { + "name": "callback_functions", + "type": "array", + "required": false, + "description": "承接的出站回调 method 列表(空/未勾选=不承接任何回调)", + "children": [ + { + "name": "method", + "type": "string", + "required": false, + "description": "回调方法名,如 notify.reply" + } + ] + }, { "name": "rate_limit", "type": "number", @@ -39255,6 +40485,12 @@ "required": false, "description": "回调通知 URL" }, + { + "name": "callback_functions", + "type": "array", + "required": false, + "description": "承接的出站回调 method 列表(空/未勾选=不承接任何回调)" + }, { "name": "rate_limit", "type": "number", @@ -39355,6 +40591,21 @@ "source": "body", "description": "API 回调通知 URL" }, + { + "name": "callback_functions", + "type": "array", + "required": false, + "source": "body", + "description": "承接的出站回调 method 列表,仅允许注册表中的方法(如 notify.reply);空数组/不传 = 不承接任何回调", + "children": [ + { + "name": "method", + "type": "string", + "required": false, + "description": "回调方法名" + } + ] + }, { "name": "rate_limit", "type": "number", @@ -39400,6 +40651,12 @@ "required": true, "description": "接口类型 ID" }, + { + "name": "callback_functions", + "type": "array", + "required": false, + "description": "承接的出站回调 method 列表" + }, { "name": "rate_limit", "type": "number", @@ -39490,6 +40747,21 @@ "source": "body", "description": "回调通知 URL" }, + { + "name": "callback_functions", + "type": "array", + "required": false, + "source": "body", + "description": "承接的出站回调 method 列表,仅允许注册表中的方法;空数组 = 不承接任何回调", + "children": [ + { + "name": "method", + "type": "string", + "required": false, + "description": "回调方法名" + } + ] + }, { "name": "rate_limit", "type": "number", @@ -39530,6 +40802,12 @@ "required": true, "description": "AppSecret(脱敏)" }, + { + "name": "callback_functions", + "type": "array", + "required": false, + "description": "承接的出站回调 method 列表" + }, { "name": "is_enabled", "type": "number", @@ -39680,6 +40958,61 @@ "message": "服务器内部错误:重新生成 AppSecret 失败" } ] + }, + { + "method": "apiApp.listCallbackFunctions", + "description": "拉取出站回调 method 注册表(代码注册,供管理端多选列表使用;应用勾选后按 method 自动路由)", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "可选的出站回调方法列表", + "children": [ + { + "name": "method", + "type": "string", + "required": true, + "description": "回调方法名(如 notify.reply)" + }, + { + "name": "name", + "type": "string", + "required": true, + "description": "方法显示名称" + }, + { + "name": "description", + "type": "string", + "required": false, + "description": "方法说明" + } + ] + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "数量" + } + ], + "errors": [ + { + "code": "401", + "message": "未登录,请先登录" + } + ] } ] },