# MCP 工具与 API 参数完整参考

日期：2026-10-29。本附录由当前 tools/list 参数、MCP 路由映射和公开 OpenAPI 逐项交叉整理。后端字段不能自动当成独立工具参数；独立工具只接收其工具 schema 所列参数。完整业务流程见 [AI 使用手册](AI_USAGE_GUIDE.md)。固定 mcp-topic 标识用于启动时切分；标题可调整而不影响 topic。字段类型引用模型时，AI 按返回提示读取 schema_ 模型主题，避免一次返回全部模型。所有成本附加权限和工具内部保护仍生效。

<!-- mcp-topic: reference_standalone -->
# 独立工具参数索引

此旧主题保留兼容，不再一次返回整份说明。请调用 usage_guide 的下列 topic；模型详情按返回提示继续读取 schema_ 主题。

- `reference_products`：商品查询与创建修改
- `reference_inventory_adjustments`：库存查询与纠正
- `reference_catalog`：分类品牌和只读字典
- `reference_pricing`：价格规则与分组
- `reference_images`：图片上传与关联
- `reference_attachments_media`：附件与媒体角色
- `reference_units`：销售单位
- `reference_usage_guide`：说明工具
- `reference_receipt_ai`：到货单文件上传识别
<!-- /mcp-topic -->

## 独立工具参数和内部 API

<!-- mcp-topic: reference_products -->
### search_products

Search products by name, SKU, or barcode in the configured tenant.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `keyword` | 否 | string | 默认 "" |  |
| `category_id` | 否 | integer / null | 默认 null |  |
| `brand_id` | 否 | integer / null | 默认 null |  |
| `status` | 否 | string / null | 默认 null |  |
| `page` | 否 | integer | 默认 1 |  |
| `page_size` | 否 | integer | 默认 20 |  |

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/products` — 商品列表

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `page` | query | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | query | 否 | integer | 默认 10；最小 1；最大 100 |  |
| `keyword` | query | 否 | string / null |  |  |
| `category` | query | 否 | string / null |  |  |
| `category_id` | query | 否 | integer / null |  |  |
| `brand_id` | query | 否 | integer / null |  |  |
| `status` | query | 否 | string / null |  |  |
| `stock_status_id` | query | 否 | integer / null |  |  |
| `expiry_status` | query | 否 | string / null |  |  |
| `filter` | query | 否 | string / null |  | low=只看低库存（可下单量≤阈值） |
| `sort_by` | query | 否 | string | 默认 "created_at"；正则 "^(created_at\|expiry_date)$" |  |
| `sort_order` | query | 否 | string | 默认 "desc"；正则 "^(asc\|desc)$" |  |

成功响应 200 `application/json`：`PageResult_ProductListOut_`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### get_product

Read product details, variants, categories, tier prices and media.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/products/{product_id}` — 商品详情

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

成功响应 200 `application/json`：`ProductOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### create_product

Create a product with fields supported by the Admin ProductCreate API, including variants, barcodes, categories and tier prices.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product` | 是 | object |  |  |

权限：`products.create`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/products` — 创建商品

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`ProductCreate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string | 最长 200 |  |
| `sku` | 是 | string | 最长 64 |  |
| `barcode` | 否 | string / null | 最长 120 | 条码（无规格商品用） |
| `barcodes` | 否 | array<string> |  | 商品级历史/别名条码 |
| `categories` | 否 | array<string / integer> |  |  |
| `brand_id` | 否 | integer / null |  |  |
| `description` | 否 | string / null |  |  |
| `base_price` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `market_price` | 否 | number / string / null |  |  |
| `member_price` | 否 | number / string / null |  |  |
| `cost_price` | 否 | number / string / null |  |  |
| `price_group` | 否 | string / null | 最长 64 | 价格规则分组（仅后台管理用） |
| `stock_qty` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `low_stock_threshold` | 否 | integer | 默认 5；最小 0.0 |  |
| `allow_oversell` | 否 | boolean | 默认 false |  |
| `status` | 否 | string | 默认 "draft" |  |
| `weight_grams` | 否 | integer | 默认 0；最小 0.0 |  |
| `length` | 否 | number / string / null |  |  |
| `width` | 否 | number / string / null |  |  |
| `height` | 否 | number / string / null |  |  |
| `slug` | 否 | string / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `seo_keywords` | 否 | string / null |  |  |
| `ai_description` | 否 | string / null |  |  |
| `shelf_life` | 否 | string / null |  |  |
| `shelf_life_en` | 否 | string / null |  |  |
| `expiry_date` | 否 | string (date) / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `ai_description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `tax_class_id` | 否 | integer / null |  |  |
| `stock_status_id` | 否 | integer / null |  |  |
| `hungrypanda_enabled` | 否 | boolean | 默认 false |  |
| `video_url` | 否 | string / null | 最长 500 |  |
| `cover_url` | 否 | string / null |  |  |
| `variants` | 否 | array<ProductVariantIn> |  |  |
| `tier_prices` | 否 | array<TierPriceIn> |  |  |

成功响应 201 `application/json`：`ProductOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

成本字段或识别任务另需 `products.cost_price.view`，详见主手册。

### update_product

Update product fields. Inventory values are ignored and current variant quantities are preserved.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `changes` | 是 | object |  |  |

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/products/{product_id}` — 商品详情

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

成功响应 200 `application/json`：`ProductOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

权限：`products.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/products/{product_id}` — 更新商品

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

请求体 `application/json`：`ProductUpdate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 否 | string / null |  |  |
| `sku` | 否 | string / null |  |  |
| `barcode` | 否 | string / null | 最长 120 | 条码（无规格商品用） |
| `barcodes` | 否 | array<string> |  | 商品级历史/别名条码 |
| `categories` | 否 | array<string / integer> |  |  |
| `brand_id` | 否 | integer / null |  |  |
| `description` | 否 | string / null |  |  |
| `base_price` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `market_price` | 否 | number / string / null |  |  |
| `member_price` | 否 | number / string / null |  |  |
| `cost_price` | 否 | number / string / null |  |  |
| `price_group` | 否 | string / null | 最长 64 | 价格规则分组（仅后台管理用） |
| `stock_qty` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `low_stock_threshold` | 否 | integer | 默认 5；最小 0.0 |  |
| `allow_oversell` | 否 | boolean | 默认 false |  |
| `status` | 否 | string | 默认 "draft" |  |
| `weight_grams` | 否 | integer | 默认 0；最小 0.0 |  |
| `length` | 否 | number / string / null |  |  |
| `width` | 否 | number / string / null |  |  |
| `height` | 否 | number / string / null |  |  |
| `slug` | 否 | string / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `seo_keywords` | 否 | string / null |  |  |
| `ai_description` | 否 | string / null |  |  |
| `shelf_life` | 否 | string / null |  |  |
| `shelf_life_en` | 否 | string / null |  |  |
| `expiry_date` | 否 | string (date) / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `ai_description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `tax_class_id` | 否 | integer / null |  |  |
| `stock_status_id` | 否 | integer / null |  |  |
| `hungrypanda_enabled` | 否 | boolean | 默认 false |  |
| `video_url` | 否 | string / null | 最长 500 |  |
| `cover_url` | 否 | string / null |  |  |
| `variants` | 否 | array<ProductVariantIn> / null |  |  |
| `tier_prices` | 否 | array<TierPriceIn> / null |  |  |

成功响应 200 `application/json`：`ProductOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

成本字段或识别任务另需 `products.cost_price.view`，详见主手册。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_inventory_adjustments -->
### set_product_stock

Set stock for a product without variants when the tenant inventory ledger is not enabled; fails closed otherwise.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `quantity` | 是 | number |  |  |

权限：`inventory.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/settings` — Get Settings

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`app__plugins__inventory__schemas__SettingsOut / null`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/products/{product_id}` — 商品详情

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

成功响应 200 `application/json`：`ProductOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

权限：`products.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/products/{product_id}` — 更新商品

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

请求体 `application/json`：`ProductUpdate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 否 | string / null |  |  |
| `sku` | 否 | string / null |  |  |
| `barcode` | 否 | string / null | 最长 120 | 条码（无规格商品用） |
| `barcodes` | 否 | array<string> |  | 商品级历史/别名条码 |
| `categories` | 否 | array<string / integer> |  |  |
| `brand_id` | 否 | integer / null |  |  |
| `description` | 否 | string / null |  |  |
| `base_price` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `market_price` | 否 | number / string / null |  |  |
| `member_price` | 否 | number / string / null |  |  |
| `cost_price` | 否 | number / string / null |  |  |
| `price_group` | 否 | string / null | 最长 64 | 价格规则分组（仅后台管理用） |
| `stock_qty` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `low_stock_threshold` | 否 | integer | 默认 5；最小 0.0 |  |
| `allow_oversell` | 否 | boolean | 默认 false |  |
| `status` | 否 | string | 默认 "draft" |  |
| `weight_grams` | 否 | integer | 默认 0；最小 0.0 |  |
| `length` | 否 | number / string / null |  |  |
| `width` | 否 | number / string / null |  |  |
| `height` | 否 | number / string / null |  |  |
| `slug` | 否 | string / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `seo_keywords` | 否 | string / null |  |  |
| `ai_description` | 否 | string / null |  |  |
| `shelf_life` | 否 | string / null |  |  |
| `shelf_life_en` | 否 | string / null |  |  |
| `expiry_date` | 否 | string (date) / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `ai_description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `tax_class_id` | 否 | integer / null |  |  |
| `stock_status_id` | 否 | integer / null |  |  |
| `hungrypanda_enabled` | 否 | boolean | 默认 false |  |
| `video_url` | 否 | string / null | 最长 500 |  |
| `cover_url` | 否 | string / null |  |  |
| `variants` | 否 | array<ProductVariantIn> / null |  |  |
| `tier_prices` | 否 | array<TierPriceIn> / null |  |  |

成功响应 200 `application/json`：`ProductOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_inventory_warehouses

List warehouses available to the authenticated tenant before preparing a stock adjustment.

模型：`object`。

权限：`inventory.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/warehouses` — List Warehouses

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<WarehouseOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_inventory_balances

Read non-zero inventory-ledger balances by product variant and warehouse.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 否 | integer / null | 默认 null |  |
| `warehouse_id` | 否 | integer / null | 默认 null |  |
| `limit` | 否 | integer | 默认 100 |  |

权限：`inventory.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/balances` — List Balances

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | query | 否 | integer / null |  |  |
| `warehouse_id` | query | 否 | integer / null |  |  |
| `stock_state` | query | 否 | string / null |  |  |
| `limit` | query | 否 | integer | 默认 100；最大 500 |  |

成功响应 200 `application/json`：`array<BalanceOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_inventory_adjustments

List inventory adjustment documents, optionally filtered by draft/done state.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `state` | 否 | string / null | 默认 null |  |

权限：`inventory.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/adjustments` — List Adjustment Documents

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `state` | query | 否 | string / null |  |  |
| `page` | query | 否 | integer / null | 最小 1 |  |
| `page_size` | query | 否 | integer | 默认 20；最小 1；最大 100 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

### get_inventory_adjustment

Read an adjustment document and its variant, warehouse, quantity, and posting details.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `operation_id` | 是 | integer |  |  |

权限：`inventory.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/adjustments/{operation_id}` — Get Adjustment Document

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

### create_inventory_adjustment

Create a draft stock adjustment for specific variants and warehouses; drafts do not change inventory.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `reason` | 是 | string |  |  |
| `lines` | 是 | array<object> |  |  |
| `reference` | 否 | string / null | 默认 null |  |
| `idempotency_key` | 否 | string / null | 默认 null |  |

权限：`inventory.adjust`。作用：创建/修改业务草稿；实际过账另行执行。

`POST /api/admin/inventory/adjustments` — Create Adjustment Document

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`AdjustmentDocumentIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `reason` | 是 | string | 最短 1；最长 255 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `lines` | 是 | array<AdjustmentDocumentLineIn> | 最少项 1 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

### update_inventory_adjustment

Replace the contents of a draft adjustment document; posted documents cannot be edited.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `operation_id` | 是 | integer |  |  |
| `reason` | 是 | string |  |  |
| `lines` | 是 | array<object> |  |  |
| `reference` | 否 | string / null | 默认 null |  |
| `idempotency_key` | 否 | string / null | 默认 null |  |

权限：`inventory.adjust`。作用：创建/修改业务草稿；实际过账另行执行。

`PUT /api/admin/inventory/adjustments/{operation_id}` — Update Adjustment Document

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path | 是 | integer |  |  |

请求体 `application/json`：`AdjustmentDocumentIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `reason` | 是 | string | 最短 1；最长 255 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `lines` | 是 | array<AdjustmentDocumentLineIn> | 最少项 1 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

### post_inventory_adjustment

Post a draft adjustment. This writes audited inventory movements and changes variant sellable stock.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `operation_id` | 是 | integer |  |  |

权限：`inventory.adjust`。作用：真实库存过账，写库存流水并影响可售量。

`POST /api/admin/inventory/adjustments/{operation_id}/post` — Post Adjustment Document

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

### cancel_inventory_adjustment

Cancel a draft inventory adjustment; posted documents cannot be cancelled through this operation.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `operation_id` | 是 | integer |  |  |

权限：`inventory.adjust`。作用：取消库存纠正草稿，不撤销已过账事实。

`POST /api/admin/inventory/adjustments/{operation_id}/cancel` — Cancel Adjustment Document

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_catalog -->
### list_categories

List categories in the configured tenant.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `keyword` | 否 | string | 默认 "" |  |
| `parent_id` | 否 | integer / null | 默认 null |  |

权限：`categories.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/categories` — List Categories

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `keyword` | query | 否 | string / null |  |  |
| `parent_id` | query | 否 | integer / null |  |  |

成功响应 200 `application/json`：`array<CategoryOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### create_category

Create a bilingual, hierarchical category with navigation and SEO fields.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `category` | 是 | object |  |  |

权限：`categories.create`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/categories` — Create Category

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`CategoryCreate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string |  |  |
| `slug` | 是 | string |  |  |
| `parent_id` | 否 | integer / null |  |  |
| `description` | 否 | string / null |  |  |
| `image_url` | 否 | string / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `seo_keywords` | 否 | string / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `is_nav_visible` | 否 | boolean | 默认 true |  |

成功响应 201 `application/json`：`CategoryOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### update_category

Update category fields. Category deletion is not exposed.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `category_id` | 是 | integer |  |  |
| `changes` | 是 | object |  |  |

权限：`categories.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/categories/{category_id}` — Update Category

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `category_id` | path | 是 | integer |  |  |

请求体 `application/json`：`CategoryUpdate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 否 | string / null |  |  |
| `slug` | 否 | string / null |  |  |
| `parent_id` | 否 | integer / null |  |  |
| `description` | 否 | string / null |  |  |
| `image_url` | 否 | string / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `seo_keywords` | 否 | string / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `sort_order` | 否 | integer / null |  |  |
| `is_active` | 否 | boolean / null |  |  |
| `is_nav_visible` | 否 | boolean / null |  |  |

成功响应 200 `application/json`：`CategoryOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_brands

List brands in the configured tenant.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `keyword` | 否 | string | 默认 "" |  |
| `page` | 否 | integer | 默认 1 |  |
| `page_size` | 否 | integer | 默认 100 |  |

权限：`brands.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/brands` — 品牌列表

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `page` | query | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | query | 否 | integer | 默认 20；最小 1；最大 100 |  |
| `keyword` | query | 否 | string / null |  |  |

成功响应 200 `application/json`：`PageResult_BrandOut_`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### create_brand

Create a brand with bilingual, logo, website, country and SEO fields.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `brand` | 是 | object |  |  |

权限：`brands.create`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/brands` — 创建品牌

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`BrandCreate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string | 最长 120 |  |
| `slug` | 是 | string | 最长 180 |  |
| `english_name` | 否 | string / null |  |  |
| `logo_url` | 否 | string / null |  |  |
| `description` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `website_url` | 否 | string / null |  |  |
| `country` | 否 | string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_featured` | 否 | boolean | 默认 false |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |

成功响应 201 `application/json`：`BrandOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### update_brand

Update brand fields. Brand deletion is not exposed.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `brand_id` | 是 | integer |  |  |
| `changes` | 是 | object |  |  |

权限：`brands.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/brands/{brand_id}` — 更新品牌

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `brand_id` | path | 是 | integer |  |  |

请求体 `application/json`：`BrandUpdate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 否 | string / null |  |  |
| `slug` | 否 | string / null |  |  |
| `english_name` | 否 | string / null |  |  |
| `logo_url` | 否 | string / null |  |  |
| `description` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `website_url` | 否 | string / null |  |  |
| `country` | 否 | string / null |  |  |
| `sort_order` | 否 | integer / null |  |  |
| `is_featured` | 否 | boolean / null |  |  |
| `is_active` | 否 | boolean / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |

成功响应 200 `application/json`：`BrandOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_member_levels

List member levels available for product tier prices.

模型：`object`。

权限：`member_levels.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/member-levels` — 会员等级列表

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `page` | query | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | query | 否 | integer | 默认 50；最小 1；最大 100 |  |
| `purpose` | query | 否 | string | 默认 "customer"；允许值 ["customer", "channel_pricing", "all"] |  |

成功响应 200 `application/json`：`PageResult_MemberLevelOut_`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_stock_statuses

List configured stock-status choices; this does not change inventory.

模型：`object`。

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/stock-statuses` — 库存状态列表

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<StockStatusOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_pricing -->
### get_product_price_rules

Read a product's current price rules and optimistic-lock version.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/products/{product_id}/price-rules` — Get Price Rules

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

成功响应 200 `application/json`：`ProductPriceRulesResponse`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### replace_product_price_rules

Atomically replace product pricing rules; this affects Store/POS prices and catalogue revision.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `ruleset` | 是 | object |  |  |

权限：`products.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/products/{product_id}/price-rules` — Replace Price Rules

原子替换单个商品的整组规则。
- price_rules_version 不匹配 → 409
- 替换成功后递增版本号与 POS catalogue revision
- 单事务 commit，所有校验一致失败就回滚

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

请求体 `application/json`：`ProductPriceRulesReplace`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `price_rules_version` | 否 | integer | 默认 0；最小 0.0 | 客户端持有的版本号，乐观锁 |
| `rules` | 否 | array<ProductPriceRuleIn> |  |  |
| `price_group` | 否 | string / null | 最长 64 | 价格规则分组（仅后台管理用） |

成功响应 200 `application/json`：`ProductPriceRulesResponse`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_price_rules

List tenant-wide product price rules, status and expiry summaries.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `keyword` | 否 | string | 默认 "" |  |
| `price_group` | 否 | string / null | 默认 null |  |
| `status` | 否 | string / null | 默认 null |  |
| `page` | 否 | integer | 默认 1 |  |
| `page_size` | 否 | integer | 默认 50 |  |

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/price-rules` — 价格规则总览

一行一条规则。状态在内存里算——规则总量是"配了特价的商品数"，不是订单量级。

ponytail: 全量取回再分页，规模上万条后改成 SQL 侧的时间窗过滤 + limit/offset。

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `keyword` | query | 否 | string / null |  | 商品名 / SKU 模糊匹配 |
| `price_group` | query | 否 | string / null |  | 分组名；传 __none__ 查未分组 |
| `status` | query | 否 | string / null |  | active/upcoming/expiring/expired/disabled |
| `sort` | query | 否 | string / null |  | product/group/price/priority/ends_at；默认按快到期优先 |
| `order` | query | 否 | string | 默认 "asc" | asc/desc |
| `page` | query | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | query | 否 | integer | 默认 20；最小 1；最大 200 |  |

成功响应 200 `application/json`：`PriceRuleOverviewResponse`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### assign_price_group

Assign or clear a price group for tenant-owned products.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_ids` | 是 | array<integer> |  |  |
| `price_group` | 是 | string / null |  |  |

权限：`products.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/price-rules/groups` — 批量设置商品的价格分组

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`PriceGroupAssign`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_ids` | 否 | array<integer> |  |  |
| `price_group` | 否 | string / null | 最长 64 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_images -->
### list_product_images

List product image metadata by URL.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/products/{product_id}/images` — List Images

列出商品所有图片

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

成功响应 200 `application/json`：`array<ImageOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### upload_product_image

Upload a base64-encoded JPEG, PNG, WebP or GIF (up to 5 MB) through the tenant's normal upload API and return its URL.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `filename` | 是 | string |  |  |
| `content_type` | 是 | string |  |  |
| `image_base64` | 是 | string |  |  |

权限：`products.images.upload`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/upload` — Upload image or product attachment

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `multipart/form-data`：`Body_upload_image_api_upload_post`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `file` | 是 | string (binary) |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

### add_product_image

Attach an existing image URL and metadata to a product.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `image` | 是 | object |  |  |

权限：`products.images.upload`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/products/{product_id}/images` — Upload Image

上传商品图片

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

请求体 `application/json`：`ImageCreate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `url` | 是 | string | 最长 500 |  |
| `alt_text` | 否 | string / null | 最长 200 |  |
| `sort_order` | 否 | integer | 默认 0；最小 0.0 |  |
| `is_primary` | 否 | boolean | 默认 false |  |

成功响应 201 `application/json`：`ImageOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### update_product_image

Update image alt text, order or primary-image status.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `image_id` | 是 | integer |  |  |
| `changes` | 是 | object |  |  |

权限：`products.images.upload`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/products/{product_id}/images/{image_id}` — Update Image

更新图片信息

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |
| `image_id` | path | 是 | integer |  |  |

请求体 `application/json`：`ImageUpdate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `alt_text` | 否 | string / null | 最长 200 |  |
| `sort_order` | 否 | integer / null | 最小 0.0 |  |
| `is_primary` | 否 | boolean / null |  |  |

成功响应 200 `application/json`：`ImageOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### delete_product_image

Delete a product image metadata row.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `image_id` | 是 | integer |  |  |

权限：`products.images.upload`。作用：删除指定图片关联或预警配置，核对目标后执行。

`DELETE /api/products/{product_id}/images/{image_id}` — Delete Image

删除图片

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |
| `image_id` | path | 是 | integer |  |  |

成功响应 204：Successful Response；可能没有响应体。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_attachments_media -->
### list_product_attachments

List product manuals, specifications, and other attachment records.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/products/{product_id}/attachments` — List Product Attachments

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

成功响应 200 `application/json`：`array<ProductAttachmentOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_attachment_types

List configured product attachment types.

模型：`object`。

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/product-attachment-types` — List Attachment Types

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<AttachmentTypeOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### create_product_attachment

Attach an existing document URL to a product.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `attachment` | 是 | object |  |  |

权限：`products.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/products/{product_id}/attachments` — Create Product Attachment

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

请求体 `application/json`：`ProductAttachmentIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `type_id` | 是 | integer |  |  |
| `title` | 否 | string / null | 最长 200 |  |
| `file_url` | 是 | string | 最长 500 |  |
| `mime_type` | 否 | string / null | 最长 120 |  |
| `file_size` | 否 | integer / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 201 `application/json`：`ProductAttachmentOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### update_product_attachment

Update an attachment URL, type, title, or visibility.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `attachment_id` | 是 | integer |  |  |
| `attachment` | 是 | object |  |  |

权限：`products.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/product-attachments/{attachment_id}` — Update Product Attachment

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `attachment_id` | path | 是 | integer |  |  |

请求体 `application/json`：`ProductAttachmentIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `type_id` | 是 | integer |  |  |
| `title` | 否 | string / null | 最长 200 |  |
| `file_url` | 是 | string | 最长 500 |  |
| `mime_type` | 否 | string / null | 最长 120 |  |
| `file_size` | 否 | integer / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 200 `application/json`：`ProductAttachmentOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_product_media_roles

List product gallery items grouped by media role.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/products/{product_id}/media-role-items` — List Product Media Role Items

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

成功响应 200 `application/json`：`array<ProductMediaRoleItemOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_media_role_options

List configured product media roles.

模型：`object`。

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/product-media-roles` — List Media Roles

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<MediaRoleOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### create_product_media_role

Add an existing image URL under a product media role.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `media` | 是 | object |  |  |

权限：`products.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/products/{product_id}/media-role-items` — Create Product Media Role Item

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

请求体 `application/json`：`ProductMediaRoleItemIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `role_id` | 是 | integer |  |  |
| `image_url` | 是 | string | 最长 500 |  |
| `alt_text` | 否 | string / null | 最长 200 |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 201 `application/json`：`ProductMediaRoleItemOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### update_product_media_role

Update a product gallery item's role, URL, alt text, or visibility.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `item_id` | 是 | integer |  |  |
| `media` | 是 | object |  |  |

权限：`products.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/product-media-role-items/{item_id}` — Update Product Media Role Item

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `item_id` | path | 是 | integer |  |  |

请求体 `application/json`：`ProductMediaRoleItemIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `role_id` | 是 | integer |  |  |
| `image_url` | 是 | string | 最长 500 |  |
| `alt_text` | 否 | string / null | 最长 200 |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 200 `application/json`：`ProductMediaRoleItemOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_units -->
### list_product_selling_units

List selling units and effective prices for a product.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/unit-split/products/{product_id}/units` — List Product Units

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

成功响应 200 `application/json`：`array<SellingUnitOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### list_selling_unit_options

List configured unit names for product selling-unit setup.

模型：`object`。

权限：`products.view`。作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/unit-split/dict` — List Unit Dict

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<UnitDictOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### create_product_selling_unit

Add a product sales unit with base-quantity conversion and optional price.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `unit` | 是 | object |  |  |

权限：`products.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/unit-split/products/{product_id}/units` — Create Product Unit

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path | 是 | integer |  |  |

请求体 `application/json`：`SellingUnitIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `dict_id` | 否 | integer / null |  |  |
| `unit_name` | 是 | string |  |  |
| `unit_name_en` | 否 | string / null |  |  |
| `qty_per_base` | 否 | integer | 默认 1 |  |
| `is_base_unit` | 否 | boolean | 默认 false |  |
| `price_override` | 否 | number / string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |

成功响应 201 `application/json`：`SellingUnitOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

### update_product_selling_unit

Update a product sales-unit conversion or override price.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `unit_id` | 是 | integer |  |  |
| `unit` | 是 | object |  |  |

权限：`products.update`。作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/unit-split/units/{unit_id}` — Update Product Unit

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `unit_id` | path | 是 | integer |  |  |

请求体 `application/json`：`SellingUnitIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `dict_id` | 否 | integer / null |  |  |
| `unit_name` | 是 | string |  |  |
| `unit_name_en` | 否 | string / null |  |  |
| `qty_per_base` | 否 | integer | 默认 1 |  |
| `is_base_unit` | 否 | boolean | 默认 false |  |
| `price_override` | 否 | number / string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |

成功响应 200 `application/json`：`SellingUnitOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_usage_guide -->
### usage_guide

Step-by-step recipes for common questions (recent order items, best sellers, sales trend, POS comparison,
low stock to draft purchase order, error meanings). Call with topic='index' first if unsure.

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `topic` | 否 | string | 默认 "index"；允许值由 Markdown 主题固定标识生成，以 tools/list 的 enum 和 index 为准 | 不手工维护另一份主题清单 |

此工具返回当前服务内置的说明文字，不调用业务 API；topic 以工具枚举为准。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_receipt_ai -->
### submit_direct_receipt_parse

Upload a base64 supplier invoice or delivery note (PDF, image, CSV or XLSX, up to 10 MB) for AI line parsing.

Returns a task_id; poll inventory_query endpoint direct_receipt_parse_status, then create a draft with
inventory_drafts create_direct_receipt.


| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `filename` | 是 | string |  |  |
| `content_type` | 是 | string |  |  |
| `file_base64` | 是 | string |  |  |

权限：`inventory.purchase`。作用：上传文件并创建 AI 识别任务，不入库。

`POST /api/admin/inventory/direct-receipts/ai-parse` — Ai Parse Direct Receipt

提交单据识别（PDF/图片/CSV/XLSX），立即返回 task_id，结果由轮询取回。

识图常跑一两分钟，同步返回会被反向代理 60s 掐断，所以改成后台任务。

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `multipart/form-data`：`Body_ai_parse_direct_receipt_api_admin_inventory_direct_receipts_ai_parse_post`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `file` | 是 | string (binary) |  |  |
| `image_url` | 否 | string | 默认 "" |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

成本字段或识别任务另需 `products.cost_price.view`，详见主手册。
<!-- /mcp-topic -->

## 分组工具全部 endpoint

<!-- mcp-topic: reference_dashboard_stats -->
### dashboard_stats 数据看板

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["stats", "trend", "order_status", "top_products", "top_customers", "customer_growth", "category_sales", "category_sales_detail", "product_sales", "inventory_alerts", "coupon_stats", "review_stats"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### dashboard_stats.stats

调用：`dashboard_stats endpoint=stats`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/stats` — 核心统计指标（含环比）

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`DashboardStats`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.trend

调用：`dashboard_stats endpoint=trend`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/trend` — 营收趋势（支持 7d/30d/90d）

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `range` | params | 否 | string | 默认 "7d"；正则 "^(7d\|30d\|90d\|custom)$" |  |
| `date_start` | params | 否 | string (date) / null |  |  |
| `date_end` | params | 否 | string (date) / null |  |  |

成功响应 200 `application/json`：`array<RevenueTrendItem>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.order_status

调用：`dashboard_stats endpoint=order_status`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/order-status` — 订单状态分布

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `range` | params | 否 | string | 默认 "7d"；正则 "^(7d\|30d\|90d\|custom)$" |  |
| `date_start` | params | 否 | string (date) / null |  |  |
| `date_end` | params | 否 | string (date) / null |  |  |

成功响应 200 `application/json`：`array<OrderStatusItem>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.top_products

调用：`dashboard_stats endpoint=top_products`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/top-products` — 销售额 Top N 商品

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `range` | params | 否 | string | 默认 "30d"；正则 "^(7d\|30d\|90d\|custom)$" |  |
| `date_start` | params | 否 | string (date) / null |  |  |
| `date_end` | params | 否 | string (date) / null |  |  |
| `limit` | params | 否 | integer | 默认 10；最小 1；最大 200 |  |

成功响应 200 `application/json`：`array<TopProductItem>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.top_customers

调用：`dashboard_stats endpoint=top_customers`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/top-customers` — 消费额 Top N 客户

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `range` | params | 否 | string | 默认 "30d"；正则 "^(7d\|30d\|90d\|custom)$" |  |
| `date_start` | params | 否 | string (date) / null |  |  |
| `date_end` | params | 否 | string (date) / null |  |  |
| `limit` | params | 否 | integer | 默认 10；最小 1；最大 50 |  |

成功响应 200 `application/json`：`array<TopCustomerItem>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.customer_growth

调用：`dashboard_stats endpoint=customer_growth`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/customer-growth` — 新客增长趋势

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `range` | params | 否 | string | 默认 "30d"；正则 "^(7d\|30d\|90d\|custom)$" |  |
| `date_start` | params | 否 | string (date) / null |  |  |
| `date_end` | params | 否 | string (date) / null |  |  |

成功响应 200 `application/json`：`array<CustomerGrowthItem>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.category_sales

调用：`dashboard_stats endpoint=category_sales`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/category-sales` — 品类销售占比

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `range` | params | 否 | string | 默认 "30d"；正则 "^(7d\|30d\|90d\|custom)$" |  |
| `date_start` | params | 否 | string (date) / null |  |  |
| `date_end` | params | 否 | string (date) / null |  |  |

成功响应 200 `application/json`：`array<CategorySalesItem>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.category_sales_detail

调用：`dashboard_stats endpoint=category_sales_detail`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/category-sales-detail` — 分类销售明细

全店订单商品行的分类销售额，分类树父级自动汇总子分类。

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `range` | params | 否 | string | 默认 "today"；正则 "^(today\|7d\|30d\|90d\|custom)$" |  |
| `date_start` | params | 否 | string (date) / null |  |  |
| `date_end` | params | 否 | string (date) / null |  |  |

成功响应 200 `application/json`：`CategorySalesDetailPage`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.product_sales

调用：`dashboard_stats endpoint=product_sales`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/product-sales` — 商品销售明细（搜索+分页）

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `range` | params | 否 | string | 默认 "30d"；正则 "^(7d\|30d\|90d\|custom)$" |  |
| `date_start` | params | 否 | string (date) / null |  |  |
| `date_end` | params | 否 | string (date) / null |  |  |
| `keyword` | params | 否 | string | 默认 "" | 搜索商品名称或SKU |
| `sort_by` | params | 否 | string | 默认 "revenue"；正则 "^(revenue\|quantity\|orders_count\|avg_unit_price)$" |  |
| `page` | params | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | params | 否 | integer | 默认 20；最小 5；最大 100 |  |

成功响应 200 `application/json`：`ProductSalesPage`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.inventory_alerts

调用：`dashboard_stats endpoint=inventory_alerts`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/inventory-alerts` — 库存预警商品

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<InventoryAlertItem>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.coupon_stats

调用：`dashboard_stats endpoint=coupon_stats`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/coupon-stats` — 优惠券使用统计

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<CouponStatsItem>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### dashboard_stats.review_stats

调用：`dashboard_stats endpoint=review_stats`。权限：`dashboard.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/dashboard/review-stats` — 评价数据统计

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`ReviewStatsResponse`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_advanced_stats -->
### advanced_stats 高级统计

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["report", "options", "hungrypanda_shops", "presets", "details"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### advanced_stats.report

调用：`advanced_stats endpoint=report`。权限：`adv_stats.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/adv-stats/report` — 多维度统计报表

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `dimension` | params | 否 | string | 默认 "summary" |  |
| `granularity` | params | 否 | string | 默认 "month" |  |
| `range` | params | 否 | string | 默认 "month" |  |
| `date_start` | params | 否 | string (date) / null |  |  |
| `date_end` | params | 否 | string (date) / null |  |  |
| `date_basis` | params | 否 | string | 默认 "created"；允许值 ["created", "paid"] |  |
| `source` | params | 否 | string | 默认 "all"；允许值 ["all", "pos", "non_pos", "hungrypanda"] |  |
| `hp_shop_id` | params | 否 | string / null |  |  |
| `details` | params | 否 | string | 默认 "none" |  |
| `order_no_from` | params | 否 | string / null |  |  |
| `order_no_to` | params | 否 | string / null |  |  |
| `total_min` | params | 否 | number / string / null |  |  |
| `total_max` | params | 否 | number / string / null |  |  |
| `customer_name` | params | 否 | string / null |  |  |
| `customer_email` | params | 否 | string / null |  |  |
| `customer_phone` | params | 否 | string / null |  |  |
| `country` | params | 否 | string / null |  |  |
| `province` | params | 否 | string / null |  |  |
| `city` | params | 否 | string / null |  |  |
| `district` | params | 否 | string / null |  |  |
| `postcode` | params | 否 | string / null |  |  |
| `product_keyword` | params | 否 | string / null |  |  |
| `pos_created_offline` | params | 否 | boolean / null |  |  |
| `pos_price_adjusted` | params | 否 | boolean / null |  |  |
| `dim_key` | params | 否 | string / null |  |  |
| `sort` | params | 否 | string | 默认 "dim_key" |  |
| `order` | params | 否 | string | 默认 "desc"；允许值 ["asc", "desc"] |  |
| `detail_sort` | params | 否 | string | 默认 "created_at" |  |
| `detail_order` | params | 否 | string | 默认 "desc"；允许值 ["asc", "desc"] |  |
| `page` | params | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | params | 否 | integer | 默认 50；最小 5；最大 1000 |  |

请求体 `application/json`：`Body_get_report_api_admin_adv_stats_report_get`。 GET 数组参数经 advanced_stats.params 自动转发；不要手工传 body。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `statuses` | 否 | array<string> / null |  |  |
| `member_level_ids` | 否 | array<integer> / null |  |  |
| `payment_gateways` | 否 | array<string> / null |  |  |
| `shipping_method_ids` | 否 | array<integer> / null |  |  |
| `currencies` | 否 | array<string> / null |  |  |
| `product_ids` | 否 | array<integer> / null |  |  |
| `category_ids` | 否 | array<integer> / null |  |  |
| `brand_ids` | 否 | array<integer> / null |  |  |
| `discount_ids` | 否 | array<integer> / null |  |  |
| `pos_store_ids` | 否 | array<integer> / null |  |  |
| `pos_lane_ids` | 否 | array<string> / null |  |  |
| `pos_operator_ids` | 否 | array<integer> / null |  |  |

成功响应 200 `application/json`：`ReportResponse`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### advanced_stats.options

调用：`advanced_stats endpoint=options`。权限：`adv_stats.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/adv-stats/report/options` — 筛选器下拉选项

一次返回所有下拉数据，前端进页面只发一个请求。

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### advanced_stats.hungrypanda_shops

调用：`advanced_stats endpoint=hungrypanda_shops`。权限：`adv_stats.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/adv-stats/report/hungrypanda-shops` — 高级统计可筛选的 HungryPanda 店铺

Use the report permission instead of leaking an orders-page dependency.

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### advanced_stats.presets

调用：`advanced_stats endpoint=presets`。权限：`adv_stats.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/adv-stats/presets` — 预设报表列表

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<PresetOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### advanced_stats.details

调用：`advanced_stats endpoint=details`。权限：`adv_stats.detail`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/adv-stats/report/details` — 明细下钻（含客户信息）

明细层输出客户 PII，权限在依赖里硬拦——前端隐藏不算数。

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `dimension` | params | 否 | string | 默认 "summary" |  |
| `granularity` | params | 否 | string | 默认 "month" |  |
| `range` | params | 否 | string | 默认 "month" |  |
| `date_start` | params | 否 | string (date) / null |  |  |
| `date_end` | params | 否 | string (date) / null |  |  |
| `date_basis` | params | 否 | string | 默认 "created"；允许值 ["created", "paid"] |  |
| `source` | params | 否 | string | 默认 "all"；允许值 ["all", "pos", "non_pos", "hungrypanda"] |  |
| `hp_shop_id` | params | 否 | string / null |  |  |
| `details` | params | 否 | string | 默认 "none" |  |
| `order_no_from` | params | 否 | string / null |  |  |
| `order_no_to` | params | 否 | string / null |  |  |
| `total_min` | params | 否 | number / string / null |  |  |
| `total_max` | params | 否 | number / string / null |  |  |
| `customer_name` | params | 否 | string / null |  |  |
| `customer_email` | params | 否 | string / null |  |  |
| `customer_phone` | params | 否 | string / null |  |  |
| `country` | params | 否 | string / null |  |  |
| `province` | params | 否 | string / null |  |  |
| `city` | params | 否 | string / null |  |  |
| `district` | params | 否 | string / null |  |  |
| `postcode` | params | 否 | string / null |  |  |
| `product_keyword` | params | 否 | string / null |  |  |
| `pos_created_offline` | params | 否 | boolean / null |  |  |
| `pos_price_adjusted` | params | 否 | boolean / null |  |  |
| `dim_key` | params | 否 | string / null |  |  |
| `sort` | params | 否 | string | 默认 "dim_key" |  |
| `order` | params | 否 | string | 默认 "desc"；允许值 ["asc", "desc"] |  |
| `detail_sort` | params | 否 | string | 默认 "created_at" |  |
| `detail_order` | params | 否 | string | 默认 "desc"；允许值 ["asc", "desc"] |  |
| `page` | params | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | params | 否 | integer | 默认 50；最小 5；最大 1000 |  |

请求体 `application/json`：`Body_get_details_api_admin_adv_stats_report_details_get`。 GET 数组参数经 advanced_stats.params 自动转发；不要手工传 body。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `statuses` | 否 | array<string> / null |  |  |
| `member_level_ids` | 否 | array<integer> / null |  |  |
| `payment_gateways` | 否 | array<string> / null |  |  |
| `shipping_method_ids` | 否 | array<integer> / null |  |  |
| `currencies` | 否 | array<string> / null |  |  |
| `product_ids` | 否 | array<integer> / null |  |  |
| `category_ids` | 否 | array<integer> / null |  |  |
| `brand_ids` | 否 | array<integer> / null |  |  |
| `discount_ids` | 否 | array<integer> / null |  |  |
| `pos_store_ids` | 否 | array<integer> / null |  |  |
| `pos_lane_ids` | 否 | array<string> / null |  |  |
| `pos_operator_ids` | 否 | array<integer> / null |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_inventory_query -->
### inventory_query 进销存查询

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["settings", "tax_rates", "policy", "product_profile", "locations", "putaway_rules", "transactions", "suppliers", "supplier_products", "receipt_party_mappings", "receipt_party_names", "purchase_orders", "purchase_order", "receipts", "receipt", "direct_receipt_parse_status", "operations", "transfers", "transfer", "stocktakes", "stocktake", "fulfillment_orders", "fulfillment_order", "lockable_batches", "batches", "trace_lot", "trace_serial", "replenishment_rules", "replenishment_suggestions", "revaluations", "warehouse_mapping_overview", "warehouse_mapping_options", "warehouse_mapping_stores", "warehouse_mapping_channels", "order_warehouse_overrides"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### inventory_query.settings

调用：`inventory_query endpoint=settings`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/settings` — Get Settings

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`app__plugins__inventory__schemas__SettingsOut / null`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### inventory_query.tax_rates

调用：`inventory_query endpoint=tax_rates`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/tax-rates` — List Inventory Tax Rates

供库存单据选择税率；不要求库存操作员拥有税务设置权限。

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.policy

调用：`inventory_query endpoint=policy`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/policy` — Get Inventory Policy

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.product_profile

调用：`inventory_query endpoint=product_profile`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/products/{product_id}/profile` — Get Product Profile

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path_params | 是 | integer |  |  |
| `variant_id` | params | 否 | integer / null |  |  |

成功响应 200 `application/json`：`ProductProfileOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### inventory_query.locations

调用：`inventory_query endpoint=locations`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/locations` — List Locations

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `warehouse_id` | params | 否 | integer / null |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.putaway_rules

调用：`inventory_query endpoint=putaway_rules`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/putaway-rules` — List Putaway Rules

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `warehouse_id` | params | 否 | integer / null |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.transactions

调用：`inventory_query endpoint=transactions`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/transactions` — List Transactions

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | params | 否 | integer / null |  |  |
| `cursor` | params | 否 | string / null |  | 上一页最后一条 id，按 id 降序翻页 |
| `limit` | params | 否 | integer | 默认 50；最大 200 |  |

成功响应 200 `application/json`：`array<TransactionOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### inventory_query.suppliers

调用：`inventory_query endpoint=suppliers`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/suppliers` — List Suppliers

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.supplier_products

调用：`inventory_query endpoint=supplier_products`。权限：`inventory.view` + `products.cost_price.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/supplier-products` — List Supplier Products

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `supplier_id` | params | 否 | integer / null |  |  |
| `product_id` | params | 否 | integer / null |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.receipt_party_mappings

调用：`inventory_query endpoint=receipt_party_mappings`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/receipt-party-mappings` — List Receipt Party Mappings

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.receipt_party_names

调用：`inventory_query endpoint=receipt_party_names`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/receipt-party-names` — List Receipt Party Names

到货单供货方输入框的候选：发货方映射的显示名 + 历史到货单用过的名称。

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.purchase_orders

调用：`inventory_query endpoint=purchase_orders`。权限：`inventory.view` + `products.cost_price.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/purchase-orders` — List Purchase Orders

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `keyword` | params | 否 | string / null | 最长 60 |  |
| `supplier_id` | params | 否 | integer / null |  |  |
| `status` | params | 否 | string / null |  |  |
| `page` | params | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | params | 否 | integer | 默认 20；最小 1；最大 100 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.purchase_order

调用：`inventory_query endpoint=purchase_order`。权限：`inventory.view` + `products.cost_price.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/purchase-orders/{po_id}` — Get Purchase Order

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `po_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.receipts

调用：`inventory_query endpoint=receipts`。权限：`inventory.view` + `products.cost_price.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/receipts` — List Receipts

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `state` | params | 否 | string / null |  |  |
| `source_doc_type` | params | 否 | string / null | 正则 "^(purchase_order\|direct_receipt)$" |  |
| `party_name` | params | 否 | string / null | 最长 160 |  |
| `page` | params | 否 | integer / null | 最小 1 |  |
| `page_size` | params | 否 | integer | 默认 20；最小 1；最大 100 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.receipt

调用：`inventory_query endpoint=receipt`。权限：`inventory.view` + `products.cost_price.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/receipts/{operation_id}` — Get Receipt

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.direct_receipt_parse_status

调用：`inventory_query endpoint=direct_receipt_parse_status`。权限：`inventory.purchase` + `products.cost_price.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/direct-receipts/ai-parse/{task_id}` — Ai Parse Direct Receipt Status

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `task_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.operations

调用：`inventory_query endpoint=operations`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/operations` — List Operations

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_type` | params | 否 | string / null |  |  |
| `state` | params | 否 | string / null |  |  |
| `page` | params | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | params | 否 | integer | 默认 50；最小 1；最大 100 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.transfers

调用：`inventory_query endpoint=transfers`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/transfers` — List Transfer Documents

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `state` | params | 否 | string / null |  |  |
| `page` | params | 否 | integer / null | 最小 1 |  |
| `page_size` | params | 否 | integer | 默认 20；最小 1；最大 100 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.transfer

调用：`inventory_query endpoint=transfer`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/transfers/{operation_id}` — Get Transfer Document

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.stocktakes

调用：`inventory_query endpoint=stocktakes`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/stocktakes` — List Stocktakes

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `state` | params | 否 | string / null |  |  |
| `page` | params | 否 | integer / null | 最小 1 |  |
| `page_size` | params | 否 | integer | 默认 20；最小 1；最大 100 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.stocktake

调用：`inventory_query endpoint=stocktake`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/stocktakes/{operation_id}` — Get Stocktake Document

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.fulfillment_orders

调用：`inventory_query endpoint=fulfillment_orders`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/fulfillment/orders` — List Fulfillment Orders

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `stage` | params | 否 | string / null |  |  |
| `keyword` | params | 否 | string / null | 最长 60 |  |
| `page` | params | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | params | 否 | integer | 默认 50；最小 1；最大 100 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.fulfillment_order

调用：`inventory_query endpoint=fulfillment_order`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/fulfillment/orders/{order_id}` — Get Fulfillment

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `order_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.lockable_batches

调用：`inventory_query endpoint=lockable_batches`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/batches/lockable` — List Lockable Batches

B2B 批次弹窗：建单仓里各批次当前可锁定数量（与 batch-lock 同口径）。

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.batches

调用：`inventory_query endpoint=batches`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/batches` — List Batches

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.trace_lot

调用：`inventory_query endpoint=trace_lot`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/trace/lots/{batch_id}` — Trace Inventory Lot

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `batch_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.trace_serial

调用：`inventory_query endpoint=trace_serial`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/trace/serials/{serial_no}` — Trace Inventory Serial

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `serial_no` | path_params | 是 | string |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.replenishment_rules

调用：`inventory_query endpoint=replenishment_rules`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/replenishment/rules` — List Reorder Rules

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.replenishment_suggestions

调用：`inventory_query endpoint=replenishment_suggestions`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/replenishment/suggestions` — List Replenishment

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.revaluations

调用：`inventory_query endpoint=revaluations`。权限：`inventory.view` + `products.cost_price.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/revaluations` — List Revaluations

列出已保存的成本重估及其汇总明细，供后台审计查看。

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `page` | params | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | params | 否 | integer | 默认 50；最小 1；最大 100 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.warehouse_mapping_overview

调用：`inventory_query endpoint=warehouse_mapping_overview`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/warehouse-mapping/overview` — Warehouse Mapping Overview

三类入口的映射清单。开启强制开关前先看这里，unmapped 非空就不能开。

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.warehouse_mapping_options

调用：`inventory_query endpoint=warehouse_mapping_options`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/warehouse-mapping/options` — Mapping Options

映射页可选来源；只给当前租户仍在使用的 POS/HP 入口。

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_query.warehouse_mapping_stores

调用：`inventory_query endpoint=warehouse_mapping_stores`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/warehouse-mapping/stores` — List Store Warehouse Mappings

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<StoreWarehouseMappingOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### inventory_query.warehouse_mapping_channels

调用：`inventory_query endpoint=warehouse_mapping_channels`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/warehouse-mapping/channels` — List Channel Warehouse Mappings

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<ExternalChannelMappingOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### inventory_query.order_warehouse_overrides

调用：`inventory_query endpoint=order_warehouse_overrides`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/orders/{order_id}/warehouse-override` — List Order Warehouse Overrides

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `order_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_inventory_reports -->
### inventory_reports 库存报表

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["stock_value", "low_stock", "expiring", "unallocated", "forecast", "aging", "anomalies", "fulfillment", "suppliers", "sales_gross_profit", "order_profit", "reconcile"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### inventory_reports.stock_value

调用：`inventory_reports endpoint=stock_value`。权限：`inventory.view` + `products.cost_price.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/stock-value` — Report Stock Value

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_reports.low_stock

调用：`inventory_reports endpoint=low_stock`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/low-stock` — Report Low Stock

缺货/补货建议：上架商品中可下单量不高于阈值的。口径与商品列表 filter=low 一致（<=、COALESCE）。

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_reports.expiring

调用：`inventory_reports endpoint=expiring`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/expiring` — Report Expiring

仍有在库余额的临期库存：到期日在 [今天, 今天+days]；expired=1 时改查已过期的。

启用批次的租户按批次到期日；未启用的没有批次行，改按商品/规格到期日
（规格有自己的到期日用规格的，否则用商品的），batch_id 为空。
卖空的批次行不删，不加余额条件这个数会只增不减。

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `days` | params | 否 | integer | 默认 30；最小 0；最大 3650 |  |
| `expired` | params | 否 | boolean | 默认 false |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_reports.unallocated

调用：`inventory_reports endpoint=unallocated`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/unallocated` — Report Unallocated

未分配负库存异常桶：POS 离线 FEFO 缺口，待人工补录批次冲销。

带上仓：缺口落在哪个门店仓，就该由那个仓去补录，不能混成一张全局清单。

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `warehouse_id` | params | 否 | integer / null |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_reports.forecast

调用：`inventory_reports endpoint=forecast`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/forecast` — Report Forecast

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_reports.aging

调用：`inventory_reports endpoint=aging`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/aging` — Report Aging

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_reports.anomalies

调用：`inventory_reports endpoint=anomalies`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/anomalies` — Report Anomalies

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_reports.fulfillment

调用：`inventory_reports endpoint=fulfillment`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/fulfillment` — Report Fulfillment

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `assignment_state` | params | 否 | string / null | 正则 "^(pending\|assigned)$" |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_reports.suppliers

调用：`inventory_reports endpoint=suppliers`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/suppliers` — Report Suppliers

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_reports.sales_gross_profit

调用：`inventory_reports endpoint=sales_gross_profit`。权限：`inventory.view` + `products.cost_price.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/sales-gross-profit` — Report Sales Gross Profit

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `date_from` | params | 是 | string |  | ISO date YYYY-MM-DD，含 |
| `date_to` | params | 是 | string |  | ISO date YYYY-MM-DD，不含 |
| `warehouse_id` | params | 否 | integer / null |  |  |
| `anomaly_filter` | params | 否 | string / null | 正则 "^(loss\|dropped)$" |  |
| `page` | params | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | params | 否 | integer | 默认 50；最小 1；最大 500 |  |

成功响应 200 `application/json`：`SalesGrossProfitResponse`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### inventory_reports.order_profit

调用：`inventory_reports endpoint=order_profit`。权限：`inventory.view` + `products.cost_price.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reports/order-profit` — 订单利润（一行一单）

与商品维度毛利同源，只是按订单聚合。未扣库存的订单不出现在结果里。

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `date_from` | params | 是 | string |  | ISO date YYYY-MM-DD，含 |
| `date_to` | params | 是 | string |  | ISO date YYYY-MM-DD，不含 |
| `warehouse_id` | params | 否 | integer / null |  |  |
| `keyword` | params | 否 | string / null |  | 订单号模糊搜索 |
| `page` | params | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | params | 否 | integer | 默认 20；最小 1；最大 200 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_reports.reconcile

调用：`inventory_reports endpoint=reconcile`。权限：`inventory.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory/reconcile` — Reconcile Ledger

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_pos_admin_query -->
### pos_admin_query POS 后台查询

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["reconciliation_cases", "sync_conflicts", "reconciliation_lanes", "wallet_topups", "wallet_reconcile", "wallet_rules", "product_channel", "staff", "assignable_users", "stores", "rules", "quick_buttons", "barcode_prefixes", "product_ages", "returns"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### pos_admin_query.reconciliation_cases

调用：`pos_admin_query endpoint=reconciliation_cases`。权限：`pos.reconciliation.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/pos/reconciliation` — List Reconciliation Cases

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `status` | params | 否 | string / null |  |  |
| `storeId` | params | 否 | integer / null |  |  |
| `laneId` | params | 否 | string / null |  |  |
| `limit` | params | 否 | integer | 默认 50；最大 200 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.sync_conflicts

调用：`pos_admin_query endpoint=sync_conflicts`。权限：`pos.reconciliation.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/pos/reconciliation/sync-conflicts` — List Sync Conflicts

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `limit` | params | 否 | integer | 默认 100；最大 200 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.reconciliation_lanes

调用：`pos_admin_query endpoint=reconciliation_lanes`。权限：`pos.reconciliation.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/pos/reconciliation/lanes` — List Reconciliation Lanes

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.wallet_topups

调用：`pos_admin_query endpoint=wallet_topups`。权限：`adv_stats.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/pos/wallet/topups` — Admin Topups

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `date_from` | params | 否 | string / null |  |  |
| `date_to` | params | 否 | string / null |  |  |
| `store_id` | params | 否 | integer / null |  |  |
| `lane_id` | params | 否 | string / null |  |  |
| `cashier_id` | params | 否 | string / null |  |  |
| `customer_id` | params | 否 | integer / null |  |  |
| `page` | params | 否 | integer | 默认 1 |  |
| `page_size` | params | 否 | integer | 默认 20 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.wallet_reconcile

调用：`pos_admin_query endpoint=wallet_reconcile`。权限：`adv_stats.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/pos/wallet/reconcile` — Admin Reconcile

充值侧资金流，供现有 POS 收银对账合并。赠送单列，不进外部实收。

与 /topups 共用 resolve_report_window，两个接口的日界必须逐字节一致——
对账页同时调这两个接口，边界差一秒就是「明细有、汇总没有」。

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `date_from` | params | 否 | string / null |  |  |
| `date_to` | params | 否 | string / null |  |  |
| `store_id` | params | 否 | integer / null |  |  |
| `lane_id` | params | 否 | string / null |  |  |
| `cashier_id` | params | 否 | string / null |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.wallet_rules

调用：`pos_admin_query endpoint=wallet_rules`。权限：`adv_stats.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/pos/wallet/rules` — Admin Rules

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.product_channel

调用：`pos_admin_query endpoint=product_channel`。权限：`products.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/pos/product-channels/{product_id}` — Get Product Channel

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `product_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.staff

调用：`pos_admin_query endpoint=staff`。权限：`pos.staff.manage`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/pos/operations/admin/staff` — List Staff Endpoint

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json`：`array<StaffOut>`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### pos_admin_query.assignable_users

调用：`pos_admin_query endpoint=assignable_users`。权限：`pos.staff.manage`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/pos/operations/admin/assignable-users` — List Assignable Users Endpoint

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.stores

调用：`pos_admin_query endpoint=stores`。权限：`pos.audit.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/pos/operations/admin/stores` — List Stores Endpoint

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.rules

调用：`pos_admin_query endpoint=rules`。权限：`pos.rules.manage`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/pos/operations/admin/rules` — Get Rules Endpoint

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `store_id` | params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.quick_buttons

调用：`pos_admin_query endpoint=quick_buttons`。权限：`pos.rules.manage`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/pos/operations/admin/quick-buttons` — Get Quick Buttons Endpoint

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `store_id` | params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.barcode_prefixes

调用：`pos_admin_query endpoint=barcode_prefixes`。权限：`pos.rules.manage`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/pos/operations/admin/barcode-prefixes` — List Barcode Prefixes Endpoint

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.product_ages

调用：`pos_admin_query endpoint=product_ages`。权限：`pos.rules.manage`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/pos/operations/admin/product-ages` — List Product Ages Endpoint

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `q` | params | 否 | string | 默认 "" |  |
| `only_restricted` | params | 否 | boolean | 默认 false |  |
| `limit` | params | 否 | integer | 默认 50 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### pos_admin_query.returns

调用：`pos_admin_query endpoint=returns`。权限：`pos.audit.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/pos/operations/admin/returns` — List Returns Endpoint

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `store_id` | params | 否 | integer / null |  |  |
| `fund_status` | params | 否 | string / null |  |  |
| `limit` | params | 否 | integer | 默认 50 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_customer_return_query -->
### customer_return_query 客户购买与退回汇总

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["product_purchases", "return_records_summary"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### customer_return_query.product_purchases

调用：`customer_return_query endpoint=product_purchases`。权限：`customers.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/customers/{customer_id}/product-purchases` — 客户最近购买某商品的记录

管理员建单时参考：该客户最近几单买这个商品的订单号与成交单价（不含已取消）。

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `customer_id` | path_params | 是 | integer |  |  |
| `product_id` | params | 是 | integer |  |  |
| `limit` | params | 否 | integer | 默认 5；最小 1；最大 20 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### customer_return_query.return_records_summary

调用：`customer_return_query endpoint=return_records_summary`。权限：`return_collections.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/return-collections/records/summary` — Summarize Records

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `collection_id` | params | 否 | integer / null |  |  |
| `unassigned` | params | 否 | boolean | 默认 false |  |
| `keyword` | params | 否 | string / null |  |  |
| `disposition` | params | 否 | string / null |  |  |
| `source_type` | params | 否 | string / null |  |  |
| `date_from` | params | 否 | string (date) / null |  |  |
| `date_to` | params | 否 | string (date) / null |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_stock_alerts_and_statuses -->
### stock_alerts_and_statuses 库存预警与状态维护

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["list_alerts", "set_alert", "update_alert", "delete_alert", "create_stock_status", "update_stock_status"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### stock_alerts_and_statuses.list_alerts

调用：`stock_alerts_and_statuses endpoint=list_alerts`。权限：`products.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/inventory-alerts` — List Inventory Alerts

列出当前租户的所有库存预警设置

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### stock_alerts_and_statuses.set_alert

调用：`stock_alerts_and_statuses endpoint=set_alert`。权限：`products.update`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/inventory-alerts` — Set Inventory Alert

为任意商品设置（或更新）预警阈值

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`AlertSetBody`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `threshold` | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### stock_alerts_and_statuses.update_alert

调用：`stock_alerts_and_statuses endpoint=update_alert`。权限：`products.update`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/inventory-alerts/{alert_id}` — Update Inventory Alert

更新预警阈值

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `alert_id` | path_params | 是 | integer |  |  |
| `threshold` | params | 否 | integer | 默认 10 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### stock_alerts_and_statuses.delete_alert

调用：`stock_alerts_and_statuses endpoint=delete_alert`。权限：`products.update`。

作用：删除指定图片关联或预警配置，核对目标后执行。

`DELETE /api/admin/inventory-alerts/{alert_id}` — Delete Inventory Alert

取消商品库存预警

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `alert_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### stock_alerts_and_statuses.create_stock_status

调用：`stock_alerts_and_statuses endpoint=create_stock_status`。权限：`products.update`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/stock-statuses` — 新建库存状态

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`StockStatusIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string | 最长 50 |  |
| `name_en` | 否 | string / null | 最长 50 |  |
| `slug` | 是 | string | 最长 30；正则 "^[a-z][a-z0-9_]*$" |  |
| `allow_purchase` | 否 | boolean | 默认 true |  |
| `allow_purchase_without_stock` | 否 | boolean | 默认 false |  |
| `badge_color` | 否 | string / null | 最长 20 |  |
| `badge_text` | 否 | string / null | 最长 50 |  |
| `badge_text_en` | 否 | string / null | 最长 50 |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_default` | 否 | boolean | 默认 false |  |
| `status_type` | 否 | string | 默认 "in_stock"；允许值 ["in_stock", "out_of_stock"] |  |
| `is_type_default` | 否 | boolean | 默认 false |  |

成功响应 201 `application/json`：`StockStatusOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。

#### stock_alerts_and_statuses.update_stock_status

调用：`stock_alerts_and_statuses endpoint=update_stock_status`。权限：`products.update`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/stock-statuses/{status_id}` — 编辑库存状态

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `status_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`StockStatusUpdate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 否 | string / null | 最长 50 |  |
| `name_en` | 否 | string / null | 最长 50 |  |
| `slug` | 否 | string / null | 最长 30；正则 "^[a-z][a-z0-9_]*$" |  |
| `allow_purchase` | 否 | boolean / null |  |  |
| `allow_purchase_without_stock` | 否 | boolean / null |  |  |
| `badge_color` | 否 | string / null | 最长 20 |  |
| `badge_text` | 否 | string / null | 最长 50 |  |
| `badge_text_en` | 否 | string / null | 最长 50 |  |
| `sort_order` | 否 | integer / null |  |  |
| `is_default` | 否 | boolean / null |  |  |
| `status_type` | 否 | string / null | 允许值 ["in_stock", "out_of_stock"] |  |
| `is_type_default` | 否 | boolean / null |  |  |

成功响应 200 `application/json`：`StockStatusOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_repack -->
### repack 分装规则

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["rules", "create_rule", "update_rule", "preview", "logs"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### repack.rules

调用：`repack endpoint=rules`。权限：`repack.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/repack/rules` — List Rules

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### repack.create_rule

调用：`repack endpoint=create_rule`。权限：`repack.manage`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/repack/rules` — Create Rule

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`app__plugins__repack__schemas__RuleIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `source_product_id` | 是 | integer | 大于 0.0 |  |
| `target_product_id` | 是 | integer | 大于 0.0 |  |
| `target_qty_per_source` | 是 | integer | 最小 1.0；最大 100000.0 |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### repack.update_rule

调用：`repack endpoint=update_rule`。权限：`repack.manage`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/repack/rules/{rule_id}` — Update Rule

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `rule_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`RuleUpdate`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `target_qty_per_source` | 否 | integer / null | 最小 1.0；最大 100000.0 |  |
| `is_active` | 否 | boolean / null |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### repack.preview

调用：`repack endpoint=preview`。权限：`repack.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/repack/preview` — Preview

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `rule_id` | params | 是 | integer | 大于 0 |  |
| `source_qty` | params | 是 | integer | 最小 1；最大 1000000 |  |
| `actual_qty` | params | 否 | integer / null | 最小 1 |  |
| `warehouse_id` | params | 否 | integer / null | 大于 0 |  |
| `source_batch_id` | params | 否 | integer / null | 大于 0 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### repack.logs

调用：`repack endpoint=logs`。权限：`repack.view`。

作用：读取；不会提交业务单据或改变库存。

`GET /api/admin/repack/logs` — List Logs

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `page` | params | 否 | integer | 默认 1；最小 1 |  |
| `page_size` | params | 否 | integer | 默认 20；最小 1；最大 100 |  |
| `product_id` | params | 否 | integer / null | 大于 0 |  |
| `target_batch_id` | params | 否 | integer / null | 大于 0 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_inventory_drafts -->
### inventory_drafts 库存单据草稿

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["create_purchase_order", "update_purchase_order", "submit_purchase_order", "create_receipt", "update_receipt", "create_direct_receipt", "update_direct_receipt", "create_stocktake", "update_stocktake", "create_transfer", "update_transfer", "create_vendor_return"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### inventory_drafts.create_purchase_order

调用：`inventory_drafts endpoint=create_purchase_order`。权限：`inventory.purchase` + `products.cost_price.view`。

作用：创建/修改业务草稿；实际过账另行执行。

`POST /api/admin/inventory/purchase-orders` — Create Purchase Order

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`PurchaseOrderIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `supplier_id` | 是 | integer |  |  |
| `warehouse_id` | 否 | integer / null |  |  |
| `currency` | 否 | string | 默认 "NZD"；最长 8 |  |
| `fx_rate` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `supplier_promise_date` | 否 | string / null |  |  |
| `planned_arrival_date` | 否 | string / null |  |  |
| `lines` | 是 | array<POLineIn> | 最少项 1 |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.update_purchase_order

调用：`inventory_drafts endpoint=update_purchase_order`。权限：`inventory.purchase` + `products.cost_price.view`。

作用：创建/修改业务草稿；实际过账另行执行。

`PUT /api/admin/inventory/purchase-orders/{po_id}` — Update Purchase Order

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `po_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`PurchaseOrderIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `supplier_id` | 是 | integer |  |  |
| `warehouse_id` | 否 | integer / null |  |  |
| `currency` | 否 | string | 默认 "NZD"；最长 8 |  |
| `fx_rate` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `supplier_promise_date` | 否 | string / null |  |  |
| `planned_arrival_date` | 否 | string / null |  |  |
| `lines` | 是 | array<POLineIn> | 最少项 1 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.submit_purchase_order

调用：`inventory_drafts endpoint=submit_purchase_order`。权限：`inventory.purchase`。

作用：采购单提交审批，改变状态但不是收货。

`POST /api/admin/inventory/purchase-orders/{po_id}/submit` — Submit Purchase Order

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `po_id` | path_params | 是 | integer |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.create_receipt

调用：`inventory_drafts endpoint=create_receipt`。权限：`inventory.purchase`。

作用：创建/修改业务草稿；实际过账另行执行。

`POST /api/admin/inventory/receipts` — Create Receipt

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`PurchaseReceiptIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `purchase_order_id` | 是 | integer |  |  |
| `lines` | 是 | array<PurchaseReceiptLineIn> | 最少项 1 |  |
| `planned_at` | 否 | string / null |  |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.update_receipt

调用：`inventory_drafts endpoint=update_receipt`。权限：`inventory.purchase`。

作用：创建/修改业务草稿；实际过账另行执行。

`PUT /api/admin/inventory/receipts/{operation_id}` — Update Receipt

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`PurchaseReceiptIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `purchase_order_id` | 是 | integer |  |  |
| `lines` | 是 | array<PurchaseReceiptLineIn> | 最少项 1 |  |
| `planned_at` | 否 | string / null |  |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.create_direct_receipt

调用：`inventory_drafts endpoint=create_direct_receipt`。权限：`inventory.purchase` + `products.cost_price.view`。

作用：创建/修改业务草稿；实际过账另行执行。

`POST /api/admin/inventory/direct-receipts` — Create Direct Receipt Doc

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`DirectReceiptIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 否 | integer / null |  |  |
| `received_on` | 是 | string | 最短 1；最长 32 | 到货日期，写入 planned_at |
| `lines` | 是 | array<DirectReceiptLineIn> | 最少项 1 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `party_name` | 否 | string / null | 最长 160 |  |
| `attachment_url` | 否 | string / null | 最长 500 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.update_direct_receipt

调用：`inventory_drafts endpoint=update_direct_receipt`。权限：`inventory.purchase` + `products.cost_price.view`。

作用：创建/修改业务草稿；实际过账另行执行。

`PUT /api/admin/inventory/direct-receipts/{operation_id}` — Update Direct Receipt Doc

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`DirectReceiptIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 否 | integer / null |  |  |
| `received_on` | 是 | string | 最短 1；最长 32 | 到货日期，写入 planned_at |
| `lines` | 是 | array<DirectReceiptLineIn> | 最少项 1 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `party_name` | 否 | string / null | 最长 160 |  |
| `attachment_url` | 否 | string / null | 最长 500 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.create_stocktake

调用：`inventory_drafts endpoint=create_stocktake`。权限：`inventory.operate`。

作用：创建/修改业务草稿；实际过账另行执行。

`POST /api/admin/inventory/stocktakes` — Create Stocktake Document

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`StocktakeDocumentIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `remark` | 否 | string / null | 最长 255 |  |
| `lines` | 是 | array<StocktakeLineIn> | 最少项 1 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.update_stocktake

调用：`inventory_drafts endpoint=update_stocktake`。权限：`inventory.operate`。

作用：创建/修改业务草稿；实际过账另行执行。

`PUT /api/admin/inventory/stocktakes/{operation_id}` — Update Stocktake Document

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`StocktakeDocumentIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `remark` | 否 | string / null | 最长 255 |  |
| `lines` | 是 | array<StocktakeLineIn> | 最少项 1 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.create_transfer

调用：`inventory_drafts endpoint=create_transfer`。权限：`inventory.operate`。

作用：创建/修改业务草稿；实际过账另行执行。

`POST /api/admin/inventory/transfers` — Create Transfer Operation

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`TransferOperationIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `source_warehouse_id` | 是 | integer |  |  |
| `destination_warehouse_id` | 是 | integer |  |  |
| `lines` | 是 | array<TransferLineIn> | 最少项 1 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `remark` | 否 | string / null | 最长 255 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

此模型拒绝未定义字段。

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.update_transfer

调用：`inventory_drafts endpoint=update_transfer`。权限：`inventory.operate`。

作用：创建/修改业务草稿；实际过账另行执行。

`PUT /api/admin/inventory/transfers/{operation_id}` — Update Transfer Document

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `operation_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`TransferOperationIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `source_warehouse_id` | 是 | integer |  |  |
| `destination_warehouse_id` | 是 | integer |  |  |
| `lines` | 是 | array<TransferLineIn> | 最少项 1 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `remark` | 否 | string / null | 最长 255 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

此模型拒绝未定义字段。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_drafts.create_vendor_return

调用：`inventory_drafts endpoint=create_vendor_return`。权限：`inventory.purchase`。

作用：创建/修改业务草稿；实际过账另行执行。

`POST /api/admin/inventory/vendor-returns` — Create Vendor Return

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`VendorReturnIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `purchase_order_id` | 否 | integer / null |  |  |
| `lines` | 是 | array<InventoryMoveIn> | 最少项 1 |  |
| `reason` | 是 | string | 最短 1；最长 255 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_inventory_replenishment -->
### inventory_replenishment 补货

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["save_rule", "generate", "convert"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### inventory_replenishment.save_rule

调用：`inventory_replenishment endpoint=save_rule`。权限：`inventory.operate`。

作用：保存规则/生成建议/转采购草稿，按 endpoint 区分。

`POST /api/admin/inventory/replenishment/rules` — Save Reorder Rule

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`ReorderRuleIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `warehouse_id` | 是 | integer |  |  |
| `supplier_id` | 否 | integer / null |  |  |
| `min_qty` | 是 | number / string | 最小 0.0 |  |
| `target_qty` | 是 | number / string | 最小 0.0 |  |
| `safety_qty` | 否 | number / string | 默认 0；最小 0.0 |  |
| `min_order_qty` | 否 | number / string | 默认 1；大于 0.0 |  |
| `order_multiple` | 否 | number / string | 默认 1；大于 0.0 |  |
| `is_enabled` | 否 | boolean | 默认 true |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_replenishment.generate

调用：`inventory_replenishment endpoint=generate`。权限：`inventory.operate`。

作用：保存规则/生成建议/转采购草稿，按 endpoint 区分。

`POST /api/admin/inventory/replenishment/generate` — Run Replenishment

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_replenishment.convert

调用：`inventory_replenishment endpoint=convert`。权限：`inventory.operate`。

作用：保存规则/生成建议/转采购草稿，按 endpoint 区分。

`POST /api/admin/inventory/replenishment/convert` — Convert Replenishment

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`SuggestionConvertIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `suggestion_ids` | 是 | array<integer> | 最少项 1 |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。
<!-- /mcp-topic -->

<!-- mcp-topic: reference_inventory_master_data -->
### inventory_master_data 进销存基础资料

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `endpoint` | 是 | string | 允许值 ["create_supplier", "update_supplier", "create_supplier_product", "update_supplier_product", "save_receipt_party_mapping", "create_location", "update_location", "create_putaway_rule", "update_putaway_rule", "create_warehouse"] |  |
| `path_params` | 否 | object / null | 默认 null |  |
| `params` | 否 | object / null | 默认 null |  |
| `body` | 否 | object / null | 默认 null |  |

#### inventory_master_data.create_supplier

调用：`inventory_master_data endpoint=create_supplier`。权限：`inventory.purchase`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/inventory/suppliers` — Create Supplier

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`SupplierIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `code` | 是 | string | 最长 40 |  |
| `name` | 是 | string | 最长 160 |  |
| `currency` | 否 | string | 默认 "NZD"；最长 8 |  |
| `contact` | 否 | string / null | 最长 120 |  |
| `email` | 否 | string / null | 最长 160 |  |
| `phone` | 否 | string / null | 最长 60 |  |
| `tax_id` | 否 | string / null | 最长 80 |  |
| `contacts` | 否 | array<object> |  |  |
| `addresses` | 否 | array<object> |  |  |
| `attachment_urls` | 否 | array<string> |  |  |
| `delivery_notes` | 否 | string / null |  |  |
| `payment_notes` | 否 | string / null |  |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_master_data.update_supplier

调用：`inventory_master_data endpoint=update_supplier`。权限：`inventory.purchase`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/inventory/suppliers/{supplier_id}` — Update Supplier

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `supplier_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`SupplierUpdateIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `code` | 是 | string | 最长 40 |  |
| `name` | 是 | string | 最长 160 |  |
| `currency` | 否 | string | 默认 "NZD"；最长 8 |  |
| `contact` | 否 | string / null | 最长 120 |  |
| `email` | 否 | string / null | 最长 160 |  |
| `phone` | 否 | string / null | 最长 60 |  |
| `tax_id` | 否 | string / null | 最长 80 |  |
| `contacts` | 否 | array<object> |  |  |
| `addresses` | 否 | array<object> |  |  |
| `attachment_urls` | 否 | array<string> |  |  |
| `delivery_notes` | 否 | string / null |  |  |
| `payment_notes` | 否 | string / null |  |  |
| `is_active` | 是 | boolean |  |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_master_data.create_supplier_product

调用：`inventory_master_data endpoint=create_supplier_product`。权限：`inventory.purchase` + `products.cost_price.view`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/inventory/supplier-products` — Create Supplier Product

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`SupplierProductIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `supplier_id` | 是 | integer |  |  |
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `supplier_sku` | 否 | string / null | 最长 120 |  |
| `purchase_uom` | 否 | string | 默认 "unit"；最长 40 |  |
| `uom_factor` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `unit_price` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `currency` | 否 | string | 默认 "NZD"；最长 8 |  |
| `min_order_qty` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `order_multiple` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `lead_time_days` | 否 | integer | 默认 0；最小 0.0；最大 3650.0 |  |
| `priority` | 否 | integer | 默认 100；最小 0.0；最大 10000.0 |  |
| `valid_from` | 否 | string / null |  |  |
| `valid_to` | 否 | string / null |  |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_master_data.update_supplier_product

调用：`inventory_master_data endpoint=update_supplier_product`。权限：`inventory.purchase` + `products.cost_price.view`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/inventory/supplier-products/{catalog_id}` — Update Supplier Product

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `catalog_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`SupplierProductIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `supplier_id` | 是 | integer |  |  |
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `supplier_sku` | 否 | string / null | 最长 120 |  |
| `purchase_uom` | 否 | string | 默认 "unit"；最长 40 |  |
| `uom_factor` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `unit_price` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `currency` | 否 | string | 默认 "NZD"；最长 8 |  |
| `min_order_qty` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `order_multiple` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `lead_time_days` | 否 | integer | 默认 0；最小 0.0；最大 3650.0 |  |
| `priority` | 否 | integer | 默认 100；最小 0.0；最大 10000.0 |  |
| `valid_from` | 否 | string / null |  |  |
| `valid_to` | 否 | string / null |  |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_master_data.save_receipt_party_mapping

调用：`inventory_master_data endpoint=save_receipt_party_mapping`。权限：`inventory.purchase`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/inventory/receipt-party-mappings` — Save Receipt Party Mapping

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`ReceiptPartyMappingIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `source_name` | 是 | string | 最短 1；最长 160 |  |
| `display_name` | 否 | string / null | 最长 160 |  |
| `supplier_id` | 否 | integer / null |  |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_master_data.create_location

调用：`inventory_master_data endpoint=create_location`。权限：`inventory.manage`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/inventory/locations` — Create Location

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`LocationIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `parent_id` | 否 | integer / null |  |  |
| `code` | 是 | string | 最短 1；最长 40 |  |
| `name` | 是 | string | 最短 1；最长 120 |  |
| `location_type` | 否 | string | 默认 "internal"；正则 "^(internal\|input\|output\|transit\|qc\|scrap)$" |  |
| `barcode` | 否 | string / null | 最长 80 |  |
| `is_default` | 否 | boolean | 默认 false |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_master_data.update_location

调用：`inventory_master_data endpoint=update_location`。权限：`inventory.manage`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/inventory/locations/{location_id}` — Update Location

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `location_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`LocationUpdateIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `parent_id` | 否 | integer / null |  |  |
| `code` | 是 | string | 最短 1；最长 40 |  |
| `name` | 是 | string | 最短 1；最长 120 |  |
| `location_type` | 否 | string | 默认 "internal"；正则 "^(internal\|input\|output\|transit\|qc\|scrap)$" |  |
| `barcode` | 否 | string / null | 最长 80 |  |
| `is_default` | 否 | boolean | 默认 false |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_master_data.create_putaway_rule

调用：`inventory_master_data endpoint=create_putaway_rule`。权限：`inventory.manage`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/inventory/putaway-rules` — Create Putaway Rule

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`PutawayRuleIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `product_id` | 否 | integer / null |  |  |
| `category_id` | 否 | integer / null |  |  |
| `destination_location_id` | 是 | integer |  |  |
| `priority` | 否 | integer | 默认 100；最小 0.0；最大 10000.0 |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 201 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_master_data.update_putaway_rule

调用：`inventory_master_data endpoint=update_putaway_rule`。权限：`inventory.manage`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`PUT /api/admin/inventory/putaway-rules/{rule_id}` — Update Putaway Rule

| 后端参数 | 位置 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|---|
| `rule_id` | path_params | 是 | integer |  |  |

请求体 `application/json`：`PutawayRuleIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `product_id` | 否 | integer / null |  |  |
| `category_id` | 否 | integer / null |  |  |
| `destination_location_id` | 是 | integer |  |  |
| `priority` | 否 | integer | 默认 100；最小 0.0；最大 10000.0 |  |
| `is_active` | 否 | boolean | 默认 true |  |

成功响应 200 `application/json` 未定义字段模型：先检查实际返回再解析，不猜测分页或状态。

#### inventory_master_data.create_warehouse

调用：`inventory_master_data endpoint=create_warehouse`。权限：`inventory.manage`。

作用：立即保存资料/设置/商品数据，可能影响后续业务。

`POST /api/admin/inventory/warehouses` — Create Warehouse

OpenAPI 未声明独立路径/查询参数。不要据此给工具添加未知参数。

请求体 `application/json`：`WarehouseIn`。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `code` | 是 | string | 最长 40 |  |
| `name` | 是 | string | 最长 120 |  |

成功响应 201 `application/json`：`WarehouseOut`；模型字段见本附录末尾；AI 可按同名 schema_ 主题读取。
<!-- /mcp-topic -->

## 请求与响应模型字段字典

<!-- mcp-topic: schema_AdjustmentDocumentIn -->
### AdjustmentDocumentIn

库存纠正单：原因整单统一，明细不带行原因。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `reason` | 是 | string | 最短 1；最长 255 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `lines` | 是 | array<AdjustmentDocumentLineIn> | 最少项 1 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_AdjustmentDocumentLineIn -->
### AdjustmentDocumentLineIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `warehouse_id` | 是 | integer |  |  |
| `location_id` | 否 | integer / null |  |  |
| `batch_id` | 否 | integer / null |  | 启用批次管理时必须指定批次 |
| `qty_delta` | 是 | number / string |  | 正数增、负数减，不可为 0 |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_AlertSetBody -->
### AlertSetBody



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `threshold` | 是 | integer |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_AttachmentTypeOut -->
### AttachmentTypeOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `code` | 是 | string | 最长 80 |  |
| `label` | 是 | string | 最长 160 |  |
| `description` | 否 | string / null | 最长 500 |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `id` | 是 | integer |  |  |
| `tenant_id` | 是 | integer |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_BalanceOut -->
### BalanceOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `product_name` | 是 | string |  |  |
| `variant_id` | 是 | integer |  |  |
| `sale_price` | 否 | string / null |  |  |
| `warehouse_id` | 是 | integer |  |  |
| `location_id` | 是 | integer |  |  |
| `batch_id` | 是 | integer |  |  |
| `stock_state` | 是 | string |  |  |
| `qty` | 是 | string |  |  |
| `batch_no` | 否 | string / null |  |  |
| `expires_on` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_Body_ai_parse_direct_receipt_api_admin_inventory_direct_receipts_ai_parse_post -->
### Body_ai_parse_direct_receipt_api_admin_inventory_direct_receipts_ai_parse_post



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `file` | 是 | string (binary) |  |  |
| `image_url` | 否 | string | 默认 "" |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_Body_get_details_api_admin_adv_stats_report_details_get -->
### Body_get_details_api_admin_adv_stats_report_details_get



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `statuses` | 否 | array<string> / null |  |  |
| `member_level_ids` | 否 | array<integer> / null |  |  |
| `payment_gateways` | 否 | array<string> / null |  |  |
| `shipping_method_ids` | 否 | array<integer> / null |  |  |
| `currencies` | 否 | array<string> / null |  |  |
| `product_ids` | 否 | array<integer> / null |  |  |
| `category_ids` | 否 | array<integer> / null |  |  |
| `brand_ids` | 否 | array<integer> / null |  |  |
| `discount_ids` | 否 | array<integer> / null |  |  |
| `pos_store_ids` | 否 | array<integer> / null |  |  |
| `pos_lane_ids` | 否 | array<string> / null |  |  |
| `pos_operator_ids` | 否 | array<integer> / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_Body_get_report_api_admin_adv_stats_report_get -->
### Body_get_report_api_admin_adv_stats_report_get



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `statuses` | 否 | array<string> / null |  |  |
| `member_level_ids` | 否 | array<integer> / null |  |  |
| `payment_gateways` | 否 | array<string> / null |  |  |
| `shipping_method_ids` | 否 | array<integer> / null |  |  |
| `currencies` | 否 | array<string> / null |  |  |
| `product_ids` | 否 | array<integer> / null |  |  |
| `category_ids` | 否 | array<integer> / null |  |  |
| `brand_ids` | 否 | array<integer> / null |  |  |
| `discount_ids` | 否 | array<integer> / null |  |  |
| `pos_store_ids` | 否 | array<integer> / null |  |  |
| `pos_lane_ids` | 否 | array<string> / null |  |  |
| `pos_operator_ids` | 否 | array<integer> / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_Body_upload_image_api_upload_post -->
### Body_upload_image_api_upload_post



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `file` | 是 | string (binary) |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_BrandCreate -->
### BrandCreate



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string | 最长 120 |  |
| `slug` | 是 | string | 最长 180 |  |
| `english_name` | 否 | string / null |  |  |
| `logo_url` | 否 | string / null |  |  |
| `description` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `website_url` | 否 | string / null |  |  |
| `country` | 否 | string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_featured` | 否 | boolean | 默认 false |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_BrandOut -->
### BrandOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string | 最长 120 |  |
| `slug` | 是 | string | 最长 180 |  |
| `english_name` | 否 | string / null |  |  |
| `logo_url` | 否 | string / null |  |  |
| `description` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `website_url` | 否 | string / null |  |  |
| `country` | 否 | string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_featured` | 否 | boolean | 默认 false |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `id` | 是 | integer |  |  |
| `tenant_id` | 是 | integer |  |  |
| `created_at` | 否 | string (date-time) / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_BrandUpdate -->
### BrandUpdate



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 否 | string / null |  |  |
| `slug` | 否 | string / null |  |  |
| `english_name` | 否 | string / null |  |  |
| `logo_url` | 否 | string / null |  |  |
| `description` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `website_url` | 否 | string / null |  |  |
| `country` | 否 | string / null |  |  |
| `sort_order` | 否 | integer / null |  |  |
| `is_featured` | 否 | boolean / null |  |  |
| `is_active` | 否 | boolean / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_CategoryCreate -->
### CategoryCreate



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string |  |  |
| `slug` | 是 | string |  |  |
| `parent_id` | 否 | integer / null |  |  |
| `description` | 否 | string / null |  |  |
| `image_url` | 否 | string / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `seo_keywords` | 否 | string / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `is_nav_visible` | 否 | boolean | 默认 true |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_CategoryOut -->
### CategoryOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `parent_id` | 是 | integer / null |  |  |
| `name` | 是 | string |  |  |
| `slug` | 是 | string |  |  |
| `description` | 是 | string / null |  |  |
| `image_url` | 是 | string / null |  |  |
| `meta_title` | 是 | string / null |  |  |
| `meta_description` | 是 | string / null |  |  |
| `seo_keywords` | 是 | string / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `is_nav_visible` | 否 | boolean | 默认 true |  |
| `created_at` | 否 | string (date-time) / null |  |  |
| `updated_at` | 否 | string (date-time) / null |  |  |
| `product_count` | 否 | integer | 默认 0 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_CategorySalesDetailItem -->
### CategorySalesDetailItem



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `category_id` | 是 | integer / null |  |  |
| `parent_id` | 是 | integer / null |  |  |
| `category` | 是 | string |  |  |
| `category_path` | 是 | string |  |  |
| `revenue` | 否 | string | 默认 "0" |  |
| `quantity` | 否 | string | 默认 "0" |  |
| `orders_count` | 否 | integer | 默认 0 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_CategorySalesDetailPage -->
### CategorySalesDetailPage



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `items` | 是 | array<CategorySalesDetailItem> |  |  |
| `summary` | 是 | CategorySalesDetailSummary |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_CategorySalesDetailSummary -->
### CategorySalesDetailSummary



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `revenue` | 否 | string | 默认 "0" |  |
| `quantity` | 否 | string | 默认 "0" |  |
| `orders_count` | 否 | integer | 默认 0 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_CategorySalesItem -->
### CategorySalesItem



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `category` | 是 | string |  |  |
| `revenue` | 是 | string |  |  |
| `orders_count` | 是 | integer |  |  |
| `percentage` | 是 | number |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_CategoryUpdate -->
### CategoryUpdate



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 否 | string / null |  |  |
| `slug` | 否 | string / null |  |  |
| `parent_id` | 否 | integer / null |  |  |
| `description` | 否 | string / null |  |  |
| `image_url` | 否 | string / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `seo_keywords` | 否 | string / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `sort_order` | 否 | integer / null |  |  |
| `is_active` | 否 | boolean / null |  |  |
| `is_nav_visible` | 否 | boolean / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_CouponStatsItem -->
### CouponStatsItem



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `name` | 是 | string |  |  |
| `code` | 是 | string / null |  |  |
| `type` | 是 | string |  |  |
| `value` | 是 | string |  |  |
| `usage_limit` | 是 | integer / null |  |  |
| `used_count` | 是 | integer |  |  |
| `usage_rate` | 是 | number |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_CustomerGrowthItem -->
### CustomerGrowthItem



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `date` | 是 | string |  |  |
| `new_count` | 是 | integer |  |  |
| `cumulative` | 是 | integer |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_DashboardStats -->
### DashboardStats



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `revenue_today` | 否 | string | 默认 "0" |  |
| `revenue_month` | 否 | string | 默认 "0" |  |
| `orders_today` | 否 | integer | 默认 0 |  |
| `orders_pending` | 否 | integer | 默认 0 |  |
| `customers_total` | 否 | integer | 默认 0 |  |
| `products_active` | 否 | integer | 默认 0 |  |
| `products_expiring` | 否 | integer | 默认 0 |  |
| `products_expired` | 否 | integer | 默认 0 |  |
| `revenue_today_change` | 否 | number | 默认 0.0 |  |
| `revenue_month_change` | 否 | number | 默认 0.0 |  |
| `orders_today_change` | 否 | number | 默认 0.0 |  |
| `customers_new_today` | 否 | integer | 默认 0 |  |
| `refunds_pending` | 否 | integer | 默认 0 |  |
| `refunds_month_amount` | 否 | string | 默认 "0" |  |
| `contact_form_unread` | 否 | integer | 默认 0 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_DirectReceiptIn -->
### DirectReceiptIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 否 | integer / null |  |  |
| `received_on` | 是 | string | 最短 1；最长 32 | 到货日期，写入 planned_at |
| `lines` | 是 | array<DirectReceiptLineIn> | 最少项 1 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `party_name` | 否 | string / null | 最长 160 |  |
| `attachment_url` | 否 | string / null | 最长 500 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_DirectReceiptLineIn -->
### DirectReceiptLineIn

直收到货行。数量与成本都按库存基本单位、本位币，不经采购包装与汇率换算。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `done_qty` | 是 | number / string | 大于 0.0 |  |
| `unit_cost` | 是 | number / string | 最小 0.0 |  |
| `destination_location_id` | 否 | integer / null |  |  |
| `batch_no` | 否 | string / null | 最长 80 |  |
| `produced_on` | 否 | string / null |  |  |
| `expires_on` | 否 | string / null |  |  |
| `serial_numbers` | 否 | array<string> |  |  |

此模型拒绝未定义字段。
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ExternalChannelMappingOut -->
### ExternalChannelMappingOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `channel` | 否 | string | 默认 "hungrypanda"；最长 40 |  |
| `external_shop_id` | 是 | string | 最长 64 |  |
| `warehouse_id` | 是 | integer |  |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `id` | 是 | integer |  |  |
| `shop_label` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ImageCreate -->
### ImageCreate



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `url` | 是 | string | 最长 500 |  |
| `alt_text` | 否 | string / null | 最长 200 |  |
| `sort_order` | 否 | integer | 默认 0；最小 0.0 |  |
| `is_primary` | 否 | boolean | 默认 false |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ImageOut -->
### ImageOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `product_id` | 是 | integer |  |  |
| `url` | 是 | string |  |  |
| `webp_url` | 否 | string / null |  |  |
| `alt_text` | 否 | string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_primary` | 否 | boolean | 默认 false |  |
| `created_at` | 否 | string (date-time) / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ImageUpdate -->
### ImageUpdate



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `alt_text` | 否 | string / null | 最长 200 |  |
| `sort_order` | 否 | integer / null | 最小 0.0 |  |
| `is_primary` | 否 | boolean / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_InventoryAlertItem -->
### InventoryAlertItem



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `name` | 是 | string |  |  |
| `sku` | 是 | string |  |  |
| `stock_qty` | 是 | string |  |  |
| `low_stock_threshold` | 是 | integer |  |  |
| `status` | 是 | string |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_InventoryMoveIn -->
### InventoryMoveIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `done_qty` | 是 | number / string | 大于 0.0 |  |
| `purchase_order_line_id` | 否 | integer / null |  |  |
| `source_location_id` | 否 | integer / null |  |  |
| `destination_location_id` | 否 | integer / null |  |  |
| `batch_id` | 否 | integer / null |  |  |
| `batch_no` | 否 | string / null | 最长 80 |  |
| `produced_on` | 否 | string / null |  |  |
| `expires_on` | 否 | string / null |  |  |
| `serial_numbers` | 否 | array<string> |  |  |
| `unit_cost` | 否 | number / string / null | 最小 0.0 |  |

此模型拒绝未定义字段。
<!-- /mcp-topic -->

<!-- mcp-topic: schema_LocationIn -->
### LocationIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `parent_id` | 否 | integer / null |  |  |
| `code` | 是 | string | 最短 1；最长 40 |  |
| `name` | 是 | string | 最短 1；最长 120 |  |
| `location_type` | 否 | string | 默认 "internal"；正则 "^(internal\|input\|output\|transit\|qc\|scrap)$" |  |
| `barcode` | 否 | string / null | 最长 80 |  |
| `is_default` | 否 | boolean | 默认 false |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_LocationUpdateIn -->
### LocationUpdateIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `parent_id` | 否 | integer / null |  |  |
| `code` | 是 | string | 最短 1；最长 40 |  |
| `name` | 是 | string | 最短 1；最长 120 |  |
| `location_type` | 否 | string | 默认 "internal"；正则 "^(internal\|input\|output\|transit\|qc\|scrap)$" |  |
| `barcode` | 否 | string / null | 最长 80 |  |
| `is_default` | 否 | boolean | 默认 false |  |
| `is_active` | 否 | boolean | 默认 true |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_MediaRoleOut -->
### MediaRoleOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `code` | 是 | string | 最长 80 |  |
| `label` | 是 | string | 最长 160 |  |
| `description` | 否 | string / null | 最长 500 |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `id` | 是 | integer |  |  |
| `tenant_id` | 是 | integer |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_MemberLevelOut -->
### MemberLevelOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string | 最长 80 |  |
| `name_en` | 否 | string / null | 最长 80 |  |
| `code` | 是 | string | 最长 50 |  |
| `rank` | 否 | integer | 默认 0 |  |
| `discount_rate` | 否 | string | 默认 "1.0000" |  |
| `points_multiplier` | 否 | string | 默认 "1.0000" |  |
| `free_shipping_threshold` | 否 | string / null |  |  |
| `upgrade_by` | 否 | string | 默认 "spend"；允许值 ["spend", "points", "orders"] |  |
| `upgrade_spend` | 否 | string / null |  |  |
| `upgrade_points` | 否 | integer / null | 最小 0.0 |  |
| `upgrade_orders` | 否 | integer / null | 最小 0.0 |  |
| `validity_days` | 否 | integer / null |  |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `description` | 否 | string / null |  |  |
| `id` | 是 | integer |  |  |
| `tenant_id` | 是 | integer |  |  |
| `purpose` | 否 | string | 默认 "customer" |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_OrderStatusItem -->
### OrderStatusItem



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string |  |  |
| `value` | 是 | integer |  |  |
| `color` | 是 | string |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_POLineIn -->
### POLineIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `qty` | 是 | number / string | 大于 0.0 |  |
| `unit_cost` | 是 | number / string | 最小 0.0 |  |
| `expected_date` | 否 | string / null |  |  |
| `purchase_uom` | 否 | string | 默认 "unit"；最长 40 |  |
| `uom_factor` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `batch_no` | 否 | string / null | 最长 80 |  |
| `expires_on` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PageResult_BrandOut_ -->
### PageResult_BrandOut_



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `items` | 是 | array<BrandOut> |  |  |
| `total` | 是 | integer |  |  |
| `page` | 是 | integer |  |  |
| `page_size` | 是 | integer |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PageResult_MemberLevelOut_ -->
### PageResult_MemberLevelOut_



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `items` | 是 | array<MemberLevelOut> |  |  |
| `total` | 是 | integer |  |  |
| `page` | 是 | integer |  |  |
| `page_size` | 是 | integer |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PageResult_ProductListOut_ -->
### PageResult_ProductListOut_



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `items` | 是 | array<ProductListOut> |  |  |
| `total` | 是 | integer |  |  |
| `page` | 是 | integer |  |  |
| `page_size` | 是 | integer |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PresetOut -->
### PresetOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `title` | 是 | string |  |  |
| `query` | 是 | object |  |  |
| `created_at` | 是 | string (date-time) |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PriceGroupAssign -->
### PriceGroupAssign

批量设置商品的价格分组。price_group 传空串 = 清空。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_ids` | 否 | array<integer> |  |  |
| `price_group` | 否 | string / null | 最长 64 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PriceRuleOverviewItem -->
### PriceRuleOverviewItem

价格规则总览的一行 = 一条规则 + 所属商品的展示信息。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `rule` | 是 | ProductPriceRuleOut |  |  |
| `product_id` | 是 | integer |  |  |
| `product_name` | 是 | string |  |  |
| `sku` | 否 | string / null |  |  |
| `price_group` | 否 | string / null |  |  |
| `base_price` | 否 | string | 默认 "0" |  |
| `variant_sku` | 否 | string / null |  |  |
| `member_level_name` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PriceRuleOverviewResponse -->
### PriceRuleOverviewResponse



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `items` | 否 | array<PriceRuleOverviewItem> |  |  |
| `total` | 否 | integer | 默认 0 |  |
| `groups` | 否 | array<string> |  | 本租户已用过的分组名，供下拉建议 |
| `counts` | 否 | object<string,integer> |  | 各状态条数：active/upcoming/expiring/expired |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductAttachmentIn -->
### ProductAttachmentIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `type_id` | 是 | integer |  |  |
| `title` | 否 | string / null | 最长 200 |  |
| `file_url` | 是 | string | 最长 500 |  |
| `mime_type` | 否 | string / null | 最长 120 |  |
| `file_size` | 否 | integer / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductAttachmentOut -->
### ProductAttachmentOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `type_id` | 是 | integer |  |  |
| `title` | 否 | string / null | 最长 200 |  |
| `file_url` | 是 | string | 最长 500 |  |
| `mime_type` | 否 | string / null | 最长 120 |  |
| `file_size` | 否 | integer / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `id` | 是 | integer |  |  |
| `tenant_id` | 是 | integer |  |  |
| `product_id` | 是 | integer |  |  |
| `type_code` | 否 | string / null |  |  |
| `type_label` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductCreate -->
### ProductCreate



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string | 最长 200 |  |
| `sku` | 是 | string | 最长 64 |  |
| `barcode` | 否 | string / null | 最长 120 | 条码（无规格商品用） |
| `barcodes` | 否 | array<string> |  | 商品级历史/别名条码 |
| `categories` | 否 | array<string / integer> |  |  |
| `brand_id` | 否 | integer / null |  |  |
| `description` | 否 | string / null |  |  |
| `base_price` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `market_price` | 否 | number / string / null |  |  |
| `member_price` | 否 | number / string / null |  |  |
| `cost_price` | 否 | number / string / null |  |  |
| `price_group` | 否 | string / null | 最长 64 | 价格规则分组（仅后台管理用） |
| `stock_qty` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `low_stock_threshold` | 否 | integer | 默认 5；最小 0.0 |  |
| `allow_oversell` | 否 | boolean | 默认 false |  |
| `status` | 否 | string | 默认 "draft" |  |
| `weight_grams` | 否 | integer | 默认 0；最小 0.0 |  |
| `length` | 否 | number / string / null |  |  |
| `width` | 否 | number / string / null |  |  |
| `height` | 否 | number / string / null |  |  |
| `slug` | 否 | string / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `seo_keywords` | 否 | string / null |  |  |
| `ai_description` | 否 | string / null |  |  |
| `shelf_life` | 否 | string / null |  |  |
| `shelf_life_en` | 否 | string / null |  |  |
| `expiry_date` | 否 | string (date) / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `ai_description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `tax_class_id` | 否 | integer / null |  |  |
| `stock_status_id` | 否 | integer / null |  |  |
| `hungrypanda_enabled` | 否 | boolean | 默认 false |  |
| `video_url` | 否 | string / null | 最长 500 |  |
| `cover_url` | 否 | string / null |  |  |
| `variants` | 否 | array<ProductVariantIn> |  |  |
| `tier_prices` | 否 | array<TierPriceIn> |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductListOut -->
### ProductListOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `name` | 是 | string |  |  |
| `name_en` | 否 | string / null |  |  |
| `sku` | 是 | string |  |  |
| `barcode` | 否 | string / null |  |  |
| `categories` | 否 | array<string> | 默认 [] |  |
| `categories_en` | 否 | array<string / null> | 默认 [] |  |
| `category_ids` | 否 | array<integer> | 默认 [] |  |
| `brand_id` | 否 | integer / null |  |  |
| `brand` | 否 | string / null |  |  |
| `brand_slug` | 否 | string / null |  |  |
| `base_price` | 否 | string / null |  |  |
| `market_price` | 否 | string / null |  |  |
| `member_price` | 否 | string / null |  |  |
| `stock_qty` | 是 | string |  |  |
| `reserved_qty` | 否 | string | 默认 "0" |  |
| `channel_available_qty` | 否 | string / null |  |  |
| `channel_can_purchase` | 否 | boolean / null |  |  |
| `low_stock_threshold` | 否 | integer | 默认 0 |  |
| `allow_oversell` | 否 | boolean | 默认 false |  |
| `status` | 是 | string |  |  |
| `slug` | 否 | string / null |  |  |
| `cover_url` | 否 | string / null |  |  |
| `sales_count` | 否 | integer | 默认 0 |  |
| `stock_status` | 否 | StockStatusBrief / null |  |  |
| `created_at` | 否 | string (date-time) / null |  |  |
| `tier_prices` | 否 | array<TierPriceOut> |  |  |
| `expiry_date` | 否 | string (date) / null |  |  |
| `expiry_status` | 否 | string | 默认 "none" |  |
| `expiry_batch_managed` | 否 | boolean | 默认 false |  |
| `sold_by_weight` | 否 | boolean | 默认 false |  |
| `hungrypanda_enabled` | 否 | boolean | 默认 false |  |
| `display_price` | 否 | string / null |  |  |
| `original_price` | 否 | string / null |  |  |
| `is_promotion` | 否 | boolean | 默认 false |  |
| `active_rule_summary` | 否 | object / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductMediaRoleItemIn -->
### ProductMediaRoleItemIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `role_id` | 是 | integer |  |  |
| `image_url` | 是 | string | 最长 500 |  |
| `alt_text` | 否 | string / null | 最长 200 |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductMediaRoleItemOut -->
### ProductMediaRoleItemOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `role_id` | 是 | integer |  |  |
| `image_url` | 是 | string | 最长 500 |  |
| `alt_text` | 否 | string / null | 最长 200 |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `id` | 是 | integer |  |  |
| `tenant_id` | 是 | integer |  |  |
| `product_id` | 是 | integer |  |  |
| `role_code` | 否 | string / null |  |  |
| `role_label` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductOut -->
### ProductOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string | 最长 200 |  |
| `sku` | 是 | string | 最长 64 |  |
| `barcode` | 否 | string / null | 最长 120 | 条码（无规格商品用） |
| `barcodes` | 否 | array<string> |  | 商品级历史/别名条码 |
| `categories` | 否 | array<string / integer> |  |  |
| `brand_id` | 否 | integer / null |  |  |
| `description` | 否 | string / null |  |  |
| `base_price` | 否 | string / null |  |  |
| `market_price` | 否 | string / null |  |  |
| `member_price` | 否 | string / null |  |  |
| `cost_price` | 否 | string / null |  |  |
| `price_group` | 否 | string / null | 最长 64 | 价格规则分组（仅后台管理用） |
| `stock_qty` | 否 | string | 默认 "0" |  |
| `low_stock_threshold` | 否 | integer | 默认 5；最小 0.0 |  |
| `allow_oversell` | 否 | boolean | 默认 false |  |
| `status` | 否 | string | 默认 "draft" |  |
| `weight_grams` | 否 | integer | 默认 0；最小 0.0 |  |
| `length` | 否 | string / null |  |  |
| `width` | 否 | string / null |  |  |
| `height` | 否 | string / null |  |  |
| `slug` | 否 | string / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `seo_keywords` | 否 | string / null |  |  |
| `ai_description` | 否 | string / null |  |  |
| `shelf_life` | 否 | string / null |  |  |
| `shelf_life_en` | 否 | string / null |  |  |
| `expiry_date` | 否 | string (date) / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `ai_description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `tax_class_id` | 否 | integer / null |  |  |
| `stock_status_id` | 否 | integer / null |  |  |
| `hungrypanda_enabled` | 否 | boolean | 默认 false |  |
| `video_url` | 否 | string / null | 最长 500 |  |
| `channel_available_qty` | 否 | string / null |  |  |
| `channel_can_purchase` | 否 | boolean / null |  |  |
| `channel_oversell_allowed` | 否 | boolean / null |  |  |
| `id` | 是 | integer |  |  |
| `tenant_id` | 是 | integer |  |  |
| `category_ids` | 否 | array<integer> | 默认 [] |  |
| `category_items` | 否 | array<object> | 默认 [] |  |
| `brand` | 否 | string / null |  |  |
| `brand_en` | 否 | string / null |  |  |
| `brand_slug` | 否 | string / null |  |  |
| `cover_url` | 否 | string / null |  |  |
| `images` | 否 | array<string> | 默认 [] |  |
| `variants` | 否 | array<ProductVariantOut> |  |  |
| `tier_prices` | 否 | array<TierPriceOut> |  |  |
| `attachments` | 否 | array<object> |  |  |
| `media_roles` | 否 | object |  |  |
| `sales_count` | 否 | integer | 默认 0 |  |
| `stock_status` | 否 | StockStatusBrief / null |  |  |
| `created_at` | 否 | string (date-time) / null |  |  |
| `expiry_status` | 否 | string | 默认 "none" |  |
| `expiry_batch_managed` | 否 | boolean | 默认 false |  |
| `sold_by_weight` | 否 | boolean | 默认 false |  |
| `display_price` | 否 | string / null |  |  |
| `original_price` | 否 | string / null |  |  |
| `is_promotion` | 否 | boolean | 默认 false |  |
| `active_rule_summary` | 否 | object / null |  |  |
| `inventory_cost_managed` | 否 | boolean | 默认 false |  |
| `inventory_current_unit_cost` | 否 | string / null |  |  |
| `inventory_last_purchase_unit_cost` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductPriceRuleIn -->
### ProductPriceRuleIn

单条规则的入参。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 否 | integer / null |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `member_level_id` | 否 | integer / null |  |  |
| `channel_scope` | 否 | string | 默认 "both"；允许值 ["store", "pos", "both"] |  |
| `min_quantity` | 否 | integer | 默认 1；最小 1.0 |  |
| `price_type` | 否 | string | 默认 "fixed"；允许值 ["fixed", "amount_off", "percent_off"] |  |
| `price_value` | 否 | number / string | 默认 "0" |  |
| `priority` | 否 | integer | 默认 100；最小 0.0 |  |
| `is_promotion` | 否 | boolean | 默认 false |  |
| `starts_at` | 否 | string (date-time) / null |  |  |
| `ends_at` | 否 | string (date-time) / null |  |  |
| `is_active` | 否 | boolean | 默认 true |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductPriceRuleOut -->
### ProductPriceRuleOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `member_level_id` | 否 | integer / null |  |  |
| `channel_scope` | 否 | string | 默认 "both"；允许值 ["store", "pos", "both"] |  |
| `min_quantity` | 否 | integer | 默认 1；最小 1.0 |  |
| `price_type` | 否 | string | 默认 "fixed"；允许值 ["fixed", "amount_off", "percent_off"] |  |
| `price_value` | 否 | string | 默认 "0" |  |
| `priority` | 否 | integer | 默认 100；最小 0.0 |  |
| `is_promotion` | 否 | boolean | 默认 false |  |
| `starts_at` | 否 | string (date-time) / null |  |  |
| `ends_at` | 否 | string (date-time) / null |  |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `tenant_id` | 是 | integer |  |  |
| `product_id` | 是 | integer |  |  |
| `created_at` | 是 | string (date-time) |  |  |
| `updated_at` | 是 | string (date-time) |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductPriceRulesReplace -->
### ProductPriceRulesReplace

原子替换单个商品的整组规则。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `price_rules_version` | 否 | integer | 默认 0；最小 0.0 | 客户端持有的版本号，乐观锁 |
| `rules` | 否 | array<ProductPriceRuleIn> |  |  |
| `price_group` | 否 | string / null | 最长 64 | 价格规则分组（仅后台管理用） |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductPriceRulesResponse -->
### ProductPriceRulesResponse

GET /api/products/{product_id}/price-rules 的响应。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `price_rules_version` | 是 | integer |  |  |
| `price_group` | 否 | string / null |  |  |
| `rules` | 否 | array<ProductPriceRuleOut> |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductProfileOut -->
### ProductProfileOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `variant_id` | 否 | integer / null |  |  |
| `tracking_type` | 否 | string | 默认 "none"；正则 "^(none\|lot\|serial)$" |  |
| `qc_required` | 否 | boolean | 默认 false |  |
| `shelf_life_days` | 否 | integer / null | 最小 1.0；最大 36500.0 |  |
| `removal_strategy` | 否 | string | 默认 "fifo"；正则 "^(fifo\|fefo\|manual)$" |  |
| `product_id` | 是 | integer |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductSalesItem -->
### ProductSalesItem



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `name` | 是 | string |  |  |
| `sku` | 是 | string |  |  |
| `category` | 是 | string |  |  |
| `base_price` | 是 | string |  |  |
| `revenue` | 是 | string |  |  |
| `quantity` | 是 | string |  |  |
| `orders_count` | 是 | integer |  |  |
| `avg_unit_price` | 是 | string |  |  |
| `stock_qty` | 是 | string |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductSalesPage -->
### ProductSalesPage



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `items` | 是 | array<ProductSalesItem> |  |  |
| `total` | 是 | integer |  |  |
| `page` | 是 | integer |  |  |
| `page_size` | 是 | integer |  |  |
| `summary` | 是 | ProductSalesSummary |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductSalesSummary -->
### ProductSalesSummary

筛选结果全量汇总，不受分页影响。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `revenue` | 否 | string | 默认 "0" |  |
| `quantity` | 否 | string | 默认 "0" |  |
| `orders_count` | 否 | integer | 默认 0 |  |
| `avg_order_value` | 否 | string | 默认 "0" |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductUpdate -->
### ProductUpdate



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 否 | string / null |  |  |
| `sku` | 否 | string / null |  |  |
| `barcode` | 否 | string / null | 最长 120 | 条码（无规格商品用） |
| `barcodes` | 否 | array<string> |  | 商品级历史/别名条码 |
| `categories` | 否 | array<string / integer> |  |  |
| `brand_id` | 否 | integer / null |  |  |
| `description` | 否 | string / null |  |  |
| `base_price` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `market_price` | 否 | number / string / null |  |  |
| `member_price` | 否 | number / string / null |  |  |
| `cost_price` | 否 | number / string / null |  |  |
| `price_group` | 否 | string / null | 最长 64 | 价格规则分组（仅后台管理用） |
| `stock_qty` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `low_stock_threshold` | 否 | integer | 默认 5；最小 0.0 |  |
| `allow_oversell` | 否 | boolean | 默认 false |  |
| `status` | 否 | string | 默认 "draft" |  |
| `weight_grams` | 否 | integer | 默认 0；最小 0.0 |  |
| `length` | 否 | number / string / null |  |  |
| `width` | 否 | number / string / null |  |  |
| `height` | 否 | number / string / null |  |  |
| `slug` | 否 | string / null |  |  |
| `meta_title` | 否 | string / null |  |  |
| `meta_description` | 否 | string / null |  |  |
| `seo_keywords` | 否 | string / null |  |  |
| `ai_description` | 否 | string / null |  |  |
| `shelf_life` | 否 | string / null |  |  |
| `shelf_life_en` | 否 | string / null |  |  |
| `expiry_date` | 否 | string (date) / null |  |  |
| `name_en` | 否 | string / null |  |  |
| `description_en` | 否 | string / null |  |  |
| `ai_description_en` | 否 | string / null |  |  |
| `meta_title_en` | 否 | string / null |  |  |
| `meta_description_en` | 否 | string / null |  |  |
| `seo_keywords_en` | 否 | string / null |  |  |
| `tax_class_id` | 否 | integer / null |  |  |
| `stock_status_id` | 否 | integer / null |  |  |
| `hungrypanda_enabled` | 否 | boolean | 默认 false |  |
| `video_url` | 否 | string / null | 最长 500 |  |
| `cover_url` | 否 | string / null |  |  |
| `variants` | 否 | array<ProductVariantIn> / null |  |  |
| `tier_prices` | 否 | array<TierPriceIn> / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductVariantIn -->
### ProductVariantIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 否 | integer / null |  |  |
| `sku` | 是 | string | 最长 100 |  |
| `barcode` | 否 | string / null |  |  |
| `barcodes` | 否 | array<string> |  | 历史/别名条码（批次差异） |
| `price_modifier` | 否 | number / string / null | 默认 "0" |  |
| `independent_price` | 否 | number / string / null |  |  |
| `stock_qty` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `reserved_qty` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `image_url` | 否 | string / null |  |  |
| `weight_grams` | 否 | integer / null | 最小 0.0 |  |
| `length` | 否 | number / string / null |  |  |
| `width` | 否 | number / string / null |  |  |
| `height` | 否 | number / string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `attributes` | 否 | object |  |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `is_default` | 否 | boolean | 默认 false |  |
| `expiry_date` | 否 | string (date) / null |  |  |
| `tier_prices` | 否 | array<TierPriceIn> |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ProductVariantOut -->
### ProductVariantOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `product_id` | 是 | integer |  |  |
| `tenant_id` | 是 | integer |  |  |
| `sku` | 是 | string |  |  |
| `barcode` | 否 | string / null |  |  |
| `barcodes` | 否 | array<string> |  |  |
| `price_modifier` | 否 | string / null | 默认 "0" |  |
| `independent_price` | 否 | string / null |  |  |
| `stock_qty` | 否 | string | 默认 "0" |  |
| `channel_available_qty` | 否 | string / null |  |  |
| `reserved_qty` | 否 | string | 默认 "0" |  |
| `image_url` | 否 | string / null |  |  |
| `weight_grams` | 否 | integer / null |  |  |
| `length` | 否 | string / null |  |  |
| `width` | 否 | string / null |  |  |
| `height` | 否 | string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `attributes` | 否 | object |  |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `is_default` | 否 | boolean | 默认 false |  |
| `expiry_date` | 否 | string (date) / null |  |  |
| `expiry_status` | 否 | string | 默认 "none" |  |
| `tier_prices` | 否 | array<TierPriceOut> |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PurchaseOrderIn -->
### PurchaseOrderIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `supplier_id` | 是 | integer |  |  |
| `warehouse_id` | 否 | integer / null |  |  |
| `currency` | 否 | string | 默认 "NZD"；最长 8 |  |
| `fx_rate` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `supplier_promise_date` | 否 | string / null |  |  |
| `planned_arrival_date` | 否 | string / null |  |  |
| `lines` | 是 | array<POLineIn> | 最少项 1 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PurchaseReceiptIn -->
### PurchaseReceiptIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `purchase_order_id` | 是 | integer |  |  |
| `lines` | 是 | array<PurchaseReceiptLineIn> | 最少项 1 |  |
| `planned_at` | 否 | string / null |  |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PurchaseReceiptLineIn -->
### PurchaseReceiptLineIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `purchase_order_line_id` | 是 | integer |  |  |
| `done_qty` | 是 | number / string | 大于 0.0 |  |
| `destination_location_id` | 否 | integer / null |  |  |
| `batch_no` | 否 | string / null | 最长 80 |  |
| `produced_on` | 否 | string / null |  |  |
| `expires_on` | 否 | string / null |  |  |
| `serial_numbers` | 否 | array<string> |  |  |

此模型拒绝未定义字段。
<!-- /mcp-topic -->

<!-- mcp-topic: schema_PutawayRuleIn -->
### PutawayRuleIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `product_id` | 否 | integer / null |  |  |
| `category_id` | 否 | integer / null |  |  |
| `destination_location_id` | 是 | integer |  |  |
| `priority` | 否 | integer | 默认 100；最小 0.0；最大 10000.0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ReceiptPartyMappingIn -->
### ReceiptPartyMappingIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `source_name` | 是 | string | 最短 1；最长 160 |  |
| `display_name` | 否 | string / null | 最长 160 |  |
| `supplier_id` | 否 | integer / null |  |  |
| `is_active` | 否 | boolean | 默认 true |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ReorderRuleIn -->
### ReorderRuleIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `warehouse_id` | 是 | integer |  |  |
| `supplier_id` | 否 | integer / null |  |  |
| `min_qty` | 是 | number / string | 最小 0.0 |  |
| `target_qty` | 是 | number / string | 最小 0.0 |  |
| `safety_qty` | 否 | number / string | 默认 0；最小 0.0 |  |
| `min_order_qty` | 否 | number / string | 默认 1；大于 0.0 |  |
| `order_multiple` | 否 | number / string | 默认 1；大于 0.0 |  |
| `is_enabled` | 否 | boolean | 默认 true |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ReportResponse -->
### ReportResponse



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `dimension` | 是 | string |  |  |
| `granularity` | 是 | string |  |  |
| `date_start` | 是 | string (date) / null |  |  |
| `date_end` | 是 | string (date) |  |  |
| `timezone` | 是 | string |  |  |
| `statuses` | 是 | array<string> |  |  |
| `metric_keys` | 是 | array<string> |  |  |
| `rows` | 是 | array<ReportRow> |  |  |
| `totals` | 是 | object |  |  |
| `total_rows` | 是 | integer |  |  |
| `page` | 是 | integer |  |  |
| `page_size` | 是 | integer |  |  |
| `notes` | 否 | array<string> | 默认 [] |  |
| `reconciliation_issues` | 否 | array<object> |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ReportRow -->
### ReportRow



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `dim_key` | 是 | string |  |  |
| `dim_label` | 是 | string |  |  |
| `dim_label_key` | 否 | string / null |  |  |
| `metrics` | 是 | object |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_RevenueTrendItem -->
### RevenueTrendItem



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `date` | 是 | string |  |  |
| `revenue` | 是 | string |  |  |
| `orders` | 否 | integer | 默认 0 |  |
| `refund_amount` | 否 | string | 默认 "0" |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_ReviewStatsResponse -->
### ReviewStatsResponse



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `avg_rating` | 是 | number |  |  |
| `total` | 是 | integer |  |  |
| `approved` | 是 | integer |  |  |
| `pending` | 是 | integer |  |  |
| `distribution` | 是 | object |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_RuleUpdate -->
### RuleUpdate



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `target_qty_per_source` | 否 | integer / null | 最小 1.0；最大 100000.0 |  |
| `is_active` | 否 | boolean / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SalesGrossProfitAnomalyCount -->
### SalesGrossProfitAnomalyCount



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `loss_products` | 是 | integer |  |  |
| `margin_dropped_products` | 是 | integer |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SalesGrossProfitResponse -->
### SalesGrossProfitResponse



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `inventory_enabled` | 否 | boolean | 默认 true |  |
| `tax_basis` | 是 | string | 允许值 ["known", "unknown"] |  |
| `summary` | 是 | SalesGrossProfitSummary |  |  |
| `trend` | 是 | array<SalesGrossProfitTrendPoint> |  |  |
| `anomalies` | 是 | SalesGrossProfitAnomalyCount |  |  |
| `rows` | 是 | array<SalesGrossProfitRow> |  |  |
| `page` | 是 | integer |  |  |
| `page_size` | 是 | integer |  |  |
| `total_rows` | 是 | integer |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SalesGrossProfitRow -->
### SalesGrossProfitRow



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `product_name` | 是 | string |  |  |
| `variant_name` | 否 | string / null |  |  |
| `net_revenue` | 是 | string |  |  |
| `cogs` | 是 | string |  |  |
| `gross_profit` | 是 | string |  |  |
| `gross_margin_rate` | 是 | string / null |  |  |
| `refund_impact` | 是 | string |  |  |
| `last_purchase_cost` | 是 | string / null |  |  |
| `anomaly` | 否 | string | 默认 "normal"；允许值 ["loss", "dropped", "normal"] |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SalesGrossProfitSummary -->
### SalesGrossProfitSummary



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `net_revenue` | 是 | string |  |  |
| `cogs` | 是 | string |  |  |
| `gross_profit` | 是 | string |  |  |
| `gross_margin_rate` | 是 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SalesGrossProfitTrendPoint -->
### SalesGrossProfitTrendPoint



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `date` | 是 | string |  |  |
| `net_revenue` | 是 | string |  |  |
| `cogs` | 是 | string |  |  |
| `gross_profit` | 是 | string |  |  |
| `gross_margin_rate` | 是 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SellingUnitIn -->
### SellingUnitIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `dict_id` | 否 | integer / null |  |  |
| `unit_name` | 是 | string |  |  |
| `unit_name_en` | 否 | string / null |  |  |
| `qty_per_base` | 否 | integer | 默认 1 |  |
| `is_base_unit` | 否 | boolean | 默认 false |  |
| `price_override` | 否 | number / string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SellingUnitOut -->
### SellingUnitOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `unit_name` | 是 | string |  |  |
| `unit_name_en` | 否 | string / null |  |  |
| `qty_per_base` | 是 | integer |  |  |
| `is_base_unit` | 是 | boolean |  |  |
| `price_override` | 否 | number / null |  |  |
| `sort_order` | 是 | integer |  |  |
| `base_price` | 否 | number / null | 默认 0.0 |  |
| `effective_price` | 是 | number / null | 只读 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_StaffOut -->
### StaffOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `user_id` | 是 | integer |  |  |
| `pos_enabled` | 是 | boolean |  |  |
| `store_ids` | 是 | array<integer> |  |  |
| `credential_version` | 是 | integer |  |  |
| `pin` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_StockStatusBrief -->
### StockStatusBrief



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `name` | 是 | string |  |  |
| `name_en` | 否 | string / null |  |  |
| `slug` | 是 | string |  |  |
| `allow_purchase` | 是 | boolean |  |  |
| `allow_purchase_without_stock` | 否 | boolean | 默认 false |  |
| `badge_color` | 否 | string / null |  |  |
| `badge_text` | 否 | string / null |  |  |
| `badge_text_en` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_StockStatusIn -->
### StockStatusIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 是 | string | 最长 50 |  |
| `name_en` | 否 | string / null | 最长 50 |  |
| `slug` | 是 | string | 最长 30；正则 "^[a-z][a-z0-9_]*$" |  |
| `allow_purchase` | 否 | boolean | 默认 true |  |
| `allow_purchase_without_stock` | 否 | boolean | 默认 false |  |
| `badge_color` | 否 | string / null | 最长 20 |  |
| `badge_text` | 否 | string / null | 最长 50 |  |
| `badge_text_en` | 否 | string / null | 最长 50 |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_default` | 否 | boolean | 默认 false |  |
| `status_type` | 否 | string | 默认 "in_stock"；允许值 ["in_stock", "out_of_stock"] |  |
| `is_type_default` | 否 | boolean | 默认 false |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_StockStatusOut -->
### StockStatusOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `name` | 是 | string |  |  |
| `name_en` | 否 | string / null |  |  |
| `slug` | 是 | string |  |  |
| `allow_purchase` | 是 | boolean |  |  |
| `allow_purchase_without_stock` | 否 | boolean | 默认 false |  |
| `badge_color` | 否 | string / null |  |  |
| `badge_text` | 否 | string / null |  |  |
| `badge_text_en` | 否 | string / null |  |  |
| `sort_order` | 否 | integer | 默认 0 |  |
| `is_default` | 否 | boolean | 默认 false |  |
| `is_system` | 否 | boolean | 默认 false |  |
| `status_type` | 否 | string | 默认 "in_stock" |  |
| `is_type_default` | 否 | boolean | 默认 false |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_StockStatusUpdate -->
### StockStatusUpdate



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `name` | 否 | string / null | 最长 50 |  |
| `name_en` | 否 | string / null | 最长 50 |  |
| `slug` | 否 | string / null | 最长 30；正则 "^[a-z][a-z0-9_]*$" |  |
| `allow_purchase` | 否 | boolean / null |  |  |
| `allow_purchase_without_stock` | 否 | boolean / null |  |  |
| `badge_color` | 否 | string / null | 最长 20 |  |
| `badge_text` | 否 | string / null | 最长 50 |  |
| `badge_text_en` | 否 | string / null | 最长 50 |  |
| `sort_order` | 否 | integer / null |  |  |
| `is_default` | 否 | boolean / null |  |  |
| `status_type` | 否 | string / null | 允许值 ["in_stock", "out_of_stock"] |  |
| `is_type_default` | 否 | boolean / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_StocktakeDocumentIn -->
### StocktakeDocumentIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `remark` | 否 | string / null | 最长 255 |  |
| `lines` | 是 | array<StocktakeLineIn> | 最少项 1 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_StocktakeLineIn -->
### StocktakeLineIn

实盘数量；账面数只作草稿快照，过账时必须重算。

| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `batch_id` | 否 | integer / null |  |  |
| `location_id` | 否 | integer / null |  |  |
| `counted_qty` | 是 | number / string | 最小 0.0 |  |
| `unit_cost` | 否 | number / string / null | 最小 0.0 |  |
| `remark` | 否 | string / null | 最长 255 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_StoreWarehouseMappingOut -->
### StoreWarehouseMappingOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `store_id` | 是 | integer |  |  |
| `warehouse_id` | 是 | integer |  |  |
| `is_active` | 否 | boolean | 默认 true |  |
| `id` | 是 | integer |  |  |
| `store_label` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SuggestionConvertIn -->
### SuggestionConvertIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `suggestion_ids` | 是 | array<integer> | 最少项 1 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SupplierIn -->
### SupplierIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `code` | 是 | string | 最长 40 |  |
| `name` | 是 | string | 最长 160 |  |
| `currency` | 否 | string | 默认 "NZD"；最长 8 |  |
| `contact` | 否 | string / null | 最长 120 |  |
| `email` | 否 | string / null | 最长 160 |  |
| `phone` | 否 | string / null | 最长 60 |  |
| `tax_id` | 否 | string / null | 最长 80 |  |
| `contacts` | 否 | array<object> |  |  |
| `addresses` | 否 | array<object> |  |  |
| `attachment_urls` | 否 | array<string> |  |  |
| `delivery_notes` | 否 | string / null |  |  |
| `payment_notes` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SupplierProductIn -->
### SupplierProductIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `supplier_id` | 是 | integer |  |  |
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `supplier_sku` | 否 | string / null | 最长 120 |  |
| `purchase_uom` | 否 | string | 默认 "unit"；最长 40 |  |
| `uom_factor` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `unit_price` | 否 | number / string | 默认 "0"；最小 0.0 |  |
| `currency` | 否 | string | 默认 "NZD"；最长 8 |  |
| `min_order_qty` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `order_multiple` | 否 | number / string | 默认 "1"；大于 0.0 |  |
| `lead_time_days` | 否 | integer | 默认 0；最小 0.0；最大 3650.0 |  |
| `priority` | 否 | integer | 默认 100；最小 0.0；最大 10000.0 |  |
| `valid_from` | 否 | string / null |  |  |
| `valid_to` | 否 | string / null |  |  |
| `is_active` | 否 | boolean | 默认 true |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_SupplierUpdateIn -->
### SupplierUpdateIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `code` | 是 | string | 最长 40 |  |
| `name` | 是 | string | 最长 160 |  |
| `currency` | 否 | string | 默认 "NZD"；最长 8 |  |
| `contact` | 否 | string / null | 最长 120 |  |
| `email` | 否 | string / null | 最长 160 |  |
| `phone` | 否 | string / null | 最长 60 |  |
| `tax_id` | 否 | string / null | 最长 80 |  |
| `contacts` | 否 | array<object> |  |  |
| `addresses` | 否 | array<object> |  |  |
| `attachment_urls` | 否 | array<string> |  |  |
| `delivery_notes` | 否 | string / null |  |  |
| `payment_notes` | 否 | string / null |  |  |
| `is_active` | 是 | boolean |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_TierPriceIn -->
### TierPriceIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `member_level_id` | 是 | integer |  |  |
| `price` | 是 | number / string |  |  |
| `price_source` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_TierPriceOut -->
### TierPriceOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `member_level_id` | 是 | integer |  |  |
| `price` | 是 | string |  |  |
| `price_source` | 否 | string | 默认 "manual" |  |
| `level_name` | 否 | string / null |  |  |
| `discount_rate` | 否 | string / null |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_TopCustomerItem -->
### TopCustomerItem



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `name` | 是 | string |  |  |
| `email` | 是 | string |  |  |
| `orders_count` | 是 | integer |  |  |
| `total_spent` | 是 | string |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_TopProductItem -->
### TopProductItem



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `name` | 是 | string |  |  |
| `sku` | 是 | string |  |  |
| `revenue` | 是 | string |  |  |
| `orders_count` | 是 | integer |  |  |
| `quantity` | 是 | string |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_TransactionOut -->
### TransactionOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `product_id` | 是 | integer |  |  |
| `product_name` | 是 | string |  |  |
| `variant_id` | 是 | integer / null |  |  |
| `warehouse_id` | 是 | integer |  |  |
| `stock_state` | 是 | string |  |  |
| `qty_delta` | 是 | string |  |  |
| `qty_after` | 是 | string |  |  |
| `doc_type` | 是 | string |  |  |
| `doc_id` | 是 | integer / null |  |  |
| `unallocated` | 是 | boolean |  |  |
| `created_at` | 是 | string |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_TransferLineIn -->
### TransferLineIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `product_id` | 是 | integer |  |  |
| `variant_id` | 否 | integer / null |  |  |
| `source_location_id` | 否 | integer / null |  |  |
| `destination_location_id` | 否 | integer / null |  |  |
| `qty` | 是 | number / string | 大于 0.0 |  |
| `batch_id` | 否 | integer / null |  |  |
| `serial_numbers` | 否 | array<string> |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_TransferOperationIn -->
### TransferOperationIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `source_warehouse_id` | 是 | integer |  |  |
| `destination_warehouse_id` | 是 | integer |  |  |
| `lines` | 是 | array<TransferLineIn> | 最少项 1 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `remark` | 否 | string / null | 最长 255 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |

此模型拒绝未定义字段。
<!-- /mcp-topic -->

<!-- mcp-topic: schema_UnitDictOut -->
### UnitDictOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `unit_name` | 是 | string |  |  |
| `unit_name_en` | 否 | string / null |  |  |
| `is_system` | 是 | boolean |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_VendorReturnIn -->
### VendorReturnIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `warehouse_id` | 是 | integer |  |  |
| `purchase_order_id` | 否 | integer / null |  |  |
| `lines` | 是 | array<InventoryMoveIn> | 最少项 1 |  |
| `reason` | 是 | string | 最短 1；最长 255 |  |
| `reference` | 否 | string / null | 最长 120 |  |
| `idempotency_key` | 否 | string / null | 最长 120 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_WarehouseIn -->
### WarehouseIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `code` | 是 | string | 最长 40 |  |
| `name` | 是 | string | 最长 120 |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_WarehouseOut -->
### WarehouseOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `id` | 是 | integer |  |  |
| `code` | 是 | string |  |  |
| `name` | 是 | string |  |  |
| `is_active` | 是 | boolean |  |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_app__plugins__inventory__schemas__SettingsOut -->
### app__plugins__inventory__schemas__SettingsOut



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `lifecycle_state` | 是 | string |  |  |
| `cost_method` | 是 | string |  |  |
| `batch_enabled` | 是 | boolean |  |  |
| `expiry_enabled` | 是 | boolean |  |  |
| `serial_enabled` | 是 | boolean |  |  |
| `qc_enabled` | 是 | boolean |  |  |
| `allow_negative` | 是 | boolean |  |  |
| `purchase_approval` | 是 | boolean |  |  |
| `period_close_enabled` | 是 | boolean |  |  |
| `base_currency` | 是 | string |  |  |
| `default_warehouse_id` | 是 | integer / null |  |  |
| `procurement_mode` | 否 | string | 默认 "standard" |  |
| `online_fulfillment_warehouse_id` | 否 | integer / null |  |  |
| `warehouse_mapping_enforced` | 否 | boolean | 默认 false |  |
<!-- /mcp-topic -->

<!-- mcp-topic: schema_app__plugins__repack__schemas__RuleIn -->
### app__plugins__repack__schemas__RuleIn



| 字段 | 必填 | 类型 | 默认值与约束 | 说明 |
|---|---|---|---|---|
| `source_product_id` | 是 | integer | 大于 0.0 |  |
| `target_product_id` | 是 | integer | 大于 0.0 |  |
| `target_qty_per_source` | 是 | integer | 最小 1.0；最大 100000.0 |  |
| `is_active` | 否 | boolean | 默认 true |  |
<!-- /mcp-topic -->

