# Influencer Exchange Order

> 🔴🔴 最高优先级铁律：API Key 禁止手抄，必须程序化读取（2026-08-26，吴双明确批评，务必遵行）

- Skill: `nana7536/influencer-exchange-order` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add nana7536/influencer-exchange-order`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nana7536/influencer-exchange-order/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: nana7536 (https://skillmd.com/u/nana7536)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nana7536/influencer-exchange-order

---


## 🔴🔴 最高优先级铁律：API Key 禁止手抄，必须程序化读取（2026-08-26，吴双明确批评，务必遵行）

**简道云 Open API Key 任何情况下都不得在命令/脚本里手打一个字面量。** 必须从本技能目录、不受版本控制的 `credentials.local.md` 中程序化读取后带入请求。

- **为什么**：Key 是一长串无规律字符，手抄极易漏/错，简道云会报假象 `17018 API key is invalid`，让人误以为 Key 失效/被轮换。根因通常在抄写，不在 Key。
- **正确做法（写进每一步）**：Python 里从 `credentials.local.md` 用正则读取产品生命周期或网红管理 App 的 Key；或 shell 中从同一文件提取后赋给变量。**绝不打字面量。**

依赖技能：`jdy-shipping-track`（共用其 watchlist.md 文件路径，两个技能各自独立运行，不共享cron）

> **Open API boundary:** Create and update work orders with Jiandaoyun Open API v5, using the
> App-specific key from this skill's `credentials.local.md`. Do not substitute the `member_data_create` MCP
> tool for this workflow: it uses a different authorization path and is not the proven work-order
> creation route.

> 🌐 **多语言（v1.2.0，2026-08-12）**：部门含中外籍成员。本技能的交付说明、对用户的提示、日志**语言跟随使用者**——中文使用者用中文，英文使用者用英文。对外内容（KOL 相关、发往外部）一律英文；技术标识（SKU、RMA、字段名、命令）保持原文不翻译。给简道云的提交字段值（如 SKU 中文名称、地址）必须用简体中文原值，不受内部语言偏好影响。


## ⚠️ Identity resolution — 每次运行第一步（v1.2.0，部门共用版）

本技能从 v1.2.0 起改为**部门共用**：不再硬编码任何个人身份。**每次运行开头，先解析"当前用户是谁"**：

1. `lark-cli contact +search-user --user-ids me --as user --format json` → 当前用户的 `open_id`（和姓名）
2. 读名册表：`lark-cli base +record-list --base-token UGuHbNi6GapDwTs9kdUcUGZPnzS --table-id tblfDTCs6XeMPefA --as user --format json`（部门成员表，字段：姓名 / JDY Username / Feishu Open ID / 启用）
3. 用当前 open_id 匹配名册的 `Feishu Open ID` → 得到 **当前用户姓名** 和 **当前用户 JDY Username**
4. 名册无此 open_id，或该行 `启用`=false → 停止并告知用户"你的账号尚未加入品牌部工单/发货系统，请联系管理员（吴双）在部门成员表启用"
5. 后续所有需要"提交人 / 提出人"的字段（`_widget_1774861977528` 单个工单提交人、`_widget_1780972277486` 发货管理提出人）**一律填当前用户自己的 JDY Username**，绝不硬编码为任何固定成员（旧版写死单个 username 的做法是吴双单人时代的遗留，已废弃）

**🔴 简道云 MCP 工具前缀动态解析（硬规则，2026-08-26 强化）**：JDY MCP 工具前缀（`mcp__<random>__...`）每次重连都会变，**绝不用记忆里的旧前缀，也绝不猜测**。每次调用前：
1. 看当前 turn 的 deferred tools 列表 / system 提示里列出的**本次真实可用前缀**（如 `mcp__0HD-u86s20h3DuwbDikoX__`），直接照抄该前缀 + 工具名；
2. 如果不确定当前会话的前缀，先触发一次已知工具（如 `member_data_list`）看返回值/报错里是否带可用前缀，或检查 session tools 列表；
3. **反模式**：凭记忆填一个旧前缀（`mcp__0H...` 之类），或把前缀手打成乱七八糟的字母——这是我这段时间频繁 `No such tool available` 报错的根源（Anna 单子 / Noelle 建单都因为这废了好多次调用）。
4. 用错一次就停下来：若报 `No such tool`，不要在同一 old prefix 上重试，先回本规则确认正确前缀再继续。


## 所需信息

从用户对话中提取：

1. **网红名称**（平台单号字段使用；口语化代号/绰号要先跟用户核实成正式姓名，如"er1khung"→"Erik Hung"）
2. **工单类型**：换货 / 催发货 / 催派 / 新增订单
3. **明细**：
   - 换货：原SKU → 新SKU，数量（默认1件）。**⚠️ 前后SKU必须不同**——简道云系统会判定"前后SKU相同"的换货工单为失败（2026-07-23 Ahmed Saleh - 内收外展A箱黑案例已验证：换货前后都填RF-COUGAR-BLKA-KLK01，系统直接判定换货失败）。如果用户诉求本质是"重新补发同一个SKU"（比如原箱一直卡在虚拟发货没出真实追踪号，产品本身没有新版本），**应该改用催发货工单，不要用换货**，即使用户一开始说的是"换货"。判断依据：先按第0步核实该SKU是否真的有更新版本；确认没有更新版本、纯粹是要求重发同一SKU时，直接选催发货类型（子表单填 fo_oder=原发货单的fororder_no，quantity=1，状态="已发货"），不要再走换货流程。**⚠️ 换货/新增/补发都必须同时查好SKU中文名称（见"SKU信息表查询"一节），原SKU和换货后SKU各自的中文名称都要填，否则简道云无法执行（2026-07-27技术团队反馈，见第五步末尾说明）。**
   - 新增订单：产品名称/型号 → 需要转成真实SKU编码（见第0步），数量（默认1件；如产品拆多箱发货，每箱各占子表单一行，各默认1件），SKU中文名称同样必填
4. **简道云API Key**：运行时从本技能目录内的 `credentials.local.md` 读取对应 App 的专属 Key；该文件仅保存在本机且已被 Git 忽略。**产品生命周期 App 和网红管理 App 各有一个 Key，不能混用**。文件不存在时，停止并请管理员通过安全渠道完成本机配置；不落盘存明文于 SKILL.md。

**⚠️ 判断"最新SKU"不能只看版本号数字（2026-07-27 Daniel O'Connor - GPro/BWB案例）**：用户说"换成最新的sku"时，别只凭SKU命名里的版本号（如1.1版/1.2版/1.4版）猜哪个更新——版本号更高的不一定是当前真正在用、有库存的那个。正确方法：
1. 去**执行工单**查该SKU近期是否有失败的催发货/换货记录，看`kucun`（库存）和`error`字段是否显示"库存不足/库存数据异常或不存在"——库存为0或报错的SKU即使版本号更新，也不是能用的"最新SKU"。
2. 搜同一SKU家族近期（最好含当天/近几天）其他KOL的真实成功发货记录（`执行工单`按SKU家族关键词搜，看`status`="已发货"+真实`trackno`），确认哪个SKU组合仍在被持续正常使用、库存充足。
3. 两者结合给出的结论，比单看命名里的版本号可靠得多。真实案例：`RF-BWB035070-BLK-CY05`标注"1.4版"看起来比`RF-BWB035070-BLK-JH02`"1.1版"更新，但CY05库存=0且历史上从未真正发出过；JH02库存1140+且当天仍在正常发货，最终确认JH02才是真正的"最新可用SKU"。

**⚠️ 换货导致箱数增加（如3箱→4箱）时，多出的箱子没有"旧SKU"可填，拆成两个工单**：不要在换货子表单里编造一个假的"原SKU"凑数。有对应旧箱的走正常"换货"（旧SKU→新SKU，沿用原平台单号）；多出的新箱单独开一张"新增订单"（平台单号按"网红名-产品标识"命名），因为它是全新单号，记得按第七步给它手动建一条对应的「发货管理」记录（换货那张沿用原PO本来就有发货管理记录，不需要再建）。

## 工作流程

### 第一步：确认网红身份 & 收件信息

先查 **网红信息** 表（app_id `685a468345ade02b47318ca9`，entry_id `685a4688ff01bd47de8c32a7`），按网红名称搜索；同时查飞书 Base **ALL KOLs**（`tblBqCCxHRtFvS9E`，字段 `KOL Name`）。

获取以下字段：
- 网红ID（_widget_1750747331716）
- 收件人姓名（_widget_1751246637939）
- 收件电话（_widget_1751246637940）
- 收件地址（_widget_1751246637941）
- 品牌（_widget_1754984300105）

从地址中解析出省/州、城市、邮编。

**两处都查不到** → 说明是尚未登记的网红，直接问用户要：收件人姓名、电话、详细地址、城市、省/州、邮编（国家默认美国需确认）。不必强制打断流程去要求先登记 ALL KOLs / 网红信息，除非用户主动要求登记。

### 第二步：核对历史地址（如果该网红之前走过工单流程）

⚠️ **不要去"发货管理"表核对地址**——那张表只存 SKU/物流跟踪信息，**不存地址字段**，查了也白查。

正确做法：去 **产品生命周期** 应用的 **执行工单**（即简道云前端标题显示为"工单处理结果-网红管理"）表单核对：
- app_id: `66d696158e78f315b2476b1b`
- entry_id: `69ca3653e80a04d0ebe03a38`
- 按网红名称/历史PO号全字段搜索（`source_order_no` 平台单号字段，或全字段模糊搜索）

如果搜到历史记录，直接读取该记录里的地址字段做比对（无需真的点前端"查看原始数据"按钮，MCP查询即可拿到同样的数据）：
`country` / `country_code` / `province` / `province_code` / `city` / `postal_code` / `address` / `name` / `phone`

前端"查看原始数据"实际对应字段 `_widget_1778739778796`（关联单个，lookup 到源头"单个工单"记录）——想看当次提交的完整原始表单时可以点这个跳转，但用 MCP 查数据时不需要这一步，因为 `执行工单` 记录本身就已经把地址字段直接落了一份。

**⚠️ 重要边界**：`执行工单`/"工单处理结果"表里**只有走过"单个工单/批量工单"流程（换货/催发货/催派/新增订单）的记录**才会出现。如果这个网红之前的发货是走"发货管理"直发（没有经过工单流程），这张表也查不到历史记录——这种情况下如实告诉用户"系统里没有留存过可比对的地址，只能以你提供的为准"，不要说"已核对"。

（已实测验证：Erik Hung 之前3笔发货都是发货管理直发、没走过工单流程，所以这里也查不到历史地址，属于预期内的"查不到"，不是方法错误。）

### 第三步：把口语化产品名转成真实SKU编码 + 查SKU中文名称（换货/新增/补发全部适用）

用户说的多是型号/口语（如"PLC01腿屈伸"），不是系统SKU code。去 **发货管理** 表（entry_id `685bb270318253d5402ecd23`）或部门版飞书 Base **Shipment Tracking**（table `tblSbLstfA1xz5M4`；不要使用已冻结的个人版 table `tblWl75PwJmouKlU`）按产品关键词全字段/SKU字段搜索历史记录，从 `info[].sku` + `info[].sku_name` 拿到真实SKU编码。

注意：不少产品是**拆多箱发货**的（如 PLC01 腿屈伸拆黑色箱A `RF-PLC01-BLKA-JH041` + 箱B `RF-PLC01-BLKB-JH041`），要把每个箱子都列成子表单的一行，不能只填一行。同一产品还可能有不同颜色/地区版本（黑色/粉色/德国版等 SKU 前缀不同），确认清楚再选。

**⚠️ 已知产品套装SKU速查表（吴双确认过的固定组合，遇到下列口语化说法直接套用，不用再临时查证）：**

| 用户口语化说法 | 完整发货SKU清单 |
|:---|:---|
| Buffalo配重块 / 一套Buffalo配重块 | `RF-WSBFL-BXGXC-JH01`（WSBUFFALO不锈钢小车）×1 + `RF-WSTACK8-TS01`（配重片8片装 M系列通用款）×1 + `RF-WSTACK9-TS01`（配重片9片装）×2，共4箱 |
| PBM1洞洞板 / M1洞洞板 / PBM1 Pegboard Attachment（Only for M1 PRO） | `RF-M1-PB-CY02`（M1洞洞板，2026-08-03吴双确认） |

> 该表由2026-07-22 Aymeric Jett Montaz案例修正确认（此前误用单一SKU `RF-WSBFL-899GXC`，系统查无登记导致工单卡死，用户2026-07-23事后提供完整4箱清单并要求以后自动匹配）。以后再有新的整套产品被用户明确纠正/确认过完整SKU组合，都应追加到这张表里维护，不要每次都重新查证。

#### ⚠️ SKU中文名称查询（2026-07-27新增，换货/新增/补发全部必填，否则简道云执行不了）

**背景**：2026-07-27技术团队反馈——「换货、新增、补发的SKU中文名称是必填项，否则执行不了」。真实案例验证：`Daniel O'Connor-换2`（RMA20260701504）4行换货明细的`skuname`（sku名称）和`re_skuname`（换货后sku名称）当时都留空，结果对应的「发货管理」记录（`ship-20260727002`）`info`子表单一直空着、`full`字段持续报错"请输入正确的平台单号"——事后用`data/update`把源头单个工单记录的`skuname`/`re_skuname`补全后，「发货管理」这条已生成的镶像记录**依然没有自愈**（跟"选择网红"字段/"店铺渠道字段"两个历史坑同一个规律：**修正动作晚于下游同步时间点，不会跟着重新处理**），最终只能新开一张`Daniel O'Connor-换3`（RMA20260701548）替代工单，从创建时就把skuname/re_skuname填对，验证「执行工单」4行明细`result`="待处理(To Do)"（健康状态，无`kucun`异常报错），确认问题解决。

**结论：以后任何换货/新增/补发工单，创建时（而不是事后补）就必须把SKU中文名称一次性填对**，具体：
- 换货：`sku`（原SKU）对应的`skuname`（sku名称，widgetName `_widget_1778661643449`）+ `re_sku`（换货后SKU）对应的`re_skuname`（换货后sku名称，widgetName `_widget_1778661643457`），两个都要填
- 新增订单：`sku`对应的`skuname`（`_widget_1778661643449`）要填（新增订单没有`re_sku`/`re_skuname`）
- 催发货/催派：沿用原SKU，本来就有`skuname`字段（参考`urge_order.json`），照旧填好，不受这次影响

**查询方法**：去**产品生命周期**应用的**基础数据 - SKU信息**表查询中文名称，这是全公司统一维护的SKU主数据表（跟"配件信息基础表"是两张不同的表，"配件信息基础表"只覆盖`PR-`前缀的配件/辅料，不含`RF-`前缀的成品SKU，别搞混）：
- app_id: `66d696158e78f315b2476b1b`（产品生命周期，跟"单个工单"同一个App，用同一个API Key即可）
- entry_id: `5c6a555e2ce076490e9e0595`（⚠️这张表**默认对member个人视角不可见**，2026-07-27吴双在简道云后台给这张表开了权限才能查到。**部门共用注意**：其他成员若查这张表报权限错误，说明该成员没有被授权，需要管理员在简道云后台为该成员开通 SKU 信息表权限，不是查询方法本身错了）
- SKU编码字段：`sku`（widgetName `_widget_1732062523322`）
- 中文名称字段：`name`（widgetName `_widget_1732062523324`）

用 `member_data_list` 按 `sku` `method: "in"` 一次批量查多个SKU的中文名称（比如换货工单一次要查原SKU+换货后SKU共2个，多箱产品要查全部箱子的SKU），拿到的`name`字段直接填进对应的`skuname`/`re_skuname`。如果某个SKU在这张表里查不到（真的是全新SKU，主数据还没建），如实告知用户"SKU信息表里查不到这个SKU的中文名称，需要先在简道云后台补建SKU主数据，或者请提供中文名称"，不要瞎猜/编一个名称填进去。

#### 🔴 数据源化拼装铁律（2026-08-26 新增，v1.3.0，防转录错的核心手段）

**背景**：2026-08-26 Anna Crollman 14行大单、Noelle Benepe 建单时，反复出现我**手敲 SKU/中文名/key 出错**（17018、SKU 打散、名称错字），害吴双反复确认。根因是"子表单内容靠模型转录"，且无机器端兜底比对。**结论：一切 SKU 编码 + 中文名，必须从权威数据源（MCP 查询返回）程序化落盘后再拼进 payload，禁止在 JSON/脚本里手打字面量。**

**第3步做完、两进 payload 前，强制执行：**
1. **MCP 查回的权威数据落盘**：`member_data_list` 查 SKU 信息表（或发货管理历史）拿到 `sku` + `name` 后，把返回 JSON 完整保存为临时文件（如 `sku_data.json`）
2. **SKU 行清单从落盘数据拼装**：用 Python 读 `sku_data.json`，按业务需要的 `(sku, qty)` 从磁盘取 `name` 生成子表单行；**脚本里只写 SKU 编码（ASCII，较少出错）和数量，中文名完全照抄查回值，绝不在脚本里手工敲长中文**
3. **提交前回读比对**：payload 构建完，把每行 `sku` 与 `sku_data.json` 逐一比对、数量核对，确认无一抄错再提交
4. **方便自查**：构建脚本 `print` 每行 `sku | name | qty`（中文打出来给我自己检查），不要只藏在代码里

> **反模式（禁止）**：直接在 `"value"` 里手写 `RF-XXX-YYY` 和对应中文名；在 shell heredoc / 命令行里手打长中文 + SKU。**凡手抄、手敲，都可能在长串里漏字符。**

> ⚠️ 这条与「API Key 禁止手抄」「建单前结构校验」同等重要：**所有长字符串（Key、SKU、中文名、widget id）一律程序化从权威源读取/拼装，不靠模型转录。**

### 第四步：找一个最近的同类型真实工单案例做模板

在 **单个工单** 表（entry_id `69ca3e985befcf33adf37ae6`）里搜索最近一条 **同工单类型** 的真实记录，完整读出字段取值，尤其是下面这几个容易瞎猜错的枚举/combo字段：
- 工单类型 `type`/`_widget_1774861977533`（如"新增订单"）
- 子表单里的操作类型 `zi_type`/`_widget_1776325338180`
- 店铺 `_widget_1779262885599`：实际值是 **`品牌红人:Global`**（冒号无空格，不是文档旧版写的"品牌红人"）
- 国家 `_widget_1776404378550`：**填完整显示名 `United States of America (USA)`，不要只填缩写`US`**——combo字段传缩写会被原样存成裸文本"US"，跟历史记录格式不一致（国家代码字段`_widget_1778639747618`才用"US"缩写）

靠历史真实记录反查这些取值，比死记文档或瞎猜可靠得多。

### 第五步：创建工单

通过简道云Open API在 **产品生命周期** 应用（app_id: `66d696158e78f315b2476b1b`）的 **单个工单** 表单（entry_id: `69ca3e985befcf33adf37ae6`）中创建数据。

API地址：`POST https://api.jiandaoyun.com/api/v5/app/entry/data/create`
接口限制：**20次/秒**
请求方式：**POST**

