cbs-4px-merchant-cli 0.0.8 → 0.0.11

package/skill/reference/auth.md

@@ -4,7 +4,8 @@
 
 | Command | Description |
 | --- | --- |
-| `fmc auth login` | 配置 API Key |
+| `fmc auth login` | 手动配置 API Key |
+| `fmc auth agentz` | 通过已登录的 agentz-cli 获取并配置 API Key（AgentZ / 数字员工环境） |
 | `fmc auth status` | 查看当前认证状态 |
 
 ## Command details
@@ -35,6 +36,24 @@
 fmc auth login --api-key sk-xxxxx
 ```
 
+### `fmc auth agentz`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `auth agentz` |
+| **Description** | 检测本机 `agentz-cli`，调用 `agentz-cli client token` 获取当前 AgentZ 客户端的 accessToken，再生成并保存商家 API Key |
+| **Usage** | `fmc auth agentz` |
+
+仅在已安装并登录 `agentz-cli` 的 AgentZ / 数字员工环境中使用。accessToken 仅在当前进程中用于生成 API Key，不会写入配置、终端输出或日志；成功生成的 API Key 会保存至 `~/.bportal/config.json`，输出仅展示脱敏值。
+
+若本机没有 `agentz-cli`、客户端未登录或生成失败，请改用原有 `fmc auth login --api-key <key>`，或由运行环境注入 `BPORTAL_API_KEY`。不要手动复制或提供 accessToken。
+
+#### Examples
+
+```bash
+fmc auth agentz
+```
+
 ### `fmc auth status`
 
 | Field | Value |

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) |
@@ -80,7 +83,6 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `fmc onboarding auth code` | 提交验证码完成实名认证（写） | [onboarding.md](onboarding.md) |
 | `fmc onboarding auth organ` | 发起企业实名认证（写） | [onboarding.md](onboarding.md) |
 | `fmc onboarding auth gat` | 提交港澳台/海外实名资料（写） | [onboarding.md](onboarding.md) |
-| `fmc onboarding auth remit` | 校验对公打款金额（写） | [onboarding.md](onboarding.md) |
 | `fmc onboarding brand list` | 查询可开通品牌 | [onboarding.md](onboarding.md) |
 | `fmc onboarding brand open` | 开通品牌并申请合同（写） | [onboarding.md](onboarding.md) |
 | `fmc onboarding contract list` | 查询合同列表 | [onboarding.md](onboarding.md) |
@@ -101,13 +103,14 @@ 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) |
 | `notice` | `list`, `detail`, `message list`, `message detail`, `message unread` | [notice.md](notice.md) |
 | `customs` | `cargo list`, `commodity list`, `commodity detail`, `hscode search`, `registration info` | [customs.md](customs.md) |
 | `platform` | `account list`, `sync`, `sync-record list`, `order list`, `order detail`, `order push` | [platform.md](platform.md) |
-| `onboarding` | `progress`, `customer-type`, `auth schedule`, `auth indiv`, `auth code`, `auth organ`, `auth gat`, `auth remit`, `brand list`, `brand open`, `contract list`, `contract url` | [onboarding.md](onboarding.md) |
+| `onboarding` | `progress`, `customer-type`, `auth schedule`, `auth indiv`, `auth code`, `auth organ`, `auth gat`, `brand list`, `brand open`, `contract list`, `contract url` | [onboarding.md](onboarding.md) |
 | `update` | (no subcommand) | [update.md](update.md) |
 | `skill` | `install`, `status`, `uninstall` | [update.md](update.md) |
 

package/skill/reference/onboarding.md

@@ -17,7 +17,7 @@
 | 客户类型 | 经济主体 | 认证命令 |
 | --- | --- | --- |
 | 中国大陆（0） | 个人 | `auth indiv` → `auth code` |
-| 中国大陆（0） | 企业 | `auth indiv --agent` → `auth code --agent` → `auth organ`（必要时 `auth remit`） |
+| 中国大陆（0） | 企业 | `auth indiv --agent` → `auth code --agent`（返回经办人账号 ID）→ `auth organ`（成功即认证完成，服务端自动跳过对公打款） |
 | 港澳台（1）/ 海外（2） | 个人 / 企业 | `auth gat`（提交资料后走人工审核） |
 
 认证通过后：`brand list` → `brand open` → `contract list` → `contract url`。
@@ -149,6 +149,8 @@ fmc onboarding auth schedule
 需要 API Key 认证。**写操作**，默认二次确认。仅中国大陆客户。
 
 命令返回的 `flowId` 是下一步 `auth code` 的入参，**必须记下来**。
+例外：带 `--agent` 且该经办人**已经实名过**时，返回的是经办人账号 ID（不再下发验证码），
+可直接作为 `auth organ --agent-account-id` 使用。
 
 #### Options
 
@@ -205,6 +207,9 @@ fmc onboarding auth indiv --name 张三 --cert-number 440301199001011234 \
 
 需要 API Key 认证。**写操作**，默认二次确认。
 
+返回的是**账户 ID**；经办人认证（`--agent`）时这个值就是 `auth organ` 要的
+`--agent-account-id`，**必须记下来**。
+
 #### Options
 
 | Flag | Type | Required | Description |
@@ -231,8 +236,11 @@ fmc onboarding auth code --flow-id FLOW20260831001 --auth-code 123456 --agent -y
 
 ```
   ✔ 验证码校验通过
