@xiaoyuanhao/yunzhi-cli 2.0.0 → 2.1.0

package/lib/dormitory-scope.cjs

@@ -0,0 +1,18 @@
+const { required, nullable } = require('./result.cjs');
+const schema = {
+  school_wide: required('boolean'), scope_classes: required([{ class_id: required('string'), class_name: required('string') }]),
+  scope_manage_groups: required([{ manage_id: required('string'), manage_name: required('string'), building_id: nullable('string'),
+    bedrooms: required([{ bedroom_id: required('string'), bedroom_name: required('string') }]) }]),
+};
+const positiveId = value => typeof value === 'string' && /^[1-9][0-9]*$/.test(value) && BigInt(value) <= 9223372036854775807n;
+function valid(data, payload) {
+  const classes = new Set(data.scope_classes.map(row => row.class_id));
+  const groups = new Set(data.scope_manage_groups.map(row => row.manage_id));
+  return classes.size === data.scope_classes.length && data.scope_classes.every(row => !row.class_id.includes(','))
+    && (data.school_wide ? classes.size === 0 : classes.size > 0 || groups.size > 0)
+    && (data.school_wide || payload.class_id == null || classes.has(payload.class_id))
+    && groups.size === data.scope_manage_groups.length && (payload.manage_id == null || groups.has(payload.manage_id))
+    && data.scope_manage_groups.every(group => positiveId(group.manage_id) && (group.building_id == null || positiveId(group.building_id))
+      && new Set(group.bedrooms.map(room => room.bedroom_id)).size === group.bedrooms.length && group.bedrooms.every(room => positiveId(room.bedroom_id)));
+}
+module.exports = { schema, valid };

package/lib/dormitory-statistics.cjs