> ⚠️ **请求体必需参数：**
> - `is_start_workflow`: `true` — 触发工作流
> - `is_start_trigger`: `true` — 触发触发器


> **🔴 建单 payload 构造铁律（2026-08-24 定稿）**：任何「单个工单/新增订单」payload 一律从已验证 JSON 模板继承字段，只改 value，绝不手写 widget id（手打长 id 如 `_widget_1778723390446` 极易打错 key）。模板：本目录 `new_order_template.json` / `create_order_*.json` / 已成功的 `*_workorder.json`。**提交前必须先跑结构校验脚本**：
> ```bash
> python validate_workorder_payload.py <your_payload.json>   # 可加 --print 打印待提交字段
> ```
> 脚本校验：顶层 5 键存在、data 内每值为 `{"value":..}`、子表单每行精确含且仅含 sku/skuname/quantity/zi_type 且非空、zi_type=新增订单。**PASS(exit 0) 才允许 curl；FAIL(exit 1) 必须修到过**。绝不再靠手动重写整个 JSON。

> **🔴 双保险：结构校验 + 源比对（2026-08-26 新增）**：`validate_workorder_payload.py` PASS 只是「结构合法」，不保证 SKU/名称正确。**还在提交前把 payload 的每行 `sku`、`quantity` 与第三步落盘的 `sku_data.json` 程序化比对**（行数一致、每个 sku 都存在、数量对），比对通过才 curl。这步防止「结构对但内容抄错」——正是之前错字类问题（SKU 打散/名称错字）的结构校验查不出来的盲区。

