qmai-cli-public 0.1.2 → 0.1.3

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`

package/skills/qmai-shared/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: qmai-shared
+version: 3.0.0
+description: "基础能力：开放平台认证、配置管理、安全规则、通用约定"
+metadata:
+  bins: [qmai]
+  help: "qmai --help"
+---
+
+## 概述
+
+qmai CLI 是门店经营命令行工具。通过企迈开放平台 (`openapi.qmai.cn`) 管理门店商品、门店与组织、会员、营销、订单、财务、聚合配送、进销存和排队。本 Skill 描述认证、配置和安全相关的基础能力。
+
+## 认证流程
+
+### 凭证配置
+
+```bash
+qmai auth login [--profile <name>]
+```
+
+流程：
+1. 交互式输入 openId、grantCode、openKey、shopCode
+2. openKey 存入 OS keychain（敏感凭证）
+3. openId/grantCode/shopCode 写入 config profile
+4. 设为 active_profile
+
+### 认证管理命令
+
+| 命令 | 说明 |
+|------|------|
+| `qmai auth login` | 配置开放平台凭证 |
+| `qmai auth logout` | 清除凭证（keychain + config） |
+
+### 凭证存储
+
+- **openKey**: macOS Keychain（service: `qmai-cli`），Linux: libsecret
+- **openId/grantCode/shopCode**: `~/.config/qmai/config.yaml` profile 中
+
+### 请求签名
+
+每个 API 请求自动签名，无需手动操作：
+1. 生成随机 nonce + 当前时间戳
+2. 按字典序拼接 `grantCode=xx&nonce=xx&openId=xx&timestamp=xx`
+3. HmacSHA1(拼接串, openKey) → Base64 → URL Encode → token
+4. 请求体: `{openId, grantCode, nonce, timestamp, token, params}`
+
+## 配置管理
+
+### 配置文件
+
+位置：`~/.config/qmai/config.yaml`
+
+```yaml
+active_profile: default
+default_format: table
+debug: false
+profiles:
+  default:
+    name: default
+    shop_code: "S001"
+    open_id: "d14c1559..."
+    grant_code: "ba67d4fa46"
+  store2:
+    name: store2
+    shop_code: "S002"
+    open_id: "..."
+    grant_code: "..."
+```
+
+### 配置优先级
+
+flags → profile 配置 → 默认值
+
+### 配置命令
+
+```bash
+qmai config init                                    # 交互式初始化
+qmai config set <key> <val>                         # 设置配置项
+qmai config get <key>                               # 读取配置项
+qmai config list                                    # 查看所有配置
+qmai config profile add <name> --shop-code xxx      # 添加 profile
+qmai config profile remove <name>                   # 删除 profile
+qmai config profile list                            # 列出 profiles
+```
+
+## 输出格式
+
+所有命令支持 `--format` flag：
+
+| 格式 | 说明 |
+|------|------|
+| `table` | 对齐的文本表格（默认，终端友好） |
+| `json` | JSON 输出（脚本友好） |
+| `csv` | CSV 输出（Excel/导入友好） |
+
+## Debug 模式
+
+```bash
+qmai product list --debug
+```
+
+启用后在 `Client.Call` 层输出完整日志（一行包含全部信息）：
+```
+[DEBUG] POST <url> | req=<完整请求JSON> | resp=<完整响应JSON> | <耗时>ms
+```
+
+用于排查 API 对接问题，查看实际请求参数和响应结构。
+
+## 安全规则（Agent 必读）
+
+1. **openKey 安全**: openKey 仅存储在 OS keychain，不写入配置文件或日志
+2. **不存储敏感信息**: config 中不保存 openKey
+3. **Dry-run 优先**: 所有变更操作建议先使用 `--dry-run` 预览
+4. **确认机制**: 删除/下架操作需要 `--force` 确认
+5. **批量操作安全**: 批量操作前务必备份（`export`），建议先 `--dry-run`
+
+## API 基础
+
+- Base URL: `https://openapi.qmai.cn/`
+- 协议: 全部 HTTP POST，Content-Type: application/json
+- QPS 限制: 单接口最高 10
+- 分页限制: pageSize 最大 50
+- 认证: 请求体签名（自动注入）
+- 响应格式:
+  ```json
+  {
+    "status": true,
+    "code": 0,
+    "message": "请求成功",
+    "data": { ... },
+    "traceId": "..."
+  }
+  ```
+
+## 可用命令
+
+```
+qmai
+├── auth        认证管理
+├── config      配置管理
+├── product     商品管理
+├── store       门店与组织管理
+├── member      会员服务
+├── marketing   营销服务
+├── order       订单服务
+├── finance     财务服务
+├── delivery    聚合配送
+├── inventory   进销存
+├── queue       排队服务
+├── api         Raw API 请求透传
+├── doctor      诊断检查
+├── completion  Shell 自动补全
+└── version     版本信息
+```

