cbs-4px-merchant-cli 0.0.11 → 0.0.13

package/skill/reference/order.md

@@ -268,6 +268,102 @@ fmc order country 日本 --output json
 
 ---
 
+### `fmc order field-rules`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `order field-rules` |
+| **Description** | 查询下单字段规则：哪些字段必填、填写规范、校验提示、跨字段联动约束 |
+| **Usage** | `fmc order field-rules --product-code <code> --country <cc> [flags]` |
+
+需要 API Key 认证。**建单/改单前应先调本命令**。
+
+字段必填性由后端规则库按 (产品, 目的国, 客户) 配置，三级降级取值（产品规则 → 产品组规则 → 默认规则），**同一字段在不同产品下结论可能相反**。所以不要凭经验或文档假定必填项，查这里。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--product-code <code>` | string | yes | 物流产品代码，从 `product recommend` / `product search` 获取 |
+| `--country <code>` | string | yes | 目的国家二字码，从 `order country` 获取 |
+| `--required-only` | boolean | no | 只返回必填字段 |
+| `--field <name>` | string | no | 只看指定字段（字段名或中文标签）。仅过滤展示，不改变查询范围 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+# 建单前查该产品+目的国的必填项
+fmc order field-rules --product-code A65 --country US --required-only
+```
+
+```bash
+# 查单个字段的填写规范（如邮编格式）
+fmc order field-rules --product-code A65 --country US --field consigneePostcode
+```
+
+```bash
+# 给 Agent 消费
+fmc order field-rules --product-code A65 --country DE --output json
+```
+
+#### Output (text mode)
+
+```
+下单字段规则
+────────────────────────────────────────────────────────────
+  产品        A65
+  目的国家    US
+
+  必填字段（3）
+  ──────────────────────────────────────────────────
+  * consigneeName  收件人姓名
+      规则        nullValue=Y, maxLength=35
+      提示        收件人姓名:不能为空
+  * consigneePostcode  收件人邮编
+      规则        nullValue=Y, regex
+      填写规范    5 位数字，如 97201
+  * customerWeight  重量
+      规则        nullValue=Y
+
+  非必填字段（1）
+  ──────────────────────────────────────────────────
+    iossNo  IOSS税号
+      规则        maxLength=12
+
+  跨字段联动约束
+  ──────────────────────────────────────────────────
+  · iossNo 与 consigneeVatNo 二选一必填（两者皆空才报错）
+  · 填写 iossNo 时，每个申报品的 hscode 必填
+  · 全单币种须一致：运费、申报保险费、各申报品币种不可混用
+```
+
+#### 字段名与 JSON 路径的对应
+
+返回的 `field` 是**后端订单字段名**（`consigneeName` / `customerWeight` / `pcs`），而 `order create` 的 JSON 是嵌套结构（`receiver.name` / `parcel.weight` / `declareItems[].qty`）。两者**不是驼峰转换关系**，不要自己推。
+
+**每个字段都带 `requestPath`，直接用它**：
+
+```json
+{"field":"consigneeName","requestPath":"receiver.name","required":true,"fieldLabel":"收件人姓名"}
+```
+
+`requestPath` 为 `null` 表示该字段不能通过建单/改单接口设置（只能在界面或由后端计算）。
+
+几个**靠猜必然错**的例子：
+
+| 后端字段名 | JSON 路径 | 容易猜错成 |
+| --- | --- | --- |
+| `consigneeMail` | `receiver.email` | ~~`consigneeEmail`~~ |
+| `customerWeight` | `parcel.weight` | ~~`customerWeight`~~ |
+| `pcs` | `declareItems[].qty` | ~~`pcs`~~ |
+| `brandExport` | `declareItems[].brand` | ~~`brandExport`~~ |
+| `hscode` | `declareItems[].hsCode` | 大小写不同 |
+| `consigneeTelephone` | `receiver.phone` | ~~`receiver.telephone`~~ |
+
+---
+
 ## 下单与订单写操作
 
 ### 状态模型
@@ -291,14 +387,14 @@ fmc order country 日本 --output json
 | `productCode` | string | **yes** | 物流产品代码；先用 `product recommend/search` 选 |
 | `destinationCountry` | string | **yes** | 目的国 ISO2，如 `US` |
 | `originCountry` | string | no | 始发国 ISO2，如 `CN` |
-| `status` | string | no | `P` 预报（默认）、`D` 草稿；`--draft` 自动设 D |
+| `status` | string | no | **不必写**。草稿/预报由 `--draft` 控制。仅为兼容保留（`P` 预报、`D` 草稿），写了也会被 CLI 归一成布尔发出 |
 | `customerOrderNo` | string | no | 客户参考号，建议传店铺订单号 |
 | `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` |
+| `parcel` | object | no | `weight`(kg) `length` `width` `height`(cm) `dutyPayMode` `batteryType` `iossNo` `eoriNo`(EORI，欧盟进口商登记号) `orderNote` `salesPlatform` `warehouseCode` `codPrice` `codCurrency` |
 | `declareItems` | array | no | 每项含 `ename` `cname` `qty` `unitPrice` `currency` `weight`(kg) `hsCode` `material` `uses` `url` `brand` |
 
 完整示例 `order.json`：
