cbs-4px-merchant-cli 0.0.8 → 0.0.11

package/skill/reference/order.md

@@ -49,6 +49,13 @@ fmc order get FPX12345678 --verbose
   实重(g)     500
   计费重(g)   600
 
+  包裹信息
+  件数        1
+  申报重(g)   500
+  尺寸(cm)    20 x 15 x 10
+  IOSS税号    IM1234567890
+  关税方式    DDU
+
   收件人信息
   姓名        John Doe
   国家        US
@@ -58,7 +65,7 @@ fmc order get FPX12345678 --verbose
   电话        +1234567890
 
   申报信息
-  1    T-Shirt              10.00 USD
+  1    T-Shirt              x2    10.00 USD HS:6109100021
 
   费用明细
   运费             应付: 25.00 USD
@@ -86,10 +93,18 @@ fmc order get FPX12345678 --verbose
 | `--status <status>` | string | no | 订单状态筛选，如 IN_TRANSIT、DELIVERED、CREATED 等 |
 | `--customer-order-no <no>` | string | no | 客户订单号 |
 | `--fpx-track-no <no>` | string | no | FPX 运单号 |
+| `--date-type <type>` | string | no | 日期类型: RECEIVED_DATE(预报,默认)/CREATE_DATE(创建)/IN_OPERATION_DATE(入库)/OUT_OPERATION_DATE(出库) |
 | `--start-date <date>` | string | no | 起始日期，格式 yyyy-MM-dd |
 | `--end-date <date>` | string | no | 结束日期，格式 yyyy-MM-dd |
 | `--product-code <code>` | string | no | 产品代码 |
 | `--destination-country <code>` | string | no | 目的国家二字码 |
+| `--consignee-name <name>` | string | no | 收件人姓名 |
+| `--buyer-id <id>` | string | no | 买家ID |
+| `--is-print <Y\|N>` | string | no | 是否已打印 |
+| `--oda-confirm <status>` | string | no | 偏远订单确认状态 |
+| `--intercept-status <status>` | string | no | 拦截状态 |
+| `--change-no-status <status>` | string | no | 换号状态 |
+| `--is-history <Y\|N>` | string | no | 是否查历史订单(>6个月) |
 | `--page <num>` | number | no | 页码，默认 1 |
 | `--size <num>` | number | no | 每页数量，默认 10 |
 
@@ -133,6 +148,9 @@ fmc order list --page 2 --size 20 --output json
     创建时间    2024-01-14 08:00:00
 ```
 
+列表里的**单号**可直接用于 `order edit --orderNo`、`order forecast --orderNo`、`order cancel --orderNo`、
+`order intercept --orderNo`。全部写操作只认单号，不需要也不接受订单 ID。
+
 ---
 
 ### `fmc order address-book`
@@ -140,14 +158,19 @@ fmc order list --page 2 --size 20 --output json
 | Field | Value |
 | --- | --- |
 | **Name** | `order address-book` |
-| **Description** | 查询发件地址簿（商家预存的发件/揽收/退件地址） |
+| **Description** | 查询商家地址簿（发件人/收件人/退件/揽收地址，含默认标记） |
 | **Usage** | `fmc order address-book [flags]` |
 
 需要 API Key 认证。
 
 #### Options
 
-无额外参数。
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--type <type>` | string | no | 地址类型: shipper 发件人(默认)/consignee 收件人/return 退件/collect 揽收 |
+| `--keyword <word>` | string | no | 搜索关键词（姓名/公司/电话） |
+| `--page <num>` | number | no | 页码，默认 1 |
+| `--size <num>` | number | no | 每页数量，默认 10 |
 
 支持全局选项: `--output`, `--verbose`, `--dry-run`
 
@@ -158,33 +181,37 @@ fmc order address-book
 ```
 
 ```bash
-fmc order address-book --output json
+fmc order address-book --type consignee --keyword 张
+```
+
+```bash
+fmc order address-book --type collect --output json
 ```
 
 #### Output (text mode)
 
 ```
-地址簿列表
+发件人地址列表
 ──────────────────────────────────────────────────
   共 3 条
 
-  深圳仓库
-    联系人      张三
+  1001 [默认]  张三
+    公司        shencom
     电话        13800138000
-    国家        CN
-    城市        深圳
-    地址        广东省深圳市南山区科技园路1号
+    地区        CN guangdong shenzhen
+    详细地址    科技园路1号
     邮编        518000
 
-  广州仓库
-    联系人      李四
+  1002  李四
+    公司        XSS Company
     电话        13900139000
