cbs-4px-merchant-cli 0.0.9 → 0.0.11

package/dist/types/index.d.ts

@@ -47,23 +47,43 @@ export interface LabelPrintDTO {
 }
 export interface ShipperConsigneeVO {
     orderId: number;
+    shipperName: string | null;
+    shipperCompany: string | null;
+    shipperAddress1: string | null;
+    shipperAddress2: string | null;
+    shipperPostcode: string | null;
+    shipperTelephone: string | null;
+    shipperMobile: string | null;
+    shipperEmail: string | null;
+    shipperCountry: string | null;
+    shipperCity: string | null;
+    shipperProvince: string | null;
     consigneeName: string | null;
+    consigneeFirstName: string | null;
+    consigneeLastName: string | null;
+    consigneeCompany: string | null;
     consigneeAddress1: string | null;
     consigneeAddress2: string | null;
+    consigneeStreet: string | null;
+    consigneeDoorNo: string | null;
     consigneePostcode: string | null;
     consigneeTelephone: string | null;
     consigneeMobile: string | null;
+    consigneeMail: string | null;
     consigneeCountry: string | null;
     consigneeCity: string | null;
     consigneeProvince: string | null;
-    shipperName: string | null;
-    shipperCountry: string | null;
+    consigneeVatNo: string | null;
 }
 export interface DeclareInvoiceVO {
     orderId: number;
     invoiceId: number;
     ename: string | null;
     cname: string | null;
+    pcs: number | null;
+    unitPrice: number | null;
+    hscode: string | null;
+    weight: number | null;
     totalPrice: number | null;
     currency: string | null;
 }