> **⚠️ 防重复提交（2026-07-22 Aymeric Jett Montaz案例教训）**：`data/create` 的curl命令只应执行一次。如果第一次curl返回结果不确定（比如输出被截断、看不清是否成功），**不要凡是"看不清楚就再发一次"**——应该先用 `member_data_get` 按刚才可能拿到的 `_id` 或按平台单号在"单个工单"表里搜索确认，再决定是否需要重新提交。曾因为想把返回结果打印得更清楚而又发了一次curl，导致同一个PO被创建了两条重复源记录（RMA20260701367 + 368），事后必须手动删除多余的一条。**核心原则：任何写操作（create/delete/update）只要已经拿到过一次成功回执，就不要因为"想看清楚结果"而重新发起同一个写请求；确认结果请用只读的 `member_data_get`/`member_data_list` 查证，不要用重复的写请求代替查证。**

#### 所有网红工单通用固定值

> **🔴 催发货/催派模板也曾缺渠道字段（2026-08-27 Anna 乐天事故）**：`urge_order.json` 模板历史上**也漏了渠道 5 字段**（shopid/sourcechannel/shopName/regionId/marketId），导致催发货工单源记录渠道全空 → 简道云默认解析成**乐天**（RAKUTEN），执行工单 3 行 `kucun=0`，跟 07-27 Daniel 换货乐天事故同源。已把 urge_order.json 补齐这 5 字段（含平台+店铺共 7 字段）。**教训：所有工单类型（含催发货/催派）模板都必须完整含渠道 7 字段，建单后若执行工单 shopname==乐天，立即按此排查是否模板漏了字段。**