@@ -361,7 +457,11 @@ fmc order country 日本 --output json
 }
 ```
 
-后端只硬校验 `productCode` 和 `destinationCountry`。CLI 还会对收件人姓名/地址/国家/邮编/电话、发件人、重量、申报品英文名/数量/单价缺失打印 `⚠`；`hasBattery=Y` 但缺 `parcel.batteryType` 也会告警。有告警先补齐，不要直接提交。欧盟 ≤150EUR 包裹记得填 `parcel.iossNo`，欧美目的国建议拆填 `receiver.firstName`/`lastName` 和 `address2`。
+**上表的"必填"只描述 `create` 接口自身的入参约束，不等于业务必填。**真正哪些字段必填由后端规则库按 (产品, 目的国, 客户) 配置，**不同产品结论不同**，因此建单前先用 `order field-rules --product-code <code> --country <cc>` 查一次，按返回的 `required` 补齐——不要凭本文档或经验假定。
+
+`create` 本身只硬拦 `productCode` 和 `destinationCountry`（它们是查规则的入参，缺了连规则都查不到）。CLI 另有一份本地启发式告警（收件人姓名/地址/国家/邮编/电话、发件人、重量、申报品英文名/数量/单价，以及 `hasBattery=Y` 却缺 `parcel.batteryType`），打印为 `⚠`。这份清单是固定的、对所有产品一视同仁，**只作兜底**：以 `field-rules` 的结果为准，两者冲突时听 `field-rules`。有告警先补齐，不要直接提交。
+
+`field-rules` 还会返回单字段必填表达不了的联动约束：IOSS 与收件人 VAT 二选一、填了 IOSS 则每个申报品 `hsCode` 必填、全单币种须一致等。欧美目的国建议拆填 `receiver.firstName`/`lastName` 和 `address2`。
 
 ### `fmc order create`
 
@@ -379,16 +479,46 @@ cat order.json | fmc order create --file - --draft -y
 
 # 用户明确要求直接下单时，才省略 --draft
 fmc order create --file ./order.json -y
+
+# 以历史单为底稿：复制其产品/寄件人/收件人/包裹/申报品（不复制单号/状态）
+fmc order create --like 4PX0001234567 --draft -y
 ```
 
 | Flag | Required | Description |
 | --- | --- | --- |
-| `--file <path>` | yes | JSON 文件路径；`-` 表示 stdin |
+| `--file <path>` | 二选一 | JSON 文件路径；`-` 表示 stdin（与 `--like` 互斥） |
+| `--like <orderNo>` | 二选一 | 以历史订单为底稿，复制产品/收发件人/包裹/申报品（与 `--file` 互斥） |
 | `--draft` | no | 保存草稿，不直接预报 |
 | `-y, --yes` | non-TTY yes | 跳过终端交互确认 |
 
 返回 `orderId`、物流单号、状态和客户单号。草稿确认无误后用 `forecast`。
 
+#### 校验失败时的返回
+
+后端校验不通过时退出码为 1，stderr 输出 JSON 信封，其中 `error.fieldErrors` 是**结构化的字段级错误**：
+
+```json
+{"error":{"code":"ORDER_CREATE_FAILED","message":"收件人姓名:不能为空;HS编码:不能为空",
+  "fieldErrors":[
+    {"field":"consigneeName","requestPath":"receiver.name","value":"",
+     "msg":"收件人姓名:不能为空","stdErrorCode":"CONSIGNEE_NAME_CANNOT_BE_EMPTY"},
+    {"field":"declareInvoiceList[0].hscode","requestPath":"declareItems[0].hsCode",
+     "msg":"HS编码:不能为空"}]}}
+```
+
+| 字段 | 说明 |
+| --- | --- |
+| `field` | 后端订单字段名，与 `order field-rules` 的 `field` 同一套命名 |
+| `requestPath` | **改 JSON 时用这个**——该字段在请求体里的路径（`receiver.name`、`declareItems[0].hsCode`）。注意下标会保留，指向出错的那一项 |
+| `value` | 提交时的值。空/缺失=没填；有值=填了但不合规 |
+| `msg` | 不通过的原因，可直接念给商家 |
+| `stdErrorCode` | 标准错误码，非空时可程序化判断 |
+
+**优先读 `fieldErrors` 而不是 `message`** —— message 只是把所有 `msg` 用分号拼起来给人看的。
+非校验类失败（余额不足、配额用尽等）没有 `fieldErrors`，这时才回退读 `message`。
+
+`edit` 的失败返回结构完全相同，只是 `code` 为 `ORDER_EDIT_FAILED`。
+
 ### `fmc order edit`
 
 只可编辑草稿或已取消订单。JSON 只传要改的字段；`sender` / `receiver` / `parcel` 内部也按非空字段覆盖，`declareItems` 一旦传入则整组替换。

package/skill/reference/platform.md

