qmai-cli-public 0.1.2 → 0.1.4

package/skills/qmai-product/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: qmai-product
+version: 3.1.0
+description: "商品管理：列表、同步、上下架、估清、售罄、置满、做法启停、实时查询、批量导入导出、批量调价"
+metadata:
+  bins: [qmai]
+  help: "qmai product --help"
+---
+
+> 前置条件: 请先阅读 ../qmai-shared/SKILL.md 了解认证和配置
+
+## 核心概念
+
+- **列表商品 (OpenProduct)**: API 返回的商品结构，字段包括 id（数字ID）、name（名称）、status（10=上架/20=下架）、showPriceLow（价格，单位：分）、categoryNameList（分类名数组）、goodsSkuList（SKU列表）
+- **同步商品 (ShopGoods)**: 创建/更新用的输入，用户只需填写 tradeName/tradePrice/tradeNo/className/stock 五个字段，Sync() 方法会自动补全 20+ 个 API 必填字段
+- **SaleChannel**: 1（堂食）| 2（外卖）| 11（堂食+外卖）
+- **SaleType**: 1（普通商品）| 2（套餐）
+- **shopCode**: 门店编码，从 profile config 自动读取
+- **tradeMark**: SKU 级别的商品标识，用于上下架操作（BatchUp/BatchDown）
+
+## Shortcuts（推荐优先使用）
+
+| Shortcut | 说明 | 示例 |
+|----------|------|------|
+| +quick-add | 快速添加商品 | `qmai product +quick-add "拿铁" 32.00` |
+| +on-sale | 批量上架 | `qmai product +on-sale --trade-marks TM001,TM002` |
+| +off-sale | 批量下架 | `qmai product +off-sale --trade-marks TM001` |
+| +price-adjust | 快速调价 | `qmai product +price-adjust +10%` |
+
+## API 命令
+
+### 商品列表
+```bash
+qmai product list [--name 咖啡] [--sale-channel 1] [--sale-type 1] [--page 1] [--page-size 20]
+```
+> 注意: page-size 最大 50
+
+### 商品详情
+```bash
+qmai product get <id|name>
+```
+
+### 创建/同步商品（通过 Sync API）
+```bash
+qmai product create --name "美式咖啡" --price 28.00 --trade-no P001 [--class 饮品]
+qmai product create --from-json goods.json
+qmai product create --name "拿铁" --price 32.00 --dry-run
+```
+
+### 更新商品（通过 Sync API）
+```bash
+qmai product update <tradeNo> --name "新名称" --price 30.00 [--class 饮品]
+```
+
+### 下架商品
+```bash
+qmai product delete <tradeMark> --force [--sale-channel 1]
+```
+
+### 批量上架/下架
+```bash
+qmai product batch-status --action up --trade-marks TM001,TM002 [--sale-channel 1]
+qmai product batch-status --action down --trade-marks TM001 --dry-run
+```
+
+### 估清 / 取消估清
+```bash
+qmai product estimate-clear --trade-mark TM001 --dry-run
+qmai product cancel-estimate-clear --trade-mark TM001
+qmai product cancel-estimate-clear --trade-marks TM001,TM002 --sale-channel 1 --sale-type 2
+```
+
+### 售罄 / 置满
+```bash
+qmai product sold-out --trade-marks TM001,TM002 --sale-channels 3 --sale-types 1
+qmai product fill-full --trade-marks TM001 --sale-channels 3 --sale-types 1 --dry-run
+```
+
+### 做法启停
+```bash
+qmai product practice-status --practice-values 少糖,去冰 --status 1
+qmai product practice-status --practice-values 热饮 --status 0 --dry-run
+```
+
+### 实时数据 / 加料 / 支持做法的商品列表
+```bash
+qmai product attach-list --sale-channel 3 --sale-type 1
+qmai product list-with-practice --sale-channel 3 --sale-type 1 --status 10 --include-properties PRACTICE,SKU
+qmai product energy --goods-id 20001 --store-id 10001
+qmai product realtime --store-id 10001 --goods-ids 20001,20002 --sale-channel 3 --sale-type 1
+```
+
+### 删除任务
+```bash
+qmai product delete-task --sale-channel 3 --sale-type 1 --trade-marks TM001,TM002 --dry-run
+qmai product delete-task --sale-channel 4 --sale-type 0 --spec-codes SKU001,SKU002
+```
+
+### 批量导入（通过 Sync API）
+```bash
+qmai product import --file products.csv --dry-run    # 预览
+qmai product import --file products.csv              # 执行
+qmai product import --file products.json
+```
+
+### 批量导出
+```bash
+qmai product export --file products.csv
+qmai product export --file products.json --name 咖啡
+```
+
+### 批量调价
+```bash
+qmai product batch-price --adjust +10% --dry-run
+qmai product batch-price --adjust -5%
+qmai product batch-price --adjust +2.00
+```
+
+### 分类
+```bash
+qmai product category   # 提示通过 --class 参数在创建/同步时指定分类
+```
+
+## 开放平台 API 端点
+
+| 操作 | 端点 |
+|------|------|
+| 商品列表 | POST /v3/goods/item/getItemList |
+| 商品同步 | POST /v3/goods/sync/shopGoodsSync |
+| 批量上架 | POST /v3/goods/item/externalUp |
+| 批量下架 | POST /v3/goods/item/externalDown |
+| 估清 | POST /v3/goods/item/sellOut |
+| 取消估清 | POST /v3/goods/item/fillUp |
+| 批量售罄 | POST /v3/goods/item/externalEmpty |
+| 批量置满 | POST /v3/goods/item/externalFull |
+| 查询门店加料列表 | POST /v3/goods/item/shopGoodsAttachList |
+| 查询门店商品列表(支持做法) | POST /v3/goods/item/getShopGoodsList |
+| 查询商品能量值 | POST /v3/goods/nutritional/energy |
+| 门店商品实时数据查询 | POST /v3/newPattern/goodsCenter/post/v2/item/real-time/list |
+| 门店商品做法启用停用 | POST /v3/goods/item/practiceOnOff |
+| 提交商品删除任务 | POST /v3/goods/sync/tripartiteShopGoodsDel |
+
+## API 响应结构
+
+### 列表响应 (getItemList)
+```json
+{
+  "data": {
+    "data": [ ... ],   // 商品数组（注意：嵌套在 data.data 中）
+    "total": 380
+  }
+}
+```
+
+### 商品对象字段
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | int64 | 商品列表 ID |
+| goodsId | int64 | 底层商品 ID |
+| name | string | 商品名称 |
+| status | int | 10=上架, 20=下架 |
+| showPriceLow | int | 价格（**单位：分**，显示时 /100） |
+| categoryNameList | []string | 分类名称数组 |
+| goodsSkuList | []object | SKU 列表，含 skuId/tradeMark/salePrice/inventory |
+| saleChannel | int | 销售渠道 |
+
+## 注意事项（Agent 必读）
+
+- **价格单位**: 列表 API 返回的 showPriceLow/showPriceHigh 单位是**分**，显示时需除以 100
+- **状态码**: 10=上架, 20=下架（不是 1/0）
+- **库存类型**: API 返回的 inventory 可能是 int 或 float，代码中用 float64 接收
+- **分页限制**: page-size 最大 50
+- **Sync API 必填字段多**: 用户只需填 5 个字段，Sync() 自动补全 pictureUrlList、categoryList（含 name/mark/isRequired/isBackend/isFront）、skuList（含 tradeMark/marketPrice/stock/clearStatus）、saleTime 等
+- **同步是异步的**: Sync API 返回成功后，商品不会立即出现在列表中
+- **删除任务不可撤销**: `delete-task` 只是提交删除任务，但业务效果不可撤销
+- **实时数据查询**: `realtime` 需要 `storeId`，不是 `shopCode`
+- **支持做法列表**: `list-with-practice` 需要显式传 `saleChannel`、`saleType` 和 `status`
+- 批量操作前务必使用 `--dry-run` 预览
+- 价格调整不可撤回，建议先 `export` 备份
+- 下架操作需要 `--force` 确认
+- 导入 CSV 首行必须为表头: trade_name,trade_price,trade_no,class_name,stock
+- shopCode 从 profile config 自动读取，无需手动指定
+- Debug 模式 (`--debug`) 会在一行日志中打印完整请求和响应 JSON

