cbs-4px-merchant-cli 0.0.8 → 0.0.11

package/dist/services/api-client.js

@@ -1,6 +1,34 @@
 import axios from 'axios';
-import { ApiError, DryRunSignal } from '../errors.js';
+import { ApiError, BportalError, DryRunSignal } from '../errors.js';
 const API_PREFIX = '/api/merchant/tools';
+const AGENTZ_API_KEY_GENERATE_PATH = '/api/agentz/apikey/generate';
+/**
+ * 后端以 `@Body` 绑定（整体 JSON 反序列化）的端点，必须走 {@link ApiClient.postJson}。
+ *
+ * 这类端点收到表单串会在 `JSON.parseObject` 处抛异常，后端统一兜成
+ * `SYSTEM_ERROR / 系统繁忙，请稍后再试`——症状是「不传参侥幸能通、一传参就报系统繁忙」，
+ * 极难从错误信息反推。故在 `post()` 里对照本清单做开发期断言，写错立即报错而不是发出去。
+ *
+ * 新增工具时：后端方法签名是 `@Body XxxRequest` 就登记到这里并用 `postJson`；
+ * 是 `@Param` 就用 `post`。路径为 API_PREFIX 之后的部分。
+ */
+const JSON_BODY_PATHS = new Set([
+    '/order/list',
+    '/order/create',
+    '/order/edit',
+    '/product-recommendation',
+    '/shipping-fee/calculate',
+    '/problem/list',
+    '/problem/suggestions',
+    '/problem/intercepted/list',
+    '/service/claim/order/list',
+    '/service-order/aftersale/list',
+    '/service-order/check/list',
+    '/service-order/complaint/list',
+    '/finance/fee/daily/list',
+    '/finance/recharge/list',
+    '/finance/recharge/offline/list',
+]);
 /**
  * Params whose values must never be echoed back to the terminal.
  *
@@ -10,13 +38,21 @@ const API_PREFIX = '/api/merchant/tools';
  * transcripts. Masking applies to the printed copy only — the request itself
  * still carries the real value.
  */
-const SENSITIVE_PARAMS = new Set(['certNumber', 'bankCard', 'authCode', 'mobile']);
+const SENSITIVE_PARAMS = new Set(['certNumber', 'legalCertNumber', 'bankCard', 'authCode', 'mobile']);
 /**
  * 嵌套 JSON body 同样需要递归遮蔽敏感字段，否则订单的
  * `receiver.mobile`、`sender.phone` 会被 `--dry-run` / `--verbose`
  * 原样写入终端回滚区和平台日志。
  */
