cbs-4px-merchant-cli 0.0.9 → 0.0.12

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,49 @@ fmc onboarding brand open --service-code DSS \
 ```
   ✔ 品牌开通与合同申请已提交
 
-  用 contract list 查看合同，contract url <合同编号> 获取签署链接
+  用 contract list 查看合同，contract url <合同编号> --status <状态码> 获取签署链接
+```
+
+---
+
+### `fmc onboarding notify-saler`
+
+| Field | Value |
+| --- | --- |
+| **Name** | `onboarding notify-saler` |
+| **Description** | 重复入驻场景下，向当前客户对应的销售推送钉钉通知 |
+| **Usage** | `fmc onboarding notify-saler [flags]` |
+
+需要 API Key 认证。**写操作**，默认二次确认。无业务参数：客户编码由
+服务端从 API Key 上下文自动取，通知标题与正文也由服务端写死（含企业名称与客户编码）。
+
+**仅在确认客户存在重复入驻时调用**：即 `brand open` 被拦且错误文案明确包含
+`账号存在重复申请，请等待人工审核通过后再发起申请服务`（底层业务码 50001）或
+`因您重复申请账号，审核未通过，不可继续申请服务`（底层业务码 50002）时才用。
+MCP 层可能将底层码包装成 `OPEN_BRAND_ERROR`，因此按错误文案判断，不要只匹配错误码。
+**请勿重复发送**；通知后销售需在四方钉—工作台—OA审批发起「GPN客户发起：客户账号重复注册审核申请」。
+
+#### Options
+
+| Flag | Type | Required | Description |
+| --- | --- | --- | --- |
+| `-y, --yes` | boolean | no | 跳过交互确认（非交互环境必传） |
+
+支持全局选项: `--output`, `--verbose`, `--dry-run`
+
+#### Examples
+
+```bash
+fmc onboarding notify-saler -y
+```
+
+#### Output (text mode)
+
+```
+  ✔ 已向该客户对应的销售推送重复入驻通知
+
+  通知含企业名称与客户编码，并指引销售走 OA「客户账号重复注册审核申请」
+  请勿重复发送；等销管审批通过后再重试 brand open
 ```
 
 ---
@@ -536,7 +594,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 +606,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 +632,11 @@ fmc onboarding contract url CT20260801001 --output json
 合同链接
 ──────────────────────────────────────────────────
   合同编号    CT20260801001
+  合同状态    签署中 (4)
   链接        https://esign.example.com/sign/abc123
 
   签署中的合同返回签署链接，其余状态返回下载链接；请勿频繁调用
 ```
+
+漏传 `--status` 会被 CLI 直接拒绝（commander 报 `required option ... not specified`），
+不会发出请求。