package/skills/qmai-product/references/qmai-product-advanced.md

@@ -0,0 +1,92 @@
+# 商品高级命令指南
+
+## 估清与取消估清
+
+```bash
+# 商品估清
+qmai product estimate-clear --trade-mark TM001
+
+# 取消估清
+qmai product cancel-estimate-clear --trade-mark TM001
+
+# 指定渠道和售卖类型取消估清
+qmai product cancel-estimate-clear \
+  --trade-marks TM001,TM002 \
+  --sale-channel 1 \
+  --sale-type 2 \
+  --is-all-empty 1
+```
+
+> `estimate-clear` 走 `sellOut`，`cancel-estimate-clear` 走 `fillUp`。
+
+## 售罄与置满
+
+```bash
+# 批量售罄
+qmai product sold-out --trade-marks TM001,TM002 --sale-channels 3 --sale-types 1
+
+# 批量置满
+qmai product fill-full --trade-marks TM001 --sale-channels 3 --sale-types 1 --dry-run
+```
+
+> `sold-out` 走 `externalEmpty`，`fill-full` 走 `externalFull`。
+
+## 做法启停
+
+```bash
+# 启用做法
+qmai product practice-status --practice-values 少糖,去冰 --status 1
+
+# 停用做法
+qmai product practice-status --practice-values 热饮 --status 0
+```
+
+## 支持做法商品列表
+
+```bash
+qmai product list-with-practice \
+  --sale-channel 3 \
+  --sale-type 1 \
+  --status 10 \
+  --include-properties PRACTICE,SKU,ATTACH
+```
+
+必填项：
+- `--sale-channel`
+- `--sale-type`
+- `--status`
+
+## 门店加料列表
+
+```bash
+qmai product attach-list --sale-channel 3 --sale-type 1
+```
+
+## 门店商品实时数据
+
+```bash
+qmai product energy --goods-id 20001 --store-id 10001
+
+qmai product realtime \
+  --store-id 10001 \
+  --goods-ids 20001,20002 \
+  --sale-channel 3 \
+  --sale-type 1
+```
+
+> `realtime` 用的是 `storeId`，不是 `shopCode`。
+
+## 删除任务
+
+```bash
+# 按商品标识删除
+qmai product delete-task --sale-channel 3 --sale-type 1 --trade-marks TM001,TM002 --dry-run
+
+# 按规格码删除
+qmai product delete-task --sale-channel 4 --sale-type 0 --spec-codes SKU001,SKU002
+```
+
+注意：
+- 删除任务只会返回 `taskId`
+- 该操作不可撤销
+- 必须先确认渠道和售卖类型是否正确