-const SENSITIVE_BODY_KEYS = new Set(['certNumber', 'bankCard', 'authCode', 'mobile', 'phone']);
+const SENSITIVE_BODY_KEYS = new Set([
+    'certNumber',
+    // 法人身份证号与企业证件号同级敏感，遗漏会让企业实名的 --dry-run 明文回显
+    'legalCertNumber',
+    'bankCard',
+    'authCode',
+    'mobile',
+    'phone',
+]);
 function maskSensitive(params) {
     const out = {};
     for (const [k, v] of Object.entries(params)) {
@@ -44,6 +80,26 @@ function toForm(params) {
     }
     return form;
 }
+/**
+ * 企业证件类型的数字值 → 枚举名，与后端 `OrganCertTypeEnum` 一一对应。
+ * 企业实名同时传 certType 与 certTypeEnum，两者不一致时以哪个为准并不确定，
+ * 所以 CLI 只收数字，枚举名统一从这里推导。
+ */
+const ORGAN_CERT_TYPE_ENUMS = {
+    0: 'CRED_ORG_USCC',
+    1: 'CRED_ORG_CODE',
+    2: 'CRED_ORG_REGCODE',
+    3: 'CRED_ORG_BUSINESS_REGISTTATION_CODE',
+    4: 'CRED_ORG_TAX_REGISTTATION_CODE',
+    5: 'CRED_ORG_LEGAL_PERSON_CODE',
+    6: 'CRED_ORG_ENT_LEGAL_PERSON_CODE',
+    7: 'CRED_ORG_SOCIAL_REG_CODE',
+    8: 'CRED_ORG_PRIVATE_NON_ENT_REG_CODE',
+    9: 'CRED_ORG_FOREIGN_ENT_REG_CODE',
+    10: 'CRED_ORG_GOV_APPROVAL',
+    11: 'CODE_ORG_CUSTOM',
+    12: 'CRED_ORG_UNKNOWN',
+};
 export class ApiClient {
     config;
     verbose;
@@ -53,6 +109,16 @@ export class ApiClient {
         this.verbose = options?.verbose ?? false;
         this.dryRun = options?.dryRun ?? false;
     }
+    /** 返回今天日期 yyyy-MM-dd，与 bportal MCP Server 的 defaultEndDate 对齐 */
+    todayDate() {
+        return new Date().toISOString().slice(0, 10);
+    }
+    /** 返回 N 天前的日期 yyyy-MM-dd，与 bportal MCP Server 的 defaultStartDate 对齐 */
+    recentDate(days) {
+        const d = new Date();
+        d.setDate(d.getDate() - days);
+        return d.toISOString().slice(0, 10);
+    }
     async createHttp(withAuth) {
         const baseURL = await this.config.resolveBaseUrl();
         const headers = {
@@ -65,6 +131,37 @@ export class ApiClient {
         }
         return axios.create({ baseURL, headers, timeout: 15000 });
     }
+    /**
+     * Uses the AgentZ access token only to mint the merchant API Key. The token
+     * must never be persisted, returned, or printed because it belongs to the
+     * host Agent client rather than this CLI.
+     */
+    async generateAgentzApiKey(accessToken) {
+        const baseURL = await this.config.resolveBaseUrl();
+        const http = axios.create({
+            baseURL,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Source': 'cli',
+                Authorization: `Bearer ${accessToken}`,
+            },
+            timeout: 15000,
+        });
+        if (this.verbose) {
+            process.stderr.write(`> POST ${baseURL}${AGENTZ_API_KEY_GENERATE_PATH}\n`);
+            process.stderr.write('> Authorization: Bearer ****\n');
+        }
+        const res = await http.post(AGENTZ_API_KEY_GENERATE_PATH);
+        if (this.verbose) {
+            process.stderr.write(`< ${res.status} ${res.statusText}\n`);
+        }
+        const response = res.data;
+        const apiKey = response.data?.apiKey;
+        if (response.result !== 0 || !apiKey) {
+            throw new ApiError(response.code ?? 'AGENTZ_API_KEY_GENERATION_FAILED', response.message ?? 'AgentZ API Key 生成失败', '请确认 AgentZ 登录态有效后重试');
+        }
+        return apiKey;
+    }
     async get(path, params, withAuth) {
         if (this.dryRun) {
             const info = await this.dryRunInfo(path, params, withAuth);
@@ -91,6 +188,9 @@ export class ApiClient {
         return resp.data;
     }
     async post(path, params, withAuth) {
+        if (JSON_BODY_PATHS.has(path.slice(API_PREFIX.length))) {
+            throw new BportalError(`${path} 在后端以 @Body 绑定，必须调用 postJson()；用 post() 发表单会被兜成 SYSTEM_ERROR`, 'CLIENT_BUG', '这是 CLI 代码缺陷，请把该调用改为 postJson()');
+        }
         if (this.dryRun) {
             const info = await this.dryRunPostInfo(path, params, withAuth);
             console.log(JSON.stringify(info, null, 2));
@@ -122,9 +222,12 @@ export class ApiClient {
     /**
      * 发送 JSON body 的 POST。
      *
-     * 仅用于后端以 `@Body` 绑定的接口（当前为 `order create` 和
-     * `order edit`）。其他接口必须继续调用 `post()`，因为 Solon 的
-     * `@Param` 从表单取值，发送 JSON body 会返回 400。
+     * 用于后端以 `@Body` 绑定的接口（order create/edit、problem order list、
+     * custody 全部、onboarding 的实名与开通品牌接口）。后端的 `@Body` 解析器直接
+     * 对原始 body 做 `JSON.parseObject`，收到表单串会抛
+     * `Failed to parse JSON body as ...`，因此这类接口不能走 `post()`。
+     * 其余接口必须继续调用 `post()`，因为 Solon 的 `@Param` 从表单取值，
+     * 发送 JSON body 会返回 400。
      */
     async postJson(path, body, withAuth) {
         if (this.dryRun) {
@@ -224,6 +327,8 @@ export class ApiClient {
             body.customerOrderNo = request.customerOrderNo;
         if (request.fpxTrackNo)
             body.fpxTrackNo = request.fpxTrackNo;
+        if (request.queryDateType)
+            body.queryDateType = request.queryDateType;
         if (request.queryStartDate)
             body.queryStartDate = request.queryStartDate;
         if (request.queryEndDate)
@@ -232,14 +337,37 @@ export class ApiClient {
             body.productCode = request.productCode;
         if (request.destinationCountry)
             body.destinationCountry = request.destinationCountry;
+        if (request.consigneeName)
+            body.consigneeName = request.consigneeName;
+        if (request.buyerId)
+            body.buyerId = request.buyerId;
+        if (request.isPrint)
+            body.isPrint = request.isPrint;
+        if (request.odaConfirm)
+            body.odaConfirm = request.odaConfirm;
+        if (request.interceptStatus)
+            body.interceptStatus = request.interceptStatus;
+        if (request.changeNoStatus)
+            body.changeNoStatus = request.changeNoStatus;
+        if (request.isHistory)
+            body.isHistory = request.isHistory;
         if (request.pageNum != null)
             body.pageNum = request.pageNum;
         if (request.pageSize != null)
             body.pageSize = request.pageSize;
-        return this.post(`${API_PREFIX}/order/list`, body, true);
+        return this.postJson(`${API_PREFIX}/order/list`, body, true);
     }
-    async listAddressBook() {
-        return this.get(`${API_PREFIX}/address-book/list`, {}, true);
+    async listAddressBook(request) {
+        const body = {};
+        if (request.addressType)
+            body.addressType = request.addressType;
+        if (request.keyword)
+            body.keyword = request.keyword;
+        if (request.pageNum != null)
+            body.pageNum = request.pageNum;
+        if (request.pageSize != null)
+            body.pageSize = request.pageSize;
+        return this.post(`${API_PREFIX}/address-book/list`, body, true);
     }
     async searchDestinationCountry(key, productCode) {
         const body = { key };
@@ -256,14 +384,20 @@ export class ApiClient {
     async editOrder(request) {
         return this.postJson(`${API_PREFIX}/order/edit`, request, true);
     }
-    async forecastOrder(orderIds) {
-        return this.post(`${API_PREFIX}/order/forecast`, { orderIds }, true);
+    /** 草稿转预报。传客户订单号，后端按单号反查主键。 */
+    async forecastOrder(orderNos) {
+        return this.post(`${API_PREFIX}/order/forecast`, { orderNos }, true);
+    }
+    /** 取消订单。传单号，后端按单号反查主键。 */
+    async cancelOrder(orderNos, cancelReason) {
+        return this.post(`${API_PREFIX}/order/cancel`, { orderNos, cancelReason }, true);
     }
-    async cancelOrder(orderIds, cancelReason) {
-        return this.post(`${API_PREFIX}/order/cancel`, { orderIds, cancelReason }, true);
+    /** 申请拦截。传单号，后端按单号反查主键。 */
+    async interceptOrder(orderNos) {
+        return this.post(`${API_PREFIX}/order/intercept`, { orderNos }, true);
     }
-    async interceptOrder(orderIds) {
-        return this.post(`${API_PREFIX}/order/intercept`, { orderIds }, true);
+    async uninterceptOrder(orderNos) {
+        return this.post(`${API_PREFIX}/order/unintercept`, { orderNos }, true);
     }
     async searchProduct(key, countryCode) {
         const body = { key };
@@ -284,7 +418,7 @@ export class ApiClient {
             body.isBattery = request.isBattery;
         if (request.declareValue != null)
             body.declareValue = request.declareValue;
-        return this.post(`${API_PREFIX}/product-recommendation`, body, true);
+        return this.postJson(`${API_PREFIX}/product-recommendation`, body, true);
     }
     async listAvailableProducts(country, startCity) {
         const body = { country };
@@ -312,7 +446,7 @@ export class ApiClient {
             body.isBattery = request.isBattery;
         if (request.declareValue != null)
             body.declareValue = request.declareValue;
-        return this.post(`${API_PREFIX}/shipping-fee/calculate`, body, true);
+        return this.postJson(`${API_PREFIX}/shipping-fee/calculate`, body, true);
     }
     async getEstimatedDeliveryTime(countryCode, productCode) {
         return this.get(`${API_PREFIX}/estimated-delivery-time`, { countryCode, productCode }, true);
@@ -332,7 +466,7 @@ export class ApiClient {
             body.pageNum = request.pageNum;
         if (request.pageSize != null)
             body.pageSize = request.pageSize;
-        return this.post(`${API_PREFIX}/service/claim/order/list`, body, true);
+        return this.postJson(`${API_PREFIX}/service/claim/order/list`, body, true);
     }
     // ==================== Problem / Abnormal ====================
     async listProblemOrder(request) {
@@ -343,15 +477,14 @@ export class ApiClient {
             body.abnormalStatus = request.abnormalStatus;
         if (request.abnormalType)
             body.abnormalType = request.abnormalType;
-        if (request.startDate)
-            body.startDate = request.startDate;
-        if (request.endDate)
-            body.endDate = request.endDate;
+        // 与 bportal MCP Server 保持一致：未传日期时默认查近 7 天
+        body.startDate = request.startDate || this.recentDate(7);
+        body.endDate = request.endDate || this.todayDate();
         if (request.pageNum != null)
             body.pageNum = request.pageNum;
         if (request.pageSize != null)
             body.pageSize = request.pageSize;
-        return this.post(`${API_PREFIX}/problem/order/list`, body, true);
+        return this.postJson(`${API_PREFIX}/problem/order/list`, body, true);
     }
     async getProblemSuggestions(request) {
         const body = {};
@@ -359,7 +492,7 @@ export class ApiClient {
             body.items = JSON.stringify(request.items);
         if (request.orderNoItems)
             body.orderNoItems = request.orderNoItems.join(',');
-        return this.post(`${API_PREFIX}/problem/suggestions`, body, true);
+        return this.postJson(`${API_PREFIX}/problem/suggestions`, body, true);
     }
     async listProblemNotify(pageNum, pageSize) {
         const body = {};
@@ -393,6 +526,8 @@ export class ApiClient {
             body.customerOrderNo = request.customerOrderNo;
         if (request.fpxTrackNo)
             body.fpxTrackNo = request.fpxTrackNo;
+        if (request.queryDateType)
+            body.queryDateType = request.queryDateType;
         if (request.queryStartDate)
             body.queryStartDate = request.queryStartDate;
         if (request.queryEndDate)
@@ -401,7 +536,7 @@ export class ApiClient {
             body.pageNum = request.pageNum;
         if (request.pageSize != null)
             body.pageSize = request.pageSize;
-        return this.post(`${API_PREFIX}/problem/intercepted/list`, body, true);
+        return this.postJson(`${API_PREFIX}/problem/intercepted/list`, body, true);
     }
     // ==================== Service Center ====================
     async listServiceOrderAftersale(request) {
@@ -422,7 +557,7 @@ export class ApiClient {
             body.pageNum = request.pageNum;
         if (request.pageSize != null)
             body.pageSize = request.pageSize;
-        return this.post(`${API_PREFIX}/service-order/aftersale/list`, body, true);
+        return this.postJson(`${API_PREFIX}/service-order/aftersale/list`, body, true);
     }
     async listServiceOrderCheck(request) {
         const body = {};
@@ -440,7 +575,7 @@ export class ApiClient {
             body.pageNum = request.pageNum;
         if (request.pageSize != null)
             body.pageSize = request.pageSize;
-        return this.post(`${API_PREFIX}/service-order/check/list`, body, true);
+        return this.postJson(`${API_PREFIX}/service-order/check/list`, body, true);
     }
     async listServiceOrderComplaint(request) {
         const body = {};
@@ -458,7 +593,7 @@ export class ApiClient {
             body.pageNum = request.pageNum;
         if (request.pageSize != null)
             body.pageSize = request.pageSize;
-        return this.post(`${API_PREFIX}/service-order/complaint/list`, body, true);
+        return this.postJson(`${API_PREFIX}/service-order/complaint/list`, body, true);
     }
     async getServiceOrderCheckDetail(serviceNo) {
         const body = { serviceNo };
@@ -512,7 +647,7 @@ export class ApiClient {
             body.pageNum = pageNum;
         if (pageSize != null)
             body.pageSize = pageSize;
-        return this.post(`${API_PREFIX}/finance/fee/daily/list`, body, true);
+        return this.postJson(`${API_PREFIX}/finance/fee/daily/list`, body, true);
     }
     async getUnbilledFeeDetail(businessNo, currencyCode) {
         const body = { businessNo, currencyCode };
@@ -542,7 +677,7 @@ export class ApiClient {
             body.pageNum = pageNum;
         if (pageSize != null)
             body.pageSize = pageSize;
-        return this.post(`${API_PREFIX}/finance/recharge/list`, body, true);
+        return this.postJson(`${API_PREFIX}/finance/recharge/list`, body, true);
     }
     async listOfflineRechargeRecord(businessSystem, currency, tradeNo, status, startDate, endDate, pageNum, pageSize) {
         const body = {};
@@ -562,7 +697,7 @@ export class ApiClient {
             body.pageNum = pageNum;
         if (pageSize != null)
             body.pageSize = pageSize;
-        return this.post(`${API_PREFIX}/finance/recharge/offline/list`, body, true);
+        return this.postJson(`${API_PREFIX}/finance/recharge/offline/list`, body, true);
     }
     async getBilledFeeDetail(businessNo) {
         const body = { businessNo };
@@ -697,6 +832,33 @@ export class ApiClient {
     async listProblemNotifyType() {
         return this.get(`${API_PREFIX}/problem/notify-type/list`, {}, true);
     }
+    // ==================== Custody (异常托管) ====================
+    /**
+     * 查询指定异常单支持的回复方式（走货/退件/改带电/改产品等）。
+     * bportal 端点使用 @Body，因此走 postJson。
+     */
+    async getAbnormalityHelp(reasonCode, orderNo) {
+        return this.postJson(`${API_PREFIX}/custody/abnormality-help`, { reasonCode, orderNo }, true);
+    }
+    /**
+     * 查询指定异常单可更换的带电产品列表及差价。
+     */
+    async queryElectricProducts(orderNo) {
+        return this.postJson(`${API_PREFIX}/custody/electric-products`, { orderNo }, true);
+    }
+    /**
+     * 获取 AI 推荐的异常处理建议（含推荐产品及差价）。
+     */
+    async getAIAbnormalSuggest(orderNo, reasonCode) {
+        return this.postJson(`${API_PREFIX}/custody/ai-suggest`, { orderNo, reasonCode }, true);
+    }
+    /**
+     * 提交改带电或改产品方案。
+     * 写操作——会真实改变订单的物流产品。
+     */
+    async submitProductChange(orderNo, pkCode) {
+        return this.postJson(`${API_PREFIX}/custody/change-product`, { orderNo, pkCode }, true);
+    }
     // ==================== Platform Order (平台拉单) ====================
     async listSellerAccounts(pageNum, pageSize) {
         const body = {};
@@ -717,12 +879,18 @@ export class ApiClient {
             body.pageSize = pageSize;
         return this.post(`${API_PREFIX}/platformOrder/syncRecord/list`, body, true);
     }
-    async listPlatformOrders(status, keyword, pageNum, pageSize) {
+    async listPlatformOrders(status, keyword, filters, pageNum, pageSize) {
         const body = {};
         if (status != null)
             body.status = status;
         if (keyword)
             body.keyword = keyword;
+        if (filters) {
+            for (const [k, v] of Object.entries(filters)) {
+                if (v)
+                    body[k] = v;
+            }
+        }
         if (pageNum != null)
             body.pageNum = pageNum;
         if (pageSize != null)
@@ -748,7 +916,7 @@ export class ApiClient {
             body.bankCard = request.bankCard;
         if (request.isAgent != null)
             body.isAgent = request.isAgent;
-        return this.post(`${API_PREFIX}/onboarding/indiv-auth`, body, true);
+        return this.postJson(`${API_PREFIX}/onboarding/indiv-auth`, body, true);
     }
     async checkAuthCode(request) {
         const body = {
@@ -759,18 +927,38 @@ export class ApiClient {
             body.authType = request.authType;
         if (request.isAgent != null)
             body.isAgent = request.isAgent;
-        return this.post(`${API_PREFIX}/onboarding/check-auth-code`, body, true);
+        return this.postJson(`${API_PREFIX}/onboarding/check-auth-code`, body, true);
     }
+    /**
+     * 企业实名认证：服务端把企业证件、法人、认证方式与完整注册地址一并校验，
+     * 因此这里整体组装后再发出，缺字段时由命令层提前拦截而不是靠服务端报错。
+     */
     async startOrganRealNameAuth(request) {
         const body = {
             name: request.name,
             certNumber: request.certNumber,
+            certType: request.certType,
+            authType: request.authType,
+            agentAccountId: request.agentAccountId,
+            legalName: request.legalName,
+            countryCode: request.countryCode,
+            alpha2Code: request.alpha2Code,
+            country: request.country,
+            state: request.state,
+            city: request.city,
+            county: request.county,
+            address: request.address,
         };
-        if (request.certType != null)
-            body.certType = request.certType;
-        if (request.agentAccountId)
-            body.agentAccountId = request.agentAccountId;
-        return this.post(`${API_PREFIX}/onboarding/organ-auth`, body, true);
+        // 服务端 certTypeEnum 与 certType 是同一含义的两种写法，由 certType 推导可
+        // 避免两者互相矛盾；超出枚举范围时留空，服务端允许 null。
+        const certTypeEnum = request.certTypeEnum ?? ORGAN_CERT_TYPE_ENUMS[request.certType];
+        if (certTypeEnum)
+            body.certTypeEnum = certTypeEnum;
+        if (request.legalCertNumber)
+            body.legalCertNumber = request.legalCertNumber;
+        if (request.legalCertType != null)
+            body.legalCertType = request.legalCertType;
+        return this.postJson(`${API_PREFIX}/onboarding/organ-auth`, body, true);
     }
     async openBrandAndApplyContract(request) {
         const body = {
@@ -792,7 +980,7 @@ export class ApiClient {
             body.county = request.county;
         if (request.cLegalName)
             body.cLegalName = request.cLegalName;
-        return this.post(`${API_PREFIX}/onboarding/open-brand`, body, true);
+        return this.postJson(`${API_PREFIX}/onboarding/open-brand`, body, true);
     }
     async authSaveGAT(request) {
         const body = {
@@ -829,11 +1017,7 @@ export class ApiClient {
             body.countyCode = request.countyCode;
         if (request.address)
             body.address = request.address;
-        return this.post(`${API_PREFIX}/onboarding/gat-auth`, body, true);
-    }
-    /** amount is in cents — the backend rejects yuan. */
-    async checkRemitAmount(flowId, amount) {
-        return this.post(`${API_PREFIX}/onboarding/check-remit`, { flowId, amount }, true);
+        return this.postJson(`${API_PREFIX}/onboarding/gat-auth`, body, true);
     }
     async queryOnboardingProgress() {
         return this.get(`${API_PREFIX}/onboarding/progress`, {}, true);
@@ -858,8 +1042,12 @@ export class ApiClient {
             body.pageSize = pageSize;
         return this.post(`${API_PREFIX}/onboarding/contracts`, body, true);
     }
-    async getContractSignUrl(contractCode) {
-        return this.post(`${API_PREFIX}/onboarding/contract-sign-url`, { contractCode }, true);
+    /**
+     * `status` 必填，取自 `contract list`：服务端会重新查合同详情并以实际状态为准，
+     * 详情未返回状态时用它兜底，所以状态码只能来自列表，不能猜。
+     */
+    async getContractSignUrl(contractCode, status) {
+        return this.post(`${API_PREFIX}/onboarding/contract-sign-url`, { contractCode, status }, true);
     }
 }
 //# sourceMappingURL=api-client.js.map