vps-work 2.5.0 → 2.5.1

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

@@ -0,0 +1,519 @@
+import { VertuError } from '../../core/errors.js';
+import { runVpsServiceDataView, vpsServiceGet } from '../../core/sales-query-client.js';
+import { attachSharedShortcutOptions, mergeShortcutParams, parseOptionalInt, resolveShortcutVpsServiceUrl, } from '../shortcut-common.js';
+const HR_PERSONNEL_VIEW = 'hr-personnel-directory';
+export function applyHrDirectoryScope(filters, includeNonDirectory = false) {
+    if (includeNonDirectory) {
+        return { ...filters };
+    }
+    return { ...filters, directory_visible: true };
+}
+export function assertHrDirectoryScopeApplied(result, includeNonDirectory = false) {
+    if (includeNonDirectory) {
+        return;
+    }
+    const resultRecord = asRecord(result);
+    const scope = asRecord(resultRecord?.scope);
+    if (scope?.contacts_directory === true) {
+        return;
+    }
+    throw new VertuError('当前 vps-service 尚未应用通讯录人员口径，已拒绝返回可能错误的 HR 结果。请先部署包含 directory_visible 支持的 vps-service。');
+}
+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 outputRows(value) {
+    const record = asRecord(value);
+    const rows = record ? record.rows : undefined;
+    return Array.isArray(rows)
+        ? rows.filter((row) => asRecord(row) !== null)
+        : [];
+}
+function isValidateOnly(opts) {
+    return opts.validateOnly === true || opts.dryRun === true;
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function numberValue(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim()) {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function findIdentityRecord(payload) {
+    const queue = [payload];
+    const seen = new Set();
+    while (queue.length) {
+        const current = queue.shift();
+        if (!current || seen.has(current)) {
+            continue;
+        }
+        seen.add(current);
+        const record = asRecord(current);
+        if (!record) {
+            continue;
+        }
+        if ('employee_id' in record ||
+            'employeeId' in record ||
+            'manager_id' in record ||
+            'managerEmployeeId' in record ||
+            'user_id' in record ||
+            'employee' in record ||
+            'manager' in record) {
+            return record;
+        }
+        for (const key of ['result', 'data', 'payload', 'context', 'user', 'userinfo']) {
+            if (key in record) {
+                queue.push(record[key]);
+            }
+        }
+    }
+    return {};
+}
+export function extractHrIdentity(payload) {
+    const record = findIdentityRecord(payload);
+    const employee = asRecord(record.employee);
+    const manager = asRecord(record.manager);
+    return {
+        employeeId: numberValue(record.employee_id) ??
+            numberValue(record.employeeId) ??
+            numberValue(employee?.id),
+        employeeName: stringValue(record.employee_name) ??
+            stringValue(record.employeeName) ??
+            stringValue(employee?.name) ??
+            stringValue(record.name),
+        managerEmployeeId: numberValue(record.manager_id) ??
+            numberValue(record.manager_employee_id) ??
+            numberValue(record.managerEmployeeId) ??
+            numberValue(manager?.id),
+        managerName: stringValue(record.manager_name) ??
+            stringValue(record.managerName) ??
+            stringValue(manager?.name),
+        managerUserId: numberValue(record.manager_user_id) ??
+            numberValue(record.managerUserId) ??
+            numberValue(manager?.user_id) ??
+            numberValue(manager?.userId),
+    };
+}
+async function fetchCurrentHrIdentity(opts, cmd) {
+    const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+    const payload = await vpsServiceGet('/v1/auth/me', {}, serviceBaseUrl, 'Vertu 身份');
+    return extractHrIdentity(payload);
+}
+function requireEmployeeId(identity, purpose) {
+    if (!identity.employeeId) {
+        throw new VertuError(`当前登录用户没有 employee_id，无法查询${purpose}。请先执行 \`vps-work hr +me\` 核对身份。`);
+    }
+    return identity.employeeId;
+}
+function addPersonnelOptions(cmd, limitDefault = '100') {
+    return addDirectoryScopeOption(cmd)
+        .option('--name <name>', '姓名包含')
+        .option('--barcode <code>', '工号包含')
+        .option('--employee-id <id>', 'hr.employee id')
+        .option('--user-id <id>', 'res.users id')
+        .option('--manager-employee-id <id>', '直属上级 hr.employee id')
+        .option('--manager-user-id <id>', '直属上级 res.users id')
+        .option('--manager-name <name>', '直属上级姓名包含')
+        .option('--status <name>', '在职状态包含')
+        .option('--department <name>', '当前部门包含')
+        .option('--department-l1 <name>', '一级部门包含')
+        .option('--department-l2 <name>', '二级部门包含')
+        .option('--job <name>', '工作岗位包含')
+        .option('--job-name <name>', '职位档案名称包含')
+        .option('--contract-status <status>', '合同状态包含')
+        .option('--limit <n>', '返回行数', limitDefault);
+}
+function addDirectoryScopeOption(cmd) {
+    return cmd.option('--include-non-directory', '包含授权部门内通讯录不可见人员（需要 hr.profile.history:read）', false);
+}
+function addNumberFilter(filters, key, raw, flag) {
+    const value = parseOptionalInt(raw, flag);
+    if (value !== undefined) {
+        filters[key] = value;
+    }
+}
+function buildPersonnelFilters(opts) {
+    const filters = {};
+    addNumberFilter(filters, 'employee_id', opts.employeeId, '--employee-id');
+    addNumberFilter(filters, 'user_id', opts.userId, '--user-id');
+    addNumberFilter(filters, 'manager_employee_id', opts.managerEmployeeId, '--manager-employee-id');
+    addNumberFilter(filters, 'manager_user_id', opts.managerUserId, '--manager-user-id');
+    if (opts.name) {
+        filters.name = opts.name;
+    }
+    if (opts.barcode) {
+        filters.barcode = opts.barcode;
+    }
+    if (opts.managerName) {
+        filters.manager_name = opts.managerName;
+    }
+    if (opts.status) {
+        filters.status = opts.status;
+    }
+    if (opts.department) {
+        filters.department = opts.department;
+    }
+    if (opts.departmentL1) {
+        filters.department_l1 = opts.departmentL1;
+    }
+    if (opts.departmentL2) {
+        filters.department_l2 = opts.departmentL2;
+    }
+    if (opts.job) {
+        filters.job = opts.job;
+    }
+    if (opts.jobName) {
+        filters.job_name = opts.jobName;
+    }
+    if (opts.contractStatus) {
+        filters.contract_status = opts.contractStatus;
+    }
+    return filters;
+}
+function hasPersonTarget(opts) {
+    return Boolean(opts.name ||
+        opts.barcode ||
+        opts.employeeId ||
+        opts.userId ||
+        opts.managerEmployeeId ||
+        opts.managerUserId ||
+        opts.managerName ||
+        opts.department ||
+        opts.departmentL1 ||
+        opts.departmentL2 ||
+        opts.job ||
+        opts.jobName);
+}
+async function runHrPersonnelView(opts, cmd, filters, limitDefault) {
+    const merged = applyHrDirectoryScope(await mergeShortcutParams(filters, opts), opts.includeNonDirectory);
+    const limit = parseOptionalInt(opts.limit, '--limit') ?? limitDefault;
+    const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+    if (isValidateOnly(opts)) {
+        printResult(opts, {
+            validateOnly: true,
+            endpoint: `${serviceBaseUrl}/v1/data-view/query`,
+            payload: {
+                view_id: HR_PERSONNEL_VIEW,
+                filters: merged,
+                limit,
+            },
+        });
+        return;
+    }
+    const result = await runVpsServiceDataView(HR_PERSONNEL_VIEW, merged, limit, serviceBaseUrl);
+    assertHrDirectoryScopeApplied(result, opts.includeNonDirectory);
+    printResult(opts, result);
+}
+function dataViewRows(value) {
+    return outputRows(value);
+}
+export function dataViewTotalRows(value) {
+    const record = asRecord(value);
+    const pagination = asRecord(record?.pagination);
+    return numberValue(pagination?.total_rows) ?? 0;
+}
+function addHeadcountOptions(cmd) {
+    return addDirectoryScopeOption(cmd)
+        .option('--department <name>', '当前部门包含')
+        .option('--department-l1 <name>', '一级部门包含')
+        .option('--department-l2 <name>', '二级部门包含')
+        .option('--manager-employee-id <id>', '直属上级 hr.employee id')
+        .option('--manager-user-id <id>', '直属上级 res.users id')
+        .option('--manager-name <name>', '直属上级姓名包含')
+        .option('--job <name>', '工作岗位包含')
+        .option('--job-name <name>', '职位档案名称包含');
+}
+function buildHeadcountBaseFilters(opts) {
+    const filters = {};
+    addNumberFilter(filters, 'manager_employee_id', opts.managerEmployeeId, '--manager-employee-id');
+    addNumberFilter(filters, 'manager_user_id', opts.managerUserId, '--manager-user-id');
+    if (opts.managerName) {
+        filters.manager_name = opts.managerName;
+    }
+    if (opts.department) {
+        filters.department = opts.department;
+    }
+    if (opts.departmentL1) {
+        filters.department_l1 = opts.departmentL1;
+    }
+    if (opts.departmentL2) {
+        filters.department_l2 = opts.departmentL2;
+    }
+    if (opts.job) {
+        filters.job = opts.job;
+    }
+    if (opts.jobName) {
+        filters.job_name = opts.jobName;
+    }
+    return filters;
+}
+async function countPersonnelRows(serviceBaseUrl, filters, includeNonDirectory) {
+    const result = await runVpsServiceDataView(HR_PERSONNEL_VIEW, filters, 1, serviceBaseUrl);
+    assertHrDirectoryScopeApplied(result, includeNonDirectory);
+    return dataViewTotalRows(result);
+}
+async function runHeadcount(opts, cmd) {
+    const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+    const baseFilters = applyHrDirectoryScope(await mergeShortcutParams(buildHeadcountBaseFilters(opts), opts), opts.includeNonDirectory);
+    const endpoint = `${serviceBaseUrl}/v1/data-view/query`;
+    const countPlan = [
+        ['total', baseFilters],
+        ['active', { ...baseFilters, status: '在职' }],
+        ['departed', { ...baseFilters, status: '离职' }],
+        ['external_excluded', { ...baseFilters, status: '外部' }],
+        ['active_regular', { ...baseFilters, status: '在职-正式员工' }],
+        ['active_probation', { ...baseFilters, status: '在职-试用期员工' }],
+        ['active_part_time', { ...baseFilters, status: '在职-兼职员工' }],
+        ['active_intern', { ...baseFilters, status: '在职-实习生' }],
+    ];
+    if (isValidateOnly(opts)) {
+        printResult(opts, {
+            validateOnly: true,
+            endpoint,
+            requests: countPlan.map(([key, filters]) => ({
+                key,
+                payload: {
+                    view_id: HR_PERSONNEL_VIEW,
+                    filters,
+                    limit: 1,
+                },
+            })),
+        });
+        return;
+    }
+    const counts = Object.fromEntries(await Promise.all(countPlan.map(async ([key, filters]) => [
+        key,
+        await countPersonnelRows(serviceBaseUrl, filters, opts.includeNonDirectory === true),
+    ])));
+    const knownActiveBreakdown = counts.active_regular +
+        counts.active_probation +
+        counts.active_part_time +
+        counts.active_intern;
+    printResult(opts, {
+        view_id: HR_PERSONNEL_VIEW,
+        scope: opts.includeNonDirectory ? 'all_hr_personnel' : 'contacts',
+        filters: baseFilters,
+        summary: {
+            total_personnel_records: counts.total,
+            active_headcount: counts.active,
+            departed_records: counts.departed,
+            external_excluded: counts.external_excluded,
+            company_headcount: counts.active,
+        },
+        active_breakdown: {
+            regular: counts.active_regular,
+            probation: counts.active_probation,
+            part_time: counts.active_part_time,
+            intern: counts.active_intern,
+            other_active: Math.max(0, counts.active - knownActiveBreakdown),
+        },
+        note: opts.includeNonDirectory
+            ? '当前为完整 HR 档案口径；total_personnel_records 包含离职与外部不计人数档案。'
+            : '默认与通讯录可见人员口径一致；使用 --include-non-directory 查看完整 HR 档案。',
+    });
+}
+async function resolveCurrentManagerEmployeeId(identity, opts, cmd) {
+    if (identity.managerEmployeeId) {
+        return identity.managerEmployeeId;
+    }
+    const employeeId = requireEmployeeId(identity, '直属上司');
+    const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+    const result = await runVpsServiceDataView(HR_PERSONNEL_VIEW, applyHrDirectoryScope({ employee_id: employeeId }, opts.includeNonDirectory), 1, serviceBaseUrl);
+    assertHrDirectoryScopeApplied(result, opts.includeNonDirectory);
+    const managerEmployeeId = numberValue(dataViewRows(result)[0]?.manager_employee_id);
+    if (!managerEmployeeId) {
+        throw new VertuError('当前登录用户没有 manager_employee_id，无法查询直属上司。');
+    }
+    return managerEmployeeId;
+}
+function parseMaxDepth(raw) {
+    const value = parseOptionalInt(raw, '--max-depth') ?? 20;
+    if (value < 1) {
+        throw new VertuError('--max-depth must be >= 1.');
+    }
+    return Math.min(value, 50);
+}
+function resultEnvelope(firstResult, rows) {
+    const first = asRecord(firstResult) ?? {};
+    return {
+        view: first.view,
+        columns: Array.isArray(first.columns)
+            ? ['level', 'manager_chain_text', ...first.columns.filter((column) => column !== 'level' && column !== 'manager_chain_text')]
+            : undefined,
+        rows,
+        pagination: {
+            page: 1,
+            page_size: rows.length,
+            offset: 0,
+            returned_rows: rows.length,
+            total_rows: rows.length,
+            total_pages: 1,
+            has_more: false,
+            next_page: null,
+        },
+    };
+}
+async function runRecursiveSubordinates(opts, cmd, identity) {
+    const rootEmployeeId = requireEmployeeId(identity, '下属');
+    const status = opts.status;
+    const limit = parseOptionalInt(opts.limit, '--limit') ?? 100;
+    const maxDepth = parseMaxDepth(opts.maxDepth);
+    const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+    if (isValidateOnly(opts)) {
+        const filters = { manager_employee_id: rootEmployeeId };
+        if (status) {
+            filters.status = status;
+        }
+        printResult(opts, {
+            validateOnly: true,
+            recursive: true,
+            root_manager_employee_id: rootEmployeeId,
+            max_depth: maxDepth,
+            endpoint: `${serviceBaseUrl}/v1/data-view/query`,
+            first_payload: {
+                view_id: HR_PERSONNEL_VIEW,
+                filters,
+                limit,
+            },
+        });
+        return;
+    }
+    const rows = [];
+    const seenEmployees = new Set();
+    let frontier = [
+        {
+            managerEmployeeId: rootEmployeeId,
+            level: 1,
+            managerChain: [identity.employeeName ?? `employee:${rootEmployeeId}`],
+        },
+    ];
+    let firstResult = null;
+    while (frontier.length && rows.length < limit) {
+        const next = [];
+        for (const item of frontier) {
+            if (item.level > maxDepth || rows.length >= limit) {
+                continue;
+            }
+            const filters = { manager_employee_id: item.managerEmployeeId };
+            if (status) {
+                filters.status = status;
+            }
+            const remaining = Math.max(1, limit - rows.length);
+            const result = await runVpsServiceDataView(HR_PERSONNEL_VIEW, applyHrDirectoryScope(filters, opts.includeNonDirectory), remaining, serviceBaseUrl);
+            assertHrDirectoryScopeApplied(result, opts.includeNonDirectory);
+            if (!firstResult) {
+                firstResult = result;
+            }
+            for (const row of dataViewRows(result)) {
+                const employeeId = numberValue(row.employee_id);
+                if (!employeeId || seenEmployees.has(employeeId)) {
+                    continue;
+                }
+                seenEmployees.add(employeeId);
+                const name = stringValue(row.name) ?? `employee:${employeeId}`;
+                const chain = [...item.managerChain, name];
+                rows.push({
+                    level: item.level,
+                    manager_chain: item.managerChain,
+                    manager_chain_text: item.managerChain.join(' / '),
+                    ...row,
+                });
+                if (rows.length >= limit) {
+                    break;
+                }
+                next.push({
+                    managerEmployeeId: employeeId,
+                    level: item.level + 1,
+                    managerChain: chain,
+                });
+            }
+        }
+        frontier = next;
+    }
+    printResult(opts, firstResult ? resultEnvelope(firstResult, rows) : resultEnvelope({}, rows));
+}
+export function attachHrDataViewShortcuts(parent) {
+    attachSharedShortcutOptions(addPersonnelOptions(parent
+        .command('+personnel-info')
+        .description('HR人员信息（默认通讯录内部在职口径，排除外部与离职人员）'))).action(async (opts, cmd) => {
+        await runHrPersonnelView(opts, cmd, buildPersonnelFilters(opts), 100);
+    });
+    attachSharedShortcutOptions(addHeadcountOptions(parent
+        .command('+headcount')
+        .description('人事人数统计（服务端 count，不拉人员明细）'))).action(async (opts, cmd) => {
+        await runHeadcount(opts, cmd);
+    });
+    attachSharedShortcutOptions(addDirectoryScopeOption(parent
+        .command('+profile')
+        .description('我的人事档案（部门、岗位、上级、入职、工龄、合同）')
+        .option('--limit <n>', '返回行数', '5'))).action(async (opts, cmd) => {
+        const identity = await fetchCurrentHrIdentity(opts, cmd);
+        await runHrPersonnelView(opts, cmd, { employee_id: requireEmployeeId(identity, '本人档案') }, 5);
+    });
+    attachSharedShortcutOptions(addDirectoryScopeOption(parent
+        .command('+tenure')
+        .description('我的工龄与入职/转正/离职信息')
+        .option('--limit <n>', '返回行数', '5'))).action(async (opts, cmd) => {
+        const identity = await fetchCurrentHrIdentity(opts, cmd);
+        await runHrPersonnelView(opts, cmd, { employee_id: requireEmployeeId(identity, '工龄') }, 5);
+    });
+    attachSharedShortcutOptions(addDirectoryScopeOption(parent
+        .command('+manager')
+        .description('我的直属上司档案')
+        .option('--limit <n>', '返回行数', '5'))).action(async (opts, cmd) => {
+        const identity = await fetchCurrentHrIdentity(opts, cmd);
+        const managerEmployeeId = await resolveCurrentManagerEmployeeId(identity, opts, cmd);
+        await runHrPersonnelView(opts, cmd, { employee_id: managerEmployeeId }, 5);
+    });
+    attachSharedShortcutOptions(addDirectoryScopeOption(parent
+        .command('+subordinates')
+        .description('我的下属（默认递归到最深层；--direct 仅直属）')
+        .option('--status <name>', '在职状态包含', '在职')
+        .option('--direct', '仅查询直属下属', false)
+        .option('--max-depth <n>', '递归最大层级（默认 20）')
+        .option('--limit <n>', '返回行数', '100'))).action(async (opts, cmd) => {
+        const identity = await fetchCurrentHrIdentity(opts, cmd);
+        if (!opts.direct) {
+            await runRecursiveSubordinates(opts, cmd, identity);
+            return;
+        }
+        const filters = {
+            manager_employee_id: requireEmployeeId(identity, '直属下属'),
+        };
+        if (opts.status) {
+            filters.status = opts.status;
+        }
+        await runHrPersonnelView(opts, cmd, filters, 100);
+    });
+    attachSharedShortcutOptions(addPersonnelOptions(parent
+        .command('+job-details')
+        .description('岗位明细（按姓名、部门、岗位、上级等过滤）'))).action(async (opts, cmd) => {
+        await runHrPersonnelView(opts, cmd, buildPersonnelFilters(opts), 100);
+    });
+    attachSharedShortcutOptions(addPersonnelOptions(parent
+        .command('+contracts')
+        .description('合同信息（本人可查；查询授权范围内他人需要 hr.profile.contract:read）')
+        .option('--all', '不默认限定本人，但不能扩大服务端授权人员范围', false))).action(async (opts, cmd) => {
+        const filters = buildPersonnelFilters(opts);
+        if (!opts.all && !hasPersonTarget(opts)) {
+            const identity = await fetchCurrentHrIdentity(opts, cmd);
+            filters.employee_id = requireEmployeeId(identity, '合同');
+        }
+        await runHrPersonnelView(opts, cmd, filters, 100);
+    });
+}

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

@@ -0,0 +1,15 @@
+import { Command } from 'commander';
+import { attachHrDataViewShortcuts } from './data-view-shortcuts.js';
+import { attachHrShortcuts } from './shortcuts.js';
+import { attachJobResponsibilitiesShortcut } from './job-responsibilities.js';
+import { attachHrBusinessShortcuts } from './business.js';
+/** Features · 人力资源 — `vps-work hr +…`（身份、组织树、人员档案、岗位、上下级、合同、工资条） */
+export function buildHrCommand() {
+    const hr = new Command('hr')
+        .description('HR shortcuts: +me, +org-tree, +headcount, +profile, +manager, +subordinates, +job-details, +job-responsibilities, +contracts, +payslip, +personnel-info。');
+    attachHrShortcuts(hr);
+    attachHrDataViewShortcuts(hr);
+    attachJobResponsibilitiesShortcut(hr);
+    attachHrBusinessShortcuts(hr);
+    return hr;
+}