qipai/docs/api-changelog/2026-08-11-M09-D3-product-storage.md

2026-08-11 M09-D3 商品寄存 API

顾客接口

• POST /app-api/product-storages
• GET /app-api/product-storages
• GET /app-api/product-storages/:storageId
• POST /app-api/product-storages/:storageId/retrieve
• POST /app-api/product-storages/:storageId/credential/rotate
• POST /app-api/product-storages/:storageId/cancel

顾客创建时提交已完成商品订单、到期时间及可选订单项数量；列表、详情和动作只允许寄存本人访问。领取请求包含一次性凭证和逐项数量，部分领取成功后响应新的领取凭证。幂等重放返回当前视图，但不会再次返回任何已经签发的原始凭证。

管理接口

以下接口同时提供 /admin-api 与 /app-api/management 前缀：

• POST /product-storages
• GET /product-storages?storeId=...
• GET /product-storages/:storageId
• POST /product-storages/:storageId/retrieve
• POST /product-storages/:storageId/credential/rotate
• POST /product-storages/:storageId/cancel
• POST /product-storages/expire-due

读取要求 goods.storage.read，写入要求 goods.storage.manage；管理动作重复校验授权门店。手工创建必须绑定同租户有效顾客、有效门店上架 SKU 和未来到期时间。过期批处理显式限定当前租户与门店，内部 worker 另有全局 SKIP LOCKED 批处理入口。

返回与错误边界

详情包含寄存快照、当前剩余数量、状态事件和逐项取出流水，不包含凭证哈希。未找到或非本人资源返回 404 语义，权限/门店范围返回 403，状态、版本、同源或幂等冲突返回 409，凭证、数量、来源订单或到期时间不合法返回 400 语义错误码。