@@ -82,6 +102,16 @@ export interface OrderDetailResp {
     shipperConsigneeDTO: ShipperConsigneeVO | null;
     declareList: DeclareInvoiceVO[];
     feeDetailList: BillingFeeItemDetailVO[];
+    batteryType: string | null;
+    iossNo: string | null;
+    orderNote: string | null;
+    customerWeight: number | null;
+    length: number | null;
+    width: number | null;
+    height: number | null;
+    dutyPayMode: string | null;
+    salesPlatform: string | null;
+    pieces: number | null;
     totalFee: string | null;
     weightFee: number | null;
     chatReplay: string | null;
@@ -93,6 +123,12 @@ export interface ProductRecommendRequest {
     postCode?: string;
     isBattery?: string;
     declareValue?: number;
+    /** 包裹长(cm)，体积重计费产品必传 */
+    length?: number;
+    /** 包裹宽(cm) */
+    width?: number;
+    /** 包裹高(cm) */
+    height?: number;
 }
 export interface RecommendProductItem {
     productName: string;
@@ -155,14 +191,23 @@ export interface OrderListRequest {
     statusName?: string;
     customerOrderNo?: string;
     fpxTrackNo?: string;
+    queryDateType?: string;
     queryStartDate?: string;
     queryEndDate?: string;
     productCode?: string;
     destinationCountry?: string;
+    consigneeName?: string;
+    buyerId?: string;
+    isPrint?: string;
+    odaConfirm?: string;
+    interceptStatus?: string;
+    changeNoStatus?: string;
+    isHistory?: string;
     pageNum?: number;
     pageSize?: number;
 }
 export interface OrderSummary {
+    orderId: number | null;
     fpxTrackNo: string | null;
     customerOrderNo: string | null;
     statusName: string | null;
@@ -180,19 +225,36 @@ export interface OrderListResp {
     total: number;
     list: OrderSummary[];
 }
+/** 地址类型：shipper 发件人 / consignee 收件人 / return 退件 / collect 揽收 */
+export type AddressType = 'shipper' | 'consignee' | 'return' | 'collect';
+export interface AddressBookListRequest {
+    addressType?: AddressType;
+    keyword?: string;
+    pageNum?: number;
+    pageSize?: number;
+}
 export interface AddressBookItem {
-    code: string | null;
-    contact: string | null;
-    contactPhone: string | null;
-    emergencyContact: string | null;
+    id: string | null;
+    addressType: string | null;
+    name: string | null;
+    company: string | null;
+    phone: string | null;
+    mobile: string | null;
+    email: string | null;
+    country: string | null;
     province: string | null;
     city: string | null;
-    county: string | null;
+    district: string | null;
     address: string | null;
-    containerStuffingLocation: string | null;
+    postcode: string | null;
+    /** 是否默认地址：Y/N */
+    isDefault: string | null;
 }
 export interface OrderAddressResp {
     list: AddressBookItem[];
+    total: number | null;
+    pageNum: number | null;
+    pageSize: number | null;
 }
 export interface CountryItem {
     code: string;
@@ -908,11 +970,39 @@ export interface CheckAuthCodeRequest {
     flowId: string;
     isAgent?: boolean;
 }
+/**
+ * 企业实名认证请求。
+ *
+ * 服务端 `startOrganRealNameAuth` 对除 `certTypeEnum` 外的字段全部做
+ * `requireNotBlank` 校验，缺一个就返回 PARAM_REQUIRED，因此这里大多为必填。
+ * `code`（客户编码）与 `creatorId` 由登录上下文填充，不接受调用方传入。
+ */
 export interface OrganAuthRequest {
     name: string;
     certNumber: string;
-    certType?: number;
-    agentAccountId?: string;
+    /** 企业证件类型：0 营业执照（统一社会信用代码）… 12 未知，服务端必填 */
+    certType: number;
+    /** 由 certType 推导，如 0 → CRED_ORG_USCC */
+    certTypeEnum?: string;
+    /** 0=企业四要素认证、1=组织机构三要素认证 */
+    authType: number;
+    /** 经办人账号 ID，来自 `auth code --agent` 的返回值 */
+    agentAccountId: string;
+    /** 法定代表人姓名 */
+    legalName: string;
+    /** 法定代表人证件号，authType=0（四要素）时服务端必填 */
+    legalCertNumber?: string;
+    /** 法定代表人证件类型：0 身份证，authType=0 时服务端必填 */
+    legalCertType?: number;
+    /** 国家数字编码，中国大陆为 485 */
+    countryCode: string;
+    /** 国家二字码，中国大陆为 CN */
+    alpha2Code: string;
+    country: string;
+    state: string;
+    city: string;
+    county: string;
+    address: string;
 }
 export interface OpenBrandRequest {
     serviceCode: string;
@@ -1017,7 +1107,10 @@ export interface OrderSenderInfo {
     name?: string;
     company?: string;
     phone?: string;
+    mobile?: string;
+    email?: string;
     address?: string;
+    address2?: string;
     country?: string;
     postcode?: string;
     city?: string;
@@ -1028,12 +1121,19 @@ export interface OrderReceiverInfo {
     company?: string;
     phone?: string;
     mobile?: string;
+    firstName?: string;
+    lastName?: string;
     address?: string;
+    address2?: string;
+    street?: string;
+    doorNo?: string;
     city?: string;
     province?: string;
     postcode?: string;
     country?: string;
     email?: string;
+    idCode?: string;
+    vatNo?: string;
 }
 export interface OrderParcelInfo {
     weight?: number;
@@ -1041,6 +1141,13 @@ export interface OrderParcelInfo {
     width?: number;
     height?: number;
     dutyPayMode?: string;
+    batteryType?: string;
+    iossNo?: string;
+    orderNote?: string;
+    salesPlatform?: string;
+    warehouseCode?: string;
+    codPrice?: number;
+    codCurrency?: string;
 }
 export interface OrderDeclareItemInfo {
     ename?: string;
@@ -1050,6 +1157,10 @@ export interface OrderDeclareItemInfo {
     currency?: string;
     weight?: number;
     hsCode?: string;
+    material?: string;
+    uses?: string;
+    url?: string;
+    brand?: string;
 }
 /** `P` = 预报（直接提交），`D` = 草稿（保存不提交）。后端默认 `P`。 */
 export type OrderWriteStatus = 'P' | 'D';
@@ -1059,6 +1170,9 @@ export interface CreateOrderRequest {
     originCountry?: string;
     status?: OrderWriteStatus;
     customerOrderNo?: string;
+    pieces?: number;
+    hasBattery?: string;
+    buyerId?: string;
     sender?: OrderSenderInfo;
     receiver?: OrderReceiverInfo;
     parcel?: OrderParcelInfo;
@@ -1071,7 +1185,8 @@ export interface CreateOrderResp {
     customerOrderNo: string | null;
 }
 export interface EditOrderRequest extends Partial<Omit<CreateOrderRequest, 'status'>> {
-    orderId: number;
+    /** 要编辑的订单单号（4px 物流单号或客户订单号）。后端按单号反查主键。 */
+    orderNo: string;
     status?: OrderWriteStatus;
 }
 export interface EditOrderResp {

package/dist/utils/run-command.d.ts

@@ -21,4 +21,10 @@ export interface RunCommandConfig<TData> {
  * empty branch at all): `consume` owns every output decision.
  */
 export declare function withClient<TData>(globalOptions: GlobalOptions, spinnerText: string, fetch: (client: ApiClient) => Promise<TData>, consume: (data: TData) => void): Promise<void>;
+/**
+ * 参数校验与文件读取发生在 `withClient` 之前，因此不会经过其统一错误
+ * 通道。本包装器确保这类失败仍输出 Agent 可解析的 JSON 错误信封，而不是
+ * 未处理的 Promise rejection。
+ */
+export declare function preflight<T>(fn: () => Promise<T>): Promise<T>;
 export declare function runCommand<TData>(globalOptions: GlobalOptions, config: RunCommandConfig<TData>): Promise<void>;

package/dist/utils/run-command.js

@@ -40,6 +40,19 @@ export async function withClient(globalOptions, spinnerText, fetch, consume) {
         handleError(error);
     }
 }
+/**
+ * 参数校验与文件读取发生在 `withClient` 之前，因此不会经过其统一错误
+ * 通道。本包装器确保这类失败仍输出 Agent 可解析的 JSON 错误信封，而不是
+ * 未处理的 Promise rejection。
+ */
+export async function preflight(fn) {
+    try {
+        return await fn();
+    }
+    catch (e) {
+        handleError(e);
+    }
+}
 export async function runCommand(globalOptions, config) {
     await withClient(globalOptions, config.spinner, (client) => config.exec(client), (data) => {
         if (globalOptions.output === 'json') {

package/dist/utils/run-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-command.js","sourceRoot":"","sources":["../../src/utils/run-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAc3D;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,aAA4B,EAC5B,WAAmB,EACnB,KAA4C,EAC5C,OAA8B;IAE9B,MAAM,OAAO,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAC3C,IAAI,CAAC;QACH,OAAO,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,IAAI,aAAa,EAAE,EAAE,aAAa,CAAC,CAAC;QACjE,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;QACjC,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,WAAW,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,aAA4B,EAC5B,MAA+B;IAE/B,MAAM,UAAU,CACd,aAAa,EACb,MAAM,CAAC,OAAO,EACd,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAC/B,CAAC,IAAI,EAAE,EAAE;QACP,IAAI,aAAa,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YACnD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,YAAY,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC;YAChE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO;QACT,CAAC;QAED,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"run-command.js","sourceRoot":"","sources":["../../src/utils/run-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAc3D;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,aAA4B,EAC5B,WAAmB,EACnB,KAA4C,EAC5C,OAA8B;IAE9B,MAAM,OAAO,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAC3C,IAAI,CAAC;QACH,OAAO,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,IAAI,aAAa,EAAE,EAAE,aAAa,CAAC,CAAC;QACjE,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;QACjC,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,WAAW,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,EAAoB;IACrD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,WAAW,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,aAA4B,EAC5B,MAA+B;IAE/B,MAAM,UAAU,CACd,aAAa,EACb,MAAM,CAAC,OAAO,EACd,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAC/B,CAAC,IAAI,EAAE,EAAE;QACP,IAAI,aAAa,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YACnD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,YAAY,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC;YAChE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO;QACT,CAAC;QAED,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbs-4px-merchant-cli",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Cbs merchant CLI tool",
   "type": "module",
   "main": "./dist/index.js",

package/skill/SKILL.md

@@ -141,11 +141,11 @@ description: >-
 用户提到"验证码/收到短信了" → `fmc onboarding auth code`（**写**）
 用户提到"企业实名/公司认证" → `fmc onboarding auth organ`（**写**）
 用户提到"港澳台/海外客户认证" → `fmc onboarding auth gat`（**写**）
-用户提到"对公打款/打款金额验证" → `fmc onboarding auth remit`（**写**）
+用户提到"对公打款/要不要打款" → 入驻流程已取消对公打款环节（`auth organ` 成功即认证完成），用 `fmc onboarding auth schedule` 佐证后告知"无需打款"
 用户提到"可开通品牌/有哪些品牌" → `fmc onboarding brand list`
 用户提到"开通品牌/申请合同" → `fmc onboarding brand open`（**写**）
 用户提到"合同/我的合同" → `fmc onboarding contract list`
-用户提到"签合同/签署链接/下载合同" → `fmc onboarding contract url`
+用户提到"签合同/签署链接/下载合同" → `fmc onboarding contract url`（须带 `--status`，取自 `contract list`）
 用户提到"登录/配置key/认证" → `fmc auth login`
 用户提到"升级/更新/新版本" → `fmc update`
 
@@ -209,7 +209,6 @@ export BPORTAL_API_KEY=sk-xxxxx
 | `platform sync` | 提交拉单任务（异步） |
 | `platform order push` | 订单进入物流履约流程 |
 | `onboarding auth indiv` / `auth code` / `auth organ` / `auth gat` | 提交实名认证资料 |
-| `onboarding auth remit` | 消耗打款校验重试次数 |
 | `onboarding brand open` | 开通品牌并发起合同申请 |
 
 执行规则：
@@ -225,8 +224,8 @@ export BPORTAL_API_KEY=sk-xxxxx
 
 1. `order create --file <json> --draft -y` → 拿到 `orderId`
 2. `order get <orderNo>` 把收件人、重量、申报品念给用户核对
-3. 有错就 `order edit --order-id <id> --file <json> --draft -y` 改，改到对
-4. 用户明确同意后 `order forecast --ids <id> -y` 提交预报
+3. 有错就 `order edit --orderNo <单号> --file <json> --draft -y` 改，改到对
+4. 用户明确同意后 `order forecast --orderNo <单号> -y` 提交预报
 5. `label get <orderNo>` 取面单
 
 只有用户明确说"直接下单/不用确认"时，才允许省掉 `--draft`。
@@ -252,14 +251,14 @@ fmc order list --status IN_TRANSIT
 
 # 下单（写操作）—— 先建草稿，用户核对无误后再预报
 fmc order create --file ./order.json --draft -y
-fmc order forecast --ids 1001 -y
+fmc order forecast --orderNo ORD-20260907-001 -y
 
 # 改草稿（写操作，只传要改的字段）
-fmc order edit --order-id 1001 --file ./patch.json --draft -y
+fmc order edit --orderNo ORD-20260907-001 --file ./patch.json --draft -y
 
 # 取消 / 拦截（写操作）
-fmc order cancel --ids 1001 --reason "客户取消" -y
-fmc order intercept --ids 1001 -y
+fmc order cancel --orderNo 4PX3003136946232CN --reason "客户取消" -y
+fmc order intercept --orderNo 4PX3003136946232CN -y
 
 # 获取推荐产品（寄美国）
 fmc product recommend --country US
@@ -292,9 +291,9 @@ fmc platform sync --seller-account-id 10086 \
 # 查询入驻进度
 fmc onboarding progress
 
-# 查询合同并获取签署链接
+# 查询合同并获取签署链接（--status 必填，取自 contract list）
 fmc onboarding contract list
-fmc onboarding contract url CT20260801001
+fmc onboarding contract url CT20260801001 --status 4
 ```
 
 ---

package/skill/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbs-4px-merchant-cli",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "BPortal Merchant CLI (fmc) skill — BPortal",
   "files": [
     "SKILL.md",

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/index.md

@@ -83,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) |
@@ -111,7 +110,7 @@ Command **details** are in sibling `<group>.md` files in this directory.
 | `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`），
+不会发出请求。