-    国家        CN
-    城市        广州
-    地址        广东省广州市天河区天河路2号
+    地区        CN Guangdong Guangzhou
+    详细地址    天河路2号
     邮编        510000
 ```
 
+创建订单时可直接复用地址簿中的地址信息填充 sender/receiver。
+
 ---
 
 ### `fmc order country`
@@ -266,10 +293,13 @@ fmc order country 日本 --output json
 | `originCountry` | string | no | 始发国 ISO2，如 `CN` |
 | `status` | string | no | `P` 预报（默认）、`D` 草稿；`--draft` 自动设 D |
 | `customerOrderNo` | string | no | 客户参考号，建议传店铺订单号 |
-| `sender` | object | no | `name` `company` `phone` `address` `country` `postcode` `city` `province` |
-| `receiver` | object | no | `name` `company` `phone` `mobile` `address` `city` `province` `postcode` `country` `email` |
-| `parcel` | object | no | `weight`(kg) `length` `width` `height`(cm) `dutyPayMode` |
-| `declareItems` | array | no | 每项含 `ename` `cname` `qty` `unitPrice` `currency` `weight` `hsCode` |
+| `pieces` | number | no | 件数，默认 1 |
+| `hasBattery` | string | no | 是否带电 `Y`/`N`；为 `Y` 时 `parcel.batteryType` 必填 |
+| `buyerId` | string | no | 电商平台买家 ID |
+| `sender` | object | no | `name` `company` `phone` `mobile` `email` `address` `address2` `country` `postcode` `city` `province` |
+| `receiver` | object | no | `name` `company` `phone` `mobile` `firstName` `lastName` `address` `address2` `street` `doorNo` `city` `province` `postcode` `country` `email` `idCode` `vatNo` |
+| `parcel` | object | no | `weight`(kg) `length` `width` `height`(cm) `dutyPayMode` `batteryType` `iossNo` `orderNote` `salesPlatform` `warehouseCode` `codPrice` `codCurrency` |
+| `declareItems` | array | no | 每项含 `ename` `cname` `qty` `unitPrice` `currency` `weight`(kg) `hsCode` `material` `uses` `url` `brand` |
 
 完整示例 `order.json`：
 
@@ -279,10 +309,15 @@ fmc order country 日本 --output json
   "destinationCountry": "US",
   "originCountry": "CN",
   "customerOrderNo": "SHOP-20260831-001",
+  "pieces": 1,
+  "hasBattery": "N",
   "sender": {
     "name": "深圳仓",
     "phone": "13800000000",
+    "mobile": "13800000000",
+    "email": "ship@example.com",
     "address": "宝安区 xx 路 1 号",
+    "address2": "3 栋 5 楼",
     "country": "CN",
     "province": "广东",
     "city": "深圳",
@@ -290,8 +325,11 @@ fmc order country 日本 --output json
   },
   "receiver": {
     "name": "John Doe",
+    "firstName": "John",
+    "lastName": "Doe",
     "mobile": "+1 555 0100",
     "address": "123 Main St",
+    "address2": "Apt 4B",
     "city": "Portland",
     "province": "OR",
     "postcode": "97201",
@@ -303,7 +341,9 @@ fmc order country 日本 --output json
     "length": 20,
     "width": 15,
     "height": 10,
-    "dutyPayMode": "DDU"
+    "dutyPayMode": "DDU",
+    "iossNo": "IM1234567890",
+    "orderNote": "轻拿轻放"
   },
   "declareItems": [
     {
@@ -313,13 +353,15 @@ fmc order country 日本 --output json
       "unitPrice": 15.5,
       "currency": "USD",
       "weight": 0.5,
-      "hsCode": "8518220000"
+      "hsCode": "8518220000",
+      "material": "ABS",
+      "uses": "家用"
     }
   ]
 }
 ```
 
-后端只硬校验 `productCode` 和 `destinationCountry`。CLI 还会对收件人姓名/地址/国家/邮编/电话、发件人、重量、申报品英文名/数量/单价缺失打印 `⚠`。有告警先补齐，不要直接提交。
+后端只硬校验 `productCode` 和 `destinationCountry`。CLI 还会对收件人姓名/地址/国家/邮编/电话、发件人、重量、申报品英文名/数量/单价缺失打印 `⚠`；`hasBattery=Y` 但缺 `parcel.batteryType` 也会告警。有告警先补齐，不要直接提交。欧盟 ≤150EUR 包裹记得填 `parcel.iossNo`，欧美目的国建议拆填 `receiver.firstName`/`lastName` 和 `address2`。
 
 ### `fmc order create`
 
@@ -353,31 +395,35 @@ fmc order create --file ./order.json -y
 
 ```bash
 # 改后保持草稿
-fmc order edit --order-id 1001 --file ./patch.json --draft -y
+fmc order edit --orderNo ORD-20240115-001 --file ./patch.json --draft -y
 
 # 改完直接预报
-fmc order edit --order-id 1001 --file ./patch.json -y
+fmc order edit --orderNo ORD-20240115-001 --file ./patch.json -y
 ```
 
 | Flag | Required | Description |
 | --- | --- | --- |