⚠️ **这7个店铺/渠道字段（平台+店铺+shopId+sourceChannel+shopName+regionId+marketId）在【所有工单类型】（换货/催发货/催派/新增订单）都必须完整填写，一个都不能省略——包括换货类型**（2026-07-27 Daniel O'Connor - GPro/BWB案例教训，详见本节末尾说明）。

| 字段 | widgetName | 值 |
|:---|:---|:---|
| 平台 | `_widget_1779262885597` | **Custom** |
| 店铺 | `_widget_1779262885599` | **品牌红人:Global** |
| shopId | `_widget_1778723390451` (shopid) | **1778247337536905217** |
| sourceChannel | `_widget_1778723390446` (sourcechannel) | **CUSTOM** |
| shopName | `_widget_1778723390447` (shopname) | **品牌红人** |
| regionId | `_widget_1778723390449` (regionid) | **200001**（number） |
| marketId | `_widget_1778723390450` (marketid) | **13**（number） |
| 提交人 | `_widget_1774861977528` | **当前用户自己的 JDY Username（Identity resolution 解析，绝不硬编码固定成员）** |

> **⚠️ 2026-07-27 Daniel O'Connor - GPro/BWB 换货工单案例（RMA20260701495）教训**：早期换货工单模板（Drew Dixon/Ahmed Saleh/Aymeric等历史案例）只填了`_widget_1779262885597`(Custom)+`_widget_1779262885599`(品牌红人)两个展示字段，**漏填了shopId/sourceChannel/shopName/regionId/marketId这5个编码字段**。这次同样照旧模板省略后，简道云工作流把店铺**默认解析成了乐天(Rakuten)渠道**（`shopid:"1778639571357908993"`/`sourcechannel:"RAKUTEN"`/`shopname:"乐天"`/`regionid:215001`），导致同步到「执行工单」的4行明细全部显示`result:"有问题"`+`kucun:0`——这不是真的没库存，是在错误的乐天店铺范围内查库存，当然查不到。已用`data/update`修正源头"单个工单"记录的这7个字段（改回Custom/品牌红人/1778247337536905217/CUSTOM/品牌红人/200001/13），验证`member_data_get`确认源头已修正；但**已经生成的4条「执行工单」镶像记录不会自动重新处理**（跟本SKILL.md第六步早就记录的"晚于同步时间点的修正不会同步进执行工单镶像数据"规律一致，这次是活生生的例子）——修正源头只能保证"以后"或"重新创建的工单"走对渠道，不能让已经跑错的执行记录自愈。`create_order.json`模板已同步补全这5个字段，以后任何换货工单都要用补全后的完整7字段，不要再省略。

