ERP商家备货清单

概述

快递助手ERP备货单生成

将商家保存的备货标准转成一次可核验的订单需求汇总，输出仓库可使用的 ERP SKU 拣货清单。只处理“当前订单要备什么、备多少”，不做采购预测，也不执行订单、库存、采购、打印或发货写操作。

快速开始

注册快递助手 ERP

如果商家还没有注册快递助手 ERP，请先完成注册：

注册链接：https://erp.kuaidizs.cn/index.html#/login?source=kfpt

注册完成后，才能使用开放平台 API 能力。

安装前提

本技能依赖 kdzs-erp-api-connector（快递助手开放平台 API 连接器）。安装本技能前，请先安装连接器：

skillhub install https://kdzs-open.oss-cn-zhangjiakou.aliyuncs.com/doc-center/sdk/kdzs-erp-api-connector.zip

如果 skillhub install 不支持 zip 地址，可手动下载安装：

1. 下载：https://kdzs-open.oss-cn-zhangjiakou.aliyuncs.com/doc-center/sdk/kdzs-erp-api-connector.zip
2. 解压到技能目录

配置开放平台凭证

1. 登录快递助手 ERP，进入 设置 → API 开放平台
2. 获取 appKey 和 appSecret
3. 将凭证保存到配置文件：

# 创建配置目录
mkdir -p ~/.kdzscli

# 创建配置文件
cat > ~/.kdzscli/config.json << 'EOF'
{
  "appKey": "你的appKey",
  "appSecret": "你的appSecret",
  "serverUrl": "https://gw.kuaidizs.cn/router"
}
EOF

安全提示：不要将凭证写入聊天记录、日志或分享给他人。

第一次使用

安装并配置完成后，直接对 AI 说：

"帮我生成今天待发货订单的备货单"

AI 会：

1. 检查凭证配置和接口连通性
2. 询问你确认备货标准（时间范围、订单状态、退款口径等）
3. 创建备货查询任务并等待结果
4. 输出仓库可用的拣货清单

日常使用示例

按默认标准生成备货单：

"按日常标准生成备货单"

按自定义时间范围：

"帮我汇总昨天下午 2 点到今天上午 10 点付款的待发货订单"

按店铺筛选：

"只看抖音店铺今天的待发货订单要备多少货"

按早班/晚班轮次：

"按早班标准生成备货单"（需先保存早班标准）

输出结果说明

成功执行后，你会看到：

## 备货结果
- 备货标准：日常待发货备货
- 统计范围：2026-09-08 00:00:00 至 14:30:00（付款时间）
- 订单状态：待发货
- 退款口径：不含退款中或退款完成商品
- 订单总数：47
- 需备货总件数：186

| # | 货品 | 规格 | SKU编码 | 条码 | 颜色/尺码 | 仓位 | 需备数量 |
|---|---|---|---|---|---|---|---:|
| 1 | 夏季防晒衣 | 白色 XL | SKU001 | 6901234567890 | 白色 / XL | A-01-02 | 23 |
| 2 | 夏季防晒衣 | 白色 L | SKU002 | 6901234567891 | 白色 / L | A-01-03 | 18 |
...

常见问题

Q: 提示"凭证未配置"怎么办？A: 检查 ~/.kdzscli/config.json 是否存在，appKey 和 appSecret 是否正确填写。

Q: 提示"当前账号已有备货单生成任务"怎么办？A: 同一账号同时只能运行一个备货任务。等待上一个任务完成后再试，或联系管理员检查是否有未完成的任务。

Q: 结果为空，显示"未返回需备货商品"？A: 可能是当前时间范围内没有符合条件的订单。检查时间范围、订单状态是否正确，或尝试扩大时间范围。

Q: 支持淘宝/拼多多吗？A: 当前开放平台不支持淘宝、天猫、1688、淘工厂和拼多多的数据查询。仅支持抖音、京东、快手、视频号、小红书等已授权平台。

Q: 可以自动创建采购单吗？A: 本技能只生成拣货清单，不执行采购、订单、库存等写操作。如需采购建议，请使用"以销定采爆品补货"技能。

