妙手 ERP 货源采集

将货源商品链接采集到妙手 ERP 公共采集箱，并返回已采集商品的映射关系，供后续流程使用。

典型用户请求

"帮我采集这个 1688 链接到公共采集箱"
"把这批 AliExpress 商品链接导入妙手ERP"
"采集这些货源链接，成功后给我 detailId"
"把这几个供应商商品抓到公共采集箱"
"批量采集下面 10 个链接"
"采集完之后帮我认领到 TikTok"

适用范围

本技能用于将货源链接导入公共采集箱。不应自行编辑、认领或发布商品。

采集成功后，返回的公共采集箱详情 ID 可用于以下后续操作：

miaoshou-erp-common-collectbox-manage：查询/编辑。
miaoshou-erp-product-claim：平台认领。
miaoshou-erp-tiktok-product-edit：TikTok 认领后编辑。

安全分级

采集属于写/导入操作，因为它会在 ERP 采集箱中创建商品记录。提交 URL 前需要用户确认。

安全规则

仅提交完整的商品详情 URL。
未经澄清前，请勿提交搜索页、分类页、店铺页、短链接或含义不明的 URL。
调用 API 前应展示链接数量和来源域名。
不要在本技能中编辑已采集的商品内容。
不要要求用户在聊天中粘贴 cookies、token、密码或密钥。
凭证必须来自本地配置、环境变量或主机连接器。
除非用户明确说明处于测试环境，否则请勿在生产环境中使用仅限测试的请求头。

API 授权（必需）

在调用妙手 ERP 开放平台 API 之前，请确保客户已通过审核的开放平台应用授权本技能。

请客户登录妙手 ERP，打开「开放平台」，创建应用，提交审核，审核通过后方可使用。
获取应用凭证：AppKey 和 AppSecret。客户可通过本地配置或安全的主机连接器提供。请勿要求客户在聊天中直接粘贴 AppSecret。
通过以下方式之一配置凭证：
- 复制 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。
- 如果接口需要账号级或主机注入的认证上下文，通过本地配置或环境变量 MIAOSHOU_ACCOUNT_ID、MIAOSHOU_AUTHORIZATION 和 MIAOSHOU_COOKIE 提供 account_id、authorization 或 cookie。
如果客户启用了账号级 IP 白名单，请确认运行本技能的机器或主机已在该白名单中。白名单在同一妙手账号下的所有应用间共享。
每个 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 输出。
切勿在最终回复或日志中打印 AppSecret、签名请求头或含凭证的完整请求。

如果授权失败，请按以下错误码处理：signMissing 表示缺少请求头，signExpired 表示本地时钟或秒级时间戳问题，signInvalid 表示签名/请求体/路径/密钥不匹配，appNotFound 表示 App Key 错误、已禁用或未通过审核，appNoPermission 表示应用缺少接口权限，ipNotInWhitelist 表示调用方 IP 不被允许。

标准工作流程

从用户请求中提取 URL。
去重并保持原始顺序。
验证 URL 格式并识别来源域名。
请用户确认采集计划。
确认后调用 fetch_item API。
展示返回的 sourceItemIdAndDetailIdMap。
询问用户是否需要查询、编辑或认领已采集的商品。

脚本工作流程

使用内置 Python 脚本进行可重复的 URL 解析、验证、签名和 API 提交。

在请求确认前预览请求：

python scripts/source_import.py preview --text "<包含货源链接的用户文本>"

从文件预览链接：

python scripts/source_import.py preview --input links.txt --json

用户明确确认采集后，方可提交：

python scripts/source_import.py fetch --text "<已确认的货源链接>" --confirm

如果输入包含混合的有效和无效链接，默认不提交。询问用户是修复无效链接还是跳过。仅当用户明确选择跳过无效链接后，才使用 --ignore-invalid。

检查本地配置而不提交商品：

python scripts/check_config.py

脚本从 resources/config.json 或环境变量读取凭证。脚本不会打印 AppSecret、签名请求头的值、cookies 或 authorization 值。

确认模板

请确认采集计划：
- 链接数量：N
- 来源域名：1688.com, aliexpress.com
- 目标位置：妙手ERP公共采集箱
- 不会执行：编辑、认领、发布

确认后才会提交采集。请回复"确认采集"或"取消"。

场景处理

| 场景 | 预期行为 | | --- | --- | | 用户提供有效的商品详情 URL | 预览域名和数量，确认后采集 | | 用户提供混合的有效和无效链接 | 分开有效/无效链接，询问如何处理 | | 用户提供供应商店铺页面 | 要求提供商品详情 URL | | 用户想在采集后认领 | 先采集，再将成功的详情 ID 传递给认领技能 | | API 返回部分成功 | 分别展示成功的映射和失败的 URL/商品 |

API 概要

接口：POST /open/v1/product/common_collect_box/common_collect_box/fetch_item
请求字段：collectLinks
响应字段：sourceItemIdAndDetailIdMap

请求示例：

{
  "collectLinks": [
    "https://www.1688.com/product/example.html",
    "https://www.aliexpress.com/item/example.html"
  ]
}

详细的请求头、请求体、响应和数据流转说明请参见 references/api-spec.md。

错误处理

无效 URL：要求提供商品详情页链接。
重复 URL：仅提交一次并报告去重情况。
授权错误：检查本地凭证；不要暴露密钥。
空响应或超时：报告网络/服务风险，未经用户同意不要重复提交。

URL 验证说明

查询参数名称不区分大小写。例如，1688 可能使用 offerId，标准化验证时应比较 offerid。
不要仅因为 URL 包含 spm 等跟踪参数就拒绝商品详情 URL。
对于 1688，接受已识别的 /offer/{id}.html、/product/... 格式，或包含 offerId/offerid 商品标识符的 URL，除非该 URL 明显是搜索、分类、店铺或供应商页面。

配置

使用环境变量或主机提供的凭证。请勿分发真实的 cookies、token 或 resources/config.json。

脚本使用

使用 scripts/source_collect.py 作为标准可执行入口。通过 --urls 传递商品详情链接；支持一个或多个 1688、AliExpress、淘宝、天猫、拼多多或已识别的供应商商品 URL。

确认前预览和验证链接：

python scripts/source_collect.py --urls "https://detail.1688.com/offer/123456789.html" "https://www.aliexpress.com/item/100500.html"