@xiaoyuanhao/yunzhi-cli 2.0.0 → 2.1.0

package/lib/arguments.cjs

@@ -1,22 +1,25 @@
 const { unknownOption } = require('./suggestions.cjs');
 const { Failure, invalid } = require('./result.cjs');
 
+const publicNames = { program_code: 'workflow-code', manage_id: 'group-id', bedroom_id: 'room-id', time_bucket: 'time-window' };
+const flagName = name => '--' + (publicNames[name] || name.replaceAll('_', '-'));
+
 // The flags remain command-specific; no unrecognized option reaches the Gateway.
 function options(args, values, booleans = [], raw = [], strict = false) {
   const payload = {};
   const seen = new Set();
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
-    const name = flag.slice(2).replaceAll('-', '_');
+    const name = values.concat(booleans).find(key => flagName(key) === flag);
     if (flag.startsWith('--') && (values.includes(name) || booleans.includes(name)) && name !== 'label_id') {
       if (seen.has(name)) throw invalid(flag + ' 不能重复传入。');
       seen.add(name);
     }
     if (booleans.includes(name) && flag.startsWith('--')) { payload[name] = true; continue; }
-    if (!flag.startsWith('--') || !values.includes(name)) throw unknownOption(flag, values.concat(booleans).map(name => '--' + name.replaceAll('_', '-')));
+    if (!flag.startsWith('--') || !values.includes(name)) throw unknownOption(flag, values.concat(booleans).map(flagName));
     const value = args[++i];
     if (!value?.trim() || ['--help', '-h'].includes(value)
-        || (value.startsWith('--') && values.concat(booleans).includes(value.slice(2).replaceAll('-', '_')))
+        || (value.startsWith('--') && values.concat(booleans).some(key => flagName(key) === value))
         || (strict && value.startsWith('--'))) throw invalid(flag + ' 需要非空参数。');
     if (name === 'label_id') (payload.label_ids ||= []).push(raw.includes(name) ? value : value.trim());
     else payload[name] = raw.includes(name) ? value : value.trim();
@@ -24,7 +27,7 @@ function options(args, values, booleans = [], raw = [], strict = false) {
   return payload;
 }
 function required(payload, ...names) {
-  for (const name of names) if (!payload[name]) throw invalid('--' + name.replaceAll('_', '-') + ' 为必填参数。');
+  for (const name of names) if (!payload[name]) throw invalid(flagName(name) + ' 为必填参数。');
 }
 function confirm(payload) {
   if (!payload.yes) throw new Failure(10, 'confirmation', 'confirmation_required', '执行前必须明确传入 --yes。');

package/lib/attendance-clock-entry.cjs

@@ -0,0 +1,31 @@
+const { options } = require('./arguments.cjs');
+const { required, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+async function execute(args) {
+  const payload = options(args, [], [], [], true);
+  let requestId;
+  try {
+    const result = await gateway.execute('attendance-leave:read', 'attendance/clock-entry', payload, {
+      tenant_id: required('string'), user_id: required('string'), domain: required('string'), kind: required('string'),
+      title: required('string'), url: required('string'), message: required('string'),
+    });
+    requestId = result.value.request_id;
+    const data = result.value.data;
+    try {
+      const url = new URL(data.url);
+      if (data.domain !== 'attendance' || data.kind !== 'PHYSICAL_CLOCK_IN' || !data.tenant_id.trim() || !data.user_id.trim()
+          || !data.title.trim() || !data.message.trim() || url.protocol !== 'https:' || !url.hostname
+          || url.username || url.password || url.hash || url.pathname !== '/micro/app/teacherAttendance/'
+          || [...url.searchParams.keys()].join(',') !== 'corpid' || !url.searchParams.get('corpid').trim()
+          || /[\x00-\x1f\x7f-\x9f]/.test(url.searchParams.get('corpid'))) throw new Error();
+    } catch { throw new Failure(1, 'api', 'invalid_response', '现场打卡入口的身份、业务范围或原客户端地址无效，未提供可用入口。'); }
+    return result;
+  } catch (failure) {
+    if (failure instanceof Failure) {
+      if (requestId) failure.result.value.request_id = requestId;
+      failure.result.value.error.details = { ...failure.result.value.error.details, domain: 'attendance' };
+    }
+    throw failure;
+  }
+}
+module.exports = { execute };

package/lib/attendance-configuration-entry.cjs

@@ -0,0 +1,35 @@
+const { options } = require('./arguments.cjs');
+const { required, Failure, invalid } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+const paths = { attendance: '/safety-campus/attendance-v2/list', 'student-attendance': '/safety-campus/attendance-student-v2/list', 'dormitory-attendance': '/safety-campus/dorm/list' };
+async function execute(args, domain) {
+  const payload = options(args, ['target'], [], [], true);
+  const target = payload.target ?? 'rules';
+  if (target !== 'rules' && target !== 'devices' && !(domain !== 'dormitory-attendance' && ['resumption-method', 'workflows'].includes(target)))
+    throw invalid(domain === 'dormitory-attendance' ? '--target 仅支持 rules（考勤规则）或 devices（设备管理）。' : '--target 仅支持 rules（考勤规则）、devices（设备管理）、workflows（审批流程）或 resumption-method（销假方式）。');
+  const path = target === 'workflows' ? '/workFlow/home' : target === 'devices' ? '/accessCenter/device/device/listPage' : target === 'rules' ? paths[domain] : domain === 'attendance'
+    ? '/safety-campus/attendance-v2/service-configuration/teacher-leave-method'
+    : '/safety-campus/attendance-student-v2/service-configuration/student-leave-method';
+  let requestId;
+  try {
+    const result = await gateway.execute('attendance-leave:read', domain + '/configuration-entry', payload, {
+      tenant_id: required('string'), user_id: required('string'), domain: required('string'), kind: required('string'),
+      title: required('string'), url: required('string'), message: required('string'),
+    });
+    requestId = result.value.request_id;
+    const data = result.value.data;
+    try {
+      const url = new URL(data.url);
+      if (data.domain !== domain || data.kind !== 'CONFIGURATION' || !data.tenant_id.trim() || !data.user_id.trim() || !data.title.trim()
+          || url.protocol !== 'https:' || !url.hostname || url.username || url.password || url.hash || url.search || url.pathname !== path) throw new Error();
+    } catch { throw new Failure(1, 'api', 'invalid_response', '考勤配置入口返回的业务范围、身份或网页地址无效。'); }
+    return result;
+  } catch (failure) {
+    if (failure instanceof Failure) {
+      if (requestId) failure.result.value.request_id = requestId;
+      failure.result.value.error.details = { ...failure.result.value.error.details, domain, ...payload };
+    }
+    throw failure;
+  }
+}
+module.exports = { execute };

package/lib/attendance-correction-applications.cjs

@@ -0,0 +1,64 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, invalid, Failure } = require('./result.cjs');
+const { positiveId } = require('./attendance-leave-ids.cjs');
+const { formField } = require('./leave.cjs');
+const gateway = require('./gateway.cjs');
+
+async function execute(action, args) {
+  const list = action === 'correction-list';
+  const payload = options(args, list ? ['status', 'page', 'page_size', ...require('./attendance-leave-list-filters.cjs').dates] : ['id'], [], [], true);
+  if (list) {
+    require('./attendance-leave-list-filters.cjs').validate(payload);
+    for (const [key, fallback, max] of [['page', 1, 2147483647], ['page_size', 20, 50]]) {
+      const value = payload[key] ?? fallback;
+      if (!/^[0-9]+$/.test(String(value)) || +value < 1 || +value > max) throw invalid('--' + key.replaceAll('_', '-') + ' 必须为1到' + max + '的整数。');
+      payload[key] = +value;
+    }
+    if (payload.status !== undefined) {
+      const enums = require('./attendance-leave-enums.cjs');
+      payload.status = enums.encode(enums.workflowStatus, payload.status, '--status');
+    }
+  } else {
+    requireArguments(payload, 'id');
+    if (!require('./attendance-leave-ids.cjs').applicationId(payload.id)) throw invalid('--id 必须为补卡工作流返回的有效申请 ID。');
+  }
+  try {
+    const result = await gateway.execute('attendance-leave:read', 'attendance/' + action, payload, list ? {
+      tenant_id: required('string'), user_id: required('string'), page: required('integer'), page_size: required('integer'),
+      total: required('integer'), total_pages: required('integer'), items: required([{
+        id: required('string'), program_code: required('string'), title: nullable('string'),
+        status: required('integer'), status_description: nullable('string'), created_at: nullable('string'),
+      }]),
+    } : {
+      tenant_id: required('string'), user_id: required('string'), id: required('string'),
+      program_code: required('string'), form_id: required('string'), title: nullable('string'),
+      status: required('integer'), status_description: nullable('string'), fields: required([formField]),
+      attachments: required([require('./teacher-leave-files.cjs').attachment]),
+      clock_reference: nullable({ date: required('string'), record_id: required('string'), clock_record_found: required('boolean') }),
+      progress: required([{ task_id: nullable('string'), node_name: nullable('string'), node_type: nullable('integer'),
+        handler_name: nullable('string'), handler_time: nullable('string'), status: required('integer'), status_description: nullable('string'), opinion: nullable('string') }]),
+    });
+    const data = result.value.data;
+    const reference = data.clock_reference;
+    const validReference = reference == null || positiveId(reference.record_id)
+      && /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/.test(reference.date) && +reference.date.slice(0, 4) > 0
+      && Number.isFinite(Date.parse(reference.date)) && new Date(reference.date).toISOString().slice(0, 10) === reference.date;
+    const readonly = fields => fields.every(field => field.editable === false && (!field.groups || field.groups.every(group => readonly(group.fields))));
+    if (list ? data.page !== payload.page || data.page_size !== payload.page_size || data.total < 0
+        || data.total_pages !== Math.ceil(data.total / data.page_size)
+        || data.items.length > Math.min(data.page_size, Math.max(0, data.total - (data.page - 1) * data.page_size))
+        || new Set(data.items.map(row => row.id)).size !== data.items.length
+        || data.items.some(row => !require('./attendance-leave-ids.cjs').applicationId(row.id) || payload.status != null && row.status !== payload.status)
+        : !validReference || data.id !== payload.id || !positiveId(data.form_id) || !readonly(data.fields)
+          || data.progress.some(step => step.task_id != null && !positiveId(step.task_id))) {
+      const failure = new Failure(1, 'api', 'invalid_response', !validReference ? '本人补卡申请的关联日期或打卡标识无效。' : '本人补卡申请的标识、字段权限、状态或分页信息不一致。');
+      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/attendance-correction-approval.cjs

@@ -0,0 +1,135 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+const positive = value => typeof value === 'string' && /^[1-9][0-9]*$/.test(value) && BigInt(value) <= 9223372036854775807n;
+const task = {
+  task_id: required('string'), application_id: required('string'), applicant_id: required('string'), applicant_tenant_id: required('string'),
+  applicant_name: nullable('string'), title: nullable('string'), submitted_at: nullable('string'), task_status: required('integer'),
+  handler_id: nullable('string'), handler_tenant_id: nullable('string'), handled_at: nullable('string'), notice_id: nullable('string'), notice_read: nullable('boolean'),
+};
+const scope = { category: required('string'), tenant_id: required('string'), reviewer_id: required('string') };
+const page = { ...scope, items: required([task]), page: required('integer'), page_size: required('integer'), total: required('integer'), total_pages: required('integer') };
+const detail = { attachments: required([require('./teacher-leave-files.cjs').attachment]), ...scope, task: required(task), form_id: required('string'), status: required('integer'), status_description: nullable('string'),
+  fields: required([require('./leave.cjs').formField]), progress: required([{ task_id: nullable('string'), node_name: nullable('string'),
+    node_type: nullable('integer'), handler_name: nullable('string'), handler_time: nullable('string'), status: required('integer'),
+    status_description: nullable('string'), opinion: nullable('string') }]),
+  can_approve: required('boolean'), can_reject: required('boolean'), opinion_visible: required('boolean'), opinion_required: required('boolean'),
+  reject_return_types: required(['integer']),
+};
+function validDetail(data) {
+  const fields = rows => rows.every(field => positive(field.widget_id) && typeof field.editable === 'boolean'
+    && (data.can_approve || field.editable === false) && (!field.groups || field.groups.every(group => fields(group.fields))));
+  return positive(data.form_id) && validTask(data.task, data)
+    && (data.category === 'pending' || !data.can_approve && !data.can_reject && !data.opinion_visible && !data.opinion_required)
+    && data.reject_return_types.every(value => [0, 1].includes(value)) && (data.can_reject || !data.reject_return_types.length)
+    && (data.opinion_visible || !data.opinion_required) && fields(data.fields)
+    && data.progress.every(step => step.task_id == null || positive(step.task_id));
+}
+function validTask(item, data) {
+  return positive(item.task_id) && require('./attendance-leave-ids.cjs').applicationId(item.application_id) && item.applicant_tenant_id === data.tenant_id
+    && (data.category !== 'pending' || item.task_status === 0)
+    && (data.category !== 'handled' || item.handler_id === data.reviewer_id && item.handler_tenant_id === data.tenant_id && [-1, 1, 2].includes(item.task_status))
+    && (data.category === 'copied' ? positive(item.notice_id) && typeof item.notice_read === 'boolean' : item.notice_id == null);
+}
+async function execute(command, args) {
+  if (['correction-approve', 'correction-reject'].includes(command)) return decide(command, args);
+  const isDetail = command === 'correction-approval';
+  const payload = isDetail ? options(args, ['category', 'task_id', 'notice_id'], [], [], true)
+    : { page: 1, page_size: 20, ...options(args, ['category', 'page', 'page_size', ...require('./attendance-leave-list-filters.cjs').dates, ...require('./attendance-leave-list-filters.cjs').applicants], [], [], true) };
+  if (!isDetail) require('./attendance-leave-list-filters.cjs').validate(payload);
+  requireArguments(payload, 'category');
+  if (!['pending', 'handled', 'copied'].includes(payload.category)) throw invalid('--category 必须为 pending、handled 或 copied。');
+  if (isDetail) {
+    requireArguments(payload, 'task_id');
+    if (!positive(payload.task_id)) throw invalid('--task-id 必须为业务返回的有效审批任务ID。');
+    if (payload.category === 'copied') {
+      requireArguments(payload, 'notice_id'); if (!positive(payload.notice_id)) throw invalid('--notice-id 必须为实际抄送通知ID。');
+    } else if (payload.notice_id !== undefined) throw invalid('仅抄送详情接受 --notice-id。');
+  } else for (const [key, maximum] of [['page', 2147483647], ['page_size', 50]]) {
+    if (!/^\d+$/.test(String(payload[key])) || +payload[key] < 1 || +payload[key] > maximum) throw invalid('--' + key.replaceAll('_', '-') + ' 超出允许范围。');
+    payload[key] = +payload[key];
+  }
+  let envelope;
+  try {
+    const { config, token } = await require('./session.cjs').session('attendance-leave:read');
+    envelope = await gateway.request(config, 'attendance/' + command, token, payload);
+    const result = gateway.publicResult(envelope, isDetail ? detail : page); const data = result.value.data;
+    if (data.category !== payload.category || (isDetail ? !validDetail(data) || data.task.task_id !== payload.task_id
+      || data.task.notice_id !== (payload.notice_id ?? null) : data.page !== payload.page || data.page_size !== payload.page_size
+      || data.total < 0 || data.total_pages !== Math.ceil(data.total / data.page_size)
+      || data.items.length > Math.min(data.page_size, Math.max(0, data.total - (data.page - 1) * data.page_size))
+      || !data.items.every(item => validTask(item, data))
+      || new Set(data.items.map(item => data.category === 'copied' ? item.notice_id : item.task_id)).size !== data.items.length))
+      throw new Failure(1, 'api', 'invalid_response', '补卡审批查询的范围、标识、字段或分页不一致。');
+    if (isDetail && payload.category === 'pending') data.form_check = require('./teacher-leave-form-check.cjs')
+      .evaluate(data, [], { approval: true });
+    return result;
+  } catch (error) {
+    if (error instanceof Failure) {
+      error.result.value.error.details = { ...error.result.value.error.details, ...payload };
+      if (envelope?.request_id) error.result.value.request_id = envelope.request_id;
+    }
+    throw error;
+  }
+}
+async function decide(command, args) {
+  const approve = command === 'correction-approve';
+  const payload = options(args, ['task_id', 'opinion', ...(approve ? ['field_values'] : ['return_to'])], [], [], true);
+  requireArguments(payload, 'task_id');
+  if (!positive(payload.task_id)) throw invalid('--task-id 必须为业务返回的有效审批任务ID。');
+  if (payload.opinion != null && payload.opinion.length > 200) throw invalid('--opinion 最多200个字符。');
+  if (!approve) {
+    requireArguments(payload, 'return_to');
+    const enums = require('./attendance-leave-enums.cjs');
+    payload.return_type = enums.encode(enums.returnTo, payload.return_to, '--return-to');
+    delete payload.return_to;
+  }
+  require('./leave.cjs').parseFieldValues(payload);
+  if (approve) {
+    let current;
+    try {
+      current = await execute('correction-approval', ['--category', 'pending', '--task-id', payload.task_id]);
+    } catch (error) {
+      const failure = error.result?.value?.error;
+      if (failure) {
+        failure.execution_status = 'NOT_EXECUTED';
+        if (['auth_required', 'missing_scope'].includes(failure.subtype))
+          failure.required_scopes = ['attendance-leave:read', 'attendance-leave:approve'];
+      }
+      throw error;
+    }
+    const check = require('./teacher-leave-form-check.cjs').evaluate(current.value.data, payload.field_values, { approval: true });
+    if (current.value.data.opinion_required && !payload.opinion?.trim()) {
+      check.issues.push({ code: 'missing_required', parameter: 'opinion', message: '请补充审批意见。' });
+      if (check.status === 'complete') check.status = 'needs_input';
+    }
+    if (check.status !== 'complete') throw new Failure(2, 'validation', 'form_input_required',
+      '审批表单还有需要处理的信息，尚未上传附件或执行审批。', { execution_status: 'NOT_EXECUTED', form_check: check });
+  }
+  const send = async () => {
+  let envelope;
+  try {
+    const { config, token } = await require('./session.cjs').session('attendance-leave:approve');
+    envelope = await gateway.request(config, 'attendance/' + command, token, payload);
+    const result = gateway.publicResult(envelope, { task_id: required('string'), request_id: required('string'), action: required('string'),
+      application_id: nullable('string'), execution_status: required('string'), post_processing_status: required('string'),
+      application_status: nullable('integer'), message: required('string') });
+    const data = result.value.data;
+    if (data.task_id !== payload.task_id || data.action !== (approve ? 'APPROVE' : 'RETURN')
+      || envelope.request_id != null && data.request_id !== envelope.request_id
+      || data.application_id != null && !require('./attendance-leave-ids.cjs').applicationId(data.application_id)
+      || !require('./command-guidance.cjs').validResult('attendance ' + command, data))
+      throw new Failure(1, 'api', 'invalid_response', '补卡审批回执与任务、请求、动作或执行阶段不一致，结果待核实，不要自动重试。');
+    require('./leave-start-receipt.cjs').project(envelope, result, '补卡审批');
+    return result;
+  } catch (error) {
+    if (error instanceof Failure) {
+      error.result.value.error.details = { ...error.result.value.error.details, task_id: payload.task_id, action: approve ? 'APPROVE' : 'RETURN' };
+      if (envelope?.request_id) error.result.value.request_id = envelope.request_id;
+    }
+    throw error;
+  }
+  };
+  return approve ? require('./teacher-leave-files.cjs').submit(command, payload, send, 'attendance') : send();
+}
+module.exports = { execute };

package/lib/attendance-correction-start.cjs

@@ -0,0 +1,47 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+
+async function execute(args, action) {
+  const payload = options(args, ['date', 'result_id', 'correction_time', 'field_values'], [], [], true);
+  requireArguments(payload, 'date', 'result_id', 'correction_time');
+  const time = payload.correction_time;
+  if (!validTime(time) || time.slice(0, 10) !== payload.date)
+    throw invalid('--correction-time 必须为有效的北京时间 YYYY-MM-DD HH:mm:ss，且属于所选考勤日期。');
+  require('./leave.cjs').parseFieldValues(payload);
+  await require('./attendance.cjs').checkCorrectionBeforeSubmit(payload);
+  return require('./teacher-leave-files.cjs').submit(action, payload, async () => {
+  let envelope;
+  try {
+    const { config, token } = await require('./session.cjs').session('attendance-leave:write');
+    envelope = await gateway.request(config, 'attendance/' + action, token, payload);
+    const result = gateway.publicResult(envelope, {
+      request_id: required('string'), date: required('string'), result_id: required('string'), correction_time: required('string'),
+      program_code: nullable('string'), id: nullable('string'), next_task_id: nullable('string'),
+      application_status: nullable('integer'), execution_status: required('string'), post_processing_status: required('string'), message: required('string'),
+    });
+    const data = result.value.data;
+    const guidance = require('./command-guidance.cjs');
+    if (!validTime(data.correction_time) || data.date !== data.correction_time.slice(0, 10)
+      || data.date !== payload.date || data.result_id !== payload.result_id
+      || time != null && data.correction_time !== time
+      || envelope.request_id != null && envelope.request_id !== data.request_id
+      || !guidance.validResult('attendance ' + action, data))
+      throw new Failure(1, 'api', 'invalid_response', '补卡申请回执与目标、请求或执行阶段不一致，结果待核实，不要自动重试。');
+    require('./leave-start-receipt.cjs').project(envelope, result, '补卡申请');
+    return result;
+  } catch (error) {
+    if (error instanceof Failure) {
+      error.result.value.error.details = { ...error.result.value.error.details, date: payload.date, result_id: payload.result_id, correction_time: time };
+      if (envelope?.request_id) error.result.value.request_id = envelope.request_id;
+    }
+    throw error;
+  }
+  }, 'attendance');
+}
+function validTime(time) {
+  if (typeof time !== 'string' || !/^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$/.test(time) || +time.slice(0, 4) < 1) return false;
+  const instant = Date.parse(time.replace(' ', 'T') + '+08:00');
+  return Number.isFinite(instant) && new Date(instant + 8 * 3600 * 1000).toISOString().slice(0, 19).replace('T', ' ') === time;
+}
+module.exports = { execute };

package/lib/attendance-leave-enums.cjs

@@ -0,0 +1,193 @@
+const { invalid, Failure } = require('./result.cjs');
+
+const direction = { in: '1', out: '2' };
+const clockDirection = { none: '0', ...direction };
+const returnTo = { start: 0, previous: 1 };
+const gateStatus = { unknown: 0, 'normal-in': 1, 'normal-out': 2, late: -1, 'early-leave': -2,
+  'missing-clock': -3, 'on-leave': -6, 'stay-school': -7, 'school-dismissed': -8 };
+const dormitoryStatus = { 'normal-out': 11, 'normal-in': 12, 'late-in': 13, 'late-out': 14,
+  'missing-out': 15, 'missing-in': 16, 'on-leave': -6 };
+const workflowStatus = { withdrawn: -2, returned: -1, draft: 0, processing: 1, completed: 2 };
+const studentBusinessStatus = { 'not-started': -2, 'handled-by-peer': -1, pending: 0, approved: 1, rejected: 2, withdrawn: 3 };
+const taskStatus = { withdrawn: -2, returned: -1, pending: 0, transferred: 1, completed: 2 };
+const nodeType = { start: 0, normal: 1, end: 10 };
+const attendanceType = { 'student-gate': '1', dormitory: '2', teacher: '4' };
+const clockSource = { device: 1, location: 2, correction: 3, 'off-site': 4 };
+const resumptionStatus = { 'not-resumed': '0', resumed: '1' };
+const resumptionSource = { workflow: 1, 'automatic-clock': 2 };
+// Saved reports use KqConstant, not the daily dormitory status codes.
+const reportStatus = { unknown: '0', 'normal-in': '1', 'normal-out': '2', 'in-dormitory': '4',
+  late: '-1', 'early-leave': '-2', 'missing-clock': '-3', 'no-record': '-4', 'manual-entry': '-5', 'on-leave': '-6' };
+const reportGroup = { total: '3', ...reportStatus };
+const reportScope = { class: '1', school: '2', grade: '3', tag: '6' };
+const dormitoryReportScope = { 'dormitory-group': '4', school: '5' };
+const reportDirection = { unknown: '0', ...direction };
+const reportDetailType = { class: '1', total: '2' };
+const retireState = { 'all-in': '1', 'not-all-in': '2' };
+
+function encode(values, value, flag) {
+  if (!Object.hasOwn(values, value)) throw invalid(flag + ' 必须为 ' + Object.keys(values).join('、') + '。');
+  return values[value];
+}
+function decode(values, value, field) {
+  if (value == null) return value;
+  const match = Object.entries(values).find(([, code]) => String(code) === String(value));
+  if (!match) throw new Failure(1, 'api', 'invalid_response', '返回的 ' + field + ' 包含无法识别的业务编码。', { details: { field, value } });
+  return match[0];
+}
+function field(row, key, values) {
+  if (!row || !Object.hasOwn(row, key) || row[key] == null) return;
+  const match = Object.entries(values).find(([, code]) => String(code) === String(row[key]));
+  if (match) row[key] = match[0];
+  else {
+    row[key + '_code'] = row[key];
+    row[key] = 'unknown';
+  }
+}
+function studentRecord(row) {
+  field(row, 'status', studentBusinessStatus);
+  field(row, 'workflow_status', workflowStatus);
+  leaveFacts(row);
+  if (row.original_leave) studentRecord(row.original_leave);
+  for (const resumption of row.resumptions || []) studentRecord(resumption);
+}
+
+function leaveFacts(row) {
+  field(row, 'resumption_status', resumptionStatus);
+  field(row, 'resumption_source', resumptionSource);
+  for (const step of row.progress || []) {
+    field(step, 'status', taskStatus);
+    field(step, 'node_type', nodeType);
+  }
+}
+
+function attendanceDirection(row, dormitory) {
+  if (!row || !Object.hasOwn(row, 'in_out_type')) return;
+  row.direction = row.in_out_type;
+  delete row.in_out_type;
+  field(row, 'direction', clockDirection);
+  row.direction_name = row.direction == null ? null : row.direction === 'in' ? dormitory ? '归寝' : '进校'
+    : row.direction === 'out' ? dormitory ? '出寝' : '出校' : row.direction === 'none' ? '不分进出' : '未知方向';
+}
+
+function savedReports(data, dormitory) {
+  for (const report of data.reports || (data.report ? [data.report] : [])) {
+    if (dormitory && require('./dormitory-report-id.cjs').currentReport(report.report_id)) continue;
+    field(report, 'scope_type', dormitory ? dormitoryReportScope : reportScope);
+    field(report, 'direction', reportDirection);
+  }
+  const rows = row => {
+    field(row, 'status', reportStatus);
+    field(row, 'direction', reportDirection);
+  };
+  for (const group of data.groups || []) {
+    field(group, 'type', reportGroup);
+    for (const row of group.rows) rows(row);
+  }
+  for (const row of data.rows || []) rows(row);
+  if (dormitory) for (const row of [data.total, ...(data.bedrooms || [])]) field(row, 'retire_state', retireState);
+  else for (const row of [data.total, ...(data.classes || [])]) field(row, 'detail_type', reportDetailType);
+}
+
+// Applied only after native response validation; dynamic form values and numeric quantities are untouched.
+function project(command, data) {
+  const [domain, action] = command.split(' ');
+  const dormitory = domain === 'dormitory-attendance';
+  if (['student-attendance', 'dormitory-attendance'].includes(domain)
+      && ['reports', 'report-summary', 'report-class', 'report-tag', 'report-group', 'report-room'].includes(action))
+    savedReports(data, dormitory);
+  if (['attendance', 'student-attendance', 'dormitory-attendance'].includes(domain)) {
+    field(data, 'attendance_type', attendanceType);
+    const statuses = dormitory ? dormitoryStatus : gateStatus;
+    const result = row => { field(row, 'status', statuses); attendanceDirection(row, dormitory); };
+    if (domain === 'attendance' && action === 'correction-form') result(data.result);
+    if (action === 'list') for (const row of data.items) {
+      result(row.result);
+      field(row, 'clock_method', clockSource);
+    }
+    if (dormitory && action === 'report-room' && data.saved_room) for (const row of data.saved_room.records) {
+      result(row.result);
+      field(row, 'clock_method', clockSource);
+    }
+    if (dormitory) require('./dormitory-report-view.cjs').project(data, action);
+    if (action === 'show') {
+      const day = data.day || data;
+      for (const row of day.attendance_results) result(row);
+      for (const row of day.clock_records) {
+        attendanceDirection(row, dormitory);
+        field(row, 'source', clockSource);
+      }
+      for (const rule of day.rules) for (const shift of rule.shifts) attendanceDirection(shift, dormitory);
+    }
+    if (action === 'applicable-rule') for (const shift of data.rule?.shifts || []) attendanceDirection(shift, dormitory);
+    if (domain === 'attendance' && action === 'statistics') for (const row of data.items) {
+      row.has_leave = row.leave_flag == null ? null : row.leave_flag === 1;
+      delete row.leave_flag;
+    }
+    if (dormitory && ['statistics', 'export'].includes(action)) field(data, 'status', statuses);
+  }
+  if (['student-attendance', 'dormitory-attendance'].includes(domain)
+      && ['manual-entry', 'manual-entries'].includes(action)) {
+    const directions = dormitory ? { none: '0' } : direction;
+    field(data, 'direction', directions);
+    for (const option of data.options || []) field(option, 'direction', directions);
+    for (const row of data.records || []) field(row, 'direction', directions);
+  }
+  if (['leave', 'student-leave', 'attendance'].includes(domain)
+      && ['approval', 'resumption-approval', 'correction-approval'].includes(action)) {
+    field(data, 'status', workflowStatus);
+    field(data.task, 'task_status', taskStatus);
+    leaveFacts(data);
+    data.reject_return_targets = data.reject_return_types.map(value => decode(returnTo, value, 'reject_return_targets'));
+    delete data.reject_return_types;
+  }
+  if (['leave', 'student-leave', 'attendance'].includes(domain)) {
+    field(data, 'application_status', workflowStatus);
+    if (['approvals', 'resumption-approvals', 'correction-approvals'].includes(action))
+      for (const row of data.items) field(row, 'task_status', taskStatus);
+  }
+  if (domain === 'attendance' && ['correction-list', 'correction-show'].includes(action)) {
+    for (const row of action === 'correction-list' ? data.items : [data]) {
+      field(row, 'status', workflowStatus);
+      leaveFacts(row);
+    }
+  }
+  if (domain === 'leave' && ['list', 'show', 'resumption-list', 'resumption-show'].includes(action)) {
+    for (const row of action.endsWith('list') ? data.items : [data]) {
+      field(row, 'workflow_status', workflowStatus);
+      field(row, 'business_status', studentBusinessStatus);
+      leaveFacts(row);
+      for (const resumption of row.resumption_applications || []) field(resumption, 'status', studentBusinessStatus);
+    }
+  }
+  if (domain === 'student-leave' && ['list', 'show', 'resumption-list', 'resumption-show'].includes(action)) {
+    for (const row of action.endsWith('list') ? data.items : [data]) {
+      field(row, 'workflow_status', workflowStatus);
+      leaveFacts(row);
+      for (const record of row.records || []) studentRecord(record);
+    }
+  }
+}
+function projectError(command, error) {
+  const details = error.details;
+  if (!details || typeof details !== 'object') return;
+  const [domain, action] = command.split(' ');
+  const statuses = domain === 'attendance' && action === 'correction-list' ? workflowStatus
+    : domain === 'student-leave' && ['list', 'resumption-list'].includes(action)
+      ? details.scope === 'mine' ? workflowStatus : details.scope === 'managed' ? studentBusinessStatus : null
+      : ['attendance', 'student-attendance', 'dormitory-attendance'].includes(domain) && ['list', 'statistics', 'export'].includes(action)
+        ? domain === 'dormitory-attendance' ? dormitoryStatus : gateStatus : null;
+  if (statuses && Object.values(statuses).includes(details.status)) field(details, 'status', statuses);
+  // Keep unknown response facts as diagnostic evidence; only known request selectors are translated.
+  if (/^(student|dormitory)-attendance manual-entry$/.test(command) && details.direction != null) {
+    const values = command.startsWith('student-') ? direction : { none: '0' };
+    const match = Object.entries(values).find(([, code]) => code === details.direction);
+    if (match) details.direction = match[0];
+  }
+  if (/^(leave|student-leave|attendance) (reject|resumption-reject|correction-reject)$/.test(command)
+      && Object.values(returnTo).includes(details.return_type)) {
+    details.return_to = decode(returnTo, details.return_type, 'return_to');
+    delete details.return_type;
+  }
+}
+module.exports = { direction, returnTo, gateStatus, dormitoryStatus, workflowStatus, studentBusinessStatus, encode, project, projectError };

package/lib/attendance-leave-ids.cjs

@@ -0,0 +1,15 @@
+function applicationId(value, purpose) {
+  const prefix = purpose === 'TEACHER_LEAVE' ? 'leave_a_' : purpose === 'TEACHER_RESUMPTION' ? 'resumption_a_' : purpose === 'STUDENT_LEAVE' ? 'student_leave_a_' : purpose === 'STUDENT_RESUMPTION' ? 'student_resumption_a_' : 'application_';
+  return typeof value === 'string' && new RegExp('^' + prefix + '[1-9][0-9]{0,18}$').test(value)
+    && BigInt(value.slice(prefix.length)) <= 9223372036854775807n;
+}
+const positiveId = value => typeof value === 'string' && /^[1-9][0-9]*$/.test(value) && BigInt(value) <= 9223372036854775807n;
+function replenishmentId(value, type, date) {
+  if (typeof value !== 'string') return false;
+  const match = /^replenishment_([12])_([0-9]{8})_([1-9][0-9]{0,9})$/.exec(value);
+  if (!match || match[1] !== type || Number(match[3]) > 2147483647) return false;
+  const day = match[2].slice(0, 4) + '-' + match[2].slice(4, 6) + '-' + match[2].slice(6);
+  return +match[2].slice(0, 4) > 0 && Number.isFinite(Date.parse(day)) && new Date(day).toISOString().slice(0, 10) === day
+    && (date == null || date === day);
+}
+module.exports = { applicationId, positiveId, replenishmentId };

package/lib/attendance-leave-list-filters.cjs

@@ -0,0 +1,21 @@
+const { invalid } = require('./result.cjs');
+const dates = ['start_date', 'end_date', 'submitted_start_date', 'submitted_end_date'];
+const applicants = ['applicant_id', 'applicant_name'];
+const subjects = ['subject_id', 'subject_name'];
+function validate(payload) {
+  for (const [start, end] of [['start_date', 'end_date'], ['submitted_start_date', 'submitted_end_date']]) {
+    if (payload[start] === undefined && payload[end] === undefined) continue;
+    for (const key of [start, end]) {
+      const value = payload[key];
+      if (typeof value !== 'string' || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/.test(value)
+          || +value.slice(0, 4) < 1 || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString().slice(0, 10) !== value)
+        throw invalid('--' + start.replaceAll('_', '-') + ' 与 --' + end.replaceAll('_', '-') + ' 须成对提供有效的 YYYY-MM-DD 日期。');
+    }
+    if (payload[start] > payload[end]) throw invalid('开始日期不能晚于结束日期。');
+  }
+  for (const key of [...applicants, ...subjects]) {
+    if (payload[key] !== undefined && (!payload[key].trim() || payload[key].length > 100))
+      throw invalid('--' + key.replaceAll('_', '-') + ' 须为 1 到 100 个字符。');
+  }
+}
+module.exports = { dates, applicants, subjects, validate };

package/lib/attendance-leave-route.cjs

@@ -0,0 +1,20 @@
+// Public CLI names map to the existing Gateway contract; no old CLI aliases are registered.
+const leaveActions = {
+  submit: 'start', remind: 'urge',
+  'resumption-submit': 'resumption-start', 'resumption-remind': 'resumption-urge',
+  'form-people-search': 'form-users', 'resumption-form-people-search': 'resumption-form-users',
+  'approval-form-people-search': 'approval-form-users',
+  'resumption-approval-form-people-search': 'resumption-approval-form-users',
+};
+const correctionActions = {
+  'correction-submit': 'correction-start',
+  'correction-form-people-search': 'correction-form-users',
+  'correction-approval-form-people-search': 'correction-approval-form-users',
+};
+function endpoint(path) {
+  const [space, action, ...rest] = path.split('/');
+  const names = ['leave', 'student-leave'].includes(space) ? leaveActions
+    : space === 'attendance' ? correctionActions : {};
+  return [space, names[action] || action, ...rest].join('/');
+}
+module.exports = { endpoint };