package/skills/qmai-shared/references/qmai-shared-auth.md

@@ -0,0 +1,54 @@
+# 开放平台认证详情
+
+## 凭证配置流程
+
+```
+$ qmai auth login
+请输入 openId: d14c1559e87b747d577c834b275a4310
+请输入 grantCode: ba67d4fa46
+请输入 openKey: LyvrkvkxRkG2R6aM55bXpPwjYAbkEXTbVnKwfDYvVHjNwNFAmx
+请输入门店编码 (shopCode): S001
+✓ 凭证已保存 (profile: default)
+```
+
+## 凭证说明
+
+| 凭证 | 说明 | 存储位置 |
+|------|------|----------|
+| openId | 开放平台应用 ID | config yaml |
+| grantCode | 授权码 | config yaml |
+| openKey | 签名密钥（敏感） | OS keychain |
+| shopCode | 门店编码 | config yaml |
+
+## 请求签名算法 (HmacSHA1)
+
+1. 取 openId, grantCode, nonce, timestamp 四个字段
+2. 按 key 字典序升序排列
+3. 拼接为 `grantCode=xx&nonce=xx&openId=xx&timestamp=xx`
+4. HmacSHA1(拼接串, openKey) → Base64 → URL Encode
+5. 得到 token，一次性使用
+
+示例签名验证：
+- openKey: `LyvrkvkxRkG2R6aM55bXpPwjYAbkEXTbVnKwfDYvVHjNwNFAmx`
+- openId: `d14c1559e87b747d577c834b275a4310`
+- grantCode: `ba67d4fa46`
+- timestamp: `1465185768`, nonce: `11886`
+- 期望 token: `cFw0t9IuvL9jVo9qAzk0qMcw5BM%3D`
+
+## AES 加解密（敏感字段）
+
+部分接口的敏感字段需要 AES 加密传输：
+
+- 算法: AES-256/CBC/PKCS5Padding
+- Key: MD5(openKey) → 32 hex chars 作为字节
+- IV: MD5(openId)[8:24] → 16 hex chars 作为字节
+
+## 多门店支持
+
+每个 profile 独立存储凭证：
+
+```bash
+qmai auth login --profile store1
+qmai auth login --profile store2
+qmai config set active_profile store1   # 切换到 store1
+```

package/skills/qmai-shared/references/qmai-shared-config.md

@@ -0,0 +1,69 @@
+# 配置管理详情
+
+## 配置文件结构
+
+```yaml
+# ~/.config/qmai/config.yaml
+active_profile: default
+default_format: table     # json | table | csv
+debug: false
+
+profiles:
+  default:
+    name: default
+    shop_code: "S001"
+    open_id: "d14c1559e87b747d577c834b275a4310"
+    grant_code: "ba67d4fa46"
+    base_url: ""          # 空则使用默认值
+
+  test-store:
+    name: test-store
+    shop_code: "S002"
+    open_id: "..."
+    grant_code: "..."
+    base_url: "https://openapi.qmai.co/"  # 沙箱环境
+```
+
+## 初始化流程
+
+```bash
+$ qmai config init
+qmai CLI 配置初始化
+------------------------------
+Profile 名称 (default): my-store
+门店编码 shopCode (可选): S001
+API Base URL (https://openapi.qmai.cn/):
+默认输出格式 [table/json/csv] (table): json
+
+✓ 配置已保存到 ~/.config/qmai/config.yaml
+  Active profile: my-store
+
+下一步: 运行 'qmai auth login' 配置开放平台凭证
+```
+
+## 配置键列表
+
+| 键 | 说明 | 默认值 |
+|---|------|--------|
+| `active_profile` | 当前活动 profile | `default` |
+| `default_format` | 默认输出格式 | `table` |
+| `debug` | 调试模式 | `false` |
+| `base_url` | API 基础 URL（per profile） | `https://openapi.qmai.cn/` |
+| `shop_code` | 门店编码（per profile） | - |
+| `open_id` | 开放平台 openId（per profile） | - |
+| `grant_code` | 开放平台 grantCode（per profile） | - |
+
+## Profile 管理
+
+```bash
+# 添加 profile
+qmai config profile add new-store --shop-code S003 --base-url https://...
+
+# 列出所有 profiles
+qmai config profile list
+# * default (shop: S001)
+#   test-store (shop: S002) [https://openapi.qmai.co/]
+
+# 删除 profile
+qmai config profile remove test-store
+```