+    返回        c5bd9d9a1b544d1bae50727555bda804
 ```
 
+经办人认证时，上面的“返回”就是经办人账号 ID，直接作为 `auth organ --agent-account-id` 使用。
+
 ---
 
 ### `fmc onboarding auth organ`
@@ -241,40 +249,86 @@ fmc onboarding auth code --flow-id FLOW20260831001 --auth-code 123456 --agent -y
 | --- | --- |
 | **Name** | `onboarding auth organ` |
 | **Description** | 发起企业实名认证 |
-| **Usage** | `fmc onboarding auth organ --name <name> --cert-number <no> [flags]` |
+| **Usage** | `fmc onboarding auth organ --name <name> --cert-number <no> --agent-account-id <id> --legal-name <name> --state <state> --city <city> --county <county> --address <address> [flags]` |
 
 需要 API Key 认证。**写操作**，默认二次确认。
 
 前置条件：经办人已通过 `auth indiv --agent` + `auth code --agent` 完成个人实名。
-若返回后 `auth schedule` 显示"待对公打款验证"，用 `auth remit` 收尾。
+**`--agent-account-id` 取自 `auth code --agent` 的返回值**（经办人已实名时，`auth indiv --agent`
+也直接返回该账号 ID），不要编造。
+
+企业名称、证件、法人、注册地址是**一次性提交**的：服务端对这些字段逐个做非空校验，
+缺一个就返回 `PARAM_REQUIRED`，认证不会落一半，所以要先把资料收齐再执行。
+
+返回值是**企业实名的 flowId**。对公打款环节已下线：服务端在认证成功后会
+**自动跳过对公打款验证**，`auth schedule` 直接变成 `已完成 (2)` 就可以 `brand open`，
+**无需再做任何打款操作**。极少数存量流程可能停在 `待对公打款验证 (4)`，属异常，转人工。
+
+**这个 flowId 是唯一来源**：`auth schedule` 不返回 flowId，CLI 也没有反查命令，
+所以要在当次会话里记下；没记下又遇到状态 `4` 只能转人工。
 
 #### Options
 
 | Flag | Type | Required | Description |
 | --- | --- | --- | --- |
 | `--name <name>` | string | yes | 企业名称 |
-| `--cert-number <no>` | string | yes | 统一社会信用代码 |
-| `--cert-type <type>` | string | no | 证件类型 |
-| `--agent-account-id <id>` | string | no | 经办人账号 ID |
+| `--cert-number <no>` | string | yes | 企业证件号（营业执照即统一社会信用代码） |
+| `--agent-account-id <id>` | string | yes | 经办人账号 ID，来自 `auth code --agent` 的返回值 |
+| `--legal-name <name>` | string | yes | 法定代表人姓名 |
+| `--state <name>` | string | yes | 注册地省/州 |
+| `--city <name>` | string | yes | 注册地市 |
+| `--county <name>` | string | yes | 注册地区/县 |
+| `--address <address>` | string | yes | 注册地详细地址（营业执照上的地址） |
+| `--legal-cert-number <no>` | string | 条件必填 | 法人证件号（身份证号）。`--auth-type 0`（默认）时必填 |
+| `--legal-cert-type <type>` | string | no | 法人证件类型：`0` 身份证（默认 `0`） |
+| `--auth-type <type>` | string | no | 认证方式：`0` 企业四要素、`1` 组织机构三要素（默认 `0`） |
+| `--cert-type <type>` | string | no | 企业证件类型：`0` 营业执照、`1` 组织机构代码证、`2` 工商注册号 …（默认 `0`） |
+| `--country <name>` | string | no | 国家/地区名称（默认 `中国大陆`） |
+| `--country-code <code>` | string | no | 国家数字编码（默认 `485`） |
+| `--alpha2-code <code>` | string | no | 国家二字码（默认 `CN`） |
 | `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
 
