cbs-4px-merchant-cli 0.0.8 → 0.0.9

package/skill/package.json

@@ -1,12 +1,13 @@
 {
   "name": "cbs-4px-merchant-cli",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "BPortal Merchant CLI (fmc) skill — BPortal",
   "files": [
     "SKILL.md",
     "package.json",
     "reference/auth.md",
     "reference/config.md",
+    "reference/custody.md",
     "reference/customs.md",
     "reference/finance.md",
     "reference/index.md",

package/skill/reference/custody.md

@@ -0,0 +1,193 @@
+# `fmc custody` command
+
+> 异常托管 — 改带电 / 改产品。配合 `fmc problem list` 使用。
+
+## 背景
+
+当订单在仓库上架时出现异常（如内置电池、磁性物品、无渠道等），商家可通过以下命令将订单
+改换为支持带电的物流产品或替换为有渠道的产品，从而让异常单恢复正常走货。
+
+### 异常原因编码速查
+
+| abnormalReasonName | reasonCode | 处理流程 |
+| --- | --- | --- |
+| 内电 | NZDC | 改带电 → `custody electric` |
+| 磁性物品 | CXW | 改带电 → `custody electric` |
+| 无渠道 | NC | 改产品 → `custody recommend` |
+
+`problem list --output json` 返回的 `abnormalProblems[].abnormalReasonName` 即为上表中文列。
+
+---
+
+## Command details
+
+### `fmc custody electric`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `custody electric` |
+| **Description** | 查询指定异常单可更换的带电产品列表及差价 |
+| **Usage** | `fmc custody electric <orderNo> [flags]` |
+
+需要 API Key 认证。
+
+#### Arguments
+
+| Argument | Type | Required | Description |
+| --- | --- | --- | --- |
+| `<orderNo>` | string | yes | 物流单号 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc custody electric FPX12345678
+```
+
+```bash
+fmc custody electric FPX12345678 --output json
+```
+
+#### Output (text mode)
+
+```
+可改带电产品
+──────────────────────────────────────────────────
+
+  ECO-PKG-BAT  经济小包带电版
+    差价(RMB)   +5.00
+
+  STD-EXP-BAT  标准快递带电版
+    差价(RMB)   +12.00
+```
+
+---
+
+### `fmc custody recommend`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `custody recommend` |
+| **Description** | 获取 AI 推荐的改产品方案（含推荐产品及预估差价） |
+| **Usage** | `fmc custody recommend <orderNo> --reason <code> [flags]` |
+
+需要 API Key 认证。
+
+#### Arguments
+
+| Argument | Type | Required | Description |
+| --- | --- | --- | --- |
+| `<orderNo>` | string | yes | 物流单号 |
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--reason <code>` | string | yes | 异常原因编码，如 NC(无渠道) |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc custody recommend FPX12345678 --reason NC
+```
+
+```bash
+fmc custody recommend FPX12345678 --reason NC --output json
+```
+
+#### Output (text mode)
+
+```
+AI 推荐改产品方案
+──────────────────────────────────────────────────
+  方案类型    改产品
+  方案说明    该订单无渠道，推荐更换为有渠道的产品
+  预估差价    +3.50
+
+  推荐产品
+    ECO-PKG  4PX经济小包
+    STD-EXP  4PX标准快递
+```
+
+---
+
+### `fmc custody change`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `custody change` |
+| **Description** | 批量提交改带电/改产品方案（写操作，会真实改变订单的物流产品） |
+| **Usage** | `fmc custody change [flags]` |
+
+需要 API Key 认证。**这是写操作**，默认在终端二次确认；非交互环境必须加 `-y`。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--order-nos <nos>` | string | yes | 物流单号，多个用逗号分隔 |
+| `--pk-code <code>` | string | yes | 目标产品编码 |
+| `--reason <code>` | string | yes | 异常原因编码：NZDC(内电)/CXW(磁性物品)/NC(无渠道) |
+| `-y, --yes` | boolean | no | 跳过确认 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+# 改带电：将内电异常单改为带电产品
+fmc custody change --order-nos FPX12345678 --pk-code ECO-PKG-BAT --reason NZDC
+```
+
+```bash
+# 批量改产品：将多条无渠道异常单改为有渠道产品
+fmc custody change --order-nos FPX001,FPX002,FPX003 --pk-code ECO-PKG --reason NC -y
+```
+
+```bash
+# 先 dry-run 查看将发送的请求
+fmc custody change --order-nos FPX12345678 --pk-code ECO-PKG-BAT --reason NZDC --dry-run
+```
+
+#### Output (text mode)
+
+```
+改带电批量执行结果
+──────────────────────────────────────────────────
+  总计        3 条
+  成功        2
+  失败        1
+
+  失败明细
+    FPX003  pkCode[ECO-PKG-BAT]不在该异常单可选的改带电产品列表中
+```
+
+---
+
+## 典型工作流
+
+### A. 内电/磁性物品 → 改带电
+
+1. `fmc problem list --abnormal-status unresolved --output json`
+   → 从结果中找到 `abnormalReasonName` 为 "内电" 或 "磁性物品" 的订单
+2. `fmc custody electric <orderNo>` → 查看可改的带电产品及差价
+3. 选择合适的产品后：`fmc custody change --order-nos <no> --pk-code <code> --reason NZDC`
+
+### B. 无渠道 → 改产品
+
+1. `fmc problem list --abnormal-status unresolved --output json`
+   → 从结果中找到 `abnormalReasonName` 为 "无渠道" 的订单
+2. `fmc custody recommend <orderNo> --reason NC` → 查看 AI 推荐产品
+3. 选择合适的产品后：`fmc custody change --order-nos <no> --pk-code <code> --reason NC`
+
+### C. 批量托管处理
+
+1. `fmc problem list --abnormal-status unresolved --size 100 --output json`
+2. 按 `abnormalReasonName` 分类订单
+3. 内电/磁性类 → 逐单 `custody electric` 查产品 → 汇总后一次 `custody change`
+4. 无渠道类 → 逐单 `custody recommend` 查推荐 → 汇总后一次 `custody change`
+5. 首次执行前向用户确认，确认后加 `-y` 批量执行
+6. 执行完毕后向用户报告成功/失败/差价

package/skill/reference/index.md

@@ -38,6 +38,9 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `fmc problem lastmile list` | 查询尾程异常列表 | [problem.md](problem.md) |
 | `fmc problem arrear list` | 查询欠费件列表 | [problem.md](problem.md) |
 | `fmc problem intercepted list` | 查询拦截件列表 | [problem.md](problem.md) |
+| `fmc custody electric` | 查询可改带电产品列表 | [custody.md](custody.md) |
+| `fmc custody recommend` | 获取 AI 推荐改产品方案 | [custody.md](custody.md) |
+| `fmc custody change` | 批量提交改带电/改产品（写） | [custody.md](custody.md) |
 | `fmc service repair list` | 查询售后工单列表 | [service.md](service.md) |
 | `fmc service check list` | 查询查件列表 | [service.md](service.md) |
 | `fmc service complaint list` | 查询投诉列表 | [service.md](service.md) |
@@ -101,6 +104,7 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `order` | `get`, `list`, `address-book`, `country`, `create`, `edit`, `forecast`, `cancel`, `intercept` | [order.md](order.md) |
 | `product` | `recommend`, `list`, `detail`, `eta`, `search` | [product.md](product.md) |
 | `problem` | `list`, `suggest`, `notify list`, `notify type`, `lastmile list`, `arrear list`, `intercepted list` | [problem.md](problem.md) |
+| `custody` | `electric`, `recommend`, `change` | [custody.md](custody.md) |
 | `service` | `repair list`, `check list`, `complaint list`, `detail`, `record`, `claim list`, `claim detail`, `claim reason` | [service.md](service.md) |
 | `finance` | `balance`, `bill list`, `daily-fee list`, `unbilled list`, `recharge list`, `fee detail`, `frozen list` | [finance.md](finance.md) |
 | `pickup` | `material list`, `material detail`, `material quota`, `address list` | [pickup.md](pickup.md) |