@@ -0,0 +1,30 @@
+const { required, nullable, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+const countKeys = ['normal_in_count', 'late_in_count', 'no_in_count', 'normal_out_count', 'late_out_count', 'no_out_count', 'leave_count', 'unknown_count'];
+const scope = require('./dormitory-scope.cjs');
+async function execute(args) {
+  const payload = require('./attendance.cjs').managedQuery(args, 'dormitory-attendance', false);
+  const result = await gateway.execute('attendance-leave:read', 'dormitory-attendance/statistics', payload, {
+    tenant_id: required('string'), operator_id: required('string'), start_date: required('string'), end_date: required('string'),
+    target_user_id: nullable('string'), class_id: nullable('string'), manage_id: nullable('string'), name_filter: nullable('string'), rule_id: nullable('string'), period: nullable('integer'), status: nullable('integer'),
+    abnormal: required('boolean'), ...scope.schema,
+    queried_at: required('integer'), total_count: required('integer'), ...Object.fromEntries(countKeys.map(key => [key, required('integer')])),
+  });
+  const data = result.value.data;
+  const filteredCount = { 11: 'normal_out_count', 12: 'normal_in_count', 13: 'late_in_count', 14: 'late_out_count', 15: 'no_out_count', 16: 'no_in_count', '-6': 'leave_count' };
+  const valid = data.start_date === payload.start_date && data.end_date === payload.end_date
+    && ['target_user_id', 'class_id', 'manage_id', 'rule_id', 'period', 'status'].every(key => data[key] === (payload[key] ?? null))
+    && data.name_filter === (payload.name ?? null) && data.queried_at > 0 && data.total_count >= 0
+    && countKeys.every(key => data[key] >= 0) && countKeys.reduce((sum, key) => sum + BigInt(data[key]), 0n) === BigInt(data.total_count)
+    && (payload.status == null || data[filteredCount[payload.status]] === data.total_count)
+    && data.abnormal === Boolean(payload.abnormal)
+    && (!payload.abnormal || ['normal_in_count', 'normal_out_count', 'leave_count', 'unknown_count'].every(key => data[key] === 0))
+    && scope.valid(data, payload);
+  if (!valid) {
+    const failure = new Failure(1, 'api', 'invalid_response', '宿舍考勤统计的日期、筛选、职责范围或计数不一致。');
+    if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+    throw failure;
+  }
+  return result;
+}
+module.exports = { execute };

package/lib/download.cjs

@@ -31,22 +31,25 @@ async function download(namespace, args) {
   const result = publicResult({ ...envelope, data: { ...data, local_path: target } }, {
     ...optionalFields({ file_id: 'string', kind: 'string', space: 'string', name: 'string', path: 'string', file_ext: 'string', size_bytes: 'integer' }), local_path: 'string',
   });
+  return saveDownload(data, target, parsed.overwrite, result);
+}
+async function saveDownload(data, target, overwrite, result, privateUrl = false) {
   try {
     const info = await fs.lstat(target);
-    if (!parsed.overwrite) throw exists(target);
+    if (!overwrite) throw exists(target);
     if (!info.isFile() || info.isSymbolicLink()) throw local('覆盖目标必须是普通文件。');
   } catch (error) { if (error instanceof Failure) throw error; if (error.code !== 'ENOENT') throw attach(local('无法检查本地目标文件。'), error); }
   let handle, opened = false, primaryError;
   try {
-    try { handle = await fs.open(target, parsed.overwrite ? 'w' : 'wx'); opened = true; }
+    try { handle = await fs.open(target, overwrite ? 'w' : 'wx'); opened = true; }
     catch (error) {
-      if (!parsed.overwrite && error.code === 'EEXIST') throw attach(exists(target), error);
+      if (!overwrite && error.code === 'EEXIST') throw attach(exists(target), error);
       throw attach(local('无法打开本地目标文件。'), error);
     }
     let response;
-    try { response = await fetch(data.download_url, { headers: { 'User-Agent': 'yunzhi-cli/' + version }, signal: AbortSignal.timeout(25 * 60 * 1000) }); }
+    try { response = await fetch(data.download_url, { headers: { 'User-Agent': 'yunzhi-cli/' + version }, signal: AbortSignal.timeout(25 * 60 * 1000), ...(privateUrl ? { redirect: 'error' } : {}) }); }
     catch (error) { throw network(error); }
-    if (!response.ok) {
+    if (!response.ok || data.size_bytes === null && response.status !== 200) {
       const failure = network(new Error('HTTP ' + response.status + ' ' + response.statusText));
       try { await response.body?.cancel(); } catch (error) { cleanup(failure, error); }
       throw failure;
@@ -55,16 +58,22 @@ async function download(namespace, args) {
     try {
       for await (const chunk of response.body) {
         size += chunk.length;
-        if (size > data.size_bytes) throw network(new Error('Download exceeds expected size: ' + size + ' > ' + data.size_bytes));
+        if (data.size_bytes !== null && size > data.size_bytes) throw network(new Error('Download exceeds expected size: ' + size + ' > ' + data.size_bytes));
         try { await handle.writeFile(chunk); } catch (error) { throw attach(local('无法写入本地文件。'), error); }
       }
     } catch (error) { if (error instanceof Failure) throw error; throw network(error); }
-    if (size !== data.size_bytes) throw network(new Error('Download size mismatch: expected ' + data.size_bytes + ', received ' + size));
+    if (data.size_bytes !== null && size !== data.size_bytes) throw network(new Error('Download size mismatch: expected ' + data.size_bytes + ', received ' + size));
     try { await handle.sync(); await handle.close(); handle = undefined; }
     catch (error) { throw attach(local('无法写入本地文件。'), error); }
+    if (data.size_bytes === null) result.value.data.downloaded_bytes = size;
     return result;
   } catch (error) {
     primaryError = error;
+    if (privateUrl && error instanceof Failure && error.result.value.error.detail) {
+      // Preserve transfer diagnostics while withholding this credential-bearing URL.
+      for (const secret of [data.download_url, encodeURI(data.download_url), encodeURIComponent(data.download_url), new URL(data.download_url).search])
+        error.result.value.error.detail = error.result.value.error.detail.split(secret).join('[临时下载授权已隐藏]');
+    }
     if (opened && error instanceof Failure) Object.assign(error.result.value.error, { local_path: target, partial_file: true });
     throw error;
   } finally {
@@ -77,4 +86,4 @@ async function download(namespace, args) {
     }
   }
 }
-module.exports = { download };
+module.exports = { download, saveDownload };

package/lib/gateway.cjs

@@ -24,15 +24,20 @@ async function execute(scope, endpoint, payload, schema) {
 }
 
 async function request(config, endpoint, token, payload, signal = AbortSignal.timeout(80000)) {
-  const address = gatewayURL(config) + '/api/v1/cli/' + endpoint;
-  const response = await send(address, {
+  const address = gatewayURL(config) + '/api/v1/cli/' + require('./attendance-leave-route.cjs').endpoint(endpoint);
+  try {
+    const response = await send(address, {
       method: payload === undefined ? 'GET' : 'POST',
       headers: { 'Content-Type': 'application/json', 'User-Agent': 'yunzhi-cli/' + require('./version.cjs').version,
         ...(token ? { Authorization: 'Bearer ' + token } : {}) },
       body: payload === undefined ? undefined : JSON.stringify(payload),
       redirect: 'error', signal,
     });
-  return responseEnvelope(response);
+    return await responseEnvelope(response);
+  } catch (error) {
+    require('./attendance-operation-result.cjs').transportFailure(endpoint, error);
+    throw error;
+  }
 }
 
 async function multipartRequest(config, endpoint, token, values, filePath) {
@@ -45,7 +50,7 @@ async function multipartRequest(config, endpoint, token, values, filePath) {
     for await (const chunk of fs.createReadStream(filePath)) yield chunk;
     yield Buffer.from(`\r\n--${boundary}--\r\n`);
   }
-  const address = gatewayURL(config) + '/api/v1/cli/' + endpoint;
+  const address = gatewayURL(config) + '/api/v1/cli/' + require('./attendance-leave-route.cjs').endpoint(endpoint);
   const response = await send(address, {
     method: 'POST', body: Readable.from(parts()), duplex: 'half', redirect: 'error',
     headers: { 'Content-Type': `multipart/form-data; boundary=${boundary}`,

package/lib/leave-approval-receipt.cjs

@@ -0,0 +1,126 @@
+const gateway = require('./gateway.cjs');
+
+function selection(field) {
+  let values = field.value;
+  if (Array.isArray(values)) values = { retain_media_ids: [], upload_keys: values };
+  if (!values || typeof values !== 'object' || Object.keys(values).length !== 2
+    || !Object.hasOwn(values, 'retain_media_ids') || !Object.hasOwn(values, 'upload_keys')) return null;
+  for (const list of Object.values(values)) {
+    if (!Array.isArray(list) || list.some(value => typeof value !== 'string' || !value.trim()) || new Set(list).size !== list.length) return null;
+  }
+  return { retain_media_ids: values.retain_media_ids, upload_keys: values.upload_keys };
+}
+
+const identity = field => JSON.stringify([field.input_parent_field_key ?? null, field.input_row_index ?? null, field.field_key]);
+const location = field => JSON.stringify([field.field_key, field.group_codes ?? null]);
+
+function requestedField(fields, receipt) {
+  const parent = receipt.input_parent_field_key, index = receipt.input_row_index, path = receipt.group_codes;
+  if (parent == null && index == null) return path == null ? fields.get(receipt.field_key) : null;
+  if (typeof parent !== 'string' || !parent.trim() || !Number.isSafeInteger(index) || index < 0
+    || !Array.isArray(path) || path.length !== 1 || typeof path[0] !== 'string' || !path[0].trim()) return null;
+  const table = fields.get(parent);
+  const rows = table?.value;
+  if (!Array.isArray(rows) || index >= rows.length) return null;
+  const row = rows[index], code = path[0];
+  if (!row || typeof row !== 'object' || Array.isArray(row)) return null;
+  if (Object.keys(row).length !== 2 || !Array.isArray(row.fields)) return null;
+  if (row.action === 'add') {
+    if (!code.startsWith(`${parent}_`) || !/^[1-9][0-9]*$/.test(code.slice(parent.length + 1))
+      || rows.some(other => other?.group_code === code)) return null;
+  } else if (row.group_code !== code) return null;
+  let selected = null;
+  for (const child of row.fields) {
+    if (!child || typeof child !== 'object' || Array.isArray(child)) return null;
+    if (child.field_key !== receipt.field_key) continue;
+    if (selected || typeof child.field_key !== 'string' || Object.keys(child).length !== 2 || !Object.hasOwn(child, 'value')) return null;
+    selected = child;
+  }
+  return selected;
+}
+
+async function execute(scope, endpoint, payload, schema) {
+  const { config, token } = await require('./session.cjs').session(scope);
+  const envelope = await gateway.request(config, endpoint, token, payload);
+  const result = gateway.publicResult(envelope, schema);
+  let damaged = require('./leave-start-receipt.cjs').project(envelope, result, '审批');
+  const fields = new Map();
+  for (const field of payload.field_values || []) {
+    if (fields.has(field.field_key)) { damaged = true; fields.set(field.field_key, null); }
+    else fields.set(field.field_key, field);
+  }
+  const preparations = result.value.data.attachment_preparations;
+  const sources = envelope.data.attachment_preparations;
+  const fieldCounts = new Map(), locationCounts = new Map(), copyCounts = new Map();
+  const rowTargets = new Map(), rowSources = new Map();
+  for (const field of Array.isArray(sources) ? sources : []) if (field) {
+    if (field.input_parent_field_key != null) {
+      const inputRow = JSON.stringify([field.input_parent_field_key, field.input_row_index]);
+      const storedRow = JSON.stringify([field.input_parent_field_key, field.group_codes]);
+      if (!rowTargets.has(inputRow)) rowTargets.set(inputRow, new Set());
+      if (!rowSources.has(storedRow)) rowSources.set(storedRow, new Set());
+      rowTargets.get(inputRow).add(storedRow); rowSources.get(storedRow).add(inputRow);
+    }
+    fieldCounts.set(identity(field), (fieldCounts.get(identity(field)) || 0) + 1);
+    locationCounts.set(location(field), (locationCounts.get(location(field)) || 0) + 1);
+    for (const copy of Array.isArray(field.copies) ? field.copies : []) if (copy?.object_key) copyCounts.set(copy.object_key, (copyCounts.get(copy.object_key) || 0) + 1);
+  }
+  if (preparations) result.value.data.attachment_preparations = preparations.map((field, index) => {
+    const receipt = sources[index];
+    const input = field && requestedField(fields, receipt);
+    if (!input || fieldCounts.get(identity(receipt)) !== 1 || locationCounts.get(location(receipt)) !== 1) { damaged = true; return null; }
+    if (receipt.input_parent_field_key != null) {
+      if (rowTargets.get(JSON.stringify([receipt.input_parent_field_key, receipt.input_row_index])).size !== 1
+        || rowSources.get(JSON.stringify([receipt.input_parent_field_key, receipt.group_codes])).size !== 1) { damaged = true; return null; }
+      field.input_parent_field_key = receipt.input_parent_field_key; field.input_row_index = receipt.input_row_index;
+    }
+    const selected = selection(input);
+    let incomplete = !field.copies || !selected;
+    if (field.copies) field.copies = field.copies.map(copy => {
+      if (!copy || !selected?.upload_keys.includes(copy.source_object_key) || copyCounts.get(copy.object_key) !== 1
+        || copy.size_bytes > 200 * 1024 * 1024) {
+        incomplete = true; damaged = true; return null;
+      }
+      if (Object.values(copy).some(value => value == null)) incomplete = true;
+      return copy;
+    });
+    const source = envelope.data.attachment_preparations[index].retained;
+    if (!Array.isArray(source)) { field.retained = null; incomplete = true; }
+    else {
+      const counts = new Map();
+      for (const file of source) if (file?.media_id) counts.set(file.media_id, (counts.get(file.media_id) || 0) + 1);
+      field.retained = source.map(file => {
+        if (!file || !['media_id', 'file_name', 'file_type'].every(key => typeof file[key] === 'string' && file[key].trim())
+          || !Number.isSafeInteger(file.size_bytes) || file.size_bytes < 0 || file.size_bytes > 200 * 1024 * 1024
+          || !selected?.retain_media_ids.includes(file.media_id) || counts.get(file.media_id) !== 1) {
+          incomplete = true; damaged = true; return null;
+        }
+        return { media_id: file.media_id, file_name: file.file_name, file_type: file.file_type, size_bytes: file.size_bytes };
+      });
+    }
+    const allVerified = field.copies?.every(copy => copy?.verified === true && copy.execution_status === 'COMPLETED');
+    const noFiles = field.copies?.length === 0 && field.retained?.length === 0;
+    if (!incomplete && ['UNCONFIRMED', 'COMPLETED'].includes(field.group_execution_status) && (noFiles || !allVerified)) {
+      field.group_id = null; field.group_execution_status = null; damaged = true;
+    }
+    const copiedKeys = new Set((field.copies || []).map(copy => copy?.source_object_key));
+    const retainedIds = new Set((field.retained || []).map(file => file?.media_id));
+    const selectionComplete = selected && copiedKeys.size === field.copies?.length && retainedIds.size === field.retained?.length
+      && selected.upload_keys.length === copiedKeys.size && selected.upload_keys.every(key => copiedKeys.has(key))
+      && selected.retain_media_ids.length === retainedIds.size && selected.retain_media_ids.every(id => retainedIds.has(id));
+    const empty = noFiles && field.group_execution_status === 'NOT_EXECUTED' && field.group_id == null;
+    if (field.verified && (incomplete || !selectionComplete || !(empty || field.group_execution_status === 'COMPLETED' && allVerified))) {
+      field.verified = false; damaged = true;
+    }
+    if (field.group_execution_status !== 'COMPLETED' && field.group_id != null) {
+      field.group_id = null; field.group_execution_status = null; damaged = true;
+    }
+    if (incomplete || field.group_execution_status == null) damaged = true;
+    return field;
+  });
+  result.value.data.attachment_preparations_complete = envelope.data.attachment_preparations_complete === true && preparations != null && !damaged;
+  if (!result.value.data.attachment_preparations_complete)
+    result.value.data.attachment_preparation_error = '附件准备回执不完整，已确认的审批和附件事实保留；未知部分不能当作未执行，不要自动重试。';
+  return result;
+}
+module.exports = { execute, selection, requestedField };

package/lib/leave-attachment-upload.cjs

@@ -0,0 +1,110 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { Failure, success, invalid, cleanupFailure } = require('./result.cjs');
+const { attach } = require('./diagnostics.cjs');
+const { options, required } = require('./arguments.cjs');
+const { session } = require('./session.cjs');
+const { request } = require('./gateway.cjs');
+
+async function upload(namespace, command, args) {
+  const approval = command.includes('approval-') || ['approve', 'resumption-approve', 'correction-approve'].includes(command);
+  const correction = namespace === 'attendance';
+  const resumption = command.startsWith('resumption-');
+  const business = approval ? '审批' : '申请';
+  const student = namespace === 'student-leave';
+  const targets = approval ? ['task_id'] : correction ? ['date', 'result_id'] : resumption ? ['leave_id'] : student ? ['class_id', 'student_id'] : [];
+  const parameters = [...(approval || correction ? [] : ['program_code']), 'field_key', 'file', ...targets];
+  const parsed = options(args, [...parameters, ...(student && resumption && !approval ? ['student_id'] : [])], [], ['file'], true);
+  required(parsed, ...parameters);
+  if (approval && (!/^[1-9][0-9]*$/.test(parsed.task_id) || BigInt(parsed.task_id) > 9223372036854775807n))
+    throw invalid('--task-id 必须是有效的正整数审批任务 ID。');
+  if (!approval && resumption && (student ? !require('./student-leave-query.cjs').validId(parsed.leave_id, false)
+    : !require('./teacher-leave-query.cjs').validId(parsed.leave_id, 'leave_')))
+    throw invalid('--leave-id 使用原请假返回的公开 ID。');
+  if (correction && !approval && (!/^\d{4}-\d{2}-\d{2}$/.test(parsed.date) || !Number.isFinite(Date.parse(parsed.date))
+    || new Date(parsed.date).toISOString().slice(0, 10) !== parsed.date)) throw invalid('--date 必须为真实有效的 YYYY-MM-DD 日期。');
+  const purpose = correction ? undefined : (student ? 'STUDENT' : 'TEACHER') + (resumption ? '_RESUMPTION' : '_LEAVE');
+  const fileName = path.basename(parsed.file);
+  if (fileName.length > 255 || /[\x00-\x1f\x7f/\\]/.test(fileName) || ['.', '..'].includes(fileName)) throw invalid('附件文件名无效。');
+  let handle, completed, primaryError, receipt, requestId;
+  let stage = 'local_file';
+  try { handle = await fs.open(parsed.file, 'r'); }
+  catch (error) { throw attach(new Failure(2, 'validation', 'invalid_local_file', '附件文件不可读取，上传尚未开始。'), error); }
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > 200 * 1024 * 1024) throw invalid('附件必须为不超过 200 MiB 的普通文件。');
+    const payload = { ...(approval || correction ? {} : { program_code: parsed.program_code }), field_key: parsed.field_key, file_name: fileName, size_bytes: info.size };
+    for (const target of targets) payload[target] = parsed[target];
+    if (student && resumption && !approval && parsed.student_id !== undefined) payload.student_id = parsed.student_id;
+    const { config, token } = await session('attendance-leave' + (approval ? ':approve' : ':write'));
+    stage = 'upload_authorization';
+    const endpoint = `${namespace}/${command}/attachment-prepare`;
+    const prepared = await request(config, endpoint, token, payload);
+    requestId = prepared.request_id;
+    const grant = prepared.data;
+    if (!validGrant(grant, payload, purpose, approval, correction)) throw new Failure(1, 'api', 'invalid_response', '附件上传授权与办理对象、文件或传输合同不一致，文件传输尚未开始。');
+    receipt = { ...(correction ? { tenant_id: grant.tenant_id, teacher_id: grant.teacher_id } : { purpose }), form_id: grant.form_id, field_key: grant.field_key,
+      ...(approval ? { task_id: grant.task_id, application_id: grant.application_id, approval_submitted: false }
+        : { program_code: grant.program_code, ...(correction ? { date: grant.date, result_id: grant.result_id } : { class_id: grant.class_id, student_id: grant.student_id, leave_id: grant.leave_id }), application_submitted: false }),
+      object_key: grant.object_key, file_name: grant.file_name, size_bytes: grant.size_bytes };
+    stage = 'file_transfer';
+    try {
+      if ((await handle.stat()).size !== info.size) throw new Error('附件源文件大小已变化。');
+      await require('./cos-upload.cjs').put(handle, info.size, { object_key: grant.object_key, bucket: grant.bucket, region: grant.region,
+        secret_id: grant.credentials.secret_id, secret_key: grant.credentials.secret_key, session_token: grant.credentials.session_token });
+      if ((await handle.stat()).size !== info.size) throw new Error('附件源文件大小已变化。');
+    }
+    catch (error) {
+      // Do not serialize storage responses or temporary storage credentials into the agent conversation.
+      throw new Failure(4, 'network', 'attachment_upload_unconfirmed', `附件传输结果待核实，尚未提交${business}；保留本次对象标识，不自动重传。`,
+        { ...receipt, hint: `停止本文件的依赖操作；核实上传结果后再决定是否提交${business}，不自动重试或删除对象。` });
+    }
+    completed = success({ ...receipt, file_transferred: true,
+      message: correction ? (approval ? '补卡审批附件字节已上传，尚未关联或提交审批。新 object_key 数组替换整个字段；保留旧文件并追加时，将同任务同字段同行的实际 media_id 放入 retain_media_ids，新键放入 upload_keys，两数组对象编码为 value，子表放入所选行；按老师明确决定调用 correction-approve。' : '补卡附件字节已上传，尚未关联或提交申请。将 object_key 放入对应字段 value 的 字符串数组；子表放入所选行，再按老师明确指令调用 correction-submit。') : approval ? '审批附件字节已上传，尚未关联或提交审批。将同一任务的 object_key 放入对应字段 value 的 字符串数组，再按老师明确决定调用对应 approve 或 resumption-approve。' : '附件字节已上传，尚未关联或提交申请。将 object_key 放入对应字段 value 的 字符串数组，再按老师指令提交申请。' });
+    if (prepared.request_id) completed.value.request_id = prepared.request_id;
+    return completed;
+  } catch (error) {
+    primaryError = error instanceof Failure ? error : attach(new Failure(5, 'local', 'attachment_file_error', '无法读取本地附件信息，文件传输尚未开始。'), error);
+    primaryError.result.value.error.upload_stage = stage;
+    if (requestId) primaryError.result.value.request_id = requestId;
+    throw primaryError;
+  } finally {
+    try { await handle.close(); }
+    catch (error) { throw cleanupFailure(primaryError || new Failure(5, 'local', 'storage_error', '附件上传已完成，但无法关闭本地源文件。'), completed, error); }
+  }
+}
+
+function validGrant(grant, payload, purpose, approval, correction) {
+  if (!grant || grant.purpose !== purpose || typeof grant.form_id !== 'string' || !/^[1-9][0-9]*$/.test(grant.form_id)
+    || BigInt(grant.form_id) > 9223372036854775807n || !Number.isSafeInteger(grant.expires_at) || grant.expires_at <= Date.now()
+    || typeof grant.object_key !== 'string' || !grant.object_key.trim()) return false;
+  if (approval && (!require('./attendance-leave-ids.cjs').applicationId(grant.application_id, purpose))) return false;
+  if (Object.entries(payload).some(([key, value]) => grant[key] !== value)
+    || ['class_id', 'student_id', 'leave_id'].some(key => (grant[key] ?? null) !== (payload[key] ?? null))) return false;
+  if (correction) {
+    if (typeof grant.tenant_id !== 'string' || !grant.tenant_id.trim() || typeof grant.teacher_id !== 'string' || !grant.teacher_id.trim()
+      || grant.expires_at > Date.now() + 900000 || Buffer.byteLength(grant.object_key) > 1023
+      || (approval ? grant.date != null || grant.result_id != null || grant.program_code != null
+        : typeof grant.program_code !== 'string' || !grant.program_code.trim() || grant.task_id != null || grant.application_id != null)) return false;
+
+    const encode = value => Buffer.from(value).toString('base64url');
+    const prefix = (approval ? 'workflow-approval-attachments/' : 'workflow-attachments/') + encode(grant.tenant_id) + '/' + encode(grant.teacher_id) + '/';
+    if (!grant.object_key.startsWith(prefix)) return false;
+    const path = grant.object_key.slice(prefix.length).split('/');
+    // Gateway verifies the native application binding; CLI treats application_id as opaque.
+    if (approval && (!/^[1-9][0-9]*$/.test(path[0]) || path[1] !== grant.task_id)) return false;
+    const context = approval ? path.slice(2) : path;
+    if (context[0] !== grant.form_id) return false;
+    const parts = context.slice(1);
+    if (parts.length !== 4 || !/^[1-9][0-9]*$/.test(parts[0]) || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(parts[1])
+      || parts[2] !== String(payload.size_bytes) || parts[3] !== encode(payload.file_name)) return false;
+  }
+  const credentials = grant.credentials;
+  const hostPart = value => typeof value === 'string' && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(value);
+  if (!hostPart(grant.bucket) || !hostPart(grant.region) || !credentials || typeof credentials !== 'object'
+    || Object.keys(credentials).length !== 4
+    || !['secret_id', 'secret_key', 'session_token'].every(key => typeof credentials[key] === 'string' && credentials[key].trim())
+    || typeof credentials.expires_at !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?(?:Z|[+-]\d\d:\d\d)$/.test(credentials.expires_at)) return false;
+  return Number.isFinite(Date.parse(credentials.expires_at)) && Date.parse(credentials.expires_at) === grant.expires_at;
+}
+module.exports = { upload };

package/lib/leave-form-users.cjs

@@ -0,0 +1,48 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, invalid, Failure } = require('./result.cjs');
+const { positiveId } = require('./attendance-leave-ids.cjs');
+const gateway = require('./gateway.cjs');
+
+async function execute(space, action, args) {
+  const approval = action.endsWith('approval-form-people-search');
+  const resumption = action.startsWith('resumption-');
+  const student = space === 'student-leave';
+  const correction = space === 'attendance';
+  const extra = approval ? ['task_id'] : correction ? ['date', 'result_id'] : resumption ? ['leave_id'] : student ? ['class_id', 'student_id'] : [];
+  const selectors = approval || correction ? [] : ['program_code'];
+  const payload = options(args, [...selectors, 'field_key', 'keyword', ...extra, ...(student && resumption && !approval ? ['student_id'] : [])], [], [], true);
+  requireArguments(payload, ...selectors, 'field_key', 'keyword', ...extra);
+  if (approval && !positiveId(payload.task_id)) throw invalid('--task-id 必须是当前待办审批任务的有效 ID。');
+  if (!approval && resumption && (student ? !require('./student-leave-query.cjs').validId(payload.leave_id, false) : !require('./teacher-leave-query.cjs').validId(payload.leave_id, 'leave_'))) throw invalid('--leave-id 必须是原请假记录的有效 ID。');
+  if (correction && !approval && (!/^\d{4}-\d{2}-\d{2}$/.test(payload.date) || !Number.isFinite(Date.parse(payload.date))
+      || new Date(payload.date).toISOString().slice(0, 10) !== payload.date)) throw invalid('--date 必须为有效的 YYYY-MM-DD 日期。');
+  const purpose = correction ? 'TEACHER_CORRECTION' : (student ? 'STUDENT_' : 'TEACHER_') + (resumption ? 'RESUMPTION' : 'LEAVE');
+  try {
+    const result = await gateway.execute('attendance-leave:read', space + '/' + action, payload, {
+      tenant_id: required('string'), user_id: required('string'), purpose: required('string'),
+      field_key: required('string'), form_id: required('string'), exhaustive: required('boolean'),
+      ...(approval ? { task_id: required('string'), application_id: required('string') }
+        : correction ? { date: required('string'), result_id: required('string'), program_code: required('string') }
+        : { program_code: required('string'), class_id: nullable('string'), student_id: nullable('string'), leave_id: nullable('string') }),
+      candidates: required([{ tenant_id: required('string'), tenant_name: nullable('string'), user_id: required('string'),
+        user_name: required('string'), departments: nullable([{ department_id: required('string'), department_name: required('string') }]) }]),
+    });
+    const data = result.value.data;
+    const contextMismatch = approval ? data.task_id !== payload.task_id || !require('./attendance-leave-ids.cjs').applicationId(data.application_id, purpose)
+      : correction ? data.date !== payload.date || data.result_id !== payload.result_id
+      : data.program_code !== payload.program_code || ['class_id', 'student_id', 'leave_id'].some(key => (data[key] ?? null) !== (payload[key] ?? null));
+    if (contextMismatch || data.purpose !== purpose || data.field_key !== payload.field_key
+        || !positiveId(data.form_id) || data.exhaustive !== false || data.candidates.length > 10
+        || data.candidates.some(person => person.tenant_id !== data.tenant_id)
+        || new Set(data.candidates.map(person => person.user_id)).size !== data.candidates.length) {
+      const failure = new Failure(1, 'api', 'invalid_response', '人员搜索返回的办理场景、表单或候选身份不一致。');
+      if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+      throw failure;
+    }
+    return result;
+  } catch (failure) {
+    if (failure instanceof Failure) failure.result.value.error.details = { ...failure.result.value.error.details, ...payload };
+    throw failure;
+  }
+}
+module.exports = { execute };

package/lib/leave-start-receipt.cjs

@@ -0,0 +1,64 @@
+const gateway = require('./gateway.cjs');
+
+// Attachment diagnostics cannot erase a separately confirmed application outcome.
+async function execute(scope, endpoint, payload, schema, business = '申请') {
+  const { config, token } = await require('./session.cjs').session(scope);
+  const envelope = await gateway.request(config, endpoint, token, payload);
+  const result = gateway.publicResult(envelope, schema);
+  project(envelope, result, business);
+  return result;
+}
+
+function project(envelope, result, business) {
+  let damaged = false;
+  const unknown = () => { damaged = true; return null; };
+  const text = value => typeof value === 'string' && value.trim() ? value : unknown();
+  const status = value => ['NOT_EXECUTED', 'UNCONFIRMED', 'COMPLETED'].includes(value) ? value : unknown();
+  const verified = value => typeof value === 'boolean' ? value : unknown();
+  const object = value => value && typeof value === 'object' && !Array.isArray(value);
+  const copies = values => !Array.isArray(values) ? unknown() : values.map(value => {
+    if (!object(value)) return unknown();
+    const item = {
+      source_object_key: text(value.source_object_key), object_key: text(value.object_key), file_name: text(value.file_name),
+      size_bytes: Number.isSafeInteger(value.size_bytes) && value.size_bytes >= 0 ? value.size_bytes : unknown(),
+      execution_status: status(value.execution_status), verified: verified(value.verified),
+    };
+    if (item.verified && item.execution_status !== 'COMPLETED') item.verified = unknown();
+    return item;
+  });
+  const values = envelope.data.attachment_preparations;
+  result.value.data.attachment_preparations = values == null ? null : !Array.isArray(values) ? unknown() : values.map(value => {
+    if (!object(value)) return unknown();
+    const item = {
+      field_key: text(value.field_key), group_id: value.group_id == null ? null : text(value.group_id),
+      group_execution_status: status(value.group_execution_status), verified: verified(value.verified), copies: copies(value.copies),
+    };
+    if (Object.hasOwn(value, 'input_parent_field_key') || Object.hasOwn(value, 'input_row_index')) {
+      const topLevel = value.input_parent_field_key == null && value.input_row_index == null;
+      const row = typeof value.input_parent_field_key === 'string' && value.input_parent_field_key.trim()
+        && Number.isSafeInteger(value.input_row_index) && value.input_row_index >= 0;
+      item.input_parent_field_key = topLevel ? null : row ? value.input_parent_field_key : unknown();
+      item.input_row_index = topLevel ? null : row ? value.input_row_index : unknown();
+    }
+    if (Object.prototype.hasOwnProperty.call(value, 'retained')) {
+      const seen = new Set();
+      item.retained = !Array.isArray(value.retained) ? unknown() : value.retained.map(file => {
+        if (!object(file) || typeof file.media_id !== 'string' || !file.media_id.trim() || seen.has(file.media_id)) return unknown();
+        seen.add(file.media_id);
+        return { media_id: file.media_id, file_name: text(file.file_name), file_type: text(file.file_type),
+          size_bytes: Number.isSafeInteger(file.size_bytes) && file.size_bytes >= 0 && file.size_bytes <= 200 * 1024 * 1024 ? file.size_bytes : unknown() };
+      });
+    }
+    if (Object.prototype.hasOwnProperty.call(value, 'group_codes'))
+      item.group_codes = Array.isArray(value.group_codes) && value.group_codes.every(code => typeof code === 'string' && code.trim())
+        ? value.group_codes : unknown();
+    if (item.group_execution_status === 'COMPLETED' && !item.group_id) item.group_execution_status = unknown();
+    const empty = item.group_execution_status === 'NOT_EXECUTED' && item.group_id == null && item.copies?.length === 0
+      && (!Object.hasOwn(item, 'retained') || item.retained?.length === 0);
+    if (item.verified && item.group_execution_status !== 'COMPLETED' && !empty) item.verified = unknown();
+    return item;
+  });
+  if (damaged) result.value.data.attachment_preparation_error = `附件回执部分缺失或无效，对应事实标为未知；已确认的${business}和其他附件事实保留，不要自动重试或删除。`;
+  return damaged;
+}
+module.exports = { execute, project };