妙手ERP-公共采集箱管理

概述

妙手 ERP 公共采集箱增删改查

使用本技能管理已存在于妙手 ERP 公共采集箱中的商品。支持只读查询以及通过妙手 ERP 开放平台进行新增、编辑和删除操作。

首次使用就绪检查

在执行任何 API 操作之前，请验证本地运行环境和凭证：

cd {base_dir}
python -m pip install -r requirements.txt
python scripts/collectbox_crud.py doctor

如果 python 不可用，请请用户安装 Python 或使用可用的 Python 运行时路径，然后使用该可执行文件重新运行相同命令。

通过以下方式之一配置凭证：

• 复制 resources/config.json.example 为 resources/config.json，填入 app_key 和 app_secret。
• 或在环境中设置 MIAOSHOU_APP_KEY 和 MIAOSHOU_APP_SECRET。
• 可选设置 MIAOSHOU_BASE_URL；否则脚本使用 https://openapi-erp.91miaoshou.com。

本地检查通过后，可选执行只读连通性检查：

python scripts/collectbox_crud.py doctor --check-api

请勿要求用户在聊天中粘贴 AppSecret。使用本地配置、环境变量或安全的主机连接器。

适用范围

本技能仅用于公共采集箱记录。

支持的操作：

• 查询商品列表或商品详情。
• 新增公共采集箱商品。
• 编辑 SPU 字段，如标题、价格、库存、重量、尺寸、图片和备注。
• 编辑 SKU 字段，如 SKU 价格、库存、商家编码、重量和属性值。
• 删除商品或在 API 支持时移除选定的商品资产。

请勿使用本技能采集供应商/货源 URL、编辑认领后的平台专属采集箱或发布商品。如有可用的 miaoshou-erp-source-import，请将货源 URL 采集路由到该技能。对于 Shopee 认领后的操作，请将平台专属工作路由到 Shopee 类目、尺码表、采集箱编辑、全球商品管理或发布技能。

安全分级

核心安全规则

• 切勿根据模糊指令执行新增、编辑或删除操作。
• 每次编辑或删除前都应查询当前商品详情。
• 写入前展示当前值、目标值、受影响字段和验证风险。
• 批量操作时，展示涉及的商品数量和商品 ID。
• 删除操作时，要求确认信息中包含精确的商品 ID。
• 不要打印签名请求头、AppSecret 或含凭证的请求。
• API 出错时停止操作，并清晰报告部分成功/失败的情况。

标准工作流程

1. 将请求分类为查询、新增、编辑、删除或批量操作。
2. 收集所需的 ID、目标字段和目标值。
3. 如果是首次使用或环境已变更，运行就绪检查。
4. 写入前对每个受影响的商品查询当前商品详情。
5. 构建变更计划，包含商品 ID、标题、当前值、目标值、受影响字段和风险。
6. 新增/编辑/删除前请求明确确认。
7. 执行脚本或 API 调用。
8. 按商品报告结果，区分成功、跳过和失败的商品。

业务规则

保存前查询关联字段

不要仅查询用户想修改的字段。部分 API 验证依赖于关联字段。

已知验证规则：库存值超过 99999 可能阻止保存操作。如果当前 SPU/SKU/原始库存超过此限制，应提示风险并询问是修正、跳过还是取消。

保留完整 SKU 记录

编辑 skuMap 时，不要仅提交修改的字段。保留详情 API 返回的所有必填 SKU 字段。

正确格式：

{
  "price": 71.28,
  "stock": 99999,
  "oriPrice": 80.0,
  "oriStock": 99999,
  "itemNum": "SKU-RED-S",
  "weight": 0.3
}

错误格式：

{
  "price": 71.28
}

一次性展示风险

查询商品详情后，在一个预览中汇总所有检测到的风险：

• 当前值。
• 拟修改值。
• 关联字段风险。
• 将保留或修正的字段。
• 确认选项。

API 授权

在调用妙手 ERP 开放平台 API 之前，请确认客户已拥有通过审核的开放平台应用。

1. 客户在妙手 ERP 开放平台创建并提交应用。
2. 客户通过本地配置或安全连接器提供 AppKey 和 AppSecret。
3. 如果启用了账号级 IP 白名单，请确认当前机器或主机已在白名单中。
4. 每个 API 请求必须是 POST 方法，包含 Content-Type: application/json 和签名请求头：x-app-key、x-timestamp 和 x-sign。

签名规则：

base_url = https://openapi-erp.91miaoshou.com
sign = HmacSHA256(appSecret, appSecret + path + timestamp + appKey + bodyJson + appSecret)

重要细节：

• path 仅为 API 路径，例如 /open/v1/order/create。
• timestamp 为秒级 Unix 时间戳。时钟偏移超过 300 秒后请求将过期。
• bodyJson 必须是 POST 请求体中发送的精确 JSON 字符串。
• x-sign 为小写十六进制 HmacSHA256 输出。

请按以下错误码处理授权错误：signMissing、signExpired、signInvalid、appNotFound、appNoPermission 和 ipNotInWhitelist。

命令行工具

使用 scripts/collectbox_crud.py 进行确定性操作：

python scripts/collectbox_crud.py doctor
python scripts/collectbox_crud.py doctor --check-api
python scripts/collectbox_crud.py list --status noClaimed --page 1 --size 20
python scripts/collectbox_crud.py detail --id 12345
python scripts/collectbox_crud.py add --data '{"title":"Test Product","price":19.99,"stock":100}'
python scripts/collectbox_crud.py edit --id 12345 --data '{"price":69.8}'
python scripts/collectbox_crud.py delete --ids 12345,12346

如果内置脚本不可用，可通过主机 HTTP 客户端或连接器调用文档中记录的 API 接口。

确认模板

编辑确认：

请确认修改计划：
- 商品ID：12345
- 标题：示例商品
- 修改字段：price
- 当前值：64.80
- 目标值：69.80
- 关联检查：SPU库存=99999，SKU库存未超限
- 不修改字段：标题、图片、类目、SKU属性

确认后才会写入。请回复"确认修改"或"取消"。

删除确认：

请确认删除计划：
- 删除商品数：3
- 商品ID：12345, 12346, 12347
- 操作结果：从公共采集箱删除，可能不可撤销

请回复"确认删除 12345,12346,12347"后再执行。

API 参考

详细的接口行为、字段定义和请求体结构请参见 references/api_reference.md。在执行重要的新增、编辑、SKU 或删除操作前请加载该文档。

错误处理

• 验证错误：识别阻断字段和当前值。
• 批量部分失败：分别报告成功、失败和跳过的商品。
• 库存超限错误：建议修正超限库存或跳过受影响的 SKU/商品。
• 签名/授权错误：检查本地配置或连接器；不要暴露密钥。
• 未知 API 响应：停止并展示上游消息；不要继续执行额外的写操作。

关联技能