cbs-4px-merchant-cli 0.0.12 → 0.0.13

package/dist/types/index.d.ts

@@ -385,6 +385,9 @@ export interface ProblemListRequest {
     pageSize?: number;
 }
 export interface AbnormalProblem {
+    reasonCode: string | null;
+    abnId: number | null;
+    reasonId: number | null;
     abnormalTypeName: string | null;
     abnormalReasonName: string | null;
     abnormalDescription: string | null;
@@ -503,6 +506,42 @@ export interface ChangeProductResp {
     success: boolean;
     message: string | null;
 }
+/** 下达走货指令参数 */
+export interface ShipmentSubmitParams {
+    orderNo: string;
+    reasonCode: string;
+    solutionChildTypeNo: number;
+    newFpxTrackNo?: string;
+    remark?: string;
+    content?: string;
+}
+/** 下达退件指令参数 */
+export interface ReturnSubmitParams {
+    orderNo: string;
+    reasonCode: string;
+    returnAddressId?: number;
+}
+/** 下达销毁指令参数 */
+export interface DestroySubmitParams {
+    orderNo: string;
+    reasonCode: string;
+}
+/** 退件地址项 */
+export interface ReturnAddressItem {
+    id: number | null;
+    consigneeName: string | null;
+    consigneeTel: string | null;
+    province: string | null;
+    city: string | null;
+    district: string | null;
+    streetAddress: string | null;
+    returnType: string | null;
+    isDefault: string | null;
+}
+/** 退件地址库列表 */
+export interface ReturnAddressListResp {
+    list: ReturnAddressItem[];
+}
 export interface ServiceRepairOrderListRequest {
     orderCodeListString?: string;
     businessLineId?: number;
@@ -1013,6 +1052,31 @@ export interface PlatformOrderDetailResp {
     buyerId: string | null;
     buyerNote: string | null;
     createdTime: string | null;
+    receiverCompany: string | null;
+    addressLine1: string | null;
+    addressLine2: string | null;
+    countryCode: string | null;
+    countryName: string | null;
+    county: string | null;
+    buyerEmail: string | null;
+    sellerNote: string | null;
+    /** 寄件人整组：平台单 sync 回来必为空，push 前须补齐 */
+    senderName: string | null;
+    senderCompany: string | null;
+    senderTelephone: string | null;
+    senderAddress: string | null;
+    senderCity: string | null;
+    senderProvince: string | null;
+    senderPostcode: string | null;
+    senderId: string | null;
+    ioss: string | null;
+    vatNo: string | null;
+    eori: string | null;
+    tariffno: string | null;
+    hasBattery: string | null;
+    returnsign: string | null;
+    transactionId: string | null;
+    fulfillmentOrderId: string | null;
     items: PlatformOrderItemDetail[] | null;
 }
 export interface IndivAuthRequest {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbs-4px-merchant-cli",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Cbs merchant CLI tool",
   "type": "module",
   "main": "./dist/index.js",

package/skill/SKILL.md

@@ -42,7 +42,7 @@ description: >-
 | 产品推荐 | [`reference/product.md`](reference/product.md) | 参数多（国家/重量/电池/邮编等），必须确认 |
 | 理赔查询 | [`reference/service.md`](reference/service.md) | 参数多（单号/时间/状态/分页），必须确认 |
 | 异常件管理 | [`reference/problem.md`](reference/problem.md) | 确认子命令和参数格式 |
-| 异常托管（改带电/改产品） | [`reference/custody.md`](reference/custody.md) | 含写操作，必须确认参数和确认机制 |
+| 异常托管（改带电/改产品/走货/退件/销毁） | [`reference/custody.md`](reference/custody.md) | 含写操作（销毁不可逆），必须确认参数和确认机制 |
 | 服务中心 | [`reference/service.md`](reference/service.md) | 确认子命令和参数格式 |
 | 财务管理 | [`reference/finance.md`](reference/finance.md) | 确认子命令和参数格式 |
 | 揽收管理 | [`reference/pickup.md`](reference/pickup.md) | 确认参数格式 |
@@ -70,7 +70,7 @@ description: >-
 | `product` | 产品推荐：推荐产品、产品列表、产品详情、时效查询、搜索产品 | [`reference/product.md`](reference/product.md) |
 | `claim` | 理赔查询：按单号/时间/状态查询理赔列表（挂在 `service` 下，即 `fmc service claim ...`） | [`reference/service.md`](reference/service.md) |
 | `problem` | 异常件管理：问题件列表、AI处理建议、通知件、尾程异常、欠费件、拦截件 | [`reference/problem.md`](reference/problem.md) |
-| `custody` | 异常托管：改带电产品查询、AI推荐改产品、批量提交改产品（写操作） | [`reference/custody.md`](reference/custody.md) |
+| `custody` | 异常托管：改带电/改产品查询与提交、查可下达指令、走货/退件/销毁指令下达（写操作，销毁不可逆）、退件地址库查询 | [`reference/custody.md`](reference/custody.md) |
 | `service` | 服务中心：售后工单、查件、投诉、服务单详情、处理记录、理赔详情 | [`reference/service.md`](reference/service.md) |
 | `finance` | 财务管理：账户余额、账单、每日费用、未出账汇总及明细、充值记录（在线及线下）、计费明细 | [`reference/finance.md`](reference/finance.md) |
 | `pickup` | 揽收管理：物料申请单查询 | [`reference/pickup.md`](reference/pickup.md) |
@@ -106,6 +106,10 @@ description: >-
 用户提到"拦截/拦截件" → `fmc problem intercepted`
 用户提到"改带电/换带电产品" → `fmc custody electric`
 用户提到"改产品/换产品/推荐异常产品" → `fmc custody recommend`
+用户提到"这个异常能下哪些指令/可下达指令" → `fmc custody help`
+用户提到"走货/确认走货/换单号走货" → `fmc custody ship`（写操作，先确认）
+用户提到"退件/退回/退货" → `fmc custody return`（写操作，先确认）；查退件地址用 `custody address`
+用户提到"销毁/丢弃/不要了" → `fmc custody destroy`（写操作，不可逆，务必确认）
 用户提到"批量处理异常/托管处理" → 参考跟单助理角色 SOP
 用户提到"工单/售后/报修" → `fmc service repair`
 用户提到"查件/查件进度" → `fmc service check`
@@ -330,7 +334,7 @@ fmc config set baseUrl https://b.4px.com
 - [`reference/order.md`](reference/order.md) — 订单管理详细参数
 - [`reference/product.md`](reference/product.md) — 产品推荐与查询详细参数
 - [`reference/problem.md`](reference/problem.md) — 异常件管理详细参数
-- [`reference/custody.md`](reference/custody.md) — 异常托管（改带电/改产品）详细参数
+- [`reference/custody.md`](reference/custody.md) — 异常托管（改带电/改产品/走货/退件/销毁）详细参数
 - [`reference/service.md`](reference/service.md) — 服务中心与理赔查询详细参数
 - [`reference/finance.md`](reference/finance.md) — 财务管理详细参数
 - [`reference/pickup.md`](reference/pickup.md) — 揽收管理详细参数

package/skill/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbs-4px-merchant-cli",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "BPortal Merchant CLI (fmc) skill — BPortal",
   "files": [
     "SKILL.md",

package/skill/reference/custody.md

@@ -1,13 +1,19 @@
 # `fmc custody` command
 
-> 异常托管 — 改带电 / 改产品。配合 `fmc problem list` 使用。
+> 异常托管 — 改带电 / 改产品 / 走货 / 退件 / 销毁。配合 `fmc problem list` 使用。
 
 ## 背景
 
 当订单在仓库上架时出现异常（如内置电池、磁性物品、无渠道等），商家可通过以下命令将订单
-改换为支持带电的物流产品或替换为有渠道的产品，从而让异常单恢复正常走货。
+改换为支持带电的物流产品或替换为有渠道的产品，或直接对异常单下达走货/退件/销毁指令，
+从而让异常单闭环处理。
 
-### 异常原因编码速查
+### reasonCode 获取方式
+
+`problem list --output json` 返回的 `abnormalProblems[]` 中直接包含 `reasonCode`、`abnId`、
+`reasonId` 三个定位字段——**下达指令时的 `--reason` 直接取 `reasonCode`，无需再做中文名映射**。
+
+### 改带电/改产品异常原因编码速查
 
 | abnormalReasonName | reasonCode | 处理流程 |
 | --- | --- | --- |
@@ -15,7 +21,22 @@
 | 磁性物品 | CXW | 改带电 → `custody electric` |
 | 无渠道 | NC | 改产品 → `custody recommend` |
 
-`problem list --output json` 返回的 `abnormalProblems[].abnormalReasonName` 即为上表中文列。
+### 走货二级指令支持矩阵
+
+`custody ship` 仅支持**无附件、无复杂表单**的走货二级指令；其余指令请转页面处理。
+
+| 类别 | 二级指令编号 | 命令支持 | 备注 |
+| --- | --- | --- | --- |
+| 直接走货 | 1, 5, 23 | ✅ | 认可重量/认可费用/填充包装走货 |
+| 换单号走货 | 8, 13, 26 | ✅ | **必须** `--new-track-no` |
+| 带说明走货 | 24, 25, 27, 28 | ✅ | **必须** `--remark` |
+| 其他 | 17 | ✅ | **必须** `--content` |
+| 需上传附件 | 2, 9, 11, 12, 16 | ❌ | 转页面处理 |
+| 需填复杂表单 | 3, 6, 7, 15 | ❌ | 转页面处理 |
+| 改带电/改产品 | 32, 33 | ❌ | 改用 `custody change` |
+
+> 服务端在提交前会强制调 `get_abnormality_help` 校验该指令是否允许下达；若指令不可下达，
+> 命令会**原样输出服务端返回的可下达指令列表提示**，据此改用正确的二级指令编号重试。
 
 ---
 
@@ -167,6 +188,185 @@ fmc custody change --order-nos FPX12345678 --pk-code ECO-PKG-BAT --reason NZDC -
 
 ---
 
+### `fmc custody help`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `custody help` |
+| **Description** | 查询异常单当前可下达的一级/二级指令列表 |
+| **Usage** | `fmc custody help <orderNo> --reason <code> [flags]` |
+
+需要 API Key 认证。下达走货/退件/销毁指令前，先用它确认可下达的指令编号。
+
+#### Arguments
+
+| Argument | Type | Required | Description |
+| --- | --- | --- | --- |
+| `<orderNo>` | string | yes | 物流单号 |
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--reason <code>` | string | yes | 异常原因编码，取自 problem list 的 `abnormalProblems[].reasonCode` |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc custody help FPX12345678 --reason WD
+fmc custody help FPX12345678 --reason WD --output json
+```
+
+#### Output (text mode)
+
+```
+可下达指令
+──────────────────────────────────────────────────
+
+  走货(1)
+    → 认可重量，确认走货(1)
+    → 更换新单号走货(8)
+
+  退件(2)
+    无二级指令
+
+  销毁(3)
+    无二级指令
+```
+
+---
+
+### `fmc custody ship`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `custody ship` |
+| **Description** | 对异常单下达走货指令（写操作） |
+| **Usage** | `fmc custody ship --order-nos <nos> --reason <code> --child <no> [flags]` |
+
+需要 API Key 认证。**这是写操作**，默认二次确认；非交互环境须加 `-y`。走货支持矩阵见上方「走货二级指令支持矩阵」。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--order-nos <nos>` | string | yes | 物流单号，多个用逗号分隔 |
+| `--reason <code>` | string | yes | 异常原因编码 |
+| `--child <no>` | string | yes | 走货二级指令编号，取自 `custody help` 输出 |
+| `--new-track-no <no>` | string | no | 新物流单号（二级指令 8/13/26 必填） |
+| `--remark <text>` | string | no | 说明（二级指令 24/25/27/28 必填） |
+| `--content <text>` | string | no | 补充说明文本（二级指令 17 必填） |
+| `-y, --yes` | boolean | no | 跳过确认 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+# 认可重量走货
+fmc custody ship --order-nos FPX12345678 --reason WD --child 1
+# 换新单号走货（必带新单号）
+fmc custody ship --order-nos FPX001,FPX002 --reason WD --child 8 --new-track-no FPXNEW001 -y
+# 其他（必带说明文本）
+fmc custody ship --order-nos FPX12345678 --reason WD --child 17 --content "已与客户确认继续走货"
+```
+
+---
+
+### `fmc custody return`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `custody return` |
+| **Description** | 对异常单下达退件指令（写操作） |
+| **Usage** | `fmc custody return --order-nos <nos> --reason <code> [flags]` |
+
+需要 API Key 认证。**这是写操作**。退件地址取自商家退件地址库；未指定 `--address-id` 时使用默认退件地址（确认文案会提示）。可先用 `custody address` 查看可用地址。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--order-nos <nos>` | string | yes | 物流单号，多个用逗号分隔 |
+| `--reason <code>` | string | yes | 异常原因编码 |
+| `--address-id <id>` | string | no | 退件地址标识（取自 `custody address`，不传则使用默认退件地址） |
+| `-y, --yes` | boolean | no | 跳过确认 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+# 使用默认退件地址
+fmc custody return --order-nos FPX12345678 --reason WD
+# 指定退件地址
+fmc custody return --order-nos FPX001,FPX002 --reason WD --address-id 3 -y
+```
+
+---
+
+### `fmc custody destroy`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `custody destroy` |
+| **Description** | 对异常单下达销毁指令（写操作，**不可逆**） |
+| **Usage** | `fmc custody destroy --order-nos <nos> --reason <code> [flags]` |
+
+需要 API Key 认证。**这是不可逆写操作**，确认文案含销毁警示，下达前务必与用户确认。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--order-nos <nos>` | string | yes | 物流单号，多个用逗号分隔 |
+| `--reason <code>` | string | yes | 异常原因编码 |
+| `-y, --yes` | boolean | no | 跳过确认 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc custody destroy --order-nos FPX12345678 --reason WD
+```
+
+---
+
+### `fmc custody address`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `custody address` |
+| **Description** | 查询商家退件地址库列表 |
+| **Usage** | `fmc custody address [flags]` |
+
+需要 API Key 认证。下达退件指令前用它确认 `--address-id`，或核对默认地址。
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc custody address
+fmc custody address --output json
+```
+
+#### Output (text mode)
+
+```
+退件地址库
+──────────────────────────────────────────────────
+
+  id=3 [默认]  张三  13800000000
+    广东省深圳市南山区科技园路1号
+    退件方式：快递退件
+```
+
+---
+
 ## 典型工作流
 
 ### A. 内电/磁性物品 → 改带电
@@ -191,3 +391,16 @@ fmc custody change --order-nos FPX12345678 --pk-code ECO-PKG-BAT --reason NZDC -
 4. 无渠道类 → 逐单 `custody recommend` 查推荐 → 汇总后一次 `custody change`
 5. 首次执行前向用户确认，确认后加 `-y` 批量执行
 6. 执行完毕后向用户报告成功/失败/差价
+
+### D. 走货 / 退件 / 销毁（通用异常处理闭环）
+
+1. `fmc problem list --abnormal-status unresolved --output json`
+   → 取每条异常问题的 `reasonCode`（直接来自 `abnormalProblems[].reasonCode`，无需中文名映射）
+2. `fmc custody help <orderNo> --reason <reasonCode>` → 列出可下达的一级/二级指令编号
+3. 根据用户诉求选择指令下达（写操作，`-y` 前须先向用户确认）：
+   - 走货：`custody ship --order-nos <no> --reason <code> --child <二级编号> [--new-track-no|--remark|--content]`
+   - 退件：先 `custody address` 确认地址 → `custody return --order-nos <no> --reason <code> [--address-id <id>]`
+   - 销毁（**不可逆**）：`custody destroy --order-nos <no> --reason <code>`（务必向用户强调不可逆）
+4. 若提交因前置校验未通过失败：命令会原样输出「可下达指令列表」提示，据此改用正确的二级指令编号重试
+5. 走货指令若命中不支持矩阵（附件类/复杂表单类/改带电改产品），提示用户转页面处理或改用 `custody change`
+6. 执行完毕后向用户报告成功/失败明细

package/skill/reference/index.md

@@ -41,6 +41,11 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `fmc custody electric` | 查询可改带电产品列表 | [custody.md](custody.md) |
 | `fmc custody recommend` | 获取 AI 推荐改产品方案 | [custody.md](custody.md) |
 | `fmc custody change` | 批量提交改带电/改产品（写） | [custody.md](custody.md) |
+| `fmc custody help` | 查询异常单可下达的指令列表 | [custody.md](custody.md) |
+| `fmc custody ship` | 下达走货指令（写） | [custody.md](custody.md) |
+| `fmc custody return` | 下达退件指令（写） | [custody.md](custody.md) |
+| `fmc custody destroy` | 下达销毁指令（写，不可逆） | [custody.md](custody.md) |
+| `fmc custody address` | 查询退件地址库 | [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) |
@@ -104,7 +109,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) |
+| `custody` | `electric`, `recommend`, `change`, `help`, `ship`, `return`, `destroy`, `address` | [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) |