+三要素认证（`--auth-type 1`）只对少数白名单客户开放，普通企业客户用默认的四要素。
+`--cert-number`、`--legal-cert-number` 在 `--verbose` / `--dry-run` 的打印中已遮蔽为 `****`，
+但**真实值仍会随请求发送**。
+
 支持全局选项: `--output`, `--verbose`, `--dry-run`
 
 #### Examples
 
 ```bash
-fmc onboarding auth organ --name 深圳市某某科技有限公司 \
-  --cert-number 91440300MA5XXXXXXX
+# 四要素认证（默认）：企业 + 法人 + 注册地址一次提交
+fmc onboarding auth organ \
+  --name 深圳市某某科技有限公司 \
+  --cert-number 91440300MA5XXXXXXX \
+  --agent-account-id c5bd9d9a1b544d1bae50727555bda804 \
+  --legal-name 张三 \
+  --legal-cert-number 440301199001011234 \
+  --state 广东省 --city 深圳市 --county 南山区 \
+  --address "科技园某某大厦 1001"
+```
+
+```bash
+# 三要素认证（白名单客户）：无需法人证件号
+fmc onboarding auth organ \
+  --name 某某社会团体 --cert-number 91440300MA5XXXXXXX --auth-type 1 \
+  --cert-type 7 --agent-account-id c5bd9d9a1b544d1bae50727555bda804 \
+  --legal-name 张三 \
+  --state 广东省 --city 深圳市 --county 南山区 --address "科技园某某大厦 1001" -y
 ```
 
 #### Output (text mode)
 
 ```
   ✔ 已发起企业实名认证
+    flowId      FLOW20260831001
 
-  待对公打款验证时，用 auth remit --flow-id <flowId> --amount <分> 完成
+  用 auth schedule 查看认证结果（已完成即可开通品牌，无需对公打款）
 ```
 
+对公打款环节已下线：`auth organ` 成功后服务端自动跳过打款，`auth schedule` 得到
+`已完成 (2)` 就可以直接 `brand open`。
+
 ---
 
 ### `fmc onboarding auth gat`
@@ -344,44 +398,6 @@ fmc onboarding auth gat --customer-profile 2 --entity 2 \
 
 ---
 
