Jdy Shipping Track

RITFIT Tracking — Jiandaoyun ↔ Base Sync + Watchlist Monitor (部门共用版)

🌐 多语言（v5.0.1，2026-08-12）：部门含中外籍成员。本技能的运行产出（daily-log、B5/B8 通知、对成员的提示）语言跟随使用者——中文使用者用中文，英文使用者用英文（Angeline Prasetio / Diego Isaac Rojo Molina 等）。对外内容（KOL 追踪邮件、SKU 英文名）一律英文；技术标识（SKU、RMA、record_id、命令）保持原文不翻译。KOL 追踪邮件模板 references/tracking.html 内已是英文，组装时按 B2 的 SKU 英文翻译规则 + Carrier 归一化规则填英文内容即可，勿因内部语言偏好改变邮件语言。

v5.0.0 (2026-08-11) — department-shared rebuild. The skill no longer belongs to one person. One department-wide Base table holds everyone's shipments (each row carries Owner = the JDY 提出人's Chinese name + 负责人 = their Feishu user). Mode 0 runs centrally (one cron on the department admin's machine, currently 吴双's) and syncs shipments for all enabled roster members. Mode B runs per-person: each brand-dept member uses the same published agent in their own Cherry Studio; the agent auto-resolves "who am I" from the 部门成员 roster table (see the next section) and only ever touches POs whose Owner = themselves. KOL tracking emails are always sent from the member's own mailbox. Base write permission is enforced server-side via advanced permissions (see Base Config) — members can only edit Tracking Info / Carrier / Email Sent? on their own rows, so skill rules and Feishu permissions say the same thing.

Two things happen daily, on two different schedules:

1. Mode 0 — Incremental sync (cron 30 1,14 * * * = 2x/day at 01:30/14:30 BJT, job "JDY-Base 每日自动同步", runs ONLY on the central admin machine): mirrors shipment items submitted/ updated in JDY 发货管理 by any enabled roster member (提出人 ∈ roster) into the department Base "Shipment Tracking" table since the last run. This is the system of record — every SKU line becomes one Base row, tracking or not.
2. Mode B — Watchlist check (each member's own environment, suggested cron weekdays 3x/day 09:00/14:00/17:00 BJT): walks that member's own watchlist, cross-references escalation work orders, flags stuck POs, moves finished POs to the completed log, drafts/sends tracking emails to KOLs from the member's own mailbox, and live-syncs any newly-appeared tracking numbers straight into Base on every check.

Mode A is manual — a human (or Mode-A-variant sync from Base) adds a PO to the watchlist.

⚠️ Identity resolution — read this FIRST on every run (v5.0)

The skill must never hardcode a person. Resolve the current user at the start of every run:

1. lark-cli contact +search-user --user-ids me --as user --format json → current user's open_id (and name).
2. Read the roster: lark-cli base +record-list --base-token UGuHbNi6GapDwTs9kdUcUGZPnzS --table-id tblfDTCs6XeMPefA --as user --format json (table 部门成员, fields: 姓名 / JDY Username / Feishu Open ID / 企业邮箱 / 启用).
3. Match the current open_id against Feishu Open ID → get my 姓名 (= Owner value on my rows) and my JDY Username (= 提出人 filter value for JDY queries).
4. If no roster row matches, or the row's 启用 is false → stop and tell the user their account isn't enrolled in the department shipping tracker yet (ask the admin, currently 吴双, to add/ enable them in the 部门成员 table).
5. Mode 0 special case: Mode 0 only runs on the central admin machine. Its JDY filter is 提出人 ∈ {JDY Username of every roster row where 启用=true and JDY Username is not empty} (an in condition), and every row it writes must carry Owner = 提出人姓名 AND 负责人 (user field) = that member's open_id (format [{"id":"ou_xxx"}]). Mode 0 never filters to a single person.

Local per-member state lives under the current agent's own workspace (resolve at runtime — never hardcode another machine's absolute path): <workspace>\_outputs\ritfit-tracking-JDY-outputs\ holding watchlist.md, completed.md, daily-log-DD-MM-YYYY.md. Mode 0's cursor mode0-state.md exists only on the central machine. The KOL email template ships inside the skill at references/tracking.html (next to this SKILL.md) — always read it from there.

Jiandaoyun Config (verified 2026-07-17)

Per-person identity (提出人 username / Feishu open_id) is NOT stored here anymore — resolve it at runtime from the 部门成员 roster table (see "Identity resolution" above). The roster is the single source of truth for who is enrolled; add/remove members by editing that table, never by editing this file.

⚠️ The Jiandaoyun MCP server prefix is NOT stable — it changes every time the MCP server reconnects (observed values so far: mcp__2k9L5gEyUsJcysSqDg6kd__, mcp__QSVObmaRs4Fi18o8Z85wV__, mcp__0HD-u86s20h3DuwbDikoX__ as of 2026-07-20). Do not hardcode or trust a prefix from memory/past runs. Before the first Jiandaoyun call each run:

1. Check the current turn's system-reminder for a "deferred tools" list — it shows the live, correct prefix (look for member_data_list, member_app_list, etc.).
2. If no such reminder is visible, just try the call with the prefix noted in your working memory; if it errors No such tool available, that confirms a reconnect happened — re-check the system-reminder or ask the user to trigger one (their next message will carry the fresh deferred-tools list).
3. Never spin up a sub-agent just to "guess" the prefix by trial and error — the correct name is already surfaced passively via the system-reminder, no guessing needed.

Once you have the live prefix, all calls below use it (e.g. <prefix>member_data_list).

Field names in 发货管理

Field names in 网红信息

Field names in 合同管理

Field names in 单个工单 (产品生命周期) — each member submits their own 催发货 here

Field names in 批量工单 (产品生命周期) — same as 单个工单 but for multiple POs

Field names in 执行工单 (产品生命周期) — warehouse processes each item, tracking lands here

⚠️ Correct two-step lookup for 执行工单 (since it's keyed by RmaId, not PO name):

1. Query 单个工单 filtered on oderid = PO name → extract the record's label (RMAID, e.g. RMA20260600411)
2. Query 执行工单 filtered on _widget_1776219080908 (RmaId) = that RMA ID

Base Config (Feishu — department-shared, built 2026-08-11)

⚠️ Advanced permissions are ON (2026-08-11). The system Editor role (rolUbyYp27y) is deliberately narrowed: members can edit only Tracking Info / Carrier / Email Sent?, cannot add/delete records, and can only edit rows where 负责人 (user field) = themselves; everyone can read all rows; the roster table is read-only for members. The department admin (currently 吴双) is the Base owner and unrestricted. Consequences for this skill:

• Mode 0 (central, runs as the admin's identity) is the only writer of new rows and of Status / All Shipped? — members' instances must not attempt those writes (they'd 403).
• Mode B (member's own instance) may write Tracking Info / Carrier (B2.5/B2.6) and Email Sent? (B3.5) only on rows where 负责人 = me. If a write returns a permission error, don't retry-loop: note it in the daily-log and let central Mode 0 catch it on its next run.
• When Mode 0 writes a row it must set both Owner (text, 提出人姓名) and 负责人 (user field, [{"id":"<open_id>"}] from the roster) — without 负责人 the row is invisible to the owner's own edit permission.

⚠️ Legacy note: the pre-department personal table (RITFIT Brand Base Dj0BbQHGKaiaFssqeWucIBIen8g, table tblWl75PwJmouKlU) is frozen as of 2026-08-11 — kept for history, never written by this skill anymore. All reads/writes below target the department Base above.

All fields already exist — do not create new fields.

File structure (per-member, inside the current agent's own workspace)

All paths below are relative to the current agent's workspace root (resolve it at runtime — on 吴双's machine the workspace is F:\Cherry Studio\Andy\Data, but each member's published-agent workspace differs; never hardcode another machine's absolute path):

Mode 0 — Daily incremental sync (JDY → Base) — central admin machine only

Runs via cron "JDY-Base 每日自动同步" (30 1,14 * * * — 2x/day at 01:30 and 14:30 BJT) on the central admin machine (currently 吴双's). Members' own instances never run Mode 0 — their environment only runs Mode B.

⚠️ v4.3.0 (2026-07-20): converted from full historical rescan to incremental. The old version re-queried and re-dedup-checked every shipment ever submitted, every single day. That was fine when JDY only had a handful of records, but by 2026-07-20 there were 100+ shipments / 988+ Base rows and it started timing out at the 15-minute cron limit (job got auto-paused). Root cause: O(all history) work repeated daily instead of only processing what changed. Fixed by adding a state file and filtering on updateTime, the same incremental pattern used by Mode B and jdy-kol-sync.

⚠️ v5.0.0 (2026-08-11): department-wide. Mode 0 now syncs shipments for every enabled roster member, not just the admin, and writes Owner (提出人姓名) + 负责人 (their Feishu user) on every row so per-member permissions work. It only picks up shipments created/updated from 2026-08-11 onward — historical shipments of other members are never backfilled (per 吴双's decision).

State file: _outputs\ritfit-tracking-JDY-outputs\mode0-state.md (central machine only) — one line: last_run_at: <ISO timestamp>.

⚠️ v4.8.0 (2026-08-07): added 执行工单 tracking-number supplementation (Mode 0 counterpart to Mode B's B2.6). JDY 发货管理's trackingno often requires a manual 查询并刷新 to appear — so a 发货/换货 work order can already have a real tracking number in 执行工单 (new_track / 跟踪号) while 发货管理 is blank. B2.6 already covers watchlist POs in Mode B; v4.8.0 extends the same idea to Mode 0's incremental sync so every shipment in the window gets its blank tracking filled from 执行工单 — not just watchlist POs. It runs as a new step 9b after the main 发货管理 sync, before updating mode0-state.md.

Logic:

1. Read mode0-state.md for last_run_at. If the file is missing, bootstrap: set last_run_at to 72 hours before now (generous overlap — safe because step 5's dedup will skip anything already in Base) and skip straight to step 8.

2. Record run_start = now (ISO) — this becomes the new last_run_at at the end of the run, not the time the run finishes (so shipments submitted mid-run next time still get picked up next time).

3. Read the roster (部门成员 table) and collect usernames = [JDY Username of every row where 启用=true and JDY Username non-empty]. Then query <current Jiandaoyun MCP prefix>member_data_list on 发货管理, filter: 提出人 ∈ usernames AND updateTime >= last_run_at (see the ⚠️ prefix-instability note in Jiandaoyun Config above — resolve the live prefix first)

   {"cond":[
     {"field":"_widget_1780972277486","method":"in","type":"user","value":["<username1>","<username2>",...]},
     {"field":"updateTime","method":"gte","type":"datetime","value":["<last_run_at>"]}
   ]}
   

   ⚠️ Must use gte, never gt — verified 2026-07-20. Jiandaoyun's datetime field type only supports eq/ne/gte/lte/range/empty/not_empty as filter methods; gt/lt are not supported for datetime fields (gt is silently ignored by the API rather than erroring — the query just returns everything unfiltered, which is exactly how the original full-rescan bug hid inside what looked like a working incremental filter during testing). Always include "type":"datetime" on the condition too. Value format: plain "YYYY-MM-DD", "YYYY-MM-DD HH:mm:ss", or full ISO "YYYY-MM-DDTHH:mm:ssZ" all parse correctly (verified) — pick one and store last_run_at in mode0-state.md in that same format so it round-trips without reformatting.

   Use updateTime, not createTime — a shipment created days ago whose tracking number just got filled in (full flips 否→是) touches updateTime, not createTime. Filtering on createTime would silently miss those updates forever. Paginate with limit=100 + cursor_data_id (should now be at most one page per day in normal operation).

4. For every shipment returned, iterate all subform items (info[]) regardless of tracking presence. Read the shipment's 提出人 (_widget_1780972277486) → look up the roster row by username → that row's 姓名 becomes Owner, its open_id becomes 负责人. If the 提出人 isn't in the roster (e.g. someone outside the brand dept, or a roster row with 启用=false) → skip the whole shipment silently (log a one-line note).

5. Map fields per the Base Config table above. full="是" → Status=Completed, All Shipped?=true; full="否" → Status=In Progress, All Shipped?=false.

6. Extract KOL Name from PO Number (see extraction rule below).

7. Dedup: before writing, lark-cli base +record-search --search-field 唯一键 --keyword "<发货单号>||<订单号>". Skip if found (this also covers the bootstrap-overlap and any edge case where the same shipment updates twice in one window).

8. Write with lark-cli base +record-upsert --base-token UGuHbNi6GapDwTs9kdUcUGZPnzS --table-id tblSbLstfA1xz5M4 --json '{...}' --as user. The JSON must include "Owner": "<提出人姓名>" and "负责人": [{"id": "<open_id>"}] (user-field cell format) — without 负责人 the row's owner can't edit their own tracking fields later.

9. Serial writes, 0.5–1s between every 3 records. Log errors, keep going — never abort the run. 9b. 执行工单追踪号补充同步 (v4.8.0, 2026-08-07; department-wide since v5.0.0). 发货管理 trackingno 常需手动"查询并刷新"才显示，但追踪号可能已真实落地在执行工单（new_track/跟踪号）。本步骤把执行工单 当作追踪号的权威补充来源，把窗口内空单号的行从执行工单补上。只在主流程（步骤 3-9）之后执行，不替代主流程。

10. Update mode0-state.md to last_run_at: <run_start> (the timestamp captured in step 2).

11. Report to the admin (via mcp__claw__notify, only if anything changed — no notify on a no-op run): how many shipments were in the incremental window (broken down by Owner), how many rows written/updated, how many skipped as duplicates.

Mode 0 step 9b — 执行工单追踪号补充同步 (v4.8.0, 2026-08-07; department-wide v5.0.0)

目的：发货管理 trackingno 常需手动"查询并刷新"才显示，但追踪号可能已真实落地在执行工单 （new_track 换货/补发新单号，或原始跟踪号 _widget_1780391793600）。本步骤把执行工单当作追踪号的权威 补充来源，把主流程步骤 3-9 里 trackingno 仍为空的 Base 行补上单号。触发时机：每次 Mode 0 主流程 （发货管理增量同步）完成后、更新 state 之前，对窗口内所有发货单执行。

前置（B2 同款两步查询）：

1. 对窗口内每个发货单，用来源单号（_widget_1752480297833）查单个工单（entry 69ca3e985befcf33adf37ae6， filter _widget_1774861977532(oderid) like 来源单号 AND _widget_1774861977528(提交人) eq 该发货单的提出人 username——即主流程步骤 4 里为该发货单解析出的同一个人），拿 RMA ID。
   • ⚠️ 单个工单表的提出人字段是 _widget_1774861977528（label=提交人），不要跟执行工单表的 _widget_1774860170326（label=提出人）搞混——两张表字段名不同！
   • ⚠️ 必须按该发货单自己的提出人过滤（v5.0 起不再是固定某一个人）：工单表里混着全部门同事发起的记录。 只有提出人在名册（启用=true）内的发货单才会进入窗口（主流程步骤 3 已保证），所以这里的过滤值就是 该发货单的提出人 username。通过 Andy (influencer-exchange-order) 创建的工单提交人=实际操作的那个 成员自己（模板显式填其 username），会正常命中。
   • ⚠️ 但注意：发货管理来源单号可能带后缀（如 "Daniel O'Connor-换3"），单个工单 oderid 存的可能是原始 PO（"Daniel O'Connor"）。所以查单个工单时用 like 而不是 eq，且要把执行工单的 source_order_no 也作为候选 PO 名一起匹配（见步骤 3 的匹配策略）。
2. 查执行工单（entry 69ca3653e80a04d0ebe03a38，filter _widget_1776219080908(RmaId) = RMA ID AND _widget_1774860170326(提出人) eq 该发货单的提出人 username，limit=100 分页），返回该工单所有行。 ⚠️ 执行工单表的提出人字段是 _widget_1774860170326（user 类型），必须过滤为该发货单自己的提出人， 防止匹配到其他同事的同名/相似 RMA。

对执行工单返回的每一行：

1. 取追踪号：优先 new_track（_widget_1780391793602）；为空则取原始跟踪号 _widget_1780391793600。 两者都为空 → 该行无单号，跳过。
2. 只认已完成的行：result（_widget_1774860170334）必须是 已完成(Done) 才采信。待处理/部分完成/ 有异常 → 跳过（追踪号是中间态，等下一轮）。
3. ⚠️ 异常检查：若 status（_widget_1778651173620，是否有异常）非空或 error（_widget_1782093678117） 非空，即使有 new_track 也不写入，把告警带出给管理员（写进 daily-log 的 ⚠️ 行），不要静默写入。
4. 匹配 Base 行：用 PO Number + SKU 中文名找 Base 行：
   • 候选 PO 名列表：发货管理来源单号、执行工单 source_order_no（_widget_1774860170329）、 after_no（_widget_1778651173621，新--平台单号，如 "Daniel O'Connor-X-RE-01"）——逐个去试， 因为换货工单下这三个值可能都不同（实测 Daniel O'Connor-换3：发货管理="Daniel O'Connor-换3"、 单个工单 oderid="Daniel O'Connor-换3"、执行工单 source_order_no="Daniel O'Connor"、 after_no="Daniel O'Connor-X-RE-01"）。
   • 对每个候选 PO 名，lark-cli base +record-search --search-field "PO Number" --keyword "<候选PO>" --as user 拿回该 PO 全部 Base 行；
   • 在结果里用 SKU 文本精确比对（trim 后完全相等）。优先比 after_skuname（_widget_1778662217863， 换货后SKU名），再比 skuname（_widget_1778662217862），再比发货管理 info[].sku_name。命中 → 拿 record_id。
   • 找不到匹配的 Base 行（PO 从未进 Base，或 SKU 名对不上）→ 跳过，记入 daily-log 备注（"执行工单有 单号但 Base 无对应行：PO= SKU="）。这通常意味着该 PO 还没被发货管理/主流程同步过，Mode 0 会在 后续窗口里通过发货管理建行；不要为了补单号而凭空建行。
5. 写入 Base：命中后 +record-upsert --record-id "<rec_id>" --json '{"Tracking Info": "<追踪号>", "Carrier": "<carrier>"}' --as user。
   • Carrier：执行工单不存物流渠道。优先取发货管理该行已有的 logisticschannel_name（原始值不 normalize）；发货管理里也没有 → 留空（不编造）。若按单号格式能猜出承运商大类（1Z→UPS、纯数字→ FedEx/DHL）可在日志/通知里标注"（from tracking format）"供该 PO 的 Owner 确认，但 Base 的 Carrier 字段只写 确切的来源值或留空。
   • 只动 Tracking Info / Carrier，不碰 Status/All Shipped?（B3/B4 职责）。
6. 幂等/去重：Base 行 Tracking Info 已等于要写的值 → 跳过（no-op）。同一 RMA 多行共用同一 new_track（几箱一个包裹）→ 逐行各写一遍，不加序号。若主流程步骤 3-9 已经写了该行且 trackingno 非空， 本步骤会 no-op 跳过，不重复。
7. 日志：daily-log 记录 "9b 执行工单补写 N 个追踪号（PO: …）"；如果本次窗口没有任何需要补写的 （多数情况下执行工单单号已同步或发货管理已有 trackingno），记一行 "9b 无待补写" 即可，不强制通知。

⚠️ 数据量控制 + 提出人过滤（双重保险）：执行工单表是全量工单历史，不能每次全扫。本步骤只对主流程 窗口内返回的发货单（提出人 ∈ 启用名册且 updateTime≥last_run_at）执行工单两步查询——也就是说，一个发货单如果 没有进入 Mode 0 增量窗口（updateTime 没变），本步骤不会主动去查它的工单。这是因为 Mode 0 的窗口设计就是 "只处理变化"；补写只在窗口内发货单的 trackingno 为空时触发。若某 PO 在窗口外但有新落地的执行工单单号，那 属于 Mode B（watchlist PO）或下一个窗口的范畴。

⚠️ ⚠️ 提出人必须在启用名册内是硬性前置条件：即使某 PO 的候选名匹配到了执行工单，也必须在单个工单 查询和执行工单查询两步都按该发货单自己的提出人 username 过滤（主流程步骤 3 已保证窗口内只会有名册 内成员的发货单）。名册外人员发起的工单即使 new_track 已落地，也不补写、不建行——每个成员只给自己 负责的网红发物流邮件，Base 只收录名册内成员的 PO。

KOL Name extraction rule

Strip trailing markers from PO Number:

• Date suffix: (26-07-17) → strip
• Restock marker: 补 → strip
• Series marker: G-PRO, GPRO → strip
• Numeric suffix: -2, -4, -7 → strip

初始化 / 清空 (reset Base) — 管理员操作

lark-cli base +record-list --base-token UGuHbNi6GapDwTs9kdUcUGZPnzS --table-id tblSbLstfA1xz5M4 --limit 200 --field-id "ID" --format json --as user
lark-cli base +record-delete --base-token UGuHbNi6GapDwTs9kdUcUGZPnzS --table-id tblSbLstfA1xz5M4 --json '{"record_id_list":["rec_xxx",...]}' --yes --as user

(batch ≤50 per delete call). Historical JDY data is never backfilled — only what syncs going forward.

Mode A — Add PO to watchlist

Triggered when the current member gives a 来源单号 to start tracking.

1. Collect inputs: PO name (e.g. showroom_0618) + ship date (ask if missing).
2. Confirm in JDY: query 发货管理 filtered on _widget_1752480297833 = PO name AND 提出人 = the current member (from identity resolution). If the record exists but belongs to someone else, warn the member instead of adding it to their watchlist.
3. Append to watchlist.md: | showroom_0618 | 2026-06-18 |
4. Confirm: "Added showroom_0618 to the watchlist (ship date: 2026-06-18). I'll check JDY daily and notify you when all tracking is filled."
5. On first use only, remind: "To run the daily check automatically, say 'schedule daily tracking check' and I'll set it up with mcp__claw__cron." (On the central admin machine this is already scheduled — see Scheduling section — so this reminder is mainly for newly-onboarded members.)

Mode A variant — Update watchlist from Base

Triggered by "update watchlist" / "sync watchlist" / "refresh watchlist" / "pull watchlist from Base".

1. Query Base tblSbLstfA1xz5M4 with filter All Shipped? = false AND PO Number not empty AND Owner = <my 姓名> (no need for a saved view — pass filter.cond on the query call).
2. Extract per row: PO Number, Ship Date, KOL Name, SKU (context only).
3. Read watchlist.md; for each PO from Base — skip if already present, else append.
4. Confirm: list what was added, or "Watchlist is already up to date."

Mode A variant — Auto-added by influencer-exchange-order (2026-07-22)

The influencer-exchange-order skill (创建网红换货/催发货/新增订单工单) writes directly to the current member's own watchlist.md after it successfully creates a 新增订单/换货/催发货 work order in JDY — this is by design, not a bug: members asked for this so they don't have to manually forward newly-created POs. No action needed on jdy-shipping-track's side; just be aware that watchlist entries can originate from that skill, not only from Mode A / Mode A variant above. The 发货管理 record for these POs is itself auto-generated by the JDY workflow ~10s after work-order submission (提出人 = the member who ran influencer-exchange-order), so Mode 0's normal incremental scan will also pick it up independently.

Mode B — Daily check (per-member)

Triggered on schedule (each member's own cron, e.g. "Daily shipping tracking check") or "check open POs" / "check watchlist". Scope is always the current member: after identity resolution, every JDY/Base query in Mode B filters to 提出人/Owner = me. If a watchlist PO turns out to belong to someone else, skip it and note it in the daily-log.

⚠️ v4.5.0 (2026-07-20): added B2.5 — live tracking sync. Previously Mode B only wrote to Base when a PO fully completed (B3) or got flagged (B4); a PO that was still in-progress but had picked up a fresh tracking number mid-day stayed blank in Base until Mode 0's nightly 0 1 * * * run. 吴双 asked for that gap closed (noticed a fresh tracking number missing from Base right after a 14:00 check), so every Mode B run now pushes any newly-appeared tracking numbers straight to Base as it finds them — Mode 0 is unchanged and still runs nightly as the full incremental system-of-record sync; B2.5 is just a same-day mirror for watchlist POs specifically.

⚠️ v4.7.0 (2026-08-07): Added B2.6 — 执行工单追踪号补充同步. JDY 发货管理's trackingno often does NOT auto-refresh — the member has to manually click 查询并刷新 before the tracking number shows up in 发货管理. That means a 发货/换货 work order can already have a real tracking number in 执行工单 (new_track / 跟踪号) while 发货管理's trackingno is still blank → Base stays blank → B3 judges the PO "missing tracking" → the KOL email can't be sent. B2.6 fixes this by treating 执行工单 as an authoritative supplementary tracking source: when 发货管理 has no tracking for a line but the PO's 执行工单 has a landing new_track/跟踪号 with result=已完成(Done), B2.6 writes that tracking number straight into Base (matched by PO Number + SKU 中文名). This directly addresses the "已发货/已换货但发货管理 不显示单号 → 无法及时更新 Base" problem 吴双 raised on 2026-08-07.

⚠️ v4.6.0 (2026-07-21): B3.5 step 1 gained a fallback — if 网红信息/合同管理/Base ALL KOLs all come up empty for a KOL's email, search the current member's own mailbox by KOL name (lark-cli mail +triage --mailbox me --query "<KOL name>") before giving up. Verified working on Alex Siquig - PLC01 (found siquigalexander@gmail.com from an existing thread). Also documented that lark-cli mail +send cannot create a draft with zero recipients — when no email is found even after this fallback, save the assembled HTML to a tmp file instead of attempting a no-recipient draft.

⚠️ v4.6.1 (2026-07-21): Diagnosed a Mode 0 timeout on 2026-07-21 — root cause was NOT data volume (manually re-ran the exact incremental query: only 5 shipments / 34 rows in the window, trivially fast), it looked like a transient infra/session hiccup shared by multiple unrelated cron jobs firing in the same ~08:56-09:15 BJT window that morning. Manually caught up the missed sync. While doing so, discovered a real dedup edge case (see B2.5 step 2 above): JDY can regenerate a subform item's fororder_no once it actually ships, silently breaking 唯一键-based lookups for that item even though its Base row already exists — added a PO-Number+SKU fallback so B2.5 updates the existing row by --record-id instead of leaving it stuck blank (or worse, creating a duplicate).

⚠️ v4.6.2 (2026-07-21): Clarified B2's "no record / empty subform / full error" branch (see above) — this is much more often a JDY propagation delay (单个新增 → 发货管理 submitted back-to-back) than an actual data-entry error. Verified on Jarell Carter - 奥杆: flagged as a data problem needing the member's attention on the 09:00 run, came back clean with real subform data on manual re-check the same day. Don't tell the member to go fix it in JDY until it's stayed empty/erroring across 2+ Mode B cycles.

⚠️ v4.6.3 (2026-07-21): Mode 0 bumped from 1x/day (0 1 * * *, 01:00 BJT) to 2x/day (30 1,14 * * *, 01:30 and 14:30 BJT) per 吴双's request, to shrink the max data-staleness window from 24h to ~13h. Job re-created (new id, old one removed — the cron tool has no update action). The :30 offset is deliberate, to avoid the exact on-the-hour minute used by Mode B / RITFIT Email Reply's cron slots (helps avoid a repeat of the 2026-07-21 morning clustering incident, even though that was judged a one-off).

B1 — Read watchlist. If empty: print "Watchlist is empty. Nothing to check." and stop.

B2 — Query JDY per PO and render.

Query 发货管理 filtered on _widget_1752480297833 = PO name AND _widget_1780972277486(提出人) = my JDY Username (from identity resolution).

• No record found, OR record found but subform empty / full field returns an error like "请输入正确的平台单号" → render ## [PO name] | ⏳ Not in JDY yet, skip 3-day flag, move to next PO. Do not conclude this is a JDY data-entry error requiring the member to fix it. As of 2026-07-21 (Jarell Carter - 奥杆 case), the far more common cause is a propagation delay: the member submitted 发货管理 immediately after doing a "单个新增" for the same PO, and JDY's backend needs some time (observed: well under a day) to sync the new-item data through to 发货管理. Just re-check on the next scheduled Mode B run — don't flag it to the member as something they need to go fix unless it's still empty/erroring after 2+ check cycles.
• Record found → extract from subform: SKU名称 (translate to English, per the rule below), 跟踪码, 物流渠道名称 (normalize per the Carrier rule below).

SKU English translation rule — strip factory/OEM names (吴双 flagged 2026-07-22, department-wide rule)

SKU中文名里常带代工厂名（拼音），不是官网展示的产品名——KOL看到会困惑，容易以为品牌/产品名变了。 案例："锦华款三段式哑铃凳黑1.1版" 曾被直译成 "Jinhua 3-Position Adjustable Dumbbell Bench, Black v1.1"（Jinhua=锦华，代工厂名），发给KOL Alex Siquig的追踪邮件里出现了这个问题。

规则（全员适用）：翻译SKU英文名时，任何代工厂拼音一律省略不译，只保留产品本身的英文描述。

已知的代工厂拼音黑名单（遇到就从翻译结果里去掉，不要出现在任何面向KOL/外部的英文文本里）：

• 锦华 → Jinhua（已确认案例）
• 创源 → Chuangyuan（已确认案例，出现在"M2 Weight Plate Flag Sticker — Chuangyuan Edition"里）

这份黑名单不是穷尽列表——翻译时如果遇到任何"看起来像代工厂名的拼音"（通常是SKU名开头的品牌感修饰词， 且不对应RITFIT官网/产品目录里的已知产品线名），都应该本着这条规则省略，不要因为不在上面两个词里就直译。 如果拿不准某个词是不是工厂名，优先省略，而不是照抄拼音。

Carrier normalization rule (for all English-facing outputs)

物流渠道名称 from JDY is inconsistent — same physical carrier shows up under different labels depending on service tier / domestic forwarder (e.g. Fedex-环世快递, FEDEX_GROUND, FEDEX_HOME_DELIVERY, FEDEX_ECONOMY, US-FedEx Ground). Showing several different-looking FedEx labels in the same KOL email is confusing (吴双 flagged this 2026-07-17) — KOLs only need to know which carrier network to track on, not the service tier or domestic broker. Rule:

• Mode 0 (Base sync): write the raw JDY value unchanged into the Base Carrier field — Base is the internal system of record and the service-tier/broker detail has ops value there.
• Mode B outputs (SKU tables in daily-log/completed.md, and anything sent to a KOL): normalize by carrier family, case-insensitive substring match on the raw value:
  • Contains fedex → FEDEX (collapses Fedex-环世快递, FEDEX_GROUND, FEDEX_HOME_DELIVERY, FEDEX_ECONOMY, US-FedEx Ground, etc. — any service tier or forwarder — into one label)
  • Contains ups → UPS
  • Contains dhl → DHL
  • Contains usps → USPS
  • Anything else (e.g. GOFO GROUND, Amazon_Ground) → keep as-is, just strip any trailing CJK text after a - if present Example: Fedex-环世快递 → FEDEX; FEDEX_HOME_DELIVERY → FEDEX; GOFO GROUND → GOFO GROUND.

Also check 单个工单 + 批量工单 for escalation status: query filtered on 平台单号 = PO name, type = 催发货. If found, note RMA ID + flowState (已完成 = processed) — do not re-flag a 3-day alert if a work order already exists.

Also check 执行工单 via the two-step RmaId lookup (see Jiandaoyun Config section above). If it has tracking for items still blank in 发货管理:

• Use that tracking (authoritative — it comes from the 催发货 escalation pipeline)
• Add 📋 RMA: [RmaId] next to it
• If 是否有异常/异常详情 is non-empty, flag it: ⚠️ Warehouse error — surface the text to the member
• v4.7.0 (2026-08-07): this is now more than a render-only note — if the tracking landed in 执行工单 but 发货管理's trackingno is still blank, B2.6 writes it straight into Base (see B2.6 below) instead of just showing it in the daily log. The render keeps showing the RMA tag for the log / notification, but the Base write is handled by B2.6.

Render:

## showroom_0618  |  Ship date: 2026-06-18
| SKU Name | Tracking No. | Shipping Method |
|----------|-------------|-----------------|
| MUSTANG Leg Extension Machine Box A | 873237155661 | FEDEX_GROUND |
| MUSTANG Leg Extension Machine Box B |  | FEDEX_GROUND |

B2.5 — Live tracking sync to Base (added v4.5.0, 2026-07-20). Don't wait for tonight's Mode 0 run to mirror newly-appeared tracking numbers — write them to Base immediately, every time Mode B checks a PO. This runs for every watchlist PO on every check, not just completed/flagged ones. Mode 0's nightly 0 1 * * * incremental sync is unaffected and keeps running exactly as before — this step is just a faster mirror scoped to watchlist POs; POs not on the watchlist still only get synced by Mode 0.

For each item in the JDY info[] subform for this PO that has a non-empty trackingno:

1. Look up the matching Base row by its dedup key (same key Mode 0 uses): lark-cli base +record-search --base-token UGuHbNi6GapDwTs9kdUcUGZPnzS --table-id tblSbLstfA1xz5M4 --search-field 唯一键 --keyword "<发货单号>||<fororder_no>" --as user. This is a substring search — verify the returned row's 唯一键 is an exact match (trim-compare) before using it.
2. Not found by 唯一键 → before concluding "not synced yet", try one fallback (added 2026-07-21, confirmed real on Kody Workman 哑铃): search Base by PO Number instead (+record-search --search-field "PO Number" --keyword "<PO name>") and match by SKU text. JDY can regenerate fororder_no for a subform item once it actually ships — an item that sat blank in Base with an old fororder_no-based 唯一键 can silently get a new fororder_no in JDY the moment its tracking number appears, so the 唯一键 search for the new value will never find the old row even though it's sitting right there in Base waiting to be filled in. If a PO Number+SKU match finds an existing blank/stale row this way, update that row by its --record-id directly rather than creating a new one — do not blindly upsert-by-唯一键, which would create a duplicate row and leave the original permanently blank. Only if PO Number search also finds nothing is it genuinely "not synced yet" (e.g. a showroom PO) → skip silently, Mode 0 will create the row later.
3. Found, and Base's Tracking Info already equals the JDY value → skip, no-op (avoid redundant writes on every check).
4. Found, and Base's Tracking Info is blank or different → write it now: lark-cli base +record-upsert --base-token UGuHbNi6GapDwTs9kdUcUGZPnzS --table-id tblSbLstfA1xz5M4 --record-id "<rec_id>" --json '{"Tracking Info": "<trackingno>", "Carrier": "<raw logisticschannel_name>"}' --as user. Carrier is written raw (unnormalized), matching the Mode 0 rule below — Base is the internal system of record and keeps the service-tier/broker detail; only Mode B's rendered/emailed output uses the normalized carrier name. ⚠️ Permission note (v5.0): this write only succeeds on rows where 负责人 = me (Base advanced permissions). If it fails with a permission error, log it and move on — central Mode 0 will catch the value on its next run.
5. This step only ever touches Tracking Info / Carrier. It never sets Status or All Shipped? — that stays B3's (completion) and B4's (flag) job, which still run right after using this now-current data. Since writes are by --record-id (not a fresh upsert-by-key), this can never create a duplicate row or race with tonight's Mode 0 run — Mode 0 will just re-write the same value later and no-op.
6. Note in the daily-log run entry if any live syncs happened this run (e.g. "Live-synced 2 tracking numbers to Base ahead of tonight's Mode 0 run").

B2.6 — 执行工单追踪号补充同步 (added v4.7.0, 2026-08-07). 发货管理 trackingno 常需手动"查询并刷新"才显示， 但追踪号往往已经真实落地在执行工单（new_track 换货/补发新单号，或 _widget_1780391793600 原始跟踪号）。 本节把执行工单当作追踪号的权威补充来源，凡是发货管理没有单号、但执行工单已完成的，直接写进 Base。 只在 B2 发现"发货管理某行 trackingno 为空"时对那一行触发（发货管理已有单号的行走 B2.5 逻辑，不要重复处理）。 （权限同 B2.5：只能写 负责人=我 的行；失败就留给集中 Mode 0 兜底。）

前置：B2 已经做过 单个工单→RMA ID→执行工单 两步查询（见 Jiandaoyun Config 的执行工单查找说明）。 本节直接复用该结果。若 B2 因某种原因没查执行工单，先补查：

{"cond":[{"field":"_widget_1776219080908","method":"eq","value":["<RMA ID>"]}]}

（app_id 66d696158e78f315b2476b1b, entry_id 69ca3653e80a04d0ebe03a38, 分页 limit=100。）

对执行工单返回的每一行：

1. 取追踪号：优先 new_track（_widget_1780391793602，换货/补发后的新单号）；为空则取原始跟踪号 _widget_1780391793600；两者都为空 → 该行无单号，跳过。
2. 只认已完成的行：result（_widget_1774860170334）必须是 已完成(Done) 才采信。若 result 不是 已完成（待处理/部分完成/有问题），跳过该行——追踪号可能是中间态，等下一轮。⚠️ 若 status（_widget_1778651173620， 是否有异常）非空或 error（_widget_1782093678117）非空，即使有 new_track 也不写入，按 B2 的 异常规则把告警带出给该成员（写进 daily-log 的 ⚠️ 行），不要静默写入。
3. 匹配 Base 行：该执行工单行有 skuname（_widget_1778662217862，原始SKU名）和 after_skuname（_widget_1778662217863，换货后的SKU名）。用 PO Number + SKU 中文名找 Base 行：
   • 优先 lark-cli base +record-search --search-field "PO Number" --keyword "<PO name>" --as user， 拿回该 PO 全部 Base 行；
   • 在结果里用 SKU 文本精确比对（trim 后完全相等）。优先比 after_skuname，再比 skuname，再比原始 发货管理里该行的 sku_name。命中 → 拿到 record_id。
   • 若 Base 里没有该 PO 的任何行（例如 showroom PO 或空壳单从未进过 Base）→ 按 B2.5 step 2 的规则静默跳过， 留待 Mode 0 建行（本功能只负责给已有行补单号，不负责建行）。
4. 写入 Base：对命中的行 +record-upsert --record-id "<rec_id>" --json '{"Tracking Info": "<追踪号>", "Carrier": "<carrier>"}' --as user。
   • Carrier：执行工单本身不存物流渠道。优先取发货管理该行已有的 logisticschannel_name（原始值不 normalize）； 若发货管理里该行也没有渠道 → 留空

…(truncated)