qmai-cli-public 0.1.2 → 0.1.4

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
+```

package/skills/qmai-store/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: qmai-store
+version: 1.0.0
+description: "门店与组织管理：门店详情、门店列表、组织树、门店组、配置查询、门店状态与门店同步"
+metadata:
+  bins: [qmai]
+  help: "qmai store --help"
+---
+
+> 前置条件: 请先阅读 ../qmai-shared/SKILL.md 了解认证和配置
+
+## 核心概念
+
+- **shopCode**: 门店编码，很多查询和状态修改命令以此为主键
+- **shopId / storeId**: 门店 ID，配置、扩展字段、标签和部分批量查询接口会使用
+- **teamId**: 门店组 ID，用于门店组别调整
+- **fieldCodes**: 门店配置或品牌配置的编码列表，一次最多建议传 10 个
+- **shopInfoSync**: 门店主数据同步接口，字段多、副作用大，建议只通过 JSON 文件驱动
+
+## 命令概览
+
+### 门店详情与列表
+```bash
+qmai store get <shop-code>
+qmai store get-by-id <shop-id>
+qmai store list [--keyword 门店名] [--page 1] [--page-size 10]
+qmai store id <shop-code>
+```
+
+### 外卖映射
+```bash
+qmai store takeout-map-list --platform-type 4 [--page 1] [--page-size 10]
+```
+
+### 门店状态与组别
+```bash
+qmai store set-status <shop-code> --status 1 --dry-run
+qmai store move-team --shop-id 1001 --team-id 2001
+```
+
+### 配置、扩展字段与标签
+```bash
+qmai store config --store-id 1001 --field-codes OrderSettingConfig:autoCancelMinutes
+qmai store brand-config --field-codes OrderSettingConfig:autoCancelMinutes
+qmai store ext-data --shop-id 1001
+qmai store labels --shop-id 1001
+```
+
+### 组织结构
+```bash
+qmai store org-tree [--contain-close 1]
+qmai store team-list [--name 华东区]
+qmai store dept-tree
+```
+
+### 门店同步
+```bash
+qmai store sync --from-json shop.json --dry-run
+qmai store sync --from-json shop.json
+```
+
+## 开放平台 API 端点
+
+| 操作 | 端点 |
+| --- | --- |
+| 根据门店编码查询门店详情 | POST /v3/org/shop/getShopDetail |
+| 批量查询门店 | POST /v3/org/shop/getShopList |
+| 查询平台外卖门店映射明细 | POST /v3/dist/meTakeoutShopMapPage |
+| 设置门店营业状态 | POST /v3/org/shop/changeStatus |
+| 门店信息同步 | POST /v3/org/shop/shopInfoSync |
+| 根据门店编码查询门店id | POST /v3/org/shop/shopCode2Id |
+| 根据ID查询门店详情 | POST /v3/org/shop/getShopDetailById |
+| 修改门店的组别 | POST /v3/org/shop/modifyShopTeam |
+| 查询门店配置(支持批量) | POST /v3/storeConfig/queryStoreConfigBatch |
+| 查询品牌配置(支持批量) | POST /v3/sellerConfig/querySellerConfigBatch |
+| 查询门店扩展字段信息 | POST /v3/newPattern/orgCenter/post/shop/get-shop-ext-data |
+| 查询门店标签列表 | POST /v3/newPattern/orgCenter/get/shop/label-by-id |
+| 查询组织机构列表 | POST /v3/org/shop/getOrgTree |
+| 查询门店组列表 | POST /v3/org/shop/shopTeamList |
+| 查询门店树结构数据 | POST /v3/org/shop/shopDeptTree |
+
+## 注意事项（Agent 必读）
+
+- `store get` 和 `store id` 用 `shopCode`
+- `store config`、`store ext-data`、`store labels` 常用 `storeId` 或 `shopId`
+- `set-status` 是变更命令，建议优先 `--dry-run`
+- `sync` 字段复杂，优先用 `--from-json`
+- `shopInfoSync` 可能不是立即一致，不要假设提交成功后列表立刻更新
+- `getShopList` 和 `takeout-map-list` 当前是显式分页，不会自动拉全量
+- `2.3 人员管理` 尚未纳入当前 `qmai store` 命令面

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

@@ -0,0 +1,45 @@
+# 门店与组织读取指南
+
+## 门店详情
+
+```bash
+# 按门店编码
+qmai store get S001
+
+# 按门店 ID
+qmai store get-by-id 10001
+
+# 门店编码转门店 ID
+qmai store id S001
+```
+
+## 门店列表
+
+```bash
+qmai store list --keyword 咖啡 --page 1 --page-size 10
+qmai store list --contain-close 1
+```
+
+## 外卖映射
+
+```bash
+# 4=美团 5=饿了么
+qmai store takeout-map-list --platform-type 4
+```
+
+## 配置、扩展字段、标签
+
+```bash
+qmai store config --store-id 10001 --field-codes OrderSettingConfig:autoCancelMinutes
+qmai store brand-config --field-codes OrderSettingConfig:autoCancelMinutes
+qmai store ext-data --shop-id 10001
+qmai store labels --shop-id 10001
+```
+
+## 组织结构
+
+```bash
+qmai store org-tree
+qmai store team-list
+qmai store dept-tree
+```

package/skills/qmai-store/references/qmai-store-write.md

@@ -0,0 +1,44 @@
+# 门店与组织写操作指南
+
+## 设置门店营业状态
+
+```bash
+# 1=开启 2=关闭
+qmai store set-status S001 --status 1 --dry-run
+qmai store set-status S001 --status 2
+```
+
+## 修改门店组别
+
+```bash
+qmai store move-team --shop-id 10001 --team-id 20001 --dry-run
+qmai store move-team --shop-id 10001 --team-id 20001
+```
+
+## 门店信息同步
+
+推荐使用 JSON 文件：
+
+```bash
+qmai store sync --from-json shop.json --dry-run
+qmai store sync --from-json shop.json
+```
+
+`shop.json` 最少应包含：
+
+```json
+{
+  "name": "测试门店",
+  "provinceId": 310000,
+  "cityId": 310100,
+  "districtId": 310101,
+  "lat": "31.2304",
+  "lng": "121.4737",
+  "managerStatus": 1
+}
+```
+
+注意：
+- `sync` 副作用大，先 `--dry-run`
+- `shopInfoSync` 字段很多，避免直接在命令行拼长 JSON
+- 提交成功不等于立即可查到变更结果