# 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 语义。