cbs-4px-merchant-cli 0.0.7 → 0.0.8

package/skill/reference/order.md

@@ -238,3 +238,197 @@ fmc order country 日本 --output json
     二字码      US
     三字码      USA
 ```
+
+---
+
+## 下单与订单写操作
+
+### 状态模型
+
+```
+草稿(D) ⇄ order edit
+   │
+   └─ order forecast ─→ 预报(P) ─→ 履约中
+                          ├─ order cancel    取消
+                          └─ order intercept 拦截申请
+```
+
+`order create` 带 `--draft` 保存草稿；不带则直接预报。默认应先建草稿，回查给用户确认后再 `forecast`。预报后不能编辑，拦截也不保证成功。
+
+### 订单 JSON
+
+`create` / `edit` 读取 JSON 文件（传 `--file -` 可从 stdin 读取），因为接口本身接收嵌套 JSON body：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `productCode` | string | **yes** | 物流产品代码；先用 `product recommend/search` 选 |
+| `destinationCountry` | string | **yes** | 目的国 ISO2，如 `US` |
+| `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` |
+
+完整示例 `order.json`：
+
+```json
+{
+  "productCode": "A65",
+  "destinationCountry": "US",
+  "originCountry": "CN",
+  "customerOrderNo": "SHOP-20260831-001",
+  "sender": {
+    "name": "深圳仓",
+    "phone": "13800000000",
+    "address": "宝安区 xx 路 1 号",
+    "country": "CN",
+    "province": "广东",
+    "city": "深圳",
+    "postcode": "518000"
+  },
+  "receiver": {
+    "name": "John Doe",
+    "mobile": "+1 555 0100",
+    "address": "123 Main St",
+    "city": "Portland",
+    "province": "OR",
+    "postcode": "97201",
+    "country": "US",
+    "email": "john@example.com"
+  },
+  "parcel": {
+    "weight": 1.2,
+    "length": 20,
+    "width": 15,
+    "height": 10,
+    "dutyPayMode": "DDU"
+  },
+  "declareItems": [
+    {
+      "ename": "Bluetooth Speaker",
+      "cname": "蓝牙音箱",
+      "qty": 2,
+      "unitPrice": 15.5,
+      "currency": "USD",
+      "weight": 0.5,
+      "hsCode": "8518220000"
+    }
+  ]
+}
+```
+
+后端只硬校验 `productCode` 和 `destinationCountry`。CLI 还会对收件人姓名/地址/国家/邮编/电话、发件人、重量、申报品英文名/数量/单价缺失打印 `⚠`。有告警先补齐，不要直接提交。
+
+### `fmc order create`
+
+创建物流订单（写操作）：
+
+```bash
+# 推荐：先建草稿
+fmc order create --file ./order.json --draft -y
+
+# 只预览 JSON 请求，不发送
+fmc order create --file ./order.json --draft --dry-run
+
+# 从 stdin 读取
+cat order.json | fmc order create --file - --draft -y
+
+# 用户明确要求直接下单时，才省略 --draft
+fmc order create --file ./order.json -y
+```
+
+| Flag | Required | Description |
+| --- | --- | --- |
+| `--file <path>` | yes | JSON 文件路径；`-` 表示 stdin |
+| `--draft` | no | 保存草稿，不直接预报 |
+| `-y, --yes` | non-TTY yes | 跳过终端交互确认 |
+
+返回 `orderId`、物流单号、状态和客户单号。草稿确认无误后用 `forecast`。
+
+### `fmc order edit`
+
+只可编辑草稿或已取消订单。JSON 只传要改的字段；`sender` / `receiver` / `parcel` 内部也按非空字段覆盖，`declareItems` 一旦传入则整组替换。
+
+```bash
+# 改后保持草稿
+fmc order edit --order-id 1001 --file ./patch.json --draft -y
+
+# 改完直接预报
+fmc order edit --order-id 1001 --file ./patch.json -y
+```
+
+| Flag | Required | Description |
+| --- | --- | --- |
+| `--order-id <id>` | yes | 订单 ID（数字） |
+| `--file <path>` | yes | JSON 文件路径；`-` 表示 stdin |
+| `--draft` | no | 保持草稿；不传则改完预报 |
+| `-y, --yes` | non-TTY yes | 跳过终端交互确认 |
+
+### `fmc order forecast`
+
+将草稿提交为预报（写操作）：
+
+```bash
+fmc order forecast --ids 1001 -y
+fmc order forecast --ids 1001,1002 -y
+```
+
+| Flag | Required | Description |
+| --- | --- | --- |
+| `--ids <ids>` | yes | 草稿订单 ID，多个逗号分隔 |
+| `-y, --yes` | non-TTY yes | 跳过终端交互确认 |
+
+批量预报可能部分成功。失败数大于 0 时应按 `failDetails` 逐单处理，不要整批重试。
+
+### `fmc order cancel`
+
+取消草稿或已预报订单（写操作）：
+
+```bash
+fmc order cancel --ids 1001 --reason "客户取消" -y
+```
+
+| Flag | Required | Description |
+| --- | --- | --- |
+| `--ids <ids>` | yes | 订单 ID，多个逗号分隔 |
+| `--reason <text>` | yes | 取消原因，优先使用用户原话 |
+| `-y, --yes` | non-TTY yes | 跳过终端交互确认 |
+
+### `fmc order intercept`
+
+对已预报订单申请拦截（写操作）：
+
+```bash
+fmc order intercept --ids 1001 -y
+```
+
+| Flag | Required | Description |
+| --- | --- | --- |
+| `--ids <ids>` | yes | 订单 ID，多个逗号分隔 |
+| `-y, --yes` | non-TTY yes | 跳过终端交互确认 |
+
+拦截是申请制，不保证成功；已出库或已交接承运商的包裹可能拦不住，必须按每个订单的返回明细告知用户。
+
+### 完整下单流程
+
+```bash
+# 1. 选产品并确认目的国
+fmc product recommend --country US --weight 1.2
+fmc order country 美国
+
+# 2. 从地址簿取发件人，不要编造
+fmc order address-book
+
+# 3. 查 HS 编码并组织 order.json
+fmc customs hscode search --name 蓝牙音箱
+
+# 4. 建草稿，回查给用户核对
+fmc order create --file ./order.json --draft -y
+fmc order get FPX12345678
+
+# 5. 用户确认后提交预报、取面单
+fmc order forecast --ids 1001 -y
+fmc label get FPX12345678
+```

package/skill/reference/platform.md

@@ -0,0 +1,317 @@
+# `fmc platform` command
+
+平台拉单：把电商平台（如 Amazon）的卖家账号订单同步到 BPortal，再推送给物流服务商履约。
+
+典型链路：
+
+```
+account list  →  sync  →  sync-record list（轮询）  →  order list  →  order push
+```
+
+> `platform sync` 与 `platform order push` 是**写操作**，默认会在终端二次确认。
+> 非交互环境（管道、CI、AI Agent）必须显式加 `-y`，否则命令会拒绝执行并以退出码 1 结束。
+> 想先看请求内容而不真正发送，用 `--dry-run`。
+
+## Command details
+
+### `fmc platform account list`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `platform account list` |
+| **Description** | 查询已授权的卖家账号列表 |
+| **Usage** | `fmc platform account list [flags]` |
+
+需要 API Key 认证。拉单前先用它拿到 `--seller-account-id`。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--page <num>` | number | no | 页码，默认 1 |
+| `--size <num>` | number | no | 每页数量，默认 10，最大 100 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc platform account list
+```
+
+```bash
+fmc platform account list --page 2 --size 20 --output json
+```
+
+#### Output (text mode)
+
+```
+卖家账号列表
+────────────────────────────────────────────────────────────
+
+  10086
+    账号名称    my-amazon-store
+    平台        AMAZON
+    站点        US
+    商户ID      A1BCDEFGHIJKLM
+    状态        已授权
+
+  共 1 个账号
+```
+
+---
+
+### `fmc platform sync`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `platform sync` |
+| **Description** | 从卖家账号拉取平台订单（异步写操作） |
+| **Usage** | `fmc platform sync --seller-account-id <id> --time-from <time> --time-to <time> [flags]` |
+
+需要 API Key 认证。**写操作**，默认二次确认。
+
+拉单是异步的：接口只回执"任务已提交"，实际拉到多少单要用 `platform sync-record list` 轮询。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--seller-account-id <id>` | string | yes | 卖家账号 ID（从 `platform account list` 获取） |
+| `--time-from <time>` | string | yes | 订单起始时间 `yyyy-MM-dd HH:mm:ss` |
+| `--time-to <time>` | string | yes | 订单截止时间 `yyyy-MM-dd HH:mm:ss` |
+| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc platform sync --seller-account-id 10086 \
+  --time-from "2026-08-01 00:00:00" --time-to "2026-08-31 23:59:59"
+```
+
+```bash
+# 脚本 / AI Agent 场景
+fmc platform sync --seller-account-id 10086 \
+  --time-from "2026-08-01 00:00:00" --time-to "2026-08-31 23:59:59" -y --output json
+```
+
+```bash
+# 只看会发出什么请求
+fmc platform sync --seller-account-id 10086 \
+  --time-from "2026-08-01 00:00:00" --time-to "2026-08-31 23:59:59" --dry-run
+```
+
+#### Output (text mode)
+
+```
+  ✔ 拉单任务已提交
+
+  拉单为异步执行，请用 sync-record list 轮询结果
+```
+
+---
+
+### `fmc platform sync-record list`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `platform sync-record list` |
+| **Description** | 查询平台订单拉取/同步记录 |
+| **Usage** | `fmc platform sync-record list [flags]` |
+
+需要 API Key 认证。`platform sync` 的结果只在这里可见。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--page <num>` | number | no | 页码，默认 1 |
+| `--size <num>` | number | no | 每页数量，默认 10，最大 100 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc platform sync-record list
+```
+
+```bash
+fmc platform sync-record list --size 5 --output json
+```
+
+#### Output (text mode)
+
+```
+拉单记录
+────────────────────────────────────────────────────────────
+
+  9001
+    卖家账号    my-amazon-store
+    起始时间    2026-08-01 00:00:00
+    截止时间    2026-08-31 23:59:59
+    状态        已完成
+    拉取总数    128
+    实际入库    126
+
+  共 1 条
+```
+
+---
+
+### `fmc platform order list`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `platform order list` |
+| **Description** | 查询已拉取的平台订单列表 |
+| **Usage** | `fmc platform order list [flags]` |
+
+需要 API Key 认证。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--status <code>` | string | no | 订单状态：`0` 待推送、`1` 已推送；不传查全部 |
+| `--keyword <word>` | string | no | 关键字（平台订单号 / 客户订单号） |
+| `--page <num>` | number | no | 页码，默认 1 |
+| `--size <num>` | number | no | 每页数量，默认 10，最大 100 |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+# 待推送的订单
+fmc platform order list --status 0
+```
+
+```bash
+fmc platform order list --keyword 113-1234567-1234567
+```
+
+#### Output (text mode)
+
+```
+平台订单列表
+────────────────────────────────────────────────────────────
+
+  [待推送] 20001
+    平台单号    113-1234567-1234567
+    客户单号    CO20260801001
+    卖家账号    my-amazon-store
+    收件人      John Smith
+    目的国家    美国
+    产品        美国专线
+    金额        29.99 USD
+    创建时间    2026-08-01 10:22:31
+
+  共 1 条
+```
+
+---
+
+### `fmc platform order detail`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `platform order detail` |
+| **Description** | 查询平台订单详情（含收件人、报关物品） |
+| **Usage** | `fmc platform order detail <id> [flags]` |
+
+需要 API Key 认证。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `<id>` | string | yes | 平台订单 ID（从 `platform order list` 获取） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc platform order detail 20001
+```
+
+```bash
+fmc platform order detail 20001 --output json
+```
+
+#### Output (text mode)
+
+```
+平台订单详情
+──────────────────────────────────────────────────
+  订单ID      20001
+  平台单号    113-1234567-1234567
+  平台        AMAZON
+  卖家账号    my-amazon-store
+  推送状态    待推送
+
+  收件信息
+  ────────────────────────────────────────
+  收件人      John Smith
+  国家        美国
+  城市        Los Angeles
+  邮编        90001
+
+  物流与金额
+  ────────────────────────────────────────
+  产品        美国专线
+  订单金额    29.99 USD
+
+  报关物品
+  ────────────────────────────────────────
+  Phone Case
+    SKU         SKU001
+    数量        2
+    单价        14.99 USD
+```
+
+---
+
+### `fmc platform order push`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `platform order push` |
+| **Description** | 将待推送的平台订单推送到物流服务商履约 |
+| **Usage** | `fmc platform order push --ids <ids> [flags]` |
+
+需要 API Key 认证。**写操作**，默认二次确认。
+
+推送后订单进入履约流程，无法通过本 CLI 撤回；推送前建议先用 `platform order detail` 核对收件信息。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `--ids <ids>` | string | yes | 平台订单 ID，多个用逗号分隔 |
+| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc platform order push --ids 20001
+```
+
+```bash
+fmc platform order push --ids 20001,20002,20003 -y
+```
+
+```bash
+fmc platform order push --ids 20001 --dry-run
+```
+
+#### Output (text mode)
+
+```
+  ✔ 已提交推送：1 个订单
+```

package/skill/reference/update.md

@@ -15,7 +15,7 @@ fmc skill install|status|uninstall [--agent <ids>] [--force] [--dry-run] [--outp
 完成后自动调用一次 `fmc skill install`，把新版 SKILL.md 同步到所有已检测到的
  AI 工具目录（`~/.qoder/skills/`、`~/.claude/skills/`、`~/.cursor/skills/` 等）。
 
-> **为何不靠 npm postinstall：**npm 11 默认拦截依赖包的安装期脚本，**且跳过时仍然退出 0**。
+> **为何不靠 npm postinstall：**npm 12 默认拦截依赖包的安装期脚本，**且跳过时仍然退出 0**。
 > 所以 skill 铺设不能依赖生命周期钩子，`fmc skill install` 才是唯一可靠的入口；
 > postinstall 仅作为“能跑就顺便跑”的便利钩子保留。