package/skills/qmai-product/references/qmai-product-batch.md

@@ -0,0 +1,113 @@
+# 批量操作指南
+
+## 批量导入（通过 Sync API）
+
+### CSV 格式
+
+首行表头，后续为数据行：
+```csv
+trade_name,trade_price,trade_no,class_name,stock
+美式咖啡,28.00,P001,饮品,100
+拿铁,32.00,P002,饮品,100
+抹茶拿铁,35.00,P003,饮品,50
+```
+
+### JSON 格式
+
+```json
+[
+  {"tradeName": "美式咖啡", "tradePrice": 28.00, "tradeNo": "P001", "className": "饮品"},
+  {"tradeName": "拿铁", "tradePrice": 32.00, "tradeNo": "P002", "className": "饮品"}
+]
+```
+
+> 用户只需提供 5 个字段，`Sync()` 方法会自动补全所有 API 必填字段（pictureUrlList、categoryList、skuList、saleTime 等）
+
+### 导入命令
+
+```bash
+# 先预览
+qmai product import --file products.csv --dry-run
+
+# 确认后执行（调用 shopGoodsSync）
+qmai product import --file products.csv
+
+# 跳过错误行继续
+qmai product import --file products.csv --skip-errors
+```
+
+> **注意**: Sync API 是异步的，导入成功后商品不会立即出现在列表中
+
+## 批量导出
+
+```bash
+# 导出为 CSV
+qmai product export --file backup.csv
+
+# 导出为 JSON
+qmai product export --file backup.json
+
+# 按名称筛选
+qmai product export --file drinks.csv --name 咖啡
+```
+
+导出 CSV 表头为: `id,name,price,status,inventory,category`
+
+> 注意: 导出最多一次获取 50 条（API 分页限制）
+
+## 批量调价
+
+### 百分比调价
+
+```bash
+# 全品涨价 10%（先预览）
+qmai product batch-price --adjust +10% --dry-run
+
+# 降价 5%
+qmai product batch-price --adjust -5%
+```
+
+### 固定金额调价
+
+```bash
+# 所有商品涨 2 元
+qmai product batch-price --adjust +2.00
+
+# 降 1.5 元
+qmai product batch-price --adjust -1.50
+```
+
+### Dry-run 输出示例
+
+```
+[dry-run] 将要调整 5 个商品价格:
+  美式咖啡: 28.00 → 30.80
+  拿铁: 32.00 → 35.20
+  卡布奇诺: 30.00 → 33.00
+  摩卡: 35.00 → 38.50
+  冰美式: 25.00 → 27.50
+```
+
+> 批量调价内部流程：先通过 List API 查询当前价格（单位：分，/100 转为元），计算新价格后通过 Sync API 更新
+
+## 批量上下架
+
+```bash
+# 批量上架（调用 externalUp API）
+qmai product batch-status --action up --trade-marks TM001,TM002 [--sale-channel 1]
+
+# 批量下架（调用 externalDown API）
+qmai product batch-status --action down --trade-marks TM001 --dry-run
+
+# 预览
+qmai product batch-status --action up --trade-marks TM001,TM002 --dry-run
+```
+
+> `--trade-marks` 的值来自商品 SKU 的 tradeMark 字段（可通过 `qmai product list --format json` 查看 goodsSkuList[].tradeMark）
+
+## 安全建议
+
+1. **操作前备份**: `qmai product export --file backup.json`
+2. **先 Dry-run**: 所有批量操作先 `--dry-run` 预览
+3. **调价不可撤回**: 价格修改后无法自动回滚，保留备份
+4. **分步执行**: 大批量操作建议按分类分步执行

