vps-work 2.5.0 → 2.5.1

package/dist/packages/vps-work/src/commands/product/abnormal-statistics.js

@@ -0,0 +1,250 @@
+import { VertuError } from '../../core/errors.js';
+import { vpsServiceGet, vpsServicePost } from '../../core/sales-query-client.js';
+import { expandAtFileToken } from '../../utils/at-file.js';
+import { attachSharedShortcutOptions, resolveShortcutVpsServiceUrl, } from '../shortcut-common.js';
+const LOCATION_PATH = '/v1/product/abnormal/location';
+const LOCATION_LIST_PATH = '/v1/product/abnormal/location-list';
+const DETAILS_PATH = '/v1/product/abnormal/details';
+function isPreview(opts) {
+    return opts.validateOnly === true || opts.dryRun === true;
+}
+function printResult(opts, value) {
+    console.log(JSON.stringify(value, null, opts.json === false ? undefined : 2));
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function remoteMessage(value, fallback) {
+    const record = asRecord(value);
+    for (const key of ['message', 'error', 'statusText']) {
+        const candidate = record?.[key];
+        if (typeof candidate === 'string' && candidate.trim())
+            return candidate.trim();
+    }
+    return fallback;
+}
+function unwrapEnvelopeRows(value, label) {
+    const envelope = asRecord(value);
+    if (!envelope || Number(envelope.code) !== 200) {
+        throw new VertuError(remoteMessage(value, `${label}返回结构无效。`));
+    }
+    const payload = asRecord(envelope.data);
+    if (!payload || !Array.isArray(payload.data)) {
+        throw new VertuError(`${label}返回结构缺少 data.data 数组。`);
+    }
+    return {
+        rows: payload.data.filter((item) => asRecord(item) !== null),
+        reportedTotal: Number.isFinite(Number(payload.total)) ? Number(payload.total) : payload.data.length,
+    };
+}
+function parseLocationIds(raw) {
+    if (!raw?.trim())
+        return [];
+    const values = raw.split(/[\s,]+/).filter(Boolean);
+    const ids = values.map((value) => Number(value));
+    if (ids.some((value) => !Number.isInteger(value) || value <= 0)) {
+        throw new VertuError('--location-ids 必须是英文逗号分隔的正整数。');
+    }
+    return [...new Set(ids)];
+}
+async function parseImeis(raw) {
+    const expanded = (await expandAtFileToken(raw, '--imeis')).trim();
+    if (!expanded)
+        throw new VertuError('--imeis 不能为空。');
+    let values;
+    if (expanded.startsWith('[')) {
+        try {
+            const parsed = JSON.parse(expanded);
+            if (!Array.isArray(parsed))
+                throw new Error('not array');
+            values = parsed;
+        }
+        catch {
+            throw new VertuError('--imeis 的 JSON 输入必须是字符串或数字数组。');
+        }
+    }
+    else {
+        values = expanded.split(/[\s,]+/).filter(Boolean);
+    }
+    if (values.some((value) => typeof value !== 'string' && typeof value !== 'number')) {
+        throw new VertuError('--imeis 的每一项必须是字符串或数字。');
+    }
+    const imeis = [...new Set(values.map((value) => String(value).trim()).filter(Boolean))];
+    if (!imeis.length)
+        throw new VertuError('--imeis 不能为空。');
+    if (imeis.length > 5000)
+        throw new VertuError('--imeis 单次最多 5000 个。');
+    return imeis;
+}
+function numeric(row, key) {
+    const value = Number(row[key]);
+    return Number.isFinite(value) ? value : 0;
+}
+function summarizeLocations(rows) {
+    const locations = new Set();
+    const abnormalImeis = new Set();
+    let totalStock = 0;
+    let physicalStock = 0;
+    let inTransitStock = 0;
+    let storeStock = 0;
+    for (const row of rows) {
+        const location = typeof row.location_name === 'string' ? row.location_name.trim() : '';
+        if (location)
+            locations.add(location);
+        totalStock += numeric(row, 'total_stock');
+        physicalStock += numeric(row, 'physical_stock');
+        inTransitStock += numeric(row, 'in_transit_stock');
+        storeStock += numeric(row, 'store_stock');
+        if (Array.isArray(row.abnormal_imeis)) {
+            for (const imei of row.abnormal_imeis) {
+                const normalized = String(imei).trim();
+                if (normalized)
+                    abnormalImeis.add(normalized);
+            }
+        }
+    }
+    return {
+        abnormal_imei_count: abnormalImeis.size,
+        in_transit_stock: inTransitStock,
+        location_count: locations.size,
+        physical_stock: physicalStock,
+        row_count: rows.length,
+        store_stock: storeStock,
+        total_stock: totalStock,
+    };
+}
+async function fetchLocationOptions(serviceBaseUrl, locationName) {
+    const response = await vpsServiceGet(LOCATION_LIST_PATH, { location_name: locationName?.trim() || undefined }, serviceBaseUrl, '设备异常仓位列表');
+    return unwrapEnvelopeRows(response, '仓位列表接口');
+}
+/** Add role-protected abnormal inventory/device statistics shortcuts to the product domain. */
+export function attachProductAbnormalStatisticsShortcuts(parent) {
+    attachSharedShortcutOptions(parent
+        .command('+abnormal-location')
+        .description('按仓位查询库存、在途、门店库存和异常 IMEI（需设备异常分析角色）')
+        .option('--location-name <name>', '仓位名称模糊搜索')
+        .option('--location-ids <ids>', '仓位 ID，多个用英文逗号分隔')
+        .option('--default-selected', '复现 vps-ep 页面：先读取仓位列表并使用 is_selected=true 的仓位')).action(async (opts, cmd) => {
+        const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+        let locationIds = parseLocationIds(opts.locationIds);
+        if (opts.defaultSelected && locationIds.length) {
+            throw new VertuError('--default-selected 与 --location-ids 不能同时使用。');
+        }
+        const locationName = opts.locationName?.trim() || undefined;
+        if (isPreview(opts)) {
+            printResult(opts, {
+                validateOnly: true,
+                source: 'vps-service-device-abnormal-proxy',
+                endpoint: `${serviceBaseUrl}${LOCATION_PATH}`,
+                required_scope: 'product.device_abnormal:read',
+                query: {
+                    ...(locationName ? { location_name: locationName } : {}),
+                    ...(locationIds.length ? { location_ids: locationIds.join(',') } : {}),
+                    ...(opts.defaultSelected ? { location_ids: `<is_selected=true from ${LOCATION_LIST_PATH}>` } : {}),
+                },
+                ...(opts.defaultSelected
+                    ? { prerequisite_endpoint: `${serviceBaseUrl}${LOCATION_LIST_PATH}` }
+                    : {}),
+            });
+            return;
+        }
+        if (opts.defaultSelected) {
+            const options = await fetchLocationOptions(serviceBaseUrl);
+            locationIds = options.rows
+                .filter((row) => row.is_selected === true)
+                .map((row) => Number(row.location_id))
+                .filter((id) => Number.isInteger(id) && id > 0);
+            if (!locationIds.length) {
+                throw new VertuError('仓位列表未返回 is_selected=true 的默认仓位，已停止查询，避免退化为全仓位。');
+            }
+        }
+        const response = await vpsServiceGet(LOCATION_PATH, {
+            location_name: locationName,
+            location_ids: locationIds.length ? locationIds.join(',') : undefined,
+        }, serviceBaseUrl, '设备异常仓位统计');
+        const result = unwrapEnvelopeRows(response, '仓位异常统计接口');
+        printResult(opts, {
+            source: 'vps-service-device-abnormal-proxy',
+            filter: {
+                location_name: locationName ?? null,
+                location_ids: locationIds,
+                default_selected: opts.defaultSelected === true,
+            },
+            summary: summarizeLocations(result.rows),
+            rows: result.rows,
+            reported_total: result.reportedTotal,
+        });
+    });
+    attachSharedShortcutOptions(parent
+        .command('+abnormal-location-list')
+        .description('查询异常统计可用仓位及 vps-ep 默认选中状态（需设备异常分析角色）')
+        .option('--location-name <name>', '仓位名称模糊搜索')).action(async (opts, cmd) => {
+        const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+        const locationName = opts.locationName?.trim() || undefined;
+        if (isPreview(opts)) {
+            printResult(opts, {
+                validateOnly: true,
+                source: 'vps-service-device-abnormal-proxy',
+                endpoint: `${serviceBaseUrl}${LOCATION_LIST_PATH}`,
+                required_scope: 'product.device_abnormal:read',
+                query: { ...(locationName ? { location_name: locationName } : {}) },
+            });
+            return;
+        }
+        const result = await fetchLocationOptions(serviceBaseUrl, locationName);
+        printResult(opts, {
+            source: 'vps-service-device-abnormal-proxy',
+            filter: { location_name: locationName ?? null },
+            rows: result.rows,
+            total: result.reportedTotal,
+            default_selected_ids: result.rows
+                .filter((row) => row.is_selected === true)
+                .map((row) => Number(row.location_id))
+                .filter((id) => Number.isInteger(id) && id > 0),
+        });
+    });
+    attachSharedShortcutOptions(parent
+        .command('+abnormal-details')
+        .description('按 IMEI 查询仍未处理的设备异常明细（需设备异常分析角色）')
+        .requiredOption('--imeis <values>', 'IMEI，逗号/空白分隔；支持 JSON 数组或 @file')
+        .option('--stat-date <date>', '统计开始时间，日期字符串或时间戳')
+        .option('--end-date <date>', '统计结束时间，日期字符串或时间戳')
+        .option('--exception-type <type>', '异常筛选类型，例如 address_exception')).action(async (opts, cmd) => {
+        const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+        const imeis = await parseImeis(opts.imeis);
+        const body = {
+            imeis,
+            ...(opts.statDate?.trim() ? { stat_date: opts.statDate.trim() } : {}),
+            ...(opts.endDate?.trim() ? { end_date: opts.endDate.trim() } : {}),
+            ...(opts.exceptionType?.trim() ? { exception_type: opts.exceptionType.trim() } : {}),
+        };
+        if (isPreview(opts)) {
+            printResult(opts, {
+                validateOnly: true,
+                source: 'vps-service-device-abnormal-proxy',
+                endpoint: `${serviceBaseUrl}${DETAILS_PATH}`,
+                required_scope: 'product.device_abnormal:read',
+                method: 'POST',
+                body,
+            });
+            return;
+        }
+        const response = await vpsServicePost(DETAILS_PATH, body, serviceBaseUrl, '设备异常明细');
+        if (!Array.isArray(response)) {
+            throw new VertuError('设备异常明细接口应返回数组，但实际响应结构不同。');
+        }
+        printResult(opts, {
+            source: 'vps-service-device-abnormal-proxy',
+            filter: {
+                imeis,
+                stat_date: body.stat_date ?? '2000-01-01',
+                end_date: body.end_date ?? '2035-01-01',
+                exception_type: body.exception_type ?? '',
+            },
+            rows: response,
+            total: response.length,
+        });
+    });
+}

package/dist/packages/vps-work/src/commands/product/data-view-shortcuts.js

@@ -0,0 +1,253 @@
+import { VertuError } from '../../core/errors.js';
+import { runVpsServiceDataView, vpsServicePost } from '../../core/sales-query-client.js';
+import { expandAtFileToken } from '../../utils/at-file.js';
+import { parseJsonArg } from '../../utils/parse-json-arg.js';
+import { attachSharedShortcutOptions, mergeShortcutParams, parseOptionalInt, resolveShortcutVpsServiceUrl, } from '../shortcut-common.js';
+function printResult(opts, result) {
+    if (opts.json !== false) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(typeof result === 'string' ? result : JSON.stringify(result));
+}
+function parsePositiveInt(raw, flag, fallback, max) {
+    const value = parseOptionalInt(raw, flag) ?? fallback;
+    if (value < 1) {
+        throw new VertuError(`Invalid ${flag}: expected a positive integer.`);
+    }
+    return max ? Math.min(value, max) : value;
+}
+function collectProductFilters(opts) {
+    const filters = {};
+    if (opts.productCode) {
+        filters.product_code = opts.productCode;
+    }
+    if (opts.productName) {
+        filters.product_name = opts.productName;
+    }
+    if (opts.productFamily) {
+        filters.product_family = opts.productFamily;
+    }
+    if (opts.productCategory) {
+        filters.product_category = opts.productCategory;
+    }
+    if (opts.productClass) {
+        filters.product_class = opts.productClass;
+    }
+    if (opts.productSubcategory) {
+        filters.product_subcategory = opts.productSubcategory;
+    }
+    if (opts.productColor) {
+        filters.product_color = opts.productColor;
+    }
+    if (opts.productMaterial) {
+        filters.product_material = opts.productMaterial;
+    }
+    if (opts.productColorMaterial) {
+        filters.product_color_material = opts.productColorMaterial;
+    }
+    if (opts.productPhoneVersion) {
+        filters.product_phone_version = opts.productPhoneVersion;
+    }
+    if (opts.priceRegion) {
+        filters.price_region = opts.priceRegion;
+    }
+    return filters;
+}
+async function resolveFiltersJson(raw) {
+    if (raw === undefined || raw.trim() === '') {
+        return {};
+    }
+    const expanded = await expandAtFileToken(raw, '--filters-json');
+    if (expanded.trim() === '') {
+        return {};
+    }
+    return parseJsonArg(expanded, '--filters-json', {
+        requireObject: true,
+        fileFlagSuggestion: '--filters-json @./filters.json',
+    });
+}
+/**
+ * 把 CLI flag 收敛为 data-view filters；空值不下发，交由服务端默认。
+ * filter key 必须与 vps-service `dataViews.views[].filters[].key` 完全一致。
+ */
+async function runProductDataView(viewId, filters, opts, cmd) {
+    const filtersJson = await resolveFiltersJson(opts.filtersJson);
+    const merged = await mergeShortcutParams({ ...filters, ...filtersJson }, opts);
+    const page = parsePositiveInt(opts.page, '--page', 1);
+    const pageSize = parsePositiveInt(opts.pageSize ?? opts.limit, opts.pageSize ? '--page-size' : '--limit', 100, 1000);
+    const groupBy = opts.groupBy?.trim() || undefined;
+    const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+    // --validate-only / --dry-run：仅本地预览将提交的请求载荷，不打网络、不查库。
+    if (opts.validateOnly === true || opts.dryRun === true) {
+        printResult(opts, {
+            validateOnly: true,
+            endpoint: `${serviceBaseUrl}/v1/data-view/query`,
+            payload: {
+                view_id: viewId,
+                filters: merged,
+                page,
+                page_size: pageSize,
+                ...(groupBy ? { group_by: groupBy } : {}),
+            },
+        });
+        return;
+    }
+    printResult(opts, await runVpsServiceDataView(viewId, merged, { page, pageSize, groupBy }, serviceBaseUrl));
+}
+/** Features · 产品与供应链 — `vps-work product +…`（data-view：库存/发货/齐套/机头）。 */
+export function attachProductDataViewShortcuts(parent) {
+    attachSharedShortcutOptions(parent
+        .command('+inventory-by-vsn')
+        .alias('+vsn-inventory')
+        .description('按 VSN 精确查询商品、当前内部/在途库存和存储位置')
+        .requiredOption('--vsn <values>', 'VSN；多个值用逗号或空白分隔，最多100个')).action(async (opts, cmd) => {
+        const vsns = [...new Set(String(opts.vsn ?? '').split(/[,，\s]+/).map((value) => value.trim()).filter(Boolean))];
+        if (!vsns.length)
+            throw new VertuError('--vsn 不能为空。');
+        if (vsns.length > 100)
+            throw new VertuError('--vsn 单次最多 100 个。');
+        const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+        const body = { vsns };
+        if (opts.validateOnly === true || opts.dryRun === true) {
+            printResult(opts, {
+                validateOnly: true,
+                endpoint: `${serviceBaseUrl}/v1/product/inventory-by-vsn`,
+                required_scope: 'product.device_abnormal:read',
+                method: 'POST',
+                body,
+            });
+            return;
+        }
+        const response = await vpsServicePost('/v1/product/inventory-by-vsn', body, serviceBaseUrl, 'VSN 库存查询');
+        const result = response && typeof response === 'object' && !Array.isArray(response) && 'result' in response
+            ? response.result
+            : response;
+        printResult(opts, result);
+    });
+    attachSharedShortcutOptions(parent
+        .command('+inventory')
+        .description('库存数据：分仓/门店库存、门店明细（inventory-data）')
+        .option('--product-code <code>', '产品编码包含')
+        .option('--product-name <name>', '商品名称包含')
+        .option('--product-family <name>', '产品包含（如 产成品 / 半成品）')
+        .option('--product-category <name>', '商品大类包含')
+        .option('--product-class <name>', '商品分类包含')
+        .option('--product-subcategory <name>', '商品细类包含')
+        .option('--product-color <name>', '颜色包含（如 黑色 / 棕色 / 蓝色）')
+        .option('--product-material <name>', '材质包含（如 小牛皮 / 鳄鱼皮）')
+        .option('--product-color-material <name>', '颜色材质包含')
+        .option('--product-phone-version <name>', '手机版本包含（如 国内 / 海外）')
+        .option('--store-detail <name>', '门店明细包含')
+        .option('--group-by <dim>', '聚合维度：product|product_category|product_class|product_subcategory|product_color|product_material|store_detail|department')
+        .option('--page <n>', '页码，从 1 开始', '1')
+        .option('--page-size <n>', '每页行数，最大 1000')
+        .option('--limit <n>', '返回行数', '100')
+        .option('--filters-json <json>', '合并高级过滤 JSON；支持 @file，例如 {"product_category":"手机"}')).action(async (opts, cmd) => {
+        const filters = collectProductFilters(opts);
+        if (opts.storeDetail) {
+            filters.store_detail = opts.storeDetail;
+        }
+        await runProductDataView('inventory-data', filters, opts, cmd);
+    });
+    attachSharedShortcutOptions(parent
+        .command('+price')
+        .description('商品价格：标准价/海外价/国内价（product-price，不依赖库存）')
+        .option('--product-code <code>', '产品编码包含')
+        .option('--product-name <name>', '商品名称包含')
+        .option('--product-family <name>', '产品包含（如 产成品 / 半成品）')
+        .option('--product-category <name>', '商品大类包含')
+        .option('--product-class <name>', '商品分类包含')
+        .option('--product-subcategory <name>', '商品细类包含')
+        .option('--product-color <name>', '颜色包含（如 黑色 / 棕色 / 蓝色）')
+        .option('--product-material <name>', '材质包含（如 小牛皮 / 鳄鱼皮）')
+        .option('--product-color-material <name>', '颜色材质包含')
+        .option('--product-phone-version <name>', '手机版本包含（如 国内 / 海外）')
+        .option('--price-region <region>', '价格区域包含（standard / domestic / overseas）')
+        .option('--page <n>', '页码，从 1 开始', '1')
+        .option('--page-size <n>', '每页行数，最大 1000')
+        .option('--limit <n>', '返回行数', '100')
+        .option('--filters-json <json>', '合并高级过滤 JSON；支持 @file，例如 {"product_category":"手机"}')).action(async (opts, cmd) => {
+        await runProductDataView('product-price', collectProductFilters(opts), opts, cmd);
+    });
+    attachSharedShortcutOptions(parent
+        .command('+delivery')
+        .description('发货数据：出库单、发货数量、收货部门（delivery-data）')
+        .option('--product-code <code>', '产品编码包含')
+        .option('--product-name <name>', '商品名称包含（如 ALPHAFOLD / FOLD）')
+        .option('--product-family <name>', '产品包含（如 产成品 / 半成品）')
+        .option('--product-category <name>', '商品大类包含（如 手机）')
+        .option('--product-class <name>', '商品分类包含')
+        .option('--product-subcategory <name>', '商品细类包含（如 VERTU ALPHAFOLD）')
+        .option('--product-color <name>', '颜色包含')
+        .option('--product-material <name>', '材质包含（如 小牛皮 / 鳄鱼皮）')
+        .option('--product-color-material <name>', '颜色材质包含')
+        .option('--product-phone-version <name>', '手机版本包含（如 国内 / 海外）')
+        .option('--warehouse <name>', '发货仓/库位完整名称包含（如 发货仓 / 成都总仓）')
+        .option('--department <name>', '部门包含')
+        .option('--start-date <date>', '发货起始日期 YYYY-MM-DD')
+        .option('--end-date <date>', '发货结束日期 YYYY-MM-DD')
+        .option('--launch-start-date <date>', '上市起始日期 YYYY-MM-DD')
+        .option('--launch-end-date <date>', '上市结束日期 YYYY-MM-DD')
+        .option('--page <n>', '页码，从 1 开始', '1')
+        .option('--page-size <n>', '每页行数，最大 1000')
+        .option('--limit <n>', '返回行数', '100')
+        .option('--filters-json <json>', '合并高级过滤 JSON；支持 @file，例如 {"product_category":"手机","warehouse":"发货仓"}')).action(async (opts, cmd) => {
+        const filters = collectProductFilters(opts);
+        if (opts.warehouse) {
+            filters.warehouse = opts.warehouse;
+        }
+        if (opts.department) {
+            filters.department = opts.department;
+        }
+        if (opts.startDate) {
+            filters.start_date = opts.startDate;
+        }
+        if (opts.endDate) {
+            filters.end_date = opts.endDate;
+        }
+        if (opts.launchStartDate) {
+            filters.launch_start_date = opts.launchStartDate;
+        }
+        if (opts.launchEndDate) {
+            filters.launch_end_date = opts.launchEndDate;
+        }
+        await runProductDataView('delivery-data', filters, opts, cmd);
+    });
+    attachSharedShortcutOptions(parent
+        .command('+kit-materials')
+        .description('齐套物料：BOM 可用库存与商品分类（kit-materials）')
+        .option('--product-name <name>', '商品名称包含')
+        .option('--product-code <code>', '产品编码包含')
+        .option('--page <n>', '页码，从 1 开始', '1')
+        .option('--page-size <n>', '每页行数，最大 1000')
+        .option('--limit <n>', '返回行数', '100')
+        .option('--filters-json <json>', '合并高级过滤 JSON；支持 @file')).action(async (opts, cmd) => {
+        const filters = {};
+        if (opts.productName) {
+            filters.product_name = opts.productName;
+        }
+        if (opts.productCode) {
+            filters.product_code = opts.productCode;
+        }
+        await runProductDataView('kit-materials', filters, opts, cmd);
+    });
+    attachSharedShortcutOptions(parent
+        .command('+phone-head-inventory')
+        .description('机头库存：机头良品、内存、颜色与库存部门（phone-head-inventory）')
+        .option('--product-name <name>', '商品名称包含')
+        .option('--department <name>', '部门包含')
+        .option('--page <n>', '页码，从 1 开始', '1')
+        .option('--page-size <n>', '每页行数，最大 1000')
+        .option('--limit <n>', '返回行数', '100')
+        .option('--filters-json <json>', '合并高级过滤 JSON；支持 @file')).action(async (opts, cmd) => {
+        const filters = {};
+        if (opts.productName) {
+            filters.product_name = opts.productName;
+        }
+        if (opts.department) {
+            filters.department = opts.department;
+        }
+        await runProductDataView('phone-head-inventory', filters, opts, cmd);
+    });
+}

package/dist/packages/vps-work/src/commands/product/index.js

@@ -0,0 +1,11 @@
+import { Command } from 'commander';
+import { attachProductAbnormalStatisticsShortcuts } from './abnormal-statistics.js';
+import { attachProductDataViewShortcuts } from './data-view-shortcuts.js';
+/** Features · 产品与供应链 — `vps-work product +…`（库存、价格、发货、异常设备等）。 */
+export function buildProductCommand() {
+    const product = new Command('product')
+        .description('Product shortcuts: inventory, VSN inventory, price, delivery, materials and abnormal devices。');
+    attachProductDataViewShortcuts(product);
+    attachProductAbnormalStatisticsShortcuts(product);
+    return product;
+}

package/dist/packages/vps-work/src/commands/purchase/index.js

@@ -0,0 +1,45 @@
+import { Command } from 'commander';
+import { attachSharedShortcutOptions, mergeShortcutParams, isValidateOnly, resolveShortcutVpsServiceUrl } from '../shortcut-common.js';
+import { executeVpsServiceScript } from '../../core/sales-query-client.js';
+export function buildPurchaseCommand() {
+    const parent = new Command('purchase').description('采购申请、采购订单及明细只读查询（独立权限）');
+    for (const [name, script, operation, description] of [
+        ['+requests', 'requests', 'list', 'VPS 采购申请列表'],
+        ['+request-detail', 'requests', 'detail', 'VPS 采购申请详情（含明细）'],
+        ['+request-lines', 'requests', 'lines', 'VPS 采购申请明细分页'],
+        ['+orders', 'orders', 'list', 'ERP 采购订单列表'],
+        ['+order-detail', 'orders', 'detail', 'ERP 采购订单详情'],
+        ['+order-lines', 'orders', 'lines', 'ERP 采购订单明细分页'],
+    ]) {
+        const cmd = parent.command(name).description(description).option('--document-number <number>', '完整单号，精确匹配');
+        if (operation === 'list')
+            cmd.option('--status <status>', '来源系统状态')
+                .option('--keyword <text>', '单号、申请事由或供应商关键词')
+                .option('--company-id <id>', '公司 ID').option('--start-date <YYYY-MM-DD>', '起始日期（上海时区，包含）')
+                .option('--end-date <YYYY-MM-DD>', '结束日期（上海时区，包含）');
+        else
+            cmd.option('--id <id>', script === 'requests' ? 'VPS 采购申请 UUID（与完整单号二选一）' : 'ERP 采购订单整数 ID（与完整单号二选一）');
+        if (operation !== 'detail')
+            cmd.option('--limit <n>', '每页条数，1–100').option('--offset <n>', '分页偏移');
+        attachSharedShortcutOptions(cmd).action(async (opts, command) => {
+            const params = { operation };
+            for (const [key, value] of Object.entries({
+                [script === 'requests' ? 'submission_id' : 'id']: opts.id,
+                document_number: opts.documentNumber, status: opts.status, keyword: opts.keyword, company_id: opts.companyId,
+                start_date: opts.startDate, end_date: opts.endDate, limit: opts.limit, offset: opts.offset,
+            }))
+                if (value !== undefined)
+                    params[key] = value;
+            // New catalog-native skills must bypass the legacy Odoo shortcut allowlist.
+            const payload = await mergeShortcutParams(params, opts);
+            const baseUrl = resolveShortcutVpsServiceUrl(opts, command);
+            if (isValidateOnly(opts)) {
+                console.log(JSON.stringify({ validateOnly: true, source: 'vps-service-execute', endpoint: `${baseUrl}/v1/execute`, skill_key: 'vps-purchase', script_key: script, params: payload }, null, 2));
+                return;
+            }
+            const result = await executeVpsServiceScript('vps-purchase', script, payload, baseUrl);
+            console.log(typeof result === 'string' && opts.json === false ? result : JSON.stringify(result, null, 2));
+        });
+    }
+    return parent;
+}