qipai/docs/api-changelog/2026-08-11-M09-D1-product-inventory-foundation.md

2026-08-11 M09-D1 商品目录与库存 API

商品目录

• GET/POST /admin-api/stores/:storeId/product-categories
• PUT/DELETE /admin-api/stores/:storeId/product-categories/:categoryId
• GET/POST /admin-api/products
• PUT/DELETE /admin-api/products/:productId
• GET/POST /admin-api/products/:productId/skus
• PUT/DELETE /admin-api/products/:productId/skus/:skuId
• GET /admin-api/stores/:storeId/product-listings
• PUT/DELETE /admin-api/stores/:storeId/product-listings/:productId
• GET/PUT /admin-api/stores/:storeId/product-sales-settings

分类、门店上架和销售设置的只读接口同时提供 /app-api/management/stores/:storeId/... 管理端别名。写接口统一由后台 API 承载；更新/归档必须携带 expectedVersion，服务端以版本 CAS 返回明确冲突。

库存管理

• GET /admin-api/inventory/stocks
• GET /admin-api/inventory/stocks/:inventoryId/ledger
• PUT /admin-api/inventory/stocks/:skuId/policy
• POST /admin-api/inventory/stocks/:skuId/inbound
• POST /admin-api/inventory/stocks/:skuId/adjust
• POST /admin-api/inventory/stocks/:skuId/stocktake
• POST /admin-api/inventory/stocks/:skuId/loss

库存写请求必填门店、requestId 和原因；需要绝对状态或并发保护的操作携带 expectedVersion。批量锁定、释放、扣减作为领域服务供 M09-D2 商品订单事务调用，不开放可由客户端伪造业务归属的裸管理接口。

权限与错误边界

• 商品读取/写入使用 product.catalog.read / product.catalog.write，库存读取/调整使用 inventory.read / inventory.adjust。
• STAFF 默认只读，STORE_ADMIN 只能访问授权门店；TENANT_ADMIN 与 PLATFORM_ADMIN 仍分别受租户和显式平台范围约束。全局商品/SKU 目录读取不向普通 STAFF 开放。
• 所有仓储和服务查询重复校验 tenantId/storeId，不依赖菜单隐藏或路由参数实现隔离。
• 版本冲突、幂等指纹冲突、库存不足、锁定归属不匹配返回冲突类错误；越权、未找到和参数越界分别保持 403、404 和 400 语义。