weaver-work-cli 0.1.2 → 0.1.5

package/dist/shortcuts/ehr/operations/attend-write.js

@@ -0,0 +1,514 @@
+import { createHash } from 'node:crypto';
+import { ehrConfirmationError, ehrPartialError, ehrValidationError, EhrCliError } from '../errors.js';
+import { READ, SCHEMA_DATE, SCHEMA_ID, ehrSuccess, schemaOf, WRITE, } from './types.js';
+import { assertEnum, assertEnumArray, compact, pickDefined, toIdList } from './shared.js';
+const CONTINUATION_TTL_SECONDS = 600;
+const CARD_TYPES = ['CHECKIN', 'CHECKOUT', 'LEAVE', 'RETURN', 'CHECKIN_AND_RETURN', 'CHECKOUT_AND_LEAVE'];
+const APPEAL_TYPES = [
+    'leave',
+    'overTime',
+    'businessTrip',
+    'respLeave',
+    'manualSignFlow',
+    'outSide',
+    'processChange',
+    'reissueCard',
+    'schedulingShift',
+    'substitute',
+];
+const HANDLE_RESULTS = ['APPROVE', 'REJECT', 'INVALID'];
+export const CARD_CHECK_NOTICE = [
+    '【考勤打卡说明】',
+    '- 若考勤打卡方式开启了“允许 PC 电脑端打卡”，可通过本技能进行签到、签退打卡；',
+    '- 若设置为只允许移动端打卡并开启了地图定位校验、WiFi 校验等，智能工具无法获取当前定位位置信息，无法完成考勤打卡，请使用 IM APP 移动端、移动端企业微信等移动端完成考勤打卡。',
+].join('\n');
+function fingerprint(value) {
+    return createHash('sha256').update(JSON.stringify(value ?? null)).digest('hex').slice(0, 32);
+}
+function requireConfirm(args, action) {
+    if (args.confirm !== true) {
+        throw ehrConfirmationError(action, { hint: '重新调用时传入 confirm=true 与 prepare 返回的 continuation' });
+    }
+}
+/** 校验 continuation 与当前登录上下文一致，避免切换租户/账号后误执行写操作。 */
+async function verifyLease(args, action, env) {
+    const lease = await env.continuation.verify(args.continuation, action);
+    const session = await env.host.getSession();
+    if (lease.baseUrl !== session.baseUrl || lease.profile !== session.profile || lease.userId !== session.userId) {
+        throw ehrValidationError('context_mismatch', '确认上下文已变化（租户或登录账号不同），请重新执行 prepare');
+    }
+    return lease;
+}
+function isNetworkError(error) {
+    return error instanceof EhrCliError && error.type === 'network';
+}
+const attendCardStatus = {
+    name: 'ehr.attend.card.status',
+    resource: 'attend',
+    method: 'card.status',
+    action: 'ehr.attend.card.status',
+    summary: '查询当前打卡按钮状态，返回 timecardStatus（CHECKIN 表示应打上班卡，CHECKOUT 表示应打下班卡）',
+    capability: 'attend',
+    risk: READ,
+    inputSchema: schemaOf({}),
+    handler: async (_args, { host }) => {
+        const response = await host.request({
+            method: 'POST',
+            path: '/api/attend/card/attendinfo/getAttendCheckButtonStatus',
+            body: {},
+        });
+        return ehrSuccess('ehr.attend.card.status', response?.data);
+    },
+};
+// ---------------------------------------------------------------------------
+// PC 端考勤打卡
+// ---------------------------------------------------------------------------
+const cardCheckSchema = {
+    type: {
+        type: 'string',
+        enum: [...CARD_TYPES],
+        description: 'CHECKIN 上班签到 / CHECKOUT 下班签退 / LEAVE 外出 / RETURN 返回 / CHECKIN_AND_RETURN 上班+返回 / CHECKOUT_AND_LEAVE 下班+外出',
+    },
+    addTime: { type: 'string', pattern: '^\\d{14}$', description: '格式 yyyyMMddHHmmss，仅租户开启多时区时生效' },
+};
+const ehrAttendCardCheckPrepare = {
+    name: 'ehr.attend.card.check.prepare',
+    resource: 'attend',
+    method: 'card.check.prepare',
+    action: 'ehr.attend.card.check.prepare',
+    summary: '准备 PC 端考勤打卡：校验打卡类型并生成确认预览，不发送打卡请求',
+    capability: 'attend',
+    risk: WRITE,
+    requiresConfirmation: true,
+    inputSchema: schemaOf({ ...cardCheckSchema }, { required: ['type'] }),
+    handler: async (args, { host, continuation }) => {
+        const type = assertEnum(args.type, CARD_TYPES, 'type');
+        const session = await host.getSession();
+        if (!session.userId || !session.eteamsId || !session.tenantKey) {
+            throw ehrValidationError('card_sign_unavailable', '无法构造打卡凭证：当前登录态缺少 empId、ETEAMSID 或 tenantKey，请重新登录后重试');
+        }
+        const preview = {
+            type,
+            attendSource: 'pc',
+            addTime: args.addTime,
+            empId: session.userId,
+            profile: session.profile,
+            baseUrl: session.baseUrl,
+            notice: CARD_CHECK_NOTICE,
+        };
+        const token = await continuation.issue({
+            operation: 'ehr.attend.card.check.apply',
+            baseUrl: session.baseUrl,
+            profile: session.profile,
+            userId: session.userId,
+            payload: { type, addTime: args.addTime },
+            fingerprint: fingerprint(preview),
+        }, CONTINUATION_TTL_SECONDS * 1000);
+        return ehrSuccess('ehr.attend.card.check.prepare', {
+            status: 'AWAITING_CONFIRMATION',
+            preview,
+            continuation: token,
+            expiresInSeconds: CONTINUATION_TTL_SECONDS,
+        });
+    },
+};
+const ehrAttendCardCheckApply = {
+    name: 'ehr.attend.card.check.apply',
+    resource: 'attend',
+    method: 'card.check.apply',
+    action: 'ehr.attend.card.check.apply',
+    summary: '执行 PC 端考勤打卡；必须在用户明确确认后调用，且要求 prepare 返回的 continuation',
+    capability: 'attend',
+    risk: WRITE,
+    requiresConfirmation: true,
+    inputSchema: schemaOf({
+        ...cardCheckSchema,
+        confirm: { const: true },
+        continuation: { type: 'string', minLength: 1 },
+    }, { required: ['type', 'confirm', 'continuation'] }),
+    handler: async (args, env) => {
+        requireConfirm(args, 'ehr.attend.card.check.apply');
+        const type = assertEnum(args.type, CARD_TYPES, 'type');
+        const lease = await verifyLease(args, 'ehr.attend.card.check.apply', env);
+        const payload = (lease.payload || {});
+        if (payload.type !== type) {
+            throw ehrValidationError('target_changed', '打卡类型与 prepare 时的快照不一致，请重新执行 prepare');
+        }
+        // 凭证在 apply 阶段按最新会话重新构造，避免 continuation 中携带可复用的签名材料。
+        const sign = await env.host.buildCardSign();
+        const session = await env.host.getSession();
+        const body = {
+            type,
+            sign,
+            // 必须显式声明 pc：否则服务端按 UA 判定来源，非浏览器 UA 会被判为非 PC 来源并在要求定位时直接失败。
+            attendSource: 'pc',
+        };
+        if (args.addTime !== undefined)
+            body.addTime = args.addTime;
+        let response;
+        try {
+            response = await env.host.request({
+                method: 'POST',
+                path: '/api/attend/card/attendinfo/check',
+                query: { ETEAMSID: session.eteamsId },
+                body,
+            });
+        }
+        catch (error) {
+            if (isNetworkError(error)) {
+                throw ehrPartialError('打卡请求发送后连接中断，是否打卡成功不确定，禁止自动重试，请通过 ehr.attend.card.status 或打卡记录复核', { attempted: { type } }, { stage: 'card.check' });
+            }
+            throw error;
+        }
+        return ehrSuccess('ehr.attend.card.check.apply', {
+            status: 'COMPLETE',
+            result: response?.data,
+            message: response?.data?.message,
+            notice: CARD_CHECK_NOTICE,
+        });
+    },
+};
+// ---------------------------------------------------------------------------
+// 创建申诉
+// ---------------------------------------------------------------------------
+const appealItemSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        appealType: { type: 'string', enum: [...APPEAL_TYPES] },
+        checkin: { type: 'string', pattern: '^\\d{2}:\\d{2}$' },
+        checkout: { type: 'string', pattern: '^\\d{2}:\\d{2}$' },
+        vacation: { type: 'string' },
+        nextday: { type: 'boolean' },
+    },
+    required: ['appealType'],
+};
+const appealSaveSchema = {
+    attendDay: { type: 'string', pattern: '^\\d{8}$', description: '考勤日期，格式 yyyyMMdd，注意不是 yyyy-MM-dd' },
+    periodId: { oneOf: [{ type: 'integer' }, { type: 'string', minLength: 1 }] },
+    attendInfoKey: { type: 'string', minLength: 1 },
+    appeals: { type: 'array', items: appealItemSchema, minItems: 1 },
+    appealDesc: { type: 'string' },
+    timecardId: { oneOf: [{ type: 'integer' }, { type: 'string' }] },
+    attendStatus: { type: 'string' },
+    nextDayVal: { type: 'boolean' },
+    appealId: { type: 'string' },
+    userId: { oneOf: [{ type: 'integer', minimum: 1 }, { type: 'string', minLength: 1 }] },
+};
+function validateAppeals(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw ehrValidationError('appeals_required', 'appeals 必填且至少包含一项');
+    }
+    return value.map((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            throw ehrValidationError('appeal_item_invalid', `appeals[${index}] 必须是对象`);
+        }
+        const record = item;
+        return {
+            appealType: assertEnum(record.appealType, APPEAL_TYPES, `appeals[${index}].appealType`),
+            ...pickDefined(record, ['checkin', 'checkout', 'vacation', 'nextday']),
+        };
+    });
+}
+const ehrAttendAppealSavePrepare = {
+    name: 'ehr.attend.appeal.save.prepare',
+    resource: 'attend',
+    method: 'appeal.save.prepare',
+    action: 'ehr.attend.appeal.save.prepare',
+    summary: '准备创建考勤申诉：校验参数（传 userId 时先校验可申诉状态）并生成确认预览，不提交申诉',
+    capability: 'attend',
+    risk: WRITE,
+    requiresConfirmation: true,
+    inputSchema: schemaOf({ ...appealSaveSchema }, { required: ['attendDay', 'periodId', 'attendInfoKey', 'appeals'] }),
+    handler: async (args, { host, continuation }) => {
+        const appeals = validateAppeals(args.appeals);
+        let appealable;
+        let appealformIds;
+        if (args.userId !== undefined) {
+            const gate = await host.request({
+                method: 'GET',
+                path: '/api/attend/web/attendinfo/getAppealformId',
+                query: { userId: String(args.userId) },
+            });
+            const gateData = gate?.data || {};
+            appealable = gateData.stillShowAppeal === true;
+            appealformIds = gateData.appealformIds;
+            if (!appealable) {
+                throw ehrValidationError('appeal_not_allowed', '当前不可申诉（stillShowAppeal=false），不要继续提交申诉', {
+                    appealformIds,
+                });
+            }
+        }
+        const preview = {
+            attendDay: args.attendDay,
+            periodId: String(args.periodId),
+            attendInfoKey: args.attendInfoKey,
+            appeals,
+            appealDesc: args.appealDesc,
+            timecardId: args.timecardId !== undefined ? String(args.timecardId) : undefined,
+            attendStatus: args.attendStatus,
+            nextDayVal: args.nextDayVal,
+            appealable,
+        };
+        const session = await host.getSession();
+        const token = await continuation.issue({
+            operation: 'ehr.attend.appeal.save.apply',
+            baseUrl: session.baseUrl,
+            profile: session.profile,
+            userId: session.userId,
+            payload: { ...preview },
+            fingerprint: fingerprint(preview),
+        }, CONTINUATION_TTL_SECONDS * 1000);
+        return ehrSuccess('ehr.attend.appeal.save.prepare', {
+            status: 'AWAITING_CONFIRMATION',
+            preview,
+            continuation: token,
+            expiresInSeconds: CONTINUATION_TTL_SECONDS,
+        });
+    },
+};
+const ehrAttendAppealSaveApply = {
+    name: 'ehr.attend.appeal.save.apply',
+    resource: 'attend',
+    method: 'appeal.save.apply',
+    action: 'ehr.attend.appeal.save.apply',
+    summary: '提交考勤申诉；会生成审批流程，必须在用户明确确认后调用',
+    capability: 'attend',
+    risk: WRITE,
+    requiresConfirmation: true,
+    inputSchema: schemaOf({
+        ...appealSaveSchema,
+        userId: undefined,
+        confirm: { const: true },
+        continuation: { type: 'string', minLength: 1 },
+    }, { required: ['attendDay', 'periodId', 'attendInfoKey', 'appeals', 'confirm', 'continuation'] }),
+    handler: async (args, env) => {
+        requireConfirm(args, 'ehr.attend.appeal.save.apply');
+        const appeals = validateAppeals(args.appeals);
+        const lease = await verifyLease(args, 'ehr.attend.appeal.save.apply', env);
+        const payload = (lease.payload || {});
+        // 申诉目标一旦变化（日期/时段/理由），继续提交会写错对象，必须重新确认。
+        for (const key of ['attendDay', 'periodId', 'attendInfoKey', 'appealDesc']) {
+            if (String(payload[key] ?? '') !== String(args[key] ?? '')) {
+                throw ehrValidationError('target_changed', `申诉参数 ${key} 与 prepare 时的快照不一致，请重新执行 prepare`);
+            }
+        }
+        const body = {
+            attendDay: args.attendDay,
+            periodId: String(args.periodId),
+            attendInfoKey: args.attendInfoKey,
+            appeals,
+            ...pickDefined(args, ['appealDesc', 'attendStatus', 'nextDayVal', 'appealId']),
+        };
+        if (args.timecardId !== undefined)
+            body.timecardId = String(args.timecardId);
+        let response;
+        try {
+            response = await env.host.request({
+                method: 'POST',
+                path: '/api/attend/web/attendinfo/saveAttendAppealInfo',
+                body: compact(body),
+            });
+        }
+        catch (error) {
+            if (isNetworkError(error)) {
+                throw ehrPartialError('申诉提交请求发送后连接中断，是否已提交不确定，禁止自动重试，请通过 ehr.attend.appeal.list 复核', { attempted: { attendDay: args.attendDay, periodId: args.periodId } }, { stage: 'appeal.save' });
+            }
+            throw error;
+        }
+        return ehrSuccess('ehr.attend.appeal.save.apply', {
+            status: 'COMPLETE',
+            result: response?.data,
+            verifyHint: '可通过 ehr.attend.appeal.list 回查申诉是否已生成',
+        });
+    },
+};
+// ---------------------------------------------------------------------------
+// 处理申诉
+// ---------------------------------------------------------------------------
+const appealResultSchema = {
+    id: { type: 'string', pattern: '^\\d+$', description: '申诉记录 ID，来自 appeal.list' },
+    handleResult: { type: 'string', enum: [...HANDLE_RESULTS] },
+    suggestion: { type: 'string', maxLength: 500 },
+};
+const ehrAttendAppealResultPrepare = {
+    name: 'ehr.attend.appeal.result.prepare',
+    resource: 'attend',
+    method: 'appeal.result.prepare',
+    action: 'ehr.attend.appeal.result.prepare',
+    summary: '准备处理申诉（通过/退回/无效）：生成确认预览，不提交处理',
+    capability: 'attend',
+    risk: WRITE,
+    requiresConfirmation: true,
+    inputSchema: schemaOf({ ...appealResultSchema }, { required: ['id', 'handleResult'] }),
+    handler: async (args, { host, continuation }) => {
+        const handleResult = assertEnum(args.handleResult, HANDLE_RESULTS, 'handleResult');
+        const preview = {
+            id: String(args.id),
+            handleResult,
+            suggestion: args.suggestion,
+        };
+        const session = await host.getSession();
+        const token = await continuation.issue({
+            operation: 'ehr.attend.appeal.result.apply',
+            baseUrl: session.baseUrl,
+            profile: session.profile,
+            userId: session.userId,
+            payload: preview,
+            fingerprint: fingerprint(preview),
+        }, CONTINUATION_TTL_SECONDS * 1000);
+        return ehrSuccess('ehr.attend.appeal.result.prepare', {
+            status: 'AWAITING_CONFIRMATION',
+            preview,
+            continuation: token,
+            expiresInSeconds: CONTINUATION_TTL_SECONDS,
+        });
+    },
+};
+const ehrAttendAppealResultApply = {
+    name: 'ehr.attend.appeal.result.apply',
+    resource: 'attend',
+    method: 'appeal.result.apply',
+    action: 'ehr.attend.appeal.result.apply',
+    summary: '提交申诉处理结果；不可逆转，必须在用户明确确认后调用',
+    capability: 'attend',
+    risk: WRITE,
+    requiresConfirmation: true,
+    inputSchema: schemaOf({ ...appealResultSchema, confirm: { const: true }, continuation: { type: 'string', minLength: 1 } }, { required: ['id', 'handleResult', 'confirm', 'continuation'] }),
+    handler: async (args, env) => {
+        requireConfirm(args, 'ehr.attend.appeal.result.apply');
+        const handleResult = assertEnum(args.handleResult, HANDLE_RESULTS, 'handleResult');
+        const lease = await verifyLease(args, 'ehr.attend.appeal.result.apply', env);
+        const payload = (lease.payload || {});
+        if (String(payload.id ?? '') !== String(args.id) || payload.handleResult !== handleResult) {
+            throw ehrValidationError('target_changed', '申诉目标或处理结果与 prepare 时的快照不一致，请重新执行 prepare');
+        }
+        const body = {
+            id: Number(args.id),
+            handleResult,
+        };
+        if (args.suggestion !== undefined)
+            body.suggestion = args.suggestion;
+        let response;
+        try {
+            response = await env.host.request({
+                method: 'POST',
+                path: '/api/attend/web/appeal/updateResult',
+                body,
+            });
+        }
+        catch (error) {
+            if (isNetworkError(error)) {
+                throw ehrPartialError('申诉处理请求发送后连接中断，是否已处理不确定，禁止自动重试，请通过 ehr.attend.appeal.list 复核', { attempted: { id: args.id, handleResult } }, { stage: 'appeal.result' });
+            }
+            throw error;
+        }
+        return ehrSuccess('ehr.attend.appeal.result.apply', {
+            status: 'COMPLETE',
+            result: response?.data,
+            verifyHint: '可通过 ehr.attend.appeal.list 回查处理结果',
+        });
+    },
+};
+// ---------------------------------------------------------------------------
+// 报表重算
+// ---------------------------------------------------------------------------
+const recalcSchema = {
+    beginDate: SCHEMA_DATE,
+    endDate: SCHEMA_DATE,
+    onlyEmpIds: { type: 'array', items: SCHEMA_ID, description: '限定重算的人员 ID；不传则重算全部' },
+};
+const ehrAttendReportRecalcPrepare = {
+    name: 'ehr.attend.report.recalc.prepare',
+    resource: 'attend',
+    method: 'report.recalc.prepare',
+    action: 'ehr.attend.report.recalc.prepare',
+    summary: '准备考勤报表重算：校验日期范围与人员范围并生成确认预览，不触发重算',
+    capability: 'attend',
+    risk: WRITE,
+    requiresConfirmation: true,
+    inputSchema: schemaOf({ ...recalcSchema }, { required: ['beginDate', 'endDate'] }),
+    handler: async (args, { host, continuation }) => {
+        const { beginDate, endDate } = args;
+        if (beginDate > endDate) {
+            throw ehrValidationError('date_range_invalid', 'beginDate 不得晚于 endDate');
+        }
+        const onlyEmpIds = toIdList(args.onlyEmpIds, 'onlyEmpIds');
+        const preview = {
+            beginDate,
+            endDate,
+            onlyEmpIds,
+            scope: onlyEmpIds?.length ? `指定 ${onlyEmpIds.length} 人` : '全部人员',
+        };
+        const session = await host.getSession();
+        const token = await continuation.issue({
+            operation: 'ehr.attend.report.recalc.apply',
+            baseUrl: session.baseUrl,
+            profile: session.profile,
+            userId: session.userId,
+            payload: preview,
+            fingerprint: fingerprint(preview),
+        }, CONTINUATION_TTL_SECONDS * 1000);
+        return ehrSuccess('ehr.attend.report.recalc.prepare', {
+            status: 'AWAITING_CONFIRMATION',
+            preview,
+            continuation: token,
+            expiresInSeconds: CONTINUATION_TTL_SECONDS,
+        });
+    },
+};
+const ehrAttendReportRecalcApply = {
+    name: 'ehr.attend.report.recalc.apply',
+    resource: 'attend',
+    method: 'report.recalc.apply',
+    action: 'ehr.attend.report.recalc.apply',
+    summary: '触发考勤报表异步重算；会占用服务端资源且同一时刻仅允许一个任务，必须在用户明确确认后调用',
+    capability: 'attend',
+    risk: WRITE,
+    requiresConfirmation: true,
+    inputSchema: schemaOf({ ...recalcSchema, confirm: { const: true }, continuation: { type: 'string', minLength: 1 } }, { required: ['beginDate', 'endDate', 'confirm', 'continuation'] }),
+    handler: async (args, env) => {
+        requireConfirm(args, 'ehr.attend.report.recalc.apply');
+        const lease = await verifyLease(args, 'ehr.attend.report.recalc.apply', env);
+        const payload = (lease.payload || {});
+        if (payload.beginDate !== args.beginDate || payload.endDate !== args.endDate) {
+            throw ehrValidationError('target_changed', '重算日期范围与 prepare 时的快照不一致，请重新执行 prepare');
+        }
+        const body = { beginDate: args.beginDate, endDate: args.endDate };
+        const onlyEmpIds = toIdList(args.onlyEmpIds, 'onlyEmpIds');
+        if (onlyEmpIds?.length)
+            body.onlyEmpIds = onlyEmpIds;
+        let response;
+        try {
+            response = await env.host.request({
+                method: 'POST',
+                path: '/api/attend/web/attendWorkTimeSummaryReport/recalcStatus',
+                body,
+            });
+        }
+        catch (error) {
+            if (isNetworkError(error)) {
+                throw ehrPartialError('重算请求发送后连接中断，任务是否已提交不确定，禁止自动重试；重算为异步任务，请稍后通过出勤报表复核', { attempted: { beginDate: args.beginDate, endDate: args.endDate } }, { stage: 'report.recalc' });
+            }
+            throw error;
+        }
+        return ehrSuccess('ehr.attend.report.recalc.apply', {
+            status: 'COMPLETE',
+            result: response?.data,
+            async: true,
+            verifyHint: '重算是异步任务，提交成功不代表计算完成；可通过 ehr.attend.report.get 复核',
+        });
+    },
+};
+export const attendWriteOperations = [
+    attendCardStatus,
+    ehrAttendCardCheckPrepare,
+    ehrAttendCardCheckApply,
+    ehrAttendAppealSavePrepare,
+    ehrAttendAppealSaveApply,
+    ehrAttendAppealResultPrepare,
+    ehrAttendAppealResultApply,
+    ehrAttendReportRecalcPrepare,
+    ehrAttendReportRecalcApply,
+];
+export { assertEnumArray };