-### `fmc onboarding auth remit`
-
-| Field | Value |
-| --- | --- |
-| **Name** | `onboarding auth remit` |
-| **Description** | 校验企业对公打款金额 |
-| **Usage** | `fmc onboarding auth remit --flow-id <id> --amount <cents> [flags]` |
-
-需要 API Key 认证。**写操作**，默认二次确认。
-
-金额单位是**分**，不是元——传 `1` 表示 1 分。校验有重试次数限制，填错会消耗次数，
-所以确认后再提交。
-
-#### Options
-
-| Flag | Type | Required | Description |
-| --- | --- | --- | --- |
-| `--flow-id <id>` | string | yes | 认证流程 ID |
-| `--amount <cents>` | string | yes | 打款金额，单位：分 |
-| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
-
-支持全局选项: `--output`, `--verbose`, `--dry-run`
-
-#### Examples
-
-```bash
-# 收到 0.37 元打款 → 传 37
-fmc onboarding auth remit --flow-id FLOW20260831001 --amount 37
-```
-
-#### Output (text mode)
-
-```
-  ✔ 打款金额校验通过
-```
-
----
-
 ### `fmc onboarding brand list`
 
 | Field | Value |
@@ -437,7 +453,7 @@ fmc onboarding brand list --customer-type 1 --output json
 需要 API Key 认证。**写操作**，默认二次确认。
 
 前置条件：中国大陆客户且已完成实名认证。开通后合同即进入申请流程，
-用 `contract list` / `contract url` 继续。
+用 `contract list` 拿到合同编号与状态码，再 `contract url <合同编号> --status <状态码>` 继续。
 
 #### Options
 
@@ -474,7 +490,7 @@ fmc onboarding brand open --service-code DSS \
 ```
   ✔ 品牌开通与合同申请已提交
 
-  用 contract list 查看合同，contract url <合同编号> 获取签署链接
+  用 contract list 查看合同，contract url <合同编号> --status <状态码> 获取签署链接
 ```
 
 ---
@@ -536,7 +552,7 @@ fmc onboarding contract list --page 2 --output json
 | --- | --- |
 | **Name** | `onboarding contract url` |
 | **Description** | 获取合同签署链接或下载链接 |
-| **Usage** | `fmc onboarding contract url <contractCode> [flags]` |
+| **Usage** | `fmc onboarding contract url <contractCode> --status <status> [flags]` |
 
 需要 API Key 认证。
 
@@ -548,17 +564,24 @@ fmc onboarding contract list --page 2 --output json
 | Flag | Type | Required | Description |
 | --- | --- | --- | --- |
 | `<contractCode>` | string | yes | 合同编号（从 `contract list` 获取） |
+| `--status <status>` | string | yes | 合同状态码（从 `contract list` 的状态原样传入） |
 
 支持全局选项: `--output`, `--verbose`, `--dry-run`
 
+`--status` 必填，且**只能取自 `contract list`**：先 `contract list` 拿到该合同的
+`合同编号` + `状态`，再原样传进来。禁止凭猜测或为了拿签署链接而伪造状态码
+（服务端会重新查合同详情，最终以**实际状态**决定返回签署链接还是下载链接）。
+
 #### Examples
 
 ```bash
-fmc onboarding contract url CT20260801001
+# 先查列表拿到编号与状态，再取链接
+fmc onboarding contract list
+fmc onboarding contract url CT20260801001 --status 4
 ```
 
 ```bash
-fmc onboarding contract url CT20260801001 --output json
+fmc onboarding contract url CT20260801001 --status 4 --output json
 ```
 
 #### Output (text mode)
@@ -567,7 +590,11 @@ fmc onboarding contract url CT20260801001 --output json
 合同链接
 ──────────────────────────────────────────────────
   合同编号    CT20260801001
+  合同状态    签署中 (4)
   链接        https://esign.example.com/sign/abc123
 
   签署中的合同返回签署链接，其余状态返回下载链接；请勿频繁调用
 ```
+
+漏传 `--status` 会被 CLI 直接拒绝（commander 报 `required option ... not specified`），
+不会发出请求。