When to Use

适用于：

• “按日常标准生成今天待发货订单的备货单。”
• “按早班标准汇总今天上午付款订单要备多少货。”
• “只看指定店铺/支持平台的待发货SKU需求。”
• “按 ERP 货品维度输出拣货清单。”

不适用于：

• 未来采购数量、爆品预测或库存补货；使用“以销定采爆品补货”。
• 修改订单、锁库存、打印、发货、创建采购单或 ERP 内业务单据。
• 淘宝、天猫、1688、淘工厂、拼多多的数据查询；当前开放平台不支持。

交付结果

一次成功运行必须交付以下可复核结果：

1. 备货范围：标准名、起止时间、时间类型、订单状态、退款口径、店铺/平台筛选和聚合维度。
2. 总览：接口返回的订单总数 tradeTotal、需备总件数 totalCount、任务 ID 与完成状态。
3. 拣货清单：按 ERP SKU（默认）或平台SKU汇总的需求数量；ERP维度尽量带出条码、颜色、尺码、仓位。
4. 数据限制：未覆盖的平台、缺失字段、空结果或服务端状态。

空结果必须写“当前标准下未返回需备货商品”，不能推断为“没有订单”。如果商家确认 ERP 页面存在订单，则标记为“页面与备货接口结果不一致”，记录任务与请求证据后停止试探性查询。

Trust：权限与数据保护

• 仅调用只读接口：stock.list、stockup.task.create、stockup.task.get，必要时调用只读货品查询；其中“创建任务”仅启动查询型异步聚合，不产生 ERP 业务单据或库存变更。
• 禁止调用采购创建、订单修改、库存调整、打印和发货接口。
• 凭证仅从受控配置读取；不在聊天、日志、方案、输出或发布包中写入 appSecret、Token、Session、签名、买家地址或手机号。
• SkillHub 发布副本不得包含配置文件、Token 缓存、真实请求结果或商家数据。

备货标准

商家可保存多个标准。标准字段及有效值如下：

首次未保存标准时，使用以下初始预设，并请商家确认后再保存：

名称：日常待发货备货
时间：当天 00:00:00 至执行时刻
时间类型：付款时间（1）
订单状态：待发货（WAIT_SELLER_SEND_GOODS）
退款口径：不含退款中或退款完成商品（1）
维度：ERP货品（0）
排序：需备数量从高到低

若用户只说“今日订单”但未指明时间类型或订单状态，必须询问，不能自行选择。多轮次标准的时间范围必须互不重叠；否则不得合并结果，也要提示可能重复备货。

Prerequisites

1. 加载 kdzs-erp-api-connector，以其接口契约、认证与错误处理规则为准。
2. 检查商家自己的开放平台凭证已在受控配置中设置；不要求其在聊天内发送密钥。
3. 先调用 kdzs.erp.api.stock.list，参数 {"pageNo":1,"pageSize":1} 做连通性验证。仅当 code=200 且 data.success=true 时执行备货任务。
4. 读取已保存标准或完成本次标准确认。

Procedure

1. 校验输入与边界

校验时间格式、起止顺序、timeType、status、refundStatus、queryVision 和可选筛选是否符合接口枚举；检查平台是否在开放平台支持范围内。

• 无效/缺失：指出具体字段、可选值和需要补充的信息。
• 不支持平台：停止并说明平台限制。
• ALL_STATUS：仅可称“备货需求估算”；未做订单级验证时不得与其他状态任务合并。

完成标准：获得一个参数完整、范围可追溯且不与已合并轮次重叠的标准。

2. 验证只读连通性

通过连接器执行库存只读验证。若返回失败，原样提供服务端的 code、message 和可用错误信息，停止；不改参数重试。

完成标准：code=200 且 data.success=true。

3. 创建一个备货查询任务

调用：

kdzs.erp.api.trade.stockup.task.create

必传参数：queryVision、status、refundStatus、startTime、endTime、timeType。保存返回的唯一 taskId。