@@ -177,6 +177,14 @@ fmc platform sync-record list --size 5 --output json
 | --- | --- | --- | --- |
 | `--status <code>` | string | no | 订单状态：`0` 待推送、`1` 已推送；不传查全部 |
 | `--keyword <word>` | string | no | 关键字（平台订单号 / 客户订单号） |
+| `--platform <name>` | string | no | 电商平台（amazon/shopee 等） |
+| `--country <code>` | string | no | 目的国家二字码（如 US/CN） |
+| `--receiver-name <name>` | string | no | 收件人姓名 |
+| `--buyer-id <id>` | string | no | 买家 ID |
+| `--seller-account-id <id>` | string | no | 卖家账号 ID（从 `platform account list` 获取） |
+| `--product-code <code>` | string | no | 产品代码 |
+| `--start-date <time>` | string | no | 起始时间 `yyyy-MM-dd HH:mm:ss` |
+| `--end-date <time>` | string | no | 截止时间 `yyyy-MM-dd HH:mm:ss` |
 | `--page <num>` | number | no | 页码，默认 1 |
 | `--size <num>` | number | no | 每页数量，默认 10，最大 100 |
 
@@ -193,6 +201,11 @@ fmc platform order list --status 0
 fmc platform order list --keyword 113-1234567-1234567
 ```
 
+```bash
+# 组合筛选：某卖家账号 + 平台 + 目的国 + 待推送
+fmc platform order list --seller-account-id <id> --platform amazon --country US --status 0
+```
+
 #### Output (text mode)
 
 ```
@@ -312,6 +325,76 @@ fmc platform order push --ids 20001 --dry-run
 
 #### Output (text mode)
 
+全部成功：
+
+```
+  ✔ 推送成功：1 个订单
+```
+
+部分失败（后端只回失败明细，逐单列出）：
+
+```
+  ✔ 推送成功：1 个
+  ✖ 推送失败：2 个
+    - CO-20001: 订单已推送（当前状态：已推送），不能重复推送，重复推送会产生重复物流单
+    - CO-20002: 未设置物流产品
+
+  缺渠道或寄件人时用 platform order update 补齐后重推；
+  已推送的订单不能重复推送（会产生重复物流单）。
+```
+
+> **已推送的订单会被后端按状态拒绝。**仅「待推送」「已合单」两种状态可推送；
+> 已推送/标记出货/回写单号一律拒绝，因为重复推送会在下游建出**重复物流单且不可撤回**。
+> 因此重试 push 是安全的：已成功的单不会被推第二次。
+>
+> 推送前用 `platform order list --status 0` 只取待推送的单，可以避免这类失败。
+
+### `fmc platform order update`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `platform order update` |
+| **Description** | 按ID批量更新平台订单（写操作）。可更新字段与界面『修改订单详情』一致，仅传入的字段被更新。典型用途：push 前补齐渠道(productCode)与寄件人(sender*)信息 |
+| **Usage** | `fmc platform order update --ids <ids> [字段flags] [-y]` |
+
+需要 API Key 认证。返回逐单成败清单：`updatedIds` 与 `failed`（含每单失败原因）。
+
+#### Options（常用）
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--ids <ids>` | string | yes | 平台订单 ID，多个用逗号分隔 |
+| `--product-code <v>` | string | no | 物流产品代码（渠道），不传不改 |
+| `--product-name <v>` | string | no | 物流产品名称，不传不改 |
+| `--sender-name <v>` | string | no | 寄件人姓名，不传不改 |
+| `--sender-company <v>` | string | no | 寄件人公司，不传不改 |
+| `--sender-telephone <v>` | string | no | 寄件人电话，不传不改 |
+| `--sender-address <v>` | string | no | 寄件地址，不传不改 |
+| `--sender-city <v>` | string | no | 寄件城市，不传不改 |
+| `--sender-province <v>` | string | no | 寄件省/州，不传不改 |
+| `--sender-postcode <v>` | string | no | 寄件邮编，不传不改 |
+| `--receiver-name <v>` | string | no | 收件人姓名，不传不改 |
+| `--phone-number <v>` | string | no | 收件人电话，不传不改 |
+| `--address-line1 <v>` | string | no | 收件地址行1，不传不改 |
+| `--city <v>` | string | no | 城市，不传不改 |
+| `--country-code <v>` | string | no | 目的国家二字码，不传不改 |
+| `--postal-code <v>` | string | no | 邮编，不传不改 |
+| `--weight <v>` | string | no | 重量(kg)，不传不改 |
+| `--ioss <v>` | string | no | IOSS号(欧盟)，不传不改 |
+| `--vat-no <v>` | string | no | VAT税号，不传不改 |
+| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
+
+> 完整可更新字段与界面『修改订单详情』白名单一致（另含 buyer*/county/country-name/state-or-province/address-line2/tariffno/eori/currency/has-battery/returnsign/单号类等），`--help` 可见全部。
+
+#### Examples
+
+```bash
+# push 前批量补渠道 + 寄件人
+fmc platform order update --ids 20001,20002 --product-code A65 --sender-name "深圳仓" --sender-postcode 518000 -y
+```
+
+#### Output (text mode)
+
 ```
-  ✔ 已提交推送：1 个订单
+  ✔ 更新成功：2 个
 ```