妙手ERP-TikTok产品发布

概述

妙手ERP TikTok发布

在商品数据就绪后将 TikTok 采集箱商品发布到 TikTok 店铺。此技能是最终工作流步骤，不应静默编辑商品数据。

典型用户请求

• "把商品 12345 发布到 TikTok 店铺 1001"
• "检查这些 TK 商品能不能发布"
• "列出待发布商品"
• "帮我发布这批 TikTok 采集箱商品"
• "商品还没认领到店铺，先认领再发布"
• "发布后告诉我哪些成功哪些失败"

适用范围

此技能用于：

• 查询 TikTok 店铺。
• 列出待发布或尚未发布的商品。
• 检查商品是否已关联目标店铺。
• 验证发布就绪状态。
• 确认后提交发布任务。
• 报告任务提交结果和最终状态限制。

不适用于以下操作：

• 自动编辑标题、描述、价格、库存、SKU、类目或属性。
• 编造仓库、责任人、制造商、认证或合规数据。
• 未经确认的商品/店铺计划直接发布。

安全分级

发布是高影响写操作。它会将商品数据提交到 TikTok 店铺并影响店铺上架状态。始终需要用户明确确认。

若发布前需要认领，认领也是写操作，需要单独确认。

核心安全规则

• 在确认精确的 detailIds、目标 shopIds 和发布计划前，不得发布。
• 发布过程中不得自动修复商品数据。
• 若就绪检查未通过，停止并引导用户使用 miaoshou-erp-tiktok-product-edit。
• 若商品未关联目标店铺，询问是否先进行认领。
• 不得编造或选择受监管/合规字段。
• 如实报告异步发布处理状态。
• 不得要求用户在对话中粘贴密钥。
• 不得打印签名请求头或包含凭证的请求数据。

API 鉴权（必需）

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

1. 请客户登录妙手ERP，打开「开放平台」，创建应用，提交审核，审核通过后方可使用。
2. 获取应用凭证：AppKey 和 AppSecret。客户可通过本地配置或安全主机连接器提供。不要要求客户在对话中直接粘贴 AppSecret。
3. 通过以下方式之一配置凭证：
   • 将 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。
4. 若客户已开启账号级 IP 白名单，确认运行此技能的机器或主机在该白名单中。白名单由同一妙手账号下所有应用共享。
5. 每个 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 不被允许。

标准工作流

1. 查询 TikTok 店铺并确定目标 shopIds。
2. 列出候选商品或查询指定的 detailIds。
3. 检查每个商品是否已关联目标店铺。
4. 执行发布就绪检查：
   • 类目。
   • 必填商品属性。
   • 必填销售属性和 SKU 值。
   • 价格和库存。
   • SKU 重量。
   • 包裹尺寸。
   • 仓库。
   • 元数据要求时的制造商/认证/责任人/合规字段。
5. 若未就绪，停止并说明缺失字段。
6. 若需要认领，展示认领确认计划，仅在确认后执行。
7. 展示最终发布确认计划。
8. 仅在明确确认后提交发布。
9. 分别报告已提交、失败、跳过和待处理的商品。
10. 说明最终状态是即时返回还是服务器异步处理。

确认模板

请确认 TikTok 发布计划：
- 商品ID：12345, 12346
- 目标店铺ID：1001
- 商品已关联目标店铺：是
- 发布前检查：类目、必填属性、SKU、价格、库存、重量、包裹尺寸均已通过
- 不会执行：自动改标题、改价格、改库存、补合规信息
- 说明：服务器可能异步处理发布任务，提交后需再次查询最终状态

确认后才会发布。请回复"确认发布"或"取消"。

发布前认领模板：

商品尚未关联目标店铺，发布前需要先认领到店铺：
- 商品ID：12345
- 目标店铺ID：1001

认领和发布是两个独立写操作。请先确认是否执行认领。

场景处理

常用命令

若内置脚本可用：

python {base_dir}/scripts/tiktok_publish.py shops
python {base_dir}/scripts/tiktok_publish.py list-products
python {base_dir}/scripts/tiktok_publish.py claim --detail-ids 12345 --shop-ids 1001
python {base_dir}/scripts/tiktok_publish.py publish --detail-ids 12345 --shop-ids 1001
python {base_dir}/scripts/tiktok_publish.py categories --site US
python {base_dir}/scripts/tiktok_publish.py attributes --site US --cid 12345 --shop-ids 1001
python {base_dir}/scripts/tiktok_publish.py warehouses --shop-ids 1001
python {base_dir}/scripts/tiktok_publish.py responsible-persons --shop-id 1001

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

发布就绪检查详情

API 参考

详细的接口行为见 references/api_reference.md，包括：

• 类目树。
• 类目元数据。
• 仓库列表。
• 责任人列表。
• 认领到店铺。
• 提交发布任务。

失败处理

• 缺少目标店铺：查询店铺并请用户选择。
• 必填字段缺失：停止；不发布。
• API 错误：展示错误码/消息和受影响的 ID。
• 部分成功：区分已提交、跳过和失败的商品。
• 异步状态：说明提交成功但最终发布状态需稍后查询。
• 反复失败：未经用户指示不持续重试写操作。

相关技能

配置

使用 resources/config.json.example 作为本地配置模板。不要分发真实的 resources/config.json。