#### 平台单号命名规则

- 换货/催发货/催派：沿用原平台单号，换货可加"-换"后缀（`_widget_1776391818759` 换/补字段）
- **新增订单**：建议用 `网红名 - 产品标识`（如 `Erik Hung - PLC01`），避免跟该网红历史PO重名冲突
- **🔴 强制规则（2026-09-08更新）：所有工单平台单号必须使用【网红全名 + 日期】格式**，如 `Tyler Dunham - 9.8`；不得只写名不带姓（如 `Tyler - 9.8`）。日期格式为月.日（如 9.8）。换货等沿用原PO时可加 `-RE` 后缀，但基础格式必须包含全名和日期。
- **⚠️ 平台单号不得过长（2026-08-11 Joselis El Hennawi 案例教训，简道云反馈）**：平台单号太长会导致简道云系统/仓库处理异常，需要人工手动改短。真实案例：`Joselis El Hennawi - Gator + 260LB Plates + 150LB Dumbbells`（约55字符）被简道云反馈"平台单号太长了"，吴双改成 `Joselis El Hennawi - 8.11` 才新增成功。**规则：新增订单平台单号控制在 20 字符以内**，优先用 `网红名 - 产品标识`（产品标识用简短词，如 `- Gator` / `- PLC01` / `- 260LB` / `- 150LB`）；产品组合较多时用 `网红名 - 日期`（如 `网红名 - 8.11`）或 `网红名 - 简短组合词`，不要把所有产品名全拼进去。

#### 换货工单特有默认值 —— 换货明细（子表单 _widget_1774861977539）

| 字段 | widgetName | 值 |
|:---|:---|:---|
| SKU | `_widget_1774861977545` (sku) | 原SKU |
| **sku名称** | `_widget_1778661643449` (skuname) | **原SKU的中文名称（第三步"SKU中文名称查询"查到，必填，否则执行不了）** |
| 数量 | `_widget_1774861977543` (quantity) | 1 |
| 操作类型 | `_widget_1776325338180` (zi_type) | **换货** |
| 订单状态 | `_widget_1778830939654` (status) | **待处理** |
| 换货后SKU | `_widget_1776218925990` (re_sku) | 新SKU |
| **换货后sku名称** | `_widget_1778661643457` (re_skuname) | **新SKU的中文名称（第三步查到，必填，否则执行不了）** |
| 换货后数量 | `_widget_1778737771478` (re_quantity) | 1（默认与原数量相同）|

#### 新增订单特有默认值 —— 明细子表单（_widget_1774861977539）

| 字段 | widgetName | 值 |
|:---|:---|:---|
| SKU | `_widget_1774861977545` (sku) | 第三步查到的真实SKU编码 |
| sku名称 | `_widget_1778661643449` (skuname) | 第三步查到的真实SKU名称 |
| 数量 | `_widget_1774861977543` (quantity) | 1（每个SKU/每箱各一行）|
| 操作类型 | `_widget_1776325338180` (zi_type) | **新增订单** |

> 新增订单不需要填 `re_sku`/`re_quantity`（换货专用字段），留空即可。

#### 地址信息（通用）

