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速查表（吴双确认过的固定组合，遇到下列口语化说法直接套用，不用再临时查证）：

该表由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。提交前必须先跑结构校验脚本：

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案例教训，详见本节末尾说明）。

⚠️ 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）

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

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

地址信息（通用）

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

用 member_data_get 把刚创建的记录（data/create 返回的 _id）读回来，逐字段核对是否符合第四步反查到的模板案例：

• 重点检查 combo/枚举字段（国家/店铺/工单类型/操作类型）是否是完整规范值，不是缩写或裸文本
• 如发现不一致（比如国家字段传成了缩写"US"），用同一套 API 的 data/update 端点二次修正：

{
  "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）创建一条新记录，只需要写两个字段：

{
  "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编码）：

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 端点（其余同上）：

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一次性带齐），再按第七步建对应发货管理记录。详见第六步末尾的红色警示框。