package/skills/qmai-product/references/qmai-product-category.md

@@ -0,0 +1,67 @@
+# 分类管理
+
+## 概述
+
+开放平台的分类通过 `className` 字段在商品同步（Sync API）时自动关联，**无独立的分类 CRUD API**。
+
+## 工作方式
+
+1. 在创建/同步商品时通过 `--class` 参数或 CSV 的 `class_name` 列指定分类名称
+2. `Sync()` 方法自动构建 `categoryList`，包含 `name`/`mark`/`categoryName`/`isRequired`/`isBackend`/`isFront`/`sort`/`type` 等必填字段
+3. 平台会自动匹配已有分类或创建新分类
+4. 分类信息可在商品列表返回结果的 `categoryNameList` 字段中查看
+
+## Sync API 的分类结构
+
+用户只需提供 `className`（字符串），代码自动生成完整的分类对象：
+
+```json
+{
+  "categoryList": [{
+    "name": "饮品",
+    "categoryName": "饮品",
+    "mark": "饮品",
+    "isRequired": 0,
+    "isBackend": 0,
+    "isFront": 0,
+    "sort": 0,
+    "type": 0
+  }]
+}
+```
+
+## 使用示例
+
+### 同步时指定分类
+
+```bash
+# 创建商品时指定分类
+qmai product create --name "美式咖啡" --price 28.00 --class 饮品
+
+# 批量导入时在 CSV 中指定
+trade_name,trade_price,trade_no,class_name,stock
+美式咖啡,28.00,P001,饮品,100
+拿铁,32.00,P002,饮品,100
+三明治,15.00,P003,小食,50
+```
+
+### 查看分类
+
+```bash
+# 列表中查看分类列
+qmai product list
+
+# JSON 输出查看分类
+qmai product list --format json
+
+# 分类提示命令
+qmai product category
+# → 提示: 通过 --class 参数在创建/同步时指定分类
+```
+
+## 注意事项
+
+- `className` 为字符串，平台按名称匹配
+- 不支持分类的独立创建、删除、排序操作
+- 修改商品分类 = 同步时传入新的 `className`
+- 不指定分类时，`categoryList` 传空数组 `[]`

package/skills/qmai-product/references/qmai-product-crud.md