| 字段 | widgetName | 来源 |
|:---|:---|:---|
| 国家 | `_widget_1776404378550` (country) | 填**完整显示名**，如 `United States of America (USA)` |
| 国家代码 | `_widget_1778639747618` (countrycode) | 如 US |
| 省/州 | `_widget_1776404378552` (province) | 从地址解析，如 `Georgia` |
| 省/州代码 | `_widget_1778551668473` (provincecode) | 如 GA |
| 城市 | `_widget_1776404378554` (city) | 从地址解析 |
| 收件人姓名 | `_widget_1778639747615` (name) | |
| 收件电话 | `_widget_1778639747617` (phone) | |
| 邮编 | `_widget_1778639747616` (postal) | |
| 详细地址 | `_widget_1774935237048` (address) | |

### 第六步：创建后校验 + 纠错

用 `member_data_get` 把刚创建的记录（`data/create` 返回的 `_id`）读回来，逐字段核对是否符合第四步反查到的模板案例：
- 重点检查 combo/枚举字段（国家/店铺/工单类型/操作类型）是否是完整规范值，不是缩写或裸文本
- 如发现不一致（比如国家字段传成了缩写"US"），用同一套 API 的 `data/update` 端点二次修正：

```json
{
  "app_id": "66d696158e78f315b2476b1b",
  "entry_id": "69ca3e985befcf33adf37ae6",
  "data_id": "刚创建的_id",
  "data": {
    "_widget_1776404378550": {"value": "United States of America (USA)"}
  }
}
```

⚠️ **注意时效性**：工单提交后，工作流会很快（通常几分钟内）把数据同步到"执行工单/工单处理结果"表并可能直接处理完成（`result` 字段变成"已完成(Done)"）。如果修正动作晚于这个同步时间点，"执行工单"里的镶像数据**不会**跟着更新——"单个工单"原始记录改对了，但下游快照可能已经是旧值。发现不一致要尽快修正，且修正后不用再回头改"执行工单"（那张表是只读镶像/处理记录，不建议手动改）。

> **🔴 重大教训（2026-08-14 LaShae Rolle 案例，吴双明确）**：**简道云识别不了"第二次修改子表单"——它只会执行第一次添加时提交的产品列表。** 也就是说，工单创建后，如果再用 `data/update` 往 `detail`/子表单里**追加**新的 SKU 行（哪怕源数据层写入成功了、读回来也是多行），简道云的工作流/执行工单/发货管理**只会按第一次提交的 SKU 列表处理，新增的行不会被执行**，前端也看不到。真实案例：LaShae Rolle 原工单先创建4件，后用 `data/update` 追加了35LB/45LB/15LB/25LB 四行，结果执行工单和发货管理只认最初的4件，补充件从未进入执行链路。
> **规则：需要给已创建的工单补充产品时，【不要】直接 `data/update` 修改子表单追加行，【必须】重新新增一张工单**（新增订单类型，把补充的SKU一次性带齐），再走第七步建对应发货管理记录。这也是本 SKILL.md 反复强调的"整单重建/新开工单比修补更保险"原则的又一实例。

### 第七步（仅新增订单/换货类型，2026-07-24新增）：直接创建对应「发货管理」记录，不再依赖JDY自动生成

**背景**：原以为工单提交后JDY工作流会自动在「发货管理」生成配套记录（Erik Hung - PLC01案例验证过一次成功，约10秒后自动出现`ship-20260722002`）。但2026-07-23创建的 Aymeric Jett Montaz - Buffalo配重块 / Jarius Joseph 补-2 两个工单（同样走API创建）证实**这个自动生成并不可靠**——两笔工单在执行工单里都已正常完成发货，但「发货管理」里从未出现过任何自动生成的配套记录，导致jdy-shipping-track巡检反复扑空（"Jarius Joseph 补-2"因此空转了好几个周期）。更麻烦的是，事后吴双自己手动去「发货管理」补"单个新增"时，只多打了一个空格（如把工单里的`Buffalo配重块`打成`Buffalo 配重块`），就导致JDY按精确字符串匹配平台单号失败，永久报错"请输入正确的平台单号"、`info`子表单永远填不进去（这种情况**不会自愈**，跟"刚提交同步延迟"是两种不同的坑）。

2026-07-24 吴双明确要求：以后创建"新增订单/换货"工单后，**不要再依赖JDY自动生成，也不要留给她手动补录**，由本技能顺手直接把「发货管理」记录建好。

操作步骤：
1. 记录下第五步提交"单个工单"时实际写入`oderid`（`_widget_1774861977532`，平台单号）字段的**精确字符串**（一字不差，包括空格/横线位置）——这是后面"来源单号"必须原样复制的值，绝对不能凭记忆重新打一遍，哪怕只多一个空格都会导致匹配失败。
2. **直接**用 `member_data_list` 在「发货管理」（entry_id `685bb270318253d5402ecd23`）按 `_widget_1752480297833`（来源单号）`eq` 精确匹配刚才那个字符串查一次（⚠️ **不要等待，创建完直接查**——2026-08-13吴双明确：等20秒纯属浪费时间，JDY自动生成本来就不可靠，等多久都大概率查不到），避免和"运气好这次JDY自动生成了"的记录产生重复：
   - 如果已查到匹配记录 → 说明这次自动生成成功了，跳过第3步，不要重复创建。
   - 如果没查到 → 继续第3步手动创建。
3. 用简道云Open API在**网红管理**App（app_id `685a468345ade02b47318ca9`，⚠️不是产品生命周期App，需要切换成从本技能目录 `credentials.local.md` 安全读取的**网红管理专属API Key**）的「发货管理」表单（entry_id `685bb270318253d5402ecd23`）创建一条新记录，只需要写两个字段：