同一账号最大并发为 1：收到 1003:当前账号已有备货单生成任务，请稍后重试 时，原样反馈并停止；不得创建第二个任务、并行任务或用新参数绕过。

完成标准：得到唯一 taskId，状态为 PROCESSING 或 SUCCESS。

4. 轮询同一任务并处理异常

只调用：

kdzs.erp.api.trade.stockup.task.get

并只传上一步 taskId：

完成标准：取得一个 SUCCESS 结果，或清晰地报告未完成/失败状态。

5. 校验、聚合与排序

• 结果必须来自同一个 taskId，且使用返回的 queryVision 校验与请求一致。
• ERP维度：以 sysSkuId 为SKU键，使用 skuList[].count；同一SKU重复行求和，明细缺 sysSkuId 时列入异常而不猜测。
• 平台维度：以店铺 + skuId 作为展示键；不得把多个平台SKU直接等同于不同 ERP 库存需求。
• tradeTotal 与 totalCount 原样展示；将脱敏的成功响应写入临时 JSON 后，运行 terminal(command="python3 {SKILL_DIR}/scripts/validate_stockup_result.py --input <response.json>") 校验SKU聚合。输出 consistent=false、rowsMissingSkuKey>0 或无法校验时标记“结果待核对”，不得声称明细完整。
• 排序仅改变展示顺序，不改变接口计数；若请求按仓位排序但仓位缺失，回退为数量降序并标记。

完成标准：每一行都有明确来源字段、数量和异常标记，且总数核验结论明确。

6. 输出仓库可用结果

默认使用 ERP 货品维度、数量降序：

## 备货结果
- 备货标准：<名称>
- 统计范围：<开始> 至 <结束>（<付款/发货/创建/结束时间>）
- 订单状态：<状态>
- 退款口径：<口径>
- 覆盖范围：<店铺/平台/筛选条件及未覆盖说明>
- 任务状态：SUCCESS（taskId：<taskId>）
- 订单总数：<tradeTotal>
- 需备货总件数：<totalCount>
- 明细校验：<一致 / 待核对及原因>

| # | 货品 | 规格 | SKU编码 | 条码 | 颜色/尺码 | 仓位 | 需备数量 |
|---|---|---|---|---|---|---|---:|

字段缺失填“待补充”，不猜测。平台维度结果必须注明“用于店铺核对，不建议作为仓库唯一拣货依据”。

Reliability：失败与边界处理

Adaptability：调用与反调用信号

应触发：当前订单、待发货、备货、拣货、配货、SKU汇总、早班/晚班备货、指定店铺或支持平台订单需求。

不应触发：采购计划、断货预测、销量趋势、库存水位、毛利分析、售后/物流巡检、订单执行操作。

商家如果需要未来采购建议，转用“以销定采爆品补货”；如果需要实际发货或打印，说明当前版本仅提供清单，不执行操作。

Convention：维护与发布规范

• 版本遵循语义化版本号；范围或默认口径变更时更新版本与变更说明。
• API 字段与枚举只引用连接器已定义的契约；不在本技能复制密钥、网关或签名实现。
• 发布包保持最小化：SKILL.md、无敏感信息的引用/模板/脚本；禁止包含配置、缓存、日志、商家数据和本机绝对路径。
• 修改任务编排、默认标准、输出结构或安全边界后，必须更新示例和验收清单。

Effectiveness：验收用例

发布前至少在测试环境或已授权的非敏感样本上逐项验证，并记录不含敏感数据的结果。验证记录使用 references/trace-validation.md；未实际通过的用例必须标为“待验证”，不得写成已通过。

发布检查清单

• [ ] 不包含密钥、Token、Session、商家订单或本机配置
• [ ] 所有接口均是已授权的只读查询/查询任务接口
• [ ] 触发场景、反场景和输出结构明确
• [ ] 正常、空结果、处理中、失败、并发冲突、不一致均有确定行为
• [ ] 至少完成上述 7 个验收用例或明确记录未通过项
• [ ] SkillHub 发布副本已通过密钥扫描与 skillhub publish --dry-run --json