vps-work 2.5.0 → 2.5.1

package/dist/packages/vps-work/src/commands/sales/shortcuts.js

@@ -0,0 +1,800 @@
+import { attachSharedShortcutOptions, parseOptionalInt, resolveShortcutVpsServiceUrl, runSkillShortcutExecute, } from '../shortcut-common.js';
+import { VertuError } from '../../core/errors.js';
+import { buildSalesPeriodParams, dailySalesSkillKey, } from './period-params.js';
+import { downloadSalesInvoiceAttachments, listSalesInvoiceAttachments, } from '../../core/sales-invoice-attachments-client.js';
+function parseOptionalBoolean(raw, flag) {
+    if (raw === undefined || raw.trim() === '') {
+        return undefined;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1') {
+        return true;
+    }
+    if (normalized === 'false' || normalized === '0') {
+        return false;
+    }
+    throw new VertuError(`${flag} 必须是 true 或 false。`);
+}
+function withOkrSource(params, opts) {
+    if (opts.okrSource) {
+        params.okr_source = opts.okrSource;
+    }
+    return params;
+}
+function periodOptions(cmd) {
+    return cmd
+        .option('--period <name>', 'today | this_week | last_week | this_month | last_month | last_n_days | YYYY-MM-DD | …')
+        .option('--start-date <date>', 'YYYY-MM-DD；单独传表示单日，配合 --end-date 表示范围')
+        .option('--end-date <date>', 'YYYY-MM-DD；单独传表示单日，配合 --start-date 表示范围')
+        .option('--days <n>', 'With period=last_n_days')
+        .option('--dept-l1 <name>', '一级部门')
+        .option('--dept-l2 <name>', '二级部门')
+        .option('--dept-l3 <name>', '三级部门')
+        .option('--dept-l4 <name>', '四级部门')
+        .option('--dept-l5 <name>', '五级部门')
+        .option('--department-mode <mode>', 'matched=匹配部门字段口径；raw=原始组织层级口径')
+        .option('--limit <n>', 'Max rows')
+        .option('--include-deposit', '含定金口径（默认不含）', false)
+        .option('--product-subcategory <name>', '商品细类精确过滤')
+        .option('--product-subcategories <names>', '多个商品细类，逗号分隔并精确匹配')
+        .option('--product-category <name>', '商品分类精确过滤，如 手机 / IOT配件')
+        .option('--product-major-categories <names>', '商品大类，逗号分隔，如 戒指,手链')
+        .option('--product-style <name>', '款式精确过滤，如 高定')
+        .option('--product-style-details <names>', '款式1，逗号分隔，如 黄金3,黄金4,金钻')
+        .option('--smart-wearable', '智能穿戴口径：戒指/手链 + vps-ep 系列白名单', false);
+}
+function customerRegionPeriodOptions(cmd) {
+    return cmd
+        .option('--period <name>', 'today | this_week | last_week | this_month | last_month | last_n_days | YYYY-MM-DD | …')
+        .option('--start-date <date>', 'YYYY-MM-DD；单独传表示单日，配合 --end-date 表示范围')
+        .option('--end-date <date>', 'YYYY-MM-DD；单独传表示单日，配合 --start-date 表示范围')
+        .option('--days <n>', 'With period=last_n_days')
+        .option('--country <name>', '客户国家/地区名称或国区号，如 马来西亚 / 60')
+        .option('--include-deposit', '含定金口径（默认不含）', false);
+}
+function dealerOrderPeriodOptions(cmd) {
+    return cmd
+        .option('--period <name>', 'today | this_week | last_week | this_month | last_month | last_n_days | YYYY-MM-DD | …')
+        .option('--start-date <date>', 'YYYY-MM-DD；单独传表示单日，配合 --end-date 表示范围')
+        .option('--end-date <date>', 'YYYY-MM-DD；单独传表示单日，配合 --start-date 表示范围')
+        .option('--days <n>', 'With period=last_n_days')
+        .option('--limit <n>', 'Max rows');
+}
+function accountOrderPeriodOptions(cmd) {
+    return cmd
+        .option('--period <name>', 'today | this_week | last_week | this_month | last_month | last_n_days | YYYY-MM-DD | …')
+        .option('--start-date <date>', '会计日期 YYYY-MM-DD；可与 --end-date 组成闭区间')
+        .option('--end-date <date>', '会计日期 YYYY-MM-DD；可与 --start-date 组成闭区间')
+        .option('--days <n>', 'With period=last_n_days')
+        .option('--dept-l1 <name>', '一级部门')
+        .option('--dept-l2 <name>', '二级部门')
+        .option('--dept-l3 <name>', '三级部门')
+        .option('--dept-l4 <name>', '四级部门')
+        .option('--dept-l5 <name>', '五级部门')
+        .option('--limit <n>', 'Max rows');
+}
+function addAgentFilter(params, opts) {
+    if (opts.dealerId !== undefined) {
+        if (!/^[1-9]\d*$/.test(opts.dealerId) || Number(opts.dealerId) > 2147483647)
+            throw new Error('--dealer-id 必须为正整数');
+        params.dealer_id = Number(opts.dealerId);
+    }
+    if (opts.agentName)
+        params.agent_name = opts.agentName;
+    else if (opts.dealer)
+        params.dealer = opts.dealer;
+}
+/** Features · 销售与经营 — `vps-work sales +…` → vps-daily-sales-report */
+export function attachSalesShortcuts(parent) {
+    const skill = dailySalesSkillKey();
+    attachSharedShortcutOptions(parent
+        .command('+order-finance')
+        .alias('+finance-detail')
+        .description('按销售单号汇总订单、开票申请、正式发票和关联会计凭证')
+        .requiredOption('--order-no <no>', '销售单号，精确匹配')
+        .option('--invoice-no <no>', '发票/凭证号包含匹配')).action(async (opts, cmd) => {
+        const orderNo = opts.orderNo?.trim();
+        if (!orderNo)
+            throw new VertuError('--order-no is required.');
+        const params = { order_no: orderNo };
+        if (opts.invoiceNo?.trim())
+            params.invoice_no = opts.invoiceNo.trim();
+        await runSkillShortcutExecute(skill, 'order_finance', params, opts, cmd);
+    });
+    attachSharedShortcutOptions(parent
+        .command('+invoice-attachments')
+        .description('查询销售单关联的发票附件；可选下载到本地目录')
+        .requiredOption('--order-no <no>', '销售单号，精确匹配')
+        .option('--download-dir <path>', '下载全部附件到本地目录（不覆盖已有文件）')).action(async (opts, cmd) => {
+        const orderNo = opts.orderNo?.trim();
+        if (!orderNo)
+            throw new VertuError('--order-no is required.');
+        const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+        if (opts.validateOnly === true || opts.dryRun === true) {
+            console.log(JSON.stringify({
+                validateOnly: true,
+                endpoint: `${serviceBaseUrl}/v1/sales/invoice-attachments`,
+                order_no: orderNo,
+                download_dir: opts.downloadDir ?? null,
+            }, null, 2));
+            return;
+        }
+        const result = await listSalesInvoiceAttachments(serviceBaseUrl, orderNo);
+        const downloads = opts.downloadDir
+            ? await downloadSalesInvoiceAttachments(serviceBaseUrl, result.attachments, opts.downloadDir)
+            : undefined;
+        console.log(JSON.stringify(downloads ? { ...result, downloads } : result, null, 2));
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+headline-kpi')
+        .description('公司核心 KPI：销量/销额/订单（默认 period=today）')
+        .option('--include-today', 'Include today segment in response', true)
+        .option('--name <text>', '销售人员姓名 ILIKE')
+        .option('--salesperson-like <text>', '销售人员姓名 ILIKE')
+        .option('--work-id <code>', '工号')
+        .option('--barcode <code>', '工号'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'today');
+        if (opts.includeToday === false) {
+            p.include_today = false;
+        }
+        const salespersonLike = opts.salespersonLike ?? opts.name;
+        if (salespersonLike) {
+            p.salesperson_like = salespersonLike;
+        }
+        const workId = opts.workId ?? opts.barcode;
+        if (workId) {
+            p.work_id = workId;
+        }
+        await runSkillShortcutExecute(skill, 'headline_kpi', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+orders')
+        .alias('+order-list')
+        .description('订单与商品销量金额：默认按订单；可按订单-商品销售明细、期间商品或商品销售人员汇总（默认 period=today）')
+        .option('--vsn <text>', '商品 VSN 包含')
+        .option('--imei <text>', 'IMEI1 / IMEI2 包含')
+        .option('--activation-address <text>', '激活国家/省市/地址原文包含，需客户信息权限')
+        .option('--order-no <no>', '订单号包含')
+        .option('--logistics-no <no>', '物流单号 / 出库单号包含')
+        .option('--product <text>', '商品名称 / 编码 / 分类包含')
+        .option('--product-code <code>', '商品编码精确匹配')
+        .option('--group-by <mode>', '结果粒度：order（默认）/ order-product / product / product-salesperson')
+        .option('--customer <text>', '客户名称或可见手机号包含')
+        .option('--salesperson <name>', '销售人员姓名 / 工号包含')
+        .option('--channel <name>', '渠道包含')
+        .option('--order-state <state>', '订单状态包含，如 sale / partial_payment')
+        .option('--order-type <type>', '订单类型包含，如 订单 / 赠品 / 退货退款')
+        .option('--is-apportioned <boolean>', '是否分摊：true|false')
+        .option('--page <n>', '页码，从 1 开始', '1'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'today');
+        if (opts.vsn)
+            p.vsn = opts.vsn;
+        if (opts.imei)
+            p.imei = opts.imei;
+        if (opts.activationAddress)
+            p.activation_address = opts.activationAddress;
+        if (opts.orderNo) {
+            p.order_no = opts.orderNo;
+        }
+        if (opts.logisticsNo) {
+            p.logistics_no = opts.logisticsNo;
+        }
+        if (opts.product) {
+            p.product = opts.product;
+        }
+        if (opts.productCode)
+            p.product_code = opts.productCode;
+        if (opts.groupBy)
+            p.group_by = opts.groupBy.replaceAll('-', '_');
+        if (opts.customer) {
+            p.customer = opts.customer;
+        }
+        if (opts.salesperson) {
+            p.salesperson = opts.salesperson;
+        }
+        if (opts.channel) {
+            p.channel = opts.channel;
+        }
+        if (opts.orderState) {
+            p.order_state = opts.orderState;
+        }
+        if (opts.orderType) {
+            p.order_type = opts.orderType;
+        }
+        const isApportioned = parseOptionalBoolean(opts.isApportioned, '--is-apportioned');
+        if (isApportioned !== undefined) {
+            p.is_apportioned = isApportioned;
+        }
+        const page = parseOptionalInt(opts.page, '--page');
+        if (page !== undefined) {
+            p.page = page;
+        }
+        await runSkillShortcutExecute(skill, 'order_list', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(accountOrderPeriodOptions(parent
+        .command('+account-orders')
+        .alias('+account-sales-detail')
+        .description('按会计科目反查凭证关联的销售订单行（默认 period=this_month，仅已过账）')
+        .option('--account-code <code>', '会计科目编码精确匹配')
+        .option('--account-name <name>', '会计科目名称包含匹配')
+        .option('--move-no <no>', '会计凭证号包含')
+        .option('--order-no <no>', '销售单号包含')
+        .option('--include-draft', '包含未过账凭证', false)
+        .option('--page <n>', '页码，从 1 开始', '1'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        const mappings = [
+            ['accountCode', 'account_code'],
+            ['accountName', 'account_name'],
+            ['moveNo', 'move_no'],
+            ['orderNo', 'order_no'],
+        ];
+        for (const [option, param] of mappings) {
+            const value = opts[option];
+            if (typeof value === 'string' && value) {
+                p[param] = value;
+            }
+        }
+        if (opts.includeDraft) {
+            p.include_draft = true;
+        }
+        const page = parseOptionalInt(opts.page, '--page');
+        if (page !== undefined) {
+            p.page = page;
+        }
+        await runSkillShortcutExecute(skill, 'account_sales_detail', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(parent
+        .command('+invoice-status')
+        .alias('+invoice-applications')
+        .description('按销售单、FPSQ 申请单或购买方查询开票申请状态、记录 ID 和详情链接')
+        .option('--application-names <names>', 'FPSQ 申请单号精确匹配；逗号分隔，最多100个')
+        .option('--buyer <name>', '购买方名称包含匹配，与单号条件取交集')
+        .option('--order-names <names>', '销售单号精确匹配；多个单号用逗号分隔，最多100个')
+        .option('--limit <n>', '返回行数，1-1000，默认500')
+        .option('--offset <n>', '结果偏移，0-4999，默认0')).action(async (opts, cmd) => {
+        const orderNames = String(opts.orderNames ?? '').split(',').map((item) => item.trim()).filter(Boolean);
+        const applicationNames = String(opts.applicationNames ?? '').split(',').map((item) => item.trim()).filter(Boolean);
+        const buyer = opts.buyer?.trim();
+        if (!orderNames.length && !applicationNames.length && !buyer) {
+            throw new VertuError('请提供 --order-names、--application-names 或 --buyer。');
+        }
+        const p = {};
+        if (orderNames.length)
+            p.order_names = orderNames;
+        if (applicationNames.length)
+            p.application_names = applicationNames;
+        if (buyer)
+            p.buyer = buyer;
+        for (const [option, param, flag] of [
+            ['limit', 'limit', '--limit'],
+            ['offset', 'offset', '--offset'],
+        ]) {
+            const value = parseOptionalInt(opts[option], flag);
+            if (value !== undefined)
+                p[param] = value;
+        }
+        await runSkillShortcutExecute(skill, 'sales_invoice_status', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(parent
+        .command('+reconciled-receipts')
+        .alias('+sales-receipts')
+        .description('最近30天已对账销售单据的收款明细（固定排除有效退货）')
+        .option('--order-types <types>', 'sale,service,repair,jky；逗号分隔，默认全部')
+        .option('--order-names <names>', '销售单号精确匹配；逗号分隔')
+        .option('--salesperson <name>', '销售员名称包含')
+        .option('--department <name>', '部门名称包含')
+        .option('--company <name>', '单据所属公司名称包含')
+        .option('--invoiced <boolean>', 'true=存在开票申请，false=不存在开票申请（不表示真实申请状态）')
+        .option('--exclude-payment-methods <keywords>', '排除收款方式关键词；逗号分隔，传空字符串表示不排除')
+        .option('--limit <n>', '返回行数，1-1000，默认500')
+        .option('--row-limit <n>', 'limit 的兼容别名')
+        .option('--offset <n>', 'SQL行偏移，0-4999，默认0')).action(async (opts, cmd) => {
+        const p = {};
+        const listMappings = [
+            ['orderTypes', 'order_types'],
+            ['orderNames', 'order_names'],
+            ['excludePaymentMethods', 'exclude_payment_methods'],
+        ];
+        for (const [option, param] of listMappings) {
+            const value = opts[option];
+            if (typeof value === 'string')
+                p[param] = value.split(',').map((item) => item.trim()).filter(Boolean);
+        }
+        for (const [option, param] of [
+            ['salesperson', 'salesperson'],
+            ['department', 'department'],
+            ['company', 'company'],
+        ]) {
+            const value = opts[option];
+            if (value)
+                p[param] = value;
+        }
+        if (opts.invoiced !== undefined) {
+            if (opts.invoiced !== 'true' && opts.invoiced !== 'false') {
+                throw new VertuError('Invalid --invoiced: expected true or false.');
+            }
+            p.invoiced = opts.invoiced === 'true';
+        }
+        for (const [option, param, flag] of [
+            ['limit', 'limit', '--limit'],
+            ['rowLimit', 'row_limit', '--row-limit'],
+            ['offset', 'offset', '--offset'],
+        ]) {
+            const value = parseOptionalInt(opts[option], flag);
+            if (value !== undefined)
+                p[param] = value;
+        }
+        await runSkillShortcutExecute(skill, 'reconciled_sales_receipts', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent
+        .command('+dealer-orders')
+        .alias('+dealer-order-list')
+        .description('经销商订单列表：仅查询 JXSD 前缀订单（默认 period=this_month）')
+        .option('--order-no <no>', 'JXSD 订单号包含')
+        .option('--dealer <name>', '经销商名称包含')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--salesperson <name>', '销售员名称包含')
+        .option('--customer <text>', '客户名称或手机号包含')
+        .option('--product <text>', '商品名称 / 编码 / 分类包含')
+        .option('--vsn <text>', 'VSN / IMEI 包含')
+        .option('--doc-type <type>', 'so=销售 / rt=退货 / ex=换货')
+        .option('--state <state>', 'draft / done')
+        .option('--nature <nature>', 'domestic / foreign')
+        .option('--page <n>', '页码，从 1 开始', '1'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        const mappings = [
+            ['orderNo', 'order_no'],
+            ['salesperson', 'salesperson'],
+            ['customer', 'customer'],
+            ['product', 'product'],
+            ['vsn', 'vsn'],
+            ['docType', 'doc_type'],
+            ['state', 'state'],
+            ['nature', 'nature'],
+        ];
+        for (const [option, param] of mappings) {
+            const value = opts[option];
+            if (typeof value === 'string' && value) {
+                p[param] = value;
+            }
+        }
+        addAgentFilter(p, opts);
+        const page = parseOptionalInt(opts.page, '--page');
+        if (page !== undefined) {
+            p.page = page;
+        }
+        await runSkillShortcutExecute(skill, 'dealer_order_list', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(parent
+        .command('+dealer-inventory')
+        .description('经销商当前库存：数量、标准价金额、SKU 数及未定价库存')
+        .option('--dealer <name>', '经销商名称包含')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--nature <nature>', 'domestic / foreign')
+        .option('--product <text>', '商品名称或编码包含')).action(async (opts, cmd) => {
+        const p = {};
+        addAgentFilter(p, opts);
+        if (opts.nature)
+            p.nature = opts.nature;
+        if (opts.product)
+            p.product = opts.product;
+        await runSkillShortcutExecute(skill, 'dealer_inventory_summary', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent
+        .command('+dealer-final-sales')
+        .description('经销商终销：按五件套客户类型统计数量、含税金额和订单数（默认本月）')
+        .option('--dealer <name>', '经销商名称包含')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--nature <nature>', 'domestic / foreign'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        if (opts.nature)
+            p.nature = opts.nature;
+        await runSkillShortcutExecute(skill, 'dealer_final_sales_summary', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent
+        .command('+dealer-customer-portrait')
+        .alias('+dealer-portrait')
+        .description('经销商终销客户画像：背景、年龄、购买原因分布（默认本月）')
+        .option('--dealer <name>', '经销商名称包含')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--nature <nature>', 'domestic / foreign'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        if (opts.nature)
+            p.nature = opts.nature;
+        await runSkillShortcutExecute(skill, 'dealer_customer_portrait', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent
+        .command('+agent-sell-in-out')
+        .alias('+sell-in-out')
+        .description('国内代理 Sell-in/Sell-out 对比（默认本月）')
+        .option('--dealer-id <id>', '代理商主体 ID，优先于名称')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        await runSkillShortcutExecute(skill, 'agent_sell_in_out_summary', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent
+        .command('+agent-sell-in-out-details')
+        .alias('+sell-in-out-details')
+        .description('国内代理 Sell-in 与 Sell-out 逐行明细（默认本月）')
+        .option('--dealer-id <id>', '代理商主体 ID，优先于名称')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称')
+        .option('--detail-type <type>', 'sell_in | sell_out', 'sell_in')
+        .option('--page <n>', '页码，从 1 开始', '1')
+        .option('--page-size <n>', '每页条数，最大 200', '50'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        const page = parseOptionalInt(opts.page, '--page');
+        const pageSize = parseOptionalInt(opts.pageSize, '--page-size');
+        if (page !== undefined)
+            p.page = page;
+        if (pageSize !== undefined)
+            p.page_size = pageSize;
+        if (opts.detailType)
+            p.detail_type = opts.detailType;
+        await runSkillShortcutExecute(skill, 'agent_sell_in_out_details', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent
+        .command('+agent-five-source')
+        .alias('+agent-wujiantao')
+        .description('国内代理五件套来源：目标、真实 Sell-out、占比与完成率（默认本月）')
+        .option('--dealer-id <id>', '代理商主体 ID，优先于名称')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        await runSkillShortcutExecute(skill, 'agent_five_source_metrics', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent
+        .command('+agent-five-source-half-year')
+        .alias('+agent-wujiantao-half-year')
+        .description('国内代理五件套半年度 Sell-out 真实业绩；可传自定义日期')
+        .option('--year <year>', '未传日期时使用的年份')
+        .option('--month <month>', '未传日期时用于判断上/下半年的月份')
+        .option('--dealer-id <id>', '代理商主体 ID，优先于名称')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts);
+        addAgentFilter(p, opts);
+        const year = parseOptionalInt(opts.year, '--year');
+        const month = parseOptionalInt(opts.month, '--month');
+        if (year !== undefined)
+            p.year = year;
+        if (month !== undefined)
+            p.month = month;
+        await runSkillShortcutExecute(skill, 'agent_five_source_half_year', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent
+        .command('+agent-walkin')
+        .description('国内代理自然进店 Walk-in 经销商销售订单（默认本月）')
+        .option('--dealer-id <id>', '代理商主体 ID，优先于名称')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称')
+        .option('--page <n>', '页码，从 1 开始', '1')
+        .option('--page-size <n>', '每页条数，最大 200', '50'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        const page = parseOptionalInt(opts.page, '--page');
+        const pageSize = parseOptionalInt(opts.pageSize, '--page-size');
+        if (page !== undefined)
+            p.page = page;
+        if (pageSize !== undefined)
+            p.page_size = pageSize;
+        await runSkillShortcutExecute(skill, 'agent_walkin_orders', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-list')
+        .description('国内代理商名单（与代理商看板组织树同口径）'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        await runSkillShortcutExecute(skill, 'agent_list', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-five-source-completion')
+        .alias('+agent-wujiantao-completion')
+        .description('国内代理五件套总体目标、Sell-in 实际与完成率')
+        .option('--dealer-id <id>', '代理商主体 ID，优先于名称')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        await runSkillShortcutExecute(skill, 'agent_wujiantao_completion_rate', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-top-metrics')
+        .description('代理商看板顶部指标：当期/当日/全年达成与时间进度')
+        .option('--current-date <date>', '当日业绩与时间进度日期，默认查询结束日')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        if (opts.currentDate)
+            p.current_date = opts.currentDate;
+        await runSkillShortcutExecute(skill, 'agent_top_metrics', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-performance')
+        .description('代理商业绩目标、实际与完成率')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        await runSkillShortcutExecute(skill, 'agent_performance', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-product-ranking')
+        .description('代理商产品系列销量排名')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        await runSkillShortcutExecute(skill, 'agent_product_ranking', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-delivery')
+        .description('代理商提货/发货情况，按分类、系列和材质汇总')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        await runSkillShortcutExecute(skill, 'agent_delivery', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-sku-ranking')
+        .description('代理商 SKU 销量排名')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        await runSkillShortcutExecute(skill, 'agent_sku_ranking', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-product-material-ranking')
+        .description('代理商指定产品系列的材质销售排名')
+        .requiredOption('--product-name <name>', '商品细类/产品系列')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        p.product_name = opts.productName;
+        await runSkillShortcutExecute(skill, 'agent_product_material_ranking', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-performance-detail')
+        .description('代理商业绩明细：目标、定金、当日、环比和同比')
+        .option('--current-date <date>', '当日业绩日期，默认查询结束日')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        if (opts.currentDate)
+            p.current_date = opts.currentDate;
+        await runSkillShortcutExecute(skill, 'agent_performance_detail', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-phone-sales-proportion')
+        .description('代理商手机系列或材质销量占比')
+        .option('--product-series <name>', '具体系列；all_materials 表示全部手机材质')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        if (opts.productSeries)
+            p.product_series = opts.productSeries;
+        await runSkillShortcutExecute(skill, 'agent_phone_sales_proportion', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-product-sales')
+        .description('代理商产品销售层级：代理商、系列、材质和 SKU')
+        .option('--category <name>', '商品大类，如手机/腕表/耳机/戒指')
+        .option('--series <name>', '商品细类/产品系列')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        if (opts.category)
+            p.category = opts.category;
+        if (opts.series)
+            p.series = opts.series;
+        await runSkillShortcutExecute(skill, 'agent_product_sales', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-iot-sales-proportion')
+        .description('代理商 IOT 系列或颜色销量占比')
+        .option('--iot-series <name>', '具体系列；all_colors 表示全部 IOT 颜色')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        if (opts.iotSeries)
+            p.iot_series = opts.iotSeries;
+        await runSkillShortcutExecute(skill, 'agent_iot_sales_proportion', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(dealerOrderPeriodOptions(parent.command('+agent-price-distribution')
+        .description('代理商手机/IOT 产品价格区间分布')
+        .option('--category <name>', '手机 | IOT配件', '手机')
+        .option('--agent-name <name>', '代理商完整名称（标准化括号后精确匹配）')
+        .option('--dealer <name>', '兼容参数：代理商名称'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        addAgentFilter(p, opts);
+        if (opts.category)
+            p.category = opts.category;
+        await runSkillShortcutExecute(skill, 'agent_price_distribution', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+order-logistics')
+        .alias('+logistics')
+        .description('订单物流精查：按订单号 / 物流单号 / 出库单号查询发货明细（默认 period=this_year）')
+        .option('--order-no <no>', '订单号 / 出库单号')
+        .option('--logistics-no <no>', '物流单号 / 出库单号')
+        .option('--department <name>', '兼容旧用法：销售员所在部门名称或路径包含；一般优先用 sales +orders')
+        .option('--salesperson <name>', '兼容旧用法：销售人员姓名包含；一般优先用 sales +orders')
+        .option('--name <name>', '兼容旧用法：销售人员姓名包含；一般优先用 sales +orders')
+        .option('--user-id <id>', '兼容旧用法：销售人员用户 ID；一般优先用 sales +orders')
+        .option('--page <n>', '页码，从 1 开始', '1'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_year');
+        if (opts.orderNo) {
+            p.order_no = opts.orderNo;
+        }
+        if (opts.logisticsNo) {
+            p.logistics_no = opts.logisticsNo;
+        }
+        if (opts.department) {
+            p.department = opts.department;
+        }
+        const salesperson = opts.salesperson ?? opts.name;
+        if (salesperson) {
+            p.salesperson = salesperson;
+        }
+        const userId = parseOptionalInt(opts.userId, '--user-id');
+        if (userId !== undefined) {
+            p.user_id = userId;
+        }
+        const page = parseOptionalInt(opts.page, '--page');
+        if (page !== undefined) {
+            p.page = page;
+        }
+        await runSkillShortcutExecute(skill, 'order_logistics', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+dept-breakdown')
+        .description('部门/销售员/产品线排名（默认 period=this_month）')
+        .option('--group-by <dim>', 'dept_l1|dept_l2|dept_l3|dept_l4|dept_l5|matched_dept|match_dept|salesperson|product_subcategory|…')
+        .option('--auto-next-level', 'Infer group_by from dept depth', true))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        if (opts.groupBy) {
+            p.group_by = opts.groupBy;
+        }
+        if (opts.autoNextLevel === false) {
+            p.auto_next_level = false;
+        }
+        await runSkillShortcutExecute(skill, 'dept_breakdown', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(customerRegionPeriodOptions(parent
+        .command('+customer-region')
+        .alias('+customer-region-summary')
+        .description('全域客户国家/地区业绩分布：订单数和营业额（默认本月）'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        if (opts.country?.trim()) {
+            p.country = opts.country.trim();
+        }
+        await runSkillShortcutExecute(skill, 'customer_region_summary', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+customer-mix')
+        .alias('+customer-sales-mix')
+        .description('新老客销售额占比（分类来源 customer_source.customer_category，默认 period=this_month）'))).action(async (opts, cmd) => {
+        await runSkillShortcutExecute(skill, 'customer_sales_mix', buildSalesPeriodParams(opts, 'this_month'), opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+dept-comparison')
+        .description('环比 / 同比（默认 period=this_month）')
+        .option('--group-by <dim>', 'dept_l1|dept_l2|org_channel|product_style1|product_subcategory|…'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        if (opts.groupBy) {
+            p.group_by = opts.groupBy;
+        }
+        await runSkillShortcutExecute(skill, 'dept_comparison', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+target-achievement')
+        .description('部门业绩目标达成（默认 period=this_month）')
+        .option('--page <n>', '页码，从 1 开始', '1')).option('--okr-source <source>', 'legacy | postgres（默认 legacy，与管理端部门业绩目标一致）')).action(async (opts, cmd) => {
+        const p = withOkrSource(buildSalesPeriodParams(opts, 'this_month'), opts);
+        const page = parseOptionalInt(opts.page, '--page');
+        if (page !== undefined) {
+            p.page = page;
+        }
+        await runSkillShortcutExecute(skill, 'dept_target_achievement', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+dept-monthly-okr')
+        .description('部门月度业绩目标明细（dept_monthly_okr）')
+        .option('--match-dept <name>', '匹配部门模糊')
+        .option('--page <n>', '页码，从 1 开始', '1')).option('--okr-source <source>', 'legacy | postgres（默认 legacy，与管理端部门业绩目标一致）')).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        withOkrSource(p, opts);
+        if (opts.matchDept) {
+            p.match_dept = opts.matchDept;
+        }
+        const page = parseOptionalInt(opts.page, '--page');
+        if (page !== undefined) {
+            p.page = page;
+        }
+        const limit = parseOptionalInt(opts.limit, '--limit');
+        if (limit !== undefined) {
+            p.limit = limit;
+        }
+        else {
+            p.limit = 100;
+        }
+        await runSkillShortcutExecute(skill, 'dept_monthly_okr', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+deposit-breakdown')
+        .description('含/不含定金销售额对照（默认 period=this_month）'))).action(async (opts, cmd) => {
+        await runSkillShortcutExecute(skill, 'with_without_deposit_breakdown', buildSalesPeriodParams(opts, 'this_month'), opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent.command('+refund-summary').description('退款 / 退换货汇总（默认 period=this_month）'))).action(async (opts, cmd) => {
+        await runSkillShortcutExecute(skill, 'refund_summary', buildSalesPeriodParams(opts, 'this_month'), opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+service-sales')
+        .description('权益部/服务部销售（默认 period=last_n_days, days=30）')
+        .option('--person <name>', '经办人 ILIKE'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'last_n_days');
+        if (!opts.days) {
+            p.days = 30;
+        }
+        if (opts.person) {
+            p.person = opts.person;
+        }
+        await runSkillShortcutExecute(skill, 'service_dept_sales_summary', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+daily-trend')
+        .alias('+trend')
+        .description('按日/周/月走势、环比和明细维度（默认 day / this_month）')
+        .option('--grain <name>', 'day | week | month', 'day')
+        .option('--group-by <dim>', '主维度，如 org_channel / dept_l1 / product_style1')
+        .option('--breakdown-by <dim>', '明细维度，如 product_style1 / product_subcategory')
+        .option('--no-include-cumulative', 'Omit cumulative series')
+        .option('--no-include-comparison', 'Omit previous-period and change-rate fields')
+        .option('--include-yoy', 'Include year-over-year alignment', false))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        if (opts.includeCumulative === false) {
+            p.include_cumulative = false;
+        }
+        if (opts.includeYoy) {
+            p.include_yoy = true;
+        }
+        if (opts.includeComparison === false) {
+            p.include_comparison = false;
+        }
+        if (opts.grain) {
+            p.grain = opts.grain;
+        }
+        if (opts.groupBy) {
+            p.group_by = opts.groupBy;
+        }
+        if (opts.breakdownBy) {
+            p.breakdown_by = opts.breakdownBy;
+        }
+        await runSkillShortcutExecute(skill, 'monthly_daily_trend', p, opts, cmd);
+    });
+    attachSharedShortcutOptions(periodOptions(parent
+        .command('+ranking')
+        .description('销售员 TOP/BOTTOM 榜（默认 period=this_month）')
+        .option('--metric <name>', 'amount | qty | orders', 'amount')
+        .option('--top-n <n>', 'TOP N', '10')
+        .option('--bottom-n <n>', 'BOTTOM N', '10')
+        .option('--no-exclude-zero', 'Include zero rows in bottom list'))).action(async (opts, cmd) => {
+        const p = buildSalesPeriodParams(opts, 'this_month');
+        if (opts.metric) {
+            p.metric = opts.metric;
+        }
+        const topN = parseOptionalInt(opts.topN, '--top-n');
+        if (topN !== undefined) {
+            p.top_n = topN;
+        }
+        const bottomN = parseOptionalInt(opts.bottomN, '--bottom-n');
+        if (bottomN !== undefined) {
+            p.bottom_n = bottomN;
+        }
+        if (opts.excludeZero === false) {
+            p.exclude_zero = false;
+        }
+        await runSkillShortcutExecute(skill, 'employee_ranking_top_bottom', p, opts, cmd);
+    });
+}