```json
{
  "app_id": "685a468345ade02b47318ca9",
  "entry_id": "685bb270318253d5402ecd23",
  "data": {
    "_widget_1780972277486": {"value": "<当前用户username>"},
    "_widget_1752480297833": {"value": "<第1步记录的精确平台单号字符串>"}
  },
  "is_start_workflow": true,
  "is_start_trigger": true
}
```
   - `_widget_1780972277486`（提出人，type: `user`）写 `{"value": "<当前用户username>"}`——Identity resolution 解析出的当前用户 JDY Username，跟「单个工单」表提交人字段的写入约定一致，已验证有效的格式；**绝不硬编码固定成员**
   - `_widget_1752480297833`（来源单号，type: `text`）必须跟第1步记录的字符串**完全一致**，一个字符都不能改
   - 其余字段（`_widget_1750907718909`编号是`type: sn`自动生成的流水号，`info`子表单，`full`字段）都不填，JDY会在后台按来源单号字符串匹配去算`info`/`full`，具体多久算出来不确定，**不代表创建失败**
4. 创建后按"写一次+只读查证"的原则核对：用 `member_data_get` 读回刚创建的 `_id`，确认来源单号字符串精确无误即可，不要因为想确认结果又发一次create。
5. 如果`info`子表单短时间内（几分钟）仍是空的，**这是正常现象，不代表出错**——只有过了较长时间（比如几天）仍然空着，才需要按已知的排查方法（去执行工单反查`source_order_no`/`new_track`）人工介入补写Base，参考 jdy-shipping-track 的相关教训记录。

> 换货/催发货/催派类工单沿用原有平台单号（该PO在「发货管理」里本来就有对应记录），不需要执行这一步，只有**新增订单**和**换货**（产生全新平台单号）才需要。

### 第八步：联动 jdy-shipping-track，自动加入 watchlist（2026-07-22 新增，免手动转发）

不管第七步是JDY自动生成的还是我们手动创建的，只要「发货管理」里有了这条`提出人`=当前用户（Identity resolution 解析）的记录，**jdy-shipping-track 的 Mode 0（每天两次增量同步）就会在下一个窗口自动扫到它**，不需要额外动作。但要让它进入 **Mode B 每日主动巡检**（催发货/3天打flag/追踪号实时同步/完成后自动发邮件），需要手动把这个平台单号加进 jdy-shipping-track 的 watchlist：

- 文件路径：当前 agent workspace 下的 `_outputs\ritfit-tracking-JDY-outputs\watchlist.md`（用相对路径，不要写死任何人的绝对路径）
- 格式：在表格里新增一行 `| 平台单号 | 今天日期(YYYY-MM-DD) |`
- **先去重**：如果该平台单号已经在 watchlist 里（比如用户已经手动加过），不要重复添加
- **强制规则（2026-09-07更新）：任何工单新建完成后，只要成功拿到RMA编号，就必须立即把其平台单号自动加入watchlist，不得等待用户提醒或事后补做**；新增订单、换货、催发货、催派全部适用。加入前先去重，若已存在则跳过并在结果中说明"已在watchlist"。

这样当前用户以后不用再手动把新建的工单PO转发给 jdy-shipping-track 手动加 watchlist，本技能创建工单后会自己接上这一棒。

### 第九步：告知用户 + notify

创建成功后，告知用户：
- 工单编号（RMA开头的流水号）
- 关键字段汇总（网红/地址/SKU明细）
- 是否已加入 jdy-shipping-track watchlist（第七步）
- 换货类工单需提示用户到简道云前端界面，在 **订单详情** 子表单中点击 **"选择数据"** 按钮，按原SKU匹配数据行，系统自动填充SKU名称等信息
- 地址无法交叉核对时（第二步查无历史记录）要单独标注风险提示，不要说"已核对"
- 这是单次任务，按规则执行完必须用 `mcp__claw__notify` 主动推送一遍结果，不管有没有在当前对话

## API调用格式（v5）

使用简道云Open API v5版本，数据字段需要用 `{"value": xxx}` 格式包裹。

### ⚠️ 中文编码注意事项

**不要**在curl命令的 `-d '...'` 参数中直接写中文！Windows终端默认使用GBK编码发送中文字符，会导致简道云系统中显示乱码。

**正确做法**：先将JSON请求体保存为UTF-8编码的 `.json` 文件，再用 `--data-binary @"文件路径"` 方式发送。

参考模板文件（与本 SKILL.md 同目录）：
- `create_order.json` —— 换货工单示例
- `urge_order.json` —— 催发货工单示例
- `new_order_template.json` —— 新增订单工单示例（占位符需替换成真实值）
- `fix_field_template.json` —— 创建后字段纠错（data/update）示例

> ⚠️ **`{{USERNAME}}` 占位符（v1.2.0）**：所有 `create_order.json` / `urge_order.json` / `new_order_template.json` 等模板的提交人字段 `_widget_1774861977528` 现在是 `{"value": "{{USERNAME}}"}`。**使用模板前，必须先把 `{{USERNAME}}` 替换为 Identity resolution 解析出的当前用户 JDY Username**（用 `sed -i 's/{{USERNAME}}/<实际username>/'` 或直接改文件），再保存 UTF-8 发送。不要原样提交含占位符的 JSON，否则提交人字段会写成一串字面量 `{{USERNAME}}`。

curl调用命令（使用文件方式确保UTF-8编码）：
```bash
curl -s -w "\n%{http_code}" -X POST "https://api.jiandaoyun.com/api/v5/app/entry/data/create" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @"create_order.json"
```

修正字段用 `data/update` 端点（其余同上）：
```bash
curl -s -w "\n%{http_code}" -X POST "https://api.jiandaoyun.com/api/v5/app/entry/data/update" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @"fix_field_template.json"
```