-| `--order-id <id>` | yes | 订单 ID（数字） |
+| `--orderNo <no>` | yes | 要编辑的订单单号（4px 物流单号或客户订单号） |
 | `--file <path>` | yes | JSON 文件路径；`-` 表示 stdin |
 | `--draft` | no | 保持草稿；不传则改完预报 |
 | `-y, --yes` | non-TTY yes | 跳过终端交互确认 |
 
+> **所有订单写操作一律用单号 `--orderNo`。** 数据库自增主键已从接口彻底移除，不存在 `--ids` 参数。
+> 单号可以是 4px 物流单号（如 `4PX3003136946232CN`）或客户订单号（如 `TEST22026090700014129`），
+> 后端两者都能识别。草稿单还没有 4px 物流单号，用客户订单号。
+
 ### `fmc order forecast`
 
 将草稿提交为预报（写操作）：
 
 ```bash
-fmc order forecast --ids 1001 -y
-fmc order forecast --ids 1001,1002 -y
+fmc order forecast --orderNo TEST22026090700014129 -y
+fmc order forecast --orderNo TEST2026...01,TEST2026...02 -y
 ```
 
 | Flag | Required | Description |
 | --- | --- | --- |
-| `--ids <ids>` | yes | 草稿订单 ID，多个逗号分隔 |
+| `--orderNo <nos>` | yes | 草稿订单单号（客户订单号；草稿还没有 4px 物流单号），多个逗号分隔 |
 | `-y, --yes` | non-TTY yes | 跳过终端交互确认 |
 
 批量预报可能部分成功。失败数大于 0 时应按 `failDetails` 逐单处理，不要整批重试。
@@ -387,29 +433,33 @@ fmc order forecast --ids 1001,1002 -y
 取消草稿或已预报订单（写操作）：
 
 ```bash
-fmc order cancel --ids 1001 --reason "客户取消" -y
+fmc order cancel --orderNo 4PX3003136946232CN --reason "客户取消" -y
+fmc order cancel --orderNo 4PX3003...CN,4PX3003...CN --reason "客户取消" -y
 ```
 
 | Flag | Required | Description |
 | --- | --- | --- |
-| `--ids <ids>` | yes | 订单 ID，多个逗号分隔 |
+| `--orderNo <nos>` | yes | 订单单号（4px 物流单号或客户订单号），多个逗号分隔 |
 | `--reason <text>` | yes | 取消原因，优先使用用户原话 |
 | `-y, --yes` | non-TTY yes | 跳过终端交互确认 |
 
+仅**预报**或**草稿**状态可取消，其他状态后端会明确拒绝并告知该单当前状态。
+
 ### `fmc order intercept`
 
 对已预报订单申请拦截（写操作）：
 
 ```bash
-fmc order intercept --ids 1001 -y
+fmc order intercept --orderNo 4PX3003136946232CN -y
 ```
 
 | Flag | Required | Description |
 | --- | --- | --- |
-| `--ids <ids>` | yes | 订单 ID，多个逗号分隔 |
+| `--orderNo <nos>` | yes | 订单单号（4px 物流单号或客户订单号），多个逗号分隔 |
 | `-y, --yes` | non-TTY yes | 跳过终端交互确认 |
 
 拦截是申请制，不保证成功；已出库或已交接承运商的包裹可能拦不住，必须按每个订单的返回明细告知用户。
+返回明细里的单号就是你传入的单号，可直接对应。
 
 ### 完整下单流程
 
@@ -428,7 +478,7 @@ fmc customs hscode search --name 蓝牙音箱
 fmc order create --file ./order.json --draft -y
 fmc order get FPX12345678
 
-# 5. 用户确认后提交预报、取面单
-fmc order forecast --ids 1001 -y
+# 5. 用户确认后提交预报、取面单（用单号，不用查 ID）
+fmc order forecast --orderNo ORD-20240114-002 -y
 fmc label get FPX12345678
 ```

package/skill/reference/platform.md

@@ -291,7 +291,7 @@ fmc platform order detail 20001 --output json
 
 | Flag | Type | Required | Description |
 | --- | --- | --- | --- |
-| `--ids <ids>` | string | yes | 平台订单 ID，多个用逗号分隔 |
+| `--ids <ids>` | string | yes | **平台订单** ID（从 `platform order list` 返回值取），多个用逗号分隔。注意这与物流订单无关——物流订单的写操作一律用 `--orderNo` 单号 |
 | `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
 
 支持全局选项: `--output`, `--verbose`, `--dry-run`

package/skill/reference/product.md

@@ -22,6 +22,9 @@
 | `--post-code <code>` | string | no | 目的地邮编 |
 | `--is-battery <flag>` | string | no | 是否带电：1-带电 2-普货 |
 | `--declare-value <amount>` | number | no | 申报总价值 |
+| `--length <cm>` | number | no | 包裹长(cm)，体积重计费产品建议传 |
+| `--width <cm>` | number | no | 包裹宽(cm) |
+| `--height <cm>` | number | no | 包裹高(cm) |
 
 支持全局选项: `--output`, `--verbose`, `--dry-run`