docs(api): 同步 business 打包分支 users 恢复说明与变更记录
This commit is contained in:
parent
df0c1735c8
commit
bf4920475d
@ -186,9 +186,9 @@ rg "class .*Service|module.exports" app/service/qimenMethods
|
||||
- 成员副表:`wms_workbench_member`(工作台成员/用户登录,user_id 可空兼容非系统账号用户、user_name 名称快照、软删除);`workbench.bindMember` 免登录免鉴权(入参 userId 可空 + userName 姓名必填 + 工作台 token)新增成员行;`workbench.removeMember` 免登录免鉴权(入参行 ids + 工作台 token)按 token 解析工作台后仅软删除归属该工作台的成员行,移除后该工作台已无任何成员时自动结束其所有未结束打包任务(wms_pack_task status<2 置 2 并写 end_time,同步回写订单打包状态与补确认打印状态、写完成操作日志、复位摄像头 OSD、失效 token 缓存,与 finishPack 语义一致,响应附 auto_finished_pack{finished,task_ids},2026-09-21 补充)
|
||||
- 401/403 口径:/system 网关不支持方法内设置 HTTP 状态码,按现有惯例返回 `flag=failure、code=XXX` 业务失败(与 stock/warehouse.js 同款);公共 token 校验方法 `resolveWorkbenchContext(token)`(app/service/systems/workbench.js):无 token 统一返回 code=401(消息「工作台 token 不能为空」,2026-09-06 由 400 调整)、token 无效/工作台不存在(含软删除)返回 403(保持原口径),解析成功后写入 ctx.workbenchToken/ctx.workbenchId/ctx.workbenchWarehouseId 供后续方法使用(仓库限定,禁止跨仓库);`workbench.getWorkbenchInfo`/`workbench.bindMember`/`workbench.removeMember` 均统一走该校验(无 token 返回 401,bindMember/removeMember token 优先校验)
|
||||
- 打包/称重三接口(2026-09-06 新增):`workbench.packOrder`(打包上报,推荐 key 模式:前端先扫码 `workbench.queryOrder` 拿 key(20 分钟有效),打包只传 token + key(除 token、key 外不再接收任何订单相关信息,body 其它字段一律忽略,防篡改;不传 key 时旧参数模式过渡兼容,后续版本移除),参数由后端从 Redis 缓存 workbench:packctx:{key} 拉取(含订单号/波次号/运单号),跨仓/跨台消费他人 key 返回 403、缺 key 或过期返回 400;响应 task_id/order_id/delivery_order_code/wave_no/isSandan/pack_mode/status,团购附 batch)、`workbench.finishPack`(打包完成,入参 token,响应 workbench_id/finished/task_id/order_id/end_time,无未结束任务 finished=false)、`workbench.sendWeight`(称重上报,入参 token/barcode/weight(单位克),散单响应 barcode/waybill_code/order_id/weighing_weight/items_weight/mode=single,团购波次响应另附 wave_id/wave_no/total_weight/order_count/mode=wave)均免登录/免权限/免鉴权,靠工作台 token 自校验;仓库与工作台均由服务端从 token 解析注入,body 传入 warehouse_id/workbench_id 一律忽略(禁止前端传值);三接口保留系统日志(systemInit 未声明免日志)
|
||||
- 打包运单维度(2026-09-21 修复一单多号):`workbench.packOrder` 传运单号时按「订单+运单号」维度写入 wms_pack_task.waybill_code 并散单去重(同时清理同订单历史 waybill_code 为空的旧流水),主单号/子单号流水互不覆盖,未传保持订单维度(兼容旧设备端);团购为波次维度不使用运单号;打包人一律由服务端取该工作台绑定成员回填(wms_workbench_member,users 入参已移除,旧设备端传 users 被忽略,2026-09-21)
|
||||
- 打包运单维度(2026-09-21 修复一单多号):`workbench.packOrder` 传运单号时按「订单+运单号」维度写入 wms_pack_task.waybill_code 并散单去重(同时清理同订单历史 waybill_code 为空的旧流水),主单号/子单号流水互不覆盖,未传保持订单维度(兼容旧设备端);团购为波次维度不使用运单号;打包人一律由服务端取该工作台绑定成员回填(wms_workbench_member,users 入参已移除、旧设备端传 users 被忽略,2026-09-21);business 旧链路(workbench.business 的 packOrder 分支)支持传入 users 上报打包人(未上报回填成员,2026-09-21 恢复)
|
||||
- 条码查单接口(2026-09-06 新增):`workbench.queryOrder`(条码查订单,入参 token/barcode,响应 barcode/waybill_code/isSandan/store_remark/express/order/items/source_table,散单 order 附 intercept_flag/pack_flag 0/1 标志、团购附 batch 波次总量信息;items 逐项合并 stock 详情含 need_recheck 是否需要复核(Y=需要 N=不需要(免验),2026-09-19 补充);pack_flag 按运单维度判定(该运单号已有打包流水 wms_pack_task.waybill_code 命中或历史订单级流水 waybill_code 为空兜底时为 1,否则 0,主单号/子单号互不影响,流水查询异常降级订单级 pack_status 判定,2026-09-21 调整);查询成功时响应另附 key(打包上下文 key,wpck 前缀 + 随机段,Redis 缓存 workbench:packctx:{key} TTL 20 分钟,内容含订单号/波次号/运单号/归属仓库与工作台,供 workbench.packOrder 消费防篡改,2026-09-21 新增))免登录/免权限/免鉴权,靠工作台 token 自校验;仓库与工作台均由服务端从 token 解析注入,body 传入 warehouse_id/workbench_id 一律忽略(禁止前端传值);只读查询不涉及缓存失效;保留系统日志(systemInit 未声明免日志)
|
||||
- 接口文档:`methods/system.json` 分组「工作台模块」(module=workbench)与「基础模块」(module=index),变更记录见 `methods/changes/system.json` 版本 `2026.09.03-workbench-login-code-token`、`2026.09.03-workbench-member-remove`、`2026.09.03-workbench-member-bind`、`2026.09.06-workbench-getWorkbenchInfo-members`、`2026.09.06-workbench-getWorkbenchInfo-current-packing`、`2026.09.06-workbench-getWorkbenchInfo-wave-items-total`、`2026.09.06-workbench-pack-order-finish-pack-send-weight`、`2026.09.06-workbench-queryOrder`、`2026.09.19-workbench-getWorkbenchInfo-order-items`、`2026.09.19-workbench-order-items-need-recheck`、`2026.09.19-workbench-getWorkbenchInfo-wave-items-summary`、`2026.09.21-workbench.packOrder-waybill-dimension`、`2026.09.21-workbench.removeMember-auto-finish-pack`、`2026.09.21-workbench.packOrder-remove-users-param`、`2026.09.21-workbench.packOrder-key-mode`、`2026.09.21-workbench.packOrder-key-only`、`2026.09.21-workbench.packOrder-legacy-compat`、`2026.09.21-workbench.packOrder-key-forward-fix`、`2026.09.21-workbench.getWorkbenchInfo-order-fields`
|
||||
- 接口文档:`methods/system.json` 分组「工作台模块」(module=workbench)与「基础模块」(module=index),变更记录见 `methods/changes/system.json` 版本 `2026.09.03-workbench-login-code-token`、`2026.09.03-workbench-member-remove`、`2026.09.03-workbench-member-bind`、`2026.09.06-workbench-getWorkbenchInfo-members`、`2026.09.06-workbench-getWorkbenchInfo-current-packing`、`2026.09.06-workbench-getWorkbenchInfo-wave-items-total`、`2026.09.06-workbench-pack-order-finish-pack-send-weight`、`2026.09.06-workbench-queryOrder`、`2026.09.19-workbench-getWorkbenchInfo-order-items`、`2026.09.19-workbench-order-items-need-recheck`、`2026.09.19-workbench-getWorkbenchInfo-wave-items-summary`、`2026.09.21-workbench.packOrder-waybill-dimension`、`2026.09.21-workbench.removeMember-auto-finish-pack`、`2026.09.21-workbench.packOrder-remove-users-param`、`2026.09.21-workbench.packOrder-key-mode`、`2026.09.21-workbench.packOrder-key-only`、`2026.09.21-workbench.packOrder-legacy-compat`、`2026.09.21-workbench.packOrder-key-forward-fix`、`2026.09.21-workbench.getWorkbenchInfo-order-fields`、`2026.09.21-workbench.packOrder-business-users-restore`
|
||||
- 当前打包信息:`workbench.getWorkbenchInfo` 响应 data 另含 `current_wave`(当前正在打包的团购波次,来自 wms_pack_task 最新一条 pack_mode=2 未结束任务,无则为空对象;含 order_count 波次订单数与 items_total 波次商品总件数,均按 current+dispatch 分表实时统计、15s 短缓存兜底)与 `current_orders`(未结束打包任务对应订单数组,逐单按 current→dispatch 分表补发货单号/order_type/store_id/items_count/items_total,另附任务表 item_quantity/sku_count/waybill_code,散单任务(pack_mode=1)附 items 商品明细数组(复用 _fetchOrderItemsDetail 公共方法,与 workbench.queryOrder 的 items 同源,含条码/图片/包装要求/need_recheck 是否需要复核),另补货主备注 store_remark 与运单信息 express(物流公司/称重重量/包材名称,与 queryOrder 口径一致,2026-09-21 补充),团购任务(pack_mode=2)items 为波次商品 SKU 聚合汇总(_fetchWaveItemsSummary,波次内全部未拦截订单按 SKU 聚合计划数量并合并 stock 详情,15s 短缓存兜底,元素另附 is_wave_summary=true),无则为空数组);打包信息随 `workbench:token:{token}` 缓存(TTL 300s)一并缓存,packOrder/finishPack 状态变更后主动失效缓存,查询异常降级为空对象/空数组(单笔商品明细异常仅 items 降级为空数组)
|
||||
- 迁移:`database/migrations/20260903100000-add-login-code-token-to-wms-workbench.js`(幂等 up/down,已在开发库执行;生产库待发布时按标准流程执行)
|
||||
|
||||
|
||||
@ -1,4 +1,31 @@
|
||||
[
|
||||
{
|
||||
"version": "2026.09.21-workbench.packOrder-business-users-restore",
|
||||
"date": "2026-09-21",
|
||||
"type": "updated",
|
||||
"summary": "workbench.business 的 packOrder 分支恢复支持传入 users 上报打包人(未上报时回填工作台成员);token+key 新链路保持剥离 users",
|
||||
"methods": [
|
||||
"workbench.business"
|
||||
],
|
||||
"notes": [
|
||||
"业务旧链路(workbench.business 的 packOrder 分支)恢复 users 上报生效:上报时以上报为准,未上报时自动回填该工作台绑定成员(wms_workbench_member);token+key 新链路(workbench.packOrder)保持剥离 users、一律取工作台绑定成员。",
|
||||
"代码变更:app/service/systems/workbench.js#_packOrder 恢复 users 入参(上报优先、未报回填)、#packOrderByToken 解构剥离 users;回归测试 test/workbench_pack_waybill_dimension.test.cjs(26 用例)。"
|
||||
],
|
||||
"module": "workbench"
|
||||
},
|
||||
{
|
||||
"version": "2026.09.21-wechat.getAuthUrl",
|
||||
"date": "2026-09-21",
|
||||
"type": "added",
|
||||
"summary": "新增微信模块 wechat.getAuthUrl:生成微信开放平台小程序授权链接(PC版),state 缓存仓库信息用于回跳绑定",
|
||||
"methods": [
|
||||
"wechat.getAuthUrl"
|
||||
],
|
||||
"notes": [
|
||||
"system.json 新增 module=wechat 方法 wechat.getAuthUrl(需登录);app/service/systems/wechat.js + app/service/systemMethods/wechat.js 生成授权链接;state=随机串,缓存 key wechat_auth_state:{state}(TTL 600s)存仓库信息;GET /Authorization 回跳凭 state 绑定仓库并落库 wms_wechat_app;state 缺失/过期展示错误页 app/view/wechat_auth_callback.html;配置 wechatOpen.redirect_uri"
|
||||
],
|
||||
"module": "wechat"
|
||||
},
|
||||
{
|
||||
"version": "2026.09.21-workbench.getWorkbenchInfo-order-fields",
|
||||
"date": "2026-09-21",
|
||||
|
||||
@ -33808,7 +33808,7 @@
|
||||
},
|
||||
{
|
||||
"method": "workbench.business",
|
||||
"description": "工作台业务入口(免登录免鉴权,入参 name + data)。name 支持 queryOrder/query(条码查订单,data 需 barcode+warehouseId)、packOrder(开始打包,凭 key 从后端缓存取订单信息防篡改;不传 key 时旧参数模式过渡兼容)、finishPack(结束打包)、sendWeight(称重);不支持的业务名称报错。以下响应结构为 queryOrder/query(条码查订单)的返回。",
|
||||
"description": "工作台业务入口(免登录免鉴权,入参 name + data)。name 支持 queryOrder/query(条码查订单,data 需 barcode+warehouseId)、packOrder(开始打包,凭 key 从后端缓存取订单信息防篡改;不传 key 时旧参数模式过渡兼容;business 旧链路支持传入 users 上报打包人,未上报时自动回填工作台绑定成员)、finishPack(结束打包)、sendWeight(称重);不支持的业务名称报错。以下响应结构为 queryOrder/query(条码查订单)的返回。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": false,
|
||||
"headers": [],
|
||||
@ -46705,6 +46705,35 @@
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"groupName": "微信模块",
|
||||
"module": "wechat",
|
||||
"list": [
|
||||
{
|
||||
"method": "wechat.getAuthUrl",
|
||||
"description": "获取微信开放平台小程序授权链接(PC版):生成随机 state 并缓存仓库信息(Redis key wechat_auth_state:{state},TTL 600s),state 拼接到微信授权链接,授权完成后回跳 /Authorization 凭 state 绑定仓库落库",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
{
|
||||
"name": "Authorization",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "Bearer token"
|
||||
}
|
||||
],
|
||||
"params": [
|
||||
{
|
||||
"name": "warehouse_id",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "仓库ID(缺省取当前登录用户所属仓库)"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user