## 注意事项

1. **`is_start_workflow` 和 `is_start_trigger`**：调用创建API时，这两个参数必须设为 `true`，否则工作流和触发器不会执行
2. **中文编码问题**：Windows终端curl命令中直接写中文会被GBK编码发送，导致简道云中显示乱码。**必须**将JSON保存为UTF-8文件后用 `--data-binary` 方式发送
3. **SKU名称填充（2026-07-27更新）**：换货/新增/补发类工单，`skuname`（sku名称）和换货类型额外的`re_skuname`（换货后sku名称）**必须在创建时就通过API填好**，去"产品生命周期-基础数据-SKU信息"表（entry_id `5c6a555e2ce076490e9e0595`）查中文名称，不要依赖前端"选择数据"按钮事后补——事后补救对已生成的下游「发货管理」镶像记录不会自愈，详见第三步说明
4. **数量默认**：如用户未指定数量，默认1件；产品拆多箱发货时每箱各1件、各占子表单一行
5. **地址核对**：一律去"执行工单/工单处理结果"表核对历史地址，不要去"发货管理"表（那张表不存地址）；查无历史记录时要如实告知用户无法核对
6. **API Key**：运行时从本技能目录内、未纳入版本控制的 `credentials.local.md` 按 App 读取对应 Key；产品生命周期 App 与网红管理 App 的 Key 不可混用，否则会报 `17053 Not among the authorized apps`。文件缺失时请管理员通过安全渠道完成本机配置，不落盘存明文于 SKILL.md。
7. **工单状态**：换货类工单的订单状态默认设为"待处理"；新增订单类工单该字段可留空
8. **combo字段填完整值**：国家类combo字段要填完整显示名（如`United States of America (USA)`），不要只填国家代码缩写，否则会存成裸文本、跟历史记录格式不一致
9. **平台单号防重名+防过长**：新增订单类工单的平台单号用"网红名 - 产品标识"格式（如 `Erik Hung - PLC01`）避免和该网红历史PO重名，**且平台单号不得超过约20字符**（2026-08-11 Joselis El Hennawi 案例：长单号被简道云退回，需改成 `网红名 - 8.11` 短格式才新增成功，详见"平台单号命名规则"节）。组合订单不要把所有产品名拼进单号
10. **⚠️ 发货管理记录不能再假设"自动生成一定可靠"（2026-07-24更新；2026-08-13补充）**：工单提交后简道云工作流**通常**会自动在"发货管理"表生成对应记录，但已证实不可靠（Aymeric Jett Montaz - Buffalo配重块 / Jarius Joseph 补-2 两个案例均未自动生成，导致空壳记录长期无法自愈）。新增订单/换货类型创建工单后，**必须**按第七步"先查后建"流程主动核实并在缺失时手动创建（**创建完直接**按来源单号精确匹配查一次→查不到就立刻创建，**中间不要等待**——2026-08-13吴双明确要求去掉等待，等20秒纯属浪费时间）；催发货/催派类型仍沿用原平台单号，不需要这一步
11. **watchlist去重**：加入 watchlist 前先检查该平台单号是否已存在，避免重复行；只有"新增订单/换货/催发货"这类会产生"待发货"状态的工单才需要加入，"催派"通常不需要
12. **⚠️ 换货前后SKU不能相同**：简道云系统会把"前后SKU一致"的换货工单直接判定为失败（2026-07-23 Ahmed Saleh - 内收外展A箱黑案例验证：原SKU和换货后SKU都填RF-COUGAR-BLKA-KLK01，提交后系统判定换货失败）。用户说"换货"但本意其实是"重发同一个SKU"（比如原箱一直卡在虚拟发货没出真实追踪号）时，要先按第0步确认该SKU确实没有更新版本，然后**改用催发货类型**，不要照字面意思硬走换货流程：催发货子表单要填 `fo_oder`（原发货单的fororder_no）+ `quantity`=1 + 状态="已发货"，不需要 `re_sku`/`re_quantity`。已有真实修复案例（RMA20260701373）可参考。
13. **⚠️ 子表单（`detail`/换货明细）用 `data/update` 做局部修正时，会整行覆盖，不是按字段合并**（2026-07-27 Daniel O'Connor-换2 修复过程中踩中）：如果 `data/update` 的payload里某一行只带了 `skuname`/`re_skuname` 而漏了 `status`/`zi_type` 等其他字段，简道云会把那一整行**替换**成payload里的内容，没带到的字段会被**静默清空**，而且该行会被分配一个全新的 `_id`（旧 `_id` 失效）。**结论**：修正子表单任何一行时，payload必须带上这一行的**完整字段集**（sku/skuname/quantity/zi_type/status/re_sku/re_skuname/re_quantity等全部原有字段），不能只传"想改的那个字段"；修正后要用 `member_data_get` 重新读一遍确认其他字段没被误清空、并记下新的行 `_id`。如果发现某一行已经被之前的局部更新清空过字段，与其继续修补，通常直接走"整单废弃重建"（参考本文件"发货管理不自愈"系列教训）更省事更保险。
14. **🔴 补充产品必须新开工单，不要 `data/update` 修改子表单追加行（2026-08-14 LaShae Rolle 案例，吴双明确）**：简道云**识别不了第二次修改子表单，只会执行第一次添加的产品列表**。给已创建工单补充SKU时，`data/update` 往 `detail` 追加行在源数据层虽成功，但下游（执行工单/发货管理/前端详情）永远只按第一次提交的SKU处理，新增行不会被执行。**规则：补充产品一律重新新增一张工单**（新增订单类型，补充SKU一次性带齐），再按第七步建对应发货管理记录。详见第六步末尾的红色警示框。