@@ -0,0 +1,126 @@
+# 商品增删改查操作指南
+
+## 数据结构
+
+### 列表返回 (OpenProduct)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | int64 | 商品列表 ID |
+| goodsId | int64 | 底层商品 ID |
+| name | string | 商品名称 |
+| status | int | 10=上架, 20=下架 |
+| showPriceLow | int | 最低价（**单位：分**） |
+| showPriceHigh | int | 最高价（**单位：分**） |
+| saleChannel | int | 销售渠道: 1=堂食, 2=外卖, 11=堂食+外卖 |
+| categoryNameList | []string | 分类名称数组 |
+| goodsSkuList | []GoodsSku | SKU 列表 |
+
+### SKU (GoodsSku)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| skuId | string | SKU ID |
+| tradeMark | string | 商品编码（用于上下架） |
+| salePrice | float64 | 销售价（元） |
+| inventory | float64 | 库存（API 可能返回 int 或 float） |
+
+### 同步输入 (ShopGoods)
+
+用户只需填写以下 5 个字段，`Sync()` 自动补全 20+ 个 API 必填字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| tradeName | string | 商品名称（必填） |
+| tradePrice | float64 | 价格（必填，> 0） |
+| tradeNo | string | 商户自定义编号 |
+| className | string | 分类名称 |
+| stock | int | 库存（默认 9999） |
+
+## 创建商品（通过 Sync API）
+
+### 命令行方式
+```bash
+qmai product create --name "美式咖啡" --price 28.00 --trade-no P001 --class 饮品
+```
+
+### JSON 文件方式
+```bash
+qmai product create --from-json goods.json
+```
+
+`goods.json` 示例（只需包含用户关心的字段）:
+```json
+[
+  {"tradeName": "美式咖啡", "tradePrice": 28.00, "tradeNo": "P001", "className": "饮品"},
+  {"tradeName": "拿铁", "tradePrice": 32.00, "tradeNo": "P002", "className": "饮品"}
+]
+```
+
+### Dry-run 预览
+```bash
+$ qmai product create --name "拿铁" --price 32.00 --dry-run
+[dry-run] 将要同步 1 个商品:
+  拿铁 (32.00)
+```
+
+> **注意**: Sync API 是异步的，创建成功后商品不会立即出现在列表中
+
+## 查询商品
+
+```bash
+# 全部商品（默认每页 20 条，最大 50）
+qmai product list
+
+# 按名称搜索
+qmai product list --name 咖啡
+
+# 按销售渠道
+qmai product list --sale-channel 1
+
+# 按类型
+qmai product list --sale-type 1
+
+# 分页
+qmai product list --page 1 --page-size 50
+
+# JSON 输出
+qmai product list --format json
+
+# 商品详情（按 ID 或名称）
+qmai product get <id|name>
+```
+
+### 列表输出示例
+```
+ID                   名称       价格    状态    库存    分类
+--                   ------   ------  ------  ------  ------
+1185299121892380796  桃花落拿铁  21.00   上架    9999    咖啡系列
+1185299121892380733  春樱拿铁   21.00   上架    9999    咖啡系列
+```
+
+## 更新商品（通过 Sync API）
+
+```bash
+# 改名（--name 必填）
+qmai product update <tradeNo> --name "新品名" --price 35.00
+
+# 改分类
+qmai product update <tradeNo> --name "原名称" --class 饮品
+
+# 多字段更新
+qmai product update <tradeNo> --name "新品" --price 30.00 --class 小食
+```
+
+## 下架商品
+
+```bash
+# 需要 --force 确认（通过 BatchDown API）
+qmai product delete <tradeMark> --force --sale-channel 1
+
+# 不带 --force 只提示
+$ qmai product delete <tradeMark>
+确定要下架商品 <tradeMark> 吗？使用 --force 确认
+```
+
+> 下架通过 BatchDown API 实现，将商品 status 从 10 改为 20

package/skills/qmai-queue/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: qmai-queue
+version: 1.0.0
+description: "排队服务：查询门店排队进度、订单排队进度和叫号列表"
+metadata:
+  bins: [qmai]
+  help: "qmai queue --help"
+---
+
+> 前置条件: 请先阅读 ../qmai-shared/SKILL.md 了解认证和配置
+
+## 核心概念
+
+- **shop-progress**: 批量查询门店当前排队进度
+- **order-progress**: 查询单笔订单的排队进度
+- **shop-queue-nos**: 查询门店叫号列表
+
+## 命令概览
+
+```bash
+qmai queue shop-progress --shop-type 1 --shop-ids 1001,1002
+qmai queue order-progress --order-no O20260407001
+qmai queue shop-queue-nos --shop-code S001 --page 1 --size 10
+```
+
+## 开放平台 API 端点
+
+| 操作 | 端点 |
+| --- | --- |
+| 查询门店排队进度 | POST /v3/queuing/queryShopQueueCup |
+| 查询订单排队进度 | POST /v3/queuing/queryOrderQueueCup |
+| 查询门店排队叫号列表 | POST /v3/queuing/queueNo/queryShopQueueNoList |
+
+## 注意事项（Agent 必读）
+
+- `shop-progress` 的 `shopIdList` 官方最多支持 20 个
+- `shop-queue-nos` 的 `size` 官方限制在 1 到 20 之间
+- 这个模块目前只有读接口，没有写操作

package/skills/qmai-queue/references/qmai-queue-read.md

@@ -0,0 +1,21 @@
+# qmai-queue 查询参考
+
+## 适用场景
+
+- 查询门店当前排队压力
+- 查询单笔订单还要等多久
+- 查询门店当前叫号列表
+
+## 推荐命令
+
+```bash
+qmai queue shop-progress --shop-type 1 --shop-ids 1001,1002
+qmai queue order-progress --order-no O20260407001
+qmai queue shop-queue-nos --shop-code S001 --page 1 --size 10
+```
+
+## 排查建议
+
+- `order-progress` 中 `order-no` 和 `source-no` 至少传一个，同时传时以 `order-no` 为准
+- `shop-queue-nos` 默认可不传 `status-list`，官方会按待制作、制作中、待取餐查询
+- 如果要保留完整原始字段，优先使用 `--format json`