@xiaoyuanhao/yunzhi-cli 2.0.0 → 2.1.0

package/lib/leave.cjs

@@ -0,0 +1,457 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, optional, invalid, internal, fields: projectFields } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+
+function formAnswer(value, path, field, configuredDefault = false) {
+  const fail = () => { throw new Error(`响应字段 ${path} 与表单类型 ${field.type} 不一致。`); };
+  const identityKey = { person: 'user_id', people: 'user_id', department: 'department_id', departments: 'department_id',
+    organization: 'tenant_id', organizations: 'tenant_id' }[field.type];
+  if (identityKey) {
+    if (!Array.isArray(value) || ['person', 'department', 'organization'].includes(field.type) && value.length > 1) return fail();
+    return projectFields(value, [{ tenant_id: required('string'), [identityKey]: required('string') }], path);
+  }
+  if (field.type === 'table' || field.type == null) return fail();
+  if (field.type === 'choices') return projectFields(value, [required('string')], path);
+  if (configuredDefault) return typeof value === 'string' ? value : fail();
+  if (field.type === 'choice') {
+    if (typeof value === 'string') return value;
+    if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.other_text !== 'string') return fail();
+    return projectFields(value, { option_id: required('string'), other_text: 'string' }, path);
+  }
+  if (field.type === 'images') {
+    if (field.attachment_upload_supported === true && typeof value === 'string') return value;
+    if (typeof field.attachment_upload_supported !== 'boolean' || !Array.isArray(value)) return fail();
+    return value.map((item, index) => {
+      if (!item || typeof item !== 'object' || Array.isArray(item)) return fail();
+      for (const key of ['width', 'height']) if (item[key] != null && (!Number.isFinite(item[key]) || item[key] < 0)) return fail();
+      return projectFields(item, { url: required('string'), width: optional('number'), height: optional('number') }, `${path}[${index}]`);
+    });
+  }
+  if (!['text', 'multiline_text', 'number', 'date', 'datetime', 'files', 'signature', 'location', 'link', 'separator'].includes(field.type)) return fail();
+  return typeof value === 'string' ? value : fail();
+}
+
+function formField(field, path, scope = 'form') {
+  const result = projectFields(field, { ...formFieldSchema,
+    value: nullable((value, valuePath) => formAnswer(value, valuePath, field)),
+    default_value: nullable((value, valuePath) => formAnswer(value, valuePath, field, true)),
+  }, path);
+  if (result.visibility && (result.visibility.scope !== scope || !result.visibility.requires_visible_controller
+      || !result.visibility.any_of.length)) throw new Error(`响应字段 ${path}.visibility 的作用域或显示规则无效。`);
+  return result;
+}
+
+const formOptions = nullable([{ option_id: required('string'), label: required('string'),
+  code: nullable('string'), default_selected: nullable('boolean'), shows_fields: nullable([required('string')]) }]);
+const formConfiguration = nullable([{ code: nullable('string'), label: nullable('string'),
+  value: nullable('string'), default_selected: nullable('boolean') }]);
+function validationRule(value, path) {
+  const rule = projectFields(value, { type: required('string'), minimum: nullable('string'),
+    maximum: nullable('string'), inclusive: nullable('boolean') }, path);
+  if (!['required', 'unique', 'phone', 'identity_card', 'number', 'number_range'].includes(rule.type))
+    throw new Error(`响应字段 ${path}.type 包含无法解释的校验规则。`);
+  if (rule.type === 'number_range') {
+    if (rule.inclusive !== true || !Object.hasOwn(value, 'minimum') || !Object.hasOwn(value, 'maximum')
+        || [rule.minimum, rule.maximum].some(bound => bound !== null && !/^-?[0-9]+(\.[0-9]+)?$/.test(bound)))
+      throw new Error(`响应字段 ${path} 缺少有效的数值范围及包含边界说明。`);
+  } else if (rule.minimum != null || rule.maximum != null || rule.inclusive != null)
+    throw new Error(`响应字段 ${path} 在非范围规则中包含数值边界。`);
+  return rule;
+}
+function formatRule(value, path) {
+  const rule = projectFields(value, { type: required('string'), digits: nullable('integer'), rounding: nullable('string') }, path);
+  if (rule.type !== 'decimal_places' || !Object.hasOwn(value, 'digits') || !Object.hasOwn(value, 'rounding')
+      || (rule.digits === null ? rule.rounding !== null : rule.digits < 0 || rule.digits > 2147483647 || rule.rounding !== 'half_up'))
+    throw new Error(`响应字段 ${path} 缺少有效的小数位数及格式化说明。`);
+  return rule;
+}
+function calculation(value, path) {
+  const result = projectFields(value, { evaluated_by: required('string'), parts: required([(part, partPath) => {
+    const projected = projectFields(part, { type: required('string'), text: nullable('string'), field_key: nullable('string') }, partPath);
+    if (projected.type === 'text' ? !projected.text || projected.field_key !== null
+        : projected.type !== 'field_reference' || !projected.field_key?.trim() || projected.text !== null)
+      throw new Error(`响应字段 ${partPath} 缺少有效的表达式片段或字段引用。`);
+    return projected;
+  }]) }, path);
+  if (result.evaluated_by !== 'server' || !result.parts.length)
+    throw new Error(`响应字段 ${path} 缺少服务端求值说明或表达式。`);
+  return result;
+}
+const formFieldSchema = {
+  widget_id: required('string'), field_key: required('string'), type: required('string'),
+  editable: required('boolean'), required: required('boolean'), validation_rules: nullable([validationRule]),
+  format_rules: nullable([formatRule]),
+  calculation: nullable(calculation),
+  calculation_links: nullable([{ field_key: required('string'), calculation: required(calculation) }]),
+  attachment_upload_supported: nullable('boolean'),
+  options: formOptions, configuration: formConfiguration,
+  display_value: nullable('string'),
+  visibility: nullable({ scope: required('string'), requires_visible_controller: required('boolean'),
+    any_of: required([{ field_key: required('string'), option_code: required('string') }]) }),
+  candidate_users: nullable([{ tenant_id: required('string'), tenant_name: nullable('string'),
+    user_id: required('string'), name: nullable('string'), default_selected: nullable('boolean') }]),
+  candidate_departments: nullable([{ tenant_id: required('string'), department_id: required('string'),
+    name: nullable('string'), default_selected: nullable('boolean') }]),
+  candidate_organizations: nullable([{ tenant_id: required('string'), name: nullable('string'), default_selected: nullable('boolean') }]),
+  ...Object.fromEntries(['label', 'description',
+    'file_type', 'select_id', 'user_assembly_id']
+    .map(key => [key, nullable('string')])),
+};
+formFieldSchema.groups = nullable([(group, path) => {
+  const value = projectFields(group, { group_code: nullable('string'),
+    fields: required([(field, childPath) => formField(field, childPath, 'row')]) }, path);
+  return value;
+}]);
+
+formFieldSchema.row_template = nullable([(field, path) => formField(field, path, 'row')]);
+
+// Application preparation uses this compact view. Saved details and approvals retain their contracts.
+function teacherFormField(field, path, scope = 'form') {
+  const schema = { ...formFieldSchema };
+  for (const key of ['widget_id', 'select_id', 'user_assembly_id', 'configuration', 'calculation', 'calculation_links']) delete schema[key];
+  Object.assign(schema, {
+    computed: required('boolean'), person_search_supported: optional(required('boolean')),
+    options: nullable([{ option_id: required('string'), label: required('string'), code: nullable('string'), default_selected: nullable('boolean') }]),
+    value: nullable((value, at) => formAnswer(value, at, field)),
+    default_value: nullable((value, at) => formAnswer(value, at, field, true)),
+    attachment_limits: optional({ upload_max_bytes: required('integer'), max_files: optional(required('integer')),
+      min_size_mib: optional(required('string')), max_size_mib: optional(required('string')) }),
+    groups: nullable([{ group_code: nullable('string'), fields: required([(child, at) => teacherFormField(child, at, 'row')]) }]),
+    row_template: nullable([(child, at) => teacherFormField(child, at, 'row')]),
+  });
+  const result = projectFields(field, schema, path);
+  if (result.visibility && (result.visibility.scope !== scope || !result.visibility.requires_visible_controller || !result.visibility.any_of.length))
+    throw new Error('表单显示规则的作用域无效。');
+  if (result.computed && !['number', 'text'].includes(result.type)) throw new Error('计算字段类型无效。');
+  if (['person', 'people'].includes(result.type) && typeof result.person_search_supported !== 'boolean')
+    throw new Error('选人字段缺少搜索能力说明。');
+  if (['files', 'images'].includes(result.type)) {
+    const limits = result.attachment_limits;
+    if (!limits || limits.upload_max_bytes !== 209715200 || result.type === 'images' && (limits.max_files !== 10
+        || !/^\d+(\.\d+)?$/.test(limits.min_size_mib || '') || !/^\d+(\.\d+)?$/.test(limits.max_size_mib || '')))
+      throw new Error('附件字段缺少有效限制。');
+  }
+  // Unknown values stay null; absent optional capabilities do not clutter the form.
+  for (const [key, value] of Object.entries(result))
+    if (value === null && !['value', 'default_value', 'display_value'].includes(key)
+        && !(key === 'candidate_users' && ['person', 'people'].includes(result.type))
+        && !(key === 'candidate_departments' && ['department', 'departments'].includes(result.type))
+        && !(key === 'candidate_organizations' && ['organization', 'organizations'].includes(result.type))) delete result[key];
+  return result;
+}
+
+function teacherForm(data, path, request, resumption) {
+  if (!data || !['ready', 'selection_required', 'unavailable'].includes(data.status)) throw new Error('表单返回了未知状态。');
+  if (resumption && data.leave_id !== request.leave_id) throw new Error('销假表单与原请假不一致。');
+  if (data.status !== 'ready') {
+    const result = projectFields(data, { status: required('string'), ...(resumption ? { leave_id: required('string') } : {}),
+      choices: required([{ program_code: required('string'), name: required('string') }]) }, path);
+    if (request.program_code !== undefined || result.status === 'unavailable' && result.choices.length !== 0
+        || result.status === 'selection_required' && (result.choices.length < 2 || new Set(result.choices.map(item => item.program_code)).size !== result.choices.length))
+      throw new Error('流程选择状态与候选项不一致。');
+    return result;
+  }
+  const result = projectFields(data, { status: required('string'), program_code: required('string'), fields: required([teacherFormField]),
+    ...(resumption ? {
+      leave_id: required('string'), tenant_id: required('string'), user_id: required('string'),
+      user_name: nullable('string'), leave_type: nullable('string'), leave_start_time: required('string'), leave_end_time: required('string'),
+      field_mappings: required(Object.fromEntries(['leaveId', 'userName', 'leaveType', 'askForLeaveTime', 'askForBackTime', 'revokeLeaveStartTime', 'revokeLeaveReason']
+        .map(key => [key, optional(required('string'))]))),
+    } : {}),
+  }, path);
+  if (request.program_code !== undefined && result.program_code !== request.program_code) throw new Error('表单流程与指定流程不一致。');
+  return result;
+}
+
+async function readTeacherForm(payload, resumption) {
+  const request = { ...(payload.program_code !== undefined ? { program_code: payload.program_code } : {}),
+    ...(resumption ? { leave_id: payload.leave_id } : {}) };
+  const result = await gateway.execute('attendance-leave:read', 'leave/' + (resumption ? 'resumption-form' : 'form'), request,
+    (data, path) => teacherForm(data, path, request, resumption));
+  if (result.value.data.status === 'ready') result.value.data.form_check = require('./teacher-leave-form-check.cjs')
+    .evaluate(result.value.data, payload.field_values, payload);
+  return result;
+}
+
+const approvalTask = {
+  task_id: required('string'), application_id: required('string'), title: nullable('string'),
+  applicant_id: required('string'), applicant_tenant_id: required('string'), applicant_name: 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'),
+  leave_subjects: required([{ leave_id: required('string'), user_id: required('string'), user_name: nullable('string') }]),
+};
+
+function parseFieldValues(payload) {
+  if (payload.field_values !== undefined) {
+    let input = payload.field_values;
+    if (input.startsWith('@')) {
+      const file = input.slice(1);
+      if (!file.trim()) throw invalid('--field-values 的 @ 后必须提供本地 JSON 文件路径。');
+      try { input = require('node:fs').readFileSync(file, 'utf8').replace(/^\uFEFF/, ''); }
+      catch (error) { throw internal('read_field_values', '无法读取表单 JSON 文件，业务请求尚未发送：' + file, error); }
+    }
+    try { payload.field_values = JSON.parse(input); }
+    catch { throw invalid('--field-values 必须是有效的 JSON 数组。'); }
+    if (!validFieldValues(payload.field_values) || payload.field_values.length > 100)
+      throw invalid('--field-values 最多 100 项，每项只包含非空 field_key 和 value；value 为文本、数字、数组或对象，子表行直接包含 fields 数组。');
+  }
+}
+
+function validFieldValues(fields) {
+  return Array.isArray(fields) && fields.every(field =>
+    field && typeof field === 'object' && !Array.isArray(field) && typeof field.field_key === 'string' && field.field_key.trim()
+    && Object.keys(field).length === 2 && Object.hasOwn(field, 'value') && field.value != null
+    && ['string', 'number', 'object'].includes(typeof field.value)
+    && (typeof field.value !== 'number' || Number.isFinite(field.value))
+    && (!Array.isArray(field.value) || field.value.every(row => !row || typeof row !== 'object' || !Object.hasOwn(row, 'fields') || validFieldValues(row.fields))));
+}
+
+async function executeResumptionOperation(command, args, domain) {
+  const own = domain === 'leave', key = 'id';
+  const payload = options(args, [key], [], [], true);
+  requireArguments(payload, key);
+  if (own ? !require('./teacher-leave-query.cjs').validId(payload.id, 'resumption_')
+    : !require('./student-leave-query.cjs').validId(payload[key], true, true))
+    throw invalid('使用销假提交或查询返回的 ID。');
+  const result = await gateway.execute('attendance-leave:write', domain + '/' + command, payload, {
+    [key]: required('string'), event: required('string'),
+    ...(command === 'resumption-remind' ? { notified_count: required('integer') } : { withdrawn: required('boolean') }),
+  });
+  if (result.value.data[key] !== payload[key]) {
+    const failure = new (require('./result.cjs').Failure)(1, 'api', 'invalid_response', '销假操作回执与指定申请不一致，请查询目标申请，不要自动重试。',
+      { details: { [key]: payload[key], action: command === 'resumption-remind' ? 'remind' : 'withdraw' } });
+    if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+    throw failure;
+  }
+  return result;
+}
+
+async function validateStudentForm(payload) {
+  const domain = 'student-leave';
+  const result = await gateway.execute('attendance-leave:read', domain + '/form/check', payload, {
+    student_id: required('string'), class_id: required('string'),
+    tenant_id: required('string'), user_id: required('string'), program_code: required('string'),
+    form_id: required('string'), valid: required('boolean'),
+    issue: nullable({ field_key: nullable('string'), parent_field_key: nullable('string'),
+      row_index: nullable('integer'), message: required('string') }),
+  });
+  const data = result.value.data, issue = data.issue;
+  if (data.student_id !== payload.student_id || data.class_id !== payload.class_id
+    || !data.tenant_id.trim() || !data.user_id.trim() || data.program_code !== payload.program_code
+    || !/^[1-9][0-9]*$/.test(data.form_id) || BigInt(data.form_id) > 9223372036854775807n
+    || data.valid !== (issue === null)
+    || issue !== null && (!issue.message.trim() || issue.field_key !== null && !issue.field_key.trim()
+      || issue.parent_field_key !== null && !issue.parent_field_key.trim()
+      || (issue.parent_field_key === null) !== (issue.row_index === null)
+      || issue.row_index !== null && issue.row_index < 0)) {
+    const failure = new (require('./result.cjs').Failure)(1, 'api', 'invalid_response',
+      '预检回执与流程、字段位置或校验状态不一致，未确认校验结果。');
+    if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+    throw failure;
+  }
+  return result;
+}
+
+async function execute(command, args) {
+  if (['list', 'show', 'resumption-list', 'resumption-show'].includes(command))
+    return require('./teacher-leave-query.cjs').execute(command, args, formField);
+  if (['resumption-remind', 'resumption-withdraw'].includes(command)) return executeResumptionOperation(command, args, 'leave');
+  if (command === 'form' || command === 'resumption-form') {
+    const resumption = command === 'resumption-form';
+    const payload = options(args, ['program_code', 'field_values', ...(resumption ? ['leave_id', 'resumption_time', 'reason'] : [])], [], [], true);
+    if (resumption) {
+      requireArguments(payload, 'leave_id');
+      if (!require('./teacher-leave-query.cjs').validId(payload.leave_id, 'leave_'))
+        throw invalid('--leave-id 必须是原请假的有效业务记录 ID。');
+    }
+    if (payload.program_code !== undefined && !payload.program_code.trim()) throw invalid('--workflow-code 不能是空白。');
+    if (payload.resumption_time !== undefined) validateResumptionTime(payload.resumption_time);
+    if (payload.reason !== undefined && payload.reason.length > 100) throw invalid('--reason 最多 100 字。');
+    parseFieldValues(payload);
+    return readTeacherForm(payload, resumption);
+  }
+
+  if (['submit', 'resumption-submit'].includes(command)) return executeStart(command, args, 'leave');
+  if (['approve', 'reject', 'approval', 'approvals', 'resumption-approve', 'resumption-reject', 'resumption-approval', 'resumption-approvals'].includes(command))
+    return executeApproval(command, args, 'leave');
+  if (['remind', 'withdraw'].includes(command)) {
+    const payload = options(args, ['id'], [], [], true);
+    requireArguments(payload, 'id');
+    if (!require('./teacher-leave-query.cjs').validId(payload.id, 'leave_'))
+      throw invalid('--id 使用请假提交或查询返回的 ID。');
+    const result = await gateway.execute('attendance-leave:write', 'leave/' + command, payload, {
+      id: required('string'), event: required('string'),
+      ...(command === 'remind' ? { notified_count: required('integer') } : { withdrawn: required('boolean') }),
+    });
+    if (result.value.data.id !== payload.id) {
+      const failure = new (require('./result.cjs').Failure)(1, 'api', 'invalid_response', '请假操作回执与目标不一致，请查询目标申请，不要自动重试。',
+        { details: { id: payload.id, action: command } });
+      if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+      throw failure;
+    }
+    return result;
+  }
+  throw invalid('未知的本人请假命令。');
+}
+
+async function executeApproval(command, args, domain) {
+  if (['approve', 'reject', 'resumption-approve', 'resumption-reject'].includes(command)) {
+    const payload = options(args, ['task_id', 'opinion', ...(['reject', 'resumption-reject'].includes(command) ? ['return_to'] : ['field_values'])], [], [], true);
+    requireArguments(payload, 'task_id');
+    if (!/^[1-9][0-9]*$/.test(payload.task_id) || BigInt(payload.task_id) > 9223372036854775807n)
+      throw invalid('--task-id 必须是业务返回的有效审批任务 ID。');
+    if (['reject', 'resumption-reject'].includes(command)) {
+      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;
+    }
+    parseFieldValues(payload);
+    if (['approve', 'resumption-approve'].includes(command)) {
+      let detail;
+      try {
+        detail = await executeApproval(command === 'approve' ? 'approval' : 'resumption-approval',
+          ['--category', 'pending', '--task-id', payload.task_id], domain);
+      } 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(detail.value.data, payload.field_values, { approval: true });
+      if (detail.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 (require('./result.cjs').Failure)(2, 'validation', 'form_input_required',
+        '审批表单还有需要处理的信息，尚未上传附件或执行审批。', { execution_status: 'NOT_EXECUTED', form_check: check });
+    }
+    const submit = ['approve', 'resumption-approve'].includes(command) ? require('./leave-approval-receipt.cjs').execute : gateway.execute;
+    const send = async () => {
+      const result = await submit('attendance-leave:approve', domain + '/' + command, payload, {
+        task_id: required('string'), request_id: required('string'), action: required('string'),
+        execution_status: required('string'), post_processing_status: required('string'),
+        application_id: nullable('string'), application_status: nullable('integer'), message: required('string'),
+      });
+      if (result.value.data.task_id !== payload.task_id) {
+        const failure = new (require('./result.cjs').Failure)(1, 'api', 'invalid_response', '审批回执任务与请求不一致，结果待核实，不要自动重试。',
+          { details: { task_id: payload.task_id, request_id: result.value.data.request_id } });
+        if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+        throw failure;
+      }
+      return result;
+    };
+    return ['approve', 'resumption-approve'].includes(command)
+      ? require('./teacher-leave-files.cjs').submit(command, payload, send, domain) : send();
+  }
+  if (['approval', 'resumption-approval'].includes(command)) {
+    const payload = options(args, ['category', 'task_id', 'notice_id'], [], [], true);
+    requireArguments(payload, 'category', 'task_id');
+    if (!['pending', 'handled', 'copied'].includes(payload.category))
+      throw invalid('--category 必须为 pending、handled 或 copied。');
+    if (payload.category === 'copied') requireArguments(payload, 'notice_id');
+    else if (payload.notice_id !== undefined) throw invalid('仅抄送详情接受 --notice-id。');
+    for (const key of ['task_id', 'notice_id']) {
+      if (payload[key] !== undefined && (!/^[1-9][0-9]*$/.test(payload[key]) || BigInt(payload[key]) > 9223372036854775807n))
+        throw invalid('--' + key.replaceAll('_', '-') + ' 必须是业务返回的有效标识。');
+    }
+    const result = await gateway.execute('attendance-leave:read', domain + '/' + command, payload, {
+      category: required('string'), tenant_id: required('string'), reviewer_id: required('string'), task: required(approvalTask),
+      form_id: required('string'), status: required('integer'), status_description: nullable('string'),
+      fields: required([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') }]),
+      attachments: required([require('./teacher-leave-files.cjs').attachment]),
+      can_approve: required('boolean'), can_reject: required('boolean'), opinion_visible: required('boolean'),
+      opinion_required: required('boolean'), reject_return_types: required(['integer']),
+    });
+    require('./teacher-leave-files.cjs').displayAttachments(result.value.data);
+    if (payload.category === 'pending') result.value.data.form_check = require('./teacher-leave-form-check.cjs')
+      .evaluate(result.value.data, [], { approval: true });
+    return result;
+  }
+  if (['approvals', 'resumption-approvals'].includes(command)) {
+    const payload = { 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, ...require('./attendance-leave-list-filters.cjs').subjects], [], [], true) };
+    require('./attendance-leave-list-filters.cjs').validate(payload);
+    requireArguments(payload, 'category');
+    if (!['pending', 'handled', 'copied'].includes(payload.category))
+      throw invalid('--category 必须为 pending、handled 或 copied。');
+    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('_', '-') + ' 必须在 1 到 ' + maximum + ' 之间。');
+      payload[key] = +payload[key];
+    }
+    return gateway.execute('attendance-leave:read', domain + '/' + command, payload, {
+      category: required('string'), tenant_id: required('string'), reviewer_id: required('string'),
+      page: required('integer'), page_size: required('integer'), total: required('integer'), total_pages: required('integer'),
+      items: required([approvalTask]),
+    });
+  }
+}
+async function executeStart(command, args, domain) {
+  const isResumption = command === 'resumption-submit';
+  const payload = options(args, ['program_code', 'field_values', ...(isResumption ? ['leave_id', 'resumption_time', 'reason', ...(domain === 'student-leave' ? ['student_id'] : [])] : [])], [], [], true);
+  requireArguments(payload, 'program_code');
+  if (isResumption) {
+    requireArguments(payload, 'leave_id', 'resumption_time');
+    if (domain === 'leave' ? !require('./teacher-leave-query.cjs').validId(payload.leave_id, 'leave_')
+      : !require('./student-leave-query.cjs').validId(payload.leave_id, false))
+      throw invalid('--leave-id 必须是原请假的有效业务记录 ID。');
+    validateResumptionTime(payload.resumption_time);
+    if (payload.reason !== undefined && payload.reason.length > 100) throw invalid('--reason 最多 100 字。');
+  }
+  parseFieldValues(payload);
+  if (domain === 'leave') {
+    try {
+      const form = (await readTeacherForm(payload, isResumption)).value.data;
+      if (form.status !== 'ready' || form.form_check.status !== 'complete')
+        throw new (require('./result.cjs').Failure)(2, 'validation', 'form_input_required', '表单还有需要处理的信息，尚未上传附件或提交申请。', {
+          form_check: form.form_check, hint: '合并处理 form_check.issues；只向老师追问缺少或有歧义的事实。信息齐全后直接提交，无需再单独检查。',
+        });
+    } catch (error) {
+      if (error.result?.value?.error) {
+        const details = error.result.value.error;
+        details.execution_status = 'NOT_EXECUTED';
+        details.step = 'check_form_before_upload';
+        if (details.subtype === 'auth_required' || details.subtype === 'missing_scope')
+          details.required_scopes = ['attendance-leave:read', 'attendance-leave:write'];
+      }
+      throw error;
+    }
+  }
+  if (domain === 'student-leave') await require('./student-leave-form.cjs').checkBeforeSubmit(payload, true);
+  const send = async () => {
+    const result = await require('./leave-start-receipt.cjs').execute('attendance-leave:write', domain + '/' + command, payload, {
+      ...(isResumption ? { leave_id: required('string') } : {}),
+      request_id: required('string'), program_code: required('string'), execution_status: required('string'),
+      post_processing_status: required('string'), next_task_id: nullable('string'),
+      id: nullable('string'), application_status: nullable('integer'), message: required('string'),
+    }, '申请');
+    if (result.value.data.program_code !== payload.program_code || isResumption && result.value.data.leave_id !== payload.leave_id) {
+      const failure = new (require('./result.cjs').Failure)(1, 'api', 'invalid_response', '提交回执流程与请求不一致，结果待核实，不要自动重试。');
+      if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+      throw failure;
+    }
+    return result;
+  };
+  if (domain === 'student-leave') return require('./teacher-leave-files.cjs').submit(command, payload, send, domain);
+  try { return await require('./teacher-leave-files.cjs').submit(command, payload, send); }
+  catch (error) {
+    const details = error.result?.value?.error;
+    if (details && ['auth_required', 'missing_scope'].includes(details.subtype))
+      details.required_scopes = ['attendance-leave:read', 'attendance-leave:write'];
+    throw error;
+  }
+}
+
+function validateResumptionTime(value) {
+    const epoch = Date.parse(value.replace(' ', 'T') + '+08:00');
+    if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value) || !Number.isFinite(epoch)
+      || new Date(epoch + 8 * 3600000).toISOString().slice(0, 19).replace('T', ' ') !== value)
+      throw invalid('--resumption-time 必须是有效的 YYYY-MM-DD HH:mm:ss（Asia/Shanghai）时间。');
+}
+
+module.exports = { execute, validateStudentForm, executeApproval, executeStart, executeResumptionOperation, formField, teacherFormField, parseFieldValues, validateResumptionTime };

package/lib/replenishment-records.cjs

@@ -0,0 +1,39 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+const { replenishmentId } = require('./attendance-leave-ids.cjs');
+function validDate(value) { return /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value; }
+async function execute(args, domain, write = false) {
+  const keys = write ? ['id'] : ['date'];
+  const type = domain === 'dormitory-attendance' ? '2' : '1';
+  const payload = options(args, keys, [], [], true); requireArguments(payload, ...keys);
+  if (write ? !replenishmentId(payload.id, type) : !validDate(payload.date)) throw invalid(write ? '--id 必须来自本业务的补录提交回执或本人补录列表。' : '--date 必须为有效的 YYYY-MM-DD 日期。');
+  try {
+    const result = await gateway.execute('attendance-leave' + (write ? ':write' : ':read'), domain + (write ? '/replenishment-delete' : '/replenishments'), payload, {
+      tenant_id: required('string'), operator_id: required('string'), date: required('string'), attendance_type: required('string'),
+      ...(write ? { subject_id: nullable('string'), id: required('string'), request_id: required('string'), execution_status: required('string'), message: required('string') }
+        : { total: required('integer'), records: required([{ id: required('string'), subject_id: required('string'), date: required('string'), subject_name: nullable('string'), department_id: nullable('string'), department_name: nullable('string'), recorded_time: nullable('string'), time_bucket: nullable('string'), direction: nullable('string'), handled_at: nullable('integer'), handler_name: nullable('string'), handler_role: nullable('string') }]) }),
+    });
+    const d = result.value.data;
+    if (!validDate(d.date) || d.attendance_type !== type
+        || (write ? d.id !== payload.id || !replenishmentId(d.id, type, d.date)
+            || d.execution_status === 'COMPLETED' && !d.subject_id
+            || result.value.request_id && result.value.request_id !== d.request_id
+            || !['COMPLETED', 'NOT_EXECUTED', 'UNCONFIRMED'].includes(d.execution_status)
+          : d.date !== payload.date || d.total !== d.records.length || new Set(d.records.map(row => row.id)).size !== d.records.length
+            || d.records.some(row => !replenishmentId(row.id, type, payload.date) || row.date !== payload.date))) {
+      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) {
+      const error = failure.result.value.error;
+      const unknown = write && (error.type === 'network' && error.subtype !== 'connection_failed' || error.type === 'api' && error.subtype === 'invalid_response');
+      error.details = { ...error.details, ...payload, ...(unknown ? { execution_status: 'UNCONFIRMED' } : {}) };
+      if (unknown) error.message += '补签到删除结果待核实，请保留记录和请求标识，按需要查询本人补签到记录，不要自动重试。';
+    }
+    throw failure;
+  }
+}
+module.exports = { execute };

package/lib/result.cjs

@@ -36,6 +36,7 @@ const present = schema => ({ $present: schema });
 const optionalFields = schema => Object.fromEntries(Object.entries(schema).map(([key, type]) => [key, optional(type)]));
 const nullableFields = schema => Object.fromEntries(Object.entries(schema).map(([key, type]) => [key, nullable(type)]));
 function fields(value, schema, path = 'data') {
+  if (typeof schema === 'function') return schema(value, path);
   if (schema.$required !== undefined) {
     if (value == null || (schema.$required === 'string' && (typeof value !== 'string' || !value.trim()))) {
       throw new Error(`响应字段 ${path} 缺失或无效。`);

package/lib/saved-report-summary.cjs

@@ -0,0 +1,16 @@
+const { required, nullable } = require('./result.cjs');
+const reportSchema = { report_id: required('string'), content_date: required('string'), delivery_date: nullable('string'), time_bucket: required('string'),
+  scope_type: required('string'), scope_id: nullable('string'), scope_name: nullable('string'), snapshot_missing_count: required('integer'),
+  configuration_name: nullable('string'), calculation_time: nullable('string'), direction: nullable('string') };
+function validDate(value) {
+  return /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+}
+function validReportContext(report, reportId, scopeTypes) {
+  return report.report_id === reportId && scopeTypes.includes(report.scope_type) && validDate(report.content_date)
+    && (report.delivery_date == null || validDate(report.delivery_date)) && !!report.time_bucket.trim()
+    && report.snapshot_missing_count >= 0;
+}
+function validReport(report, reportId, scopeTypes) {
+  return validReportContext(report, reportId, scopeTypes);
+}
+module.exports = { reportSchema, validReport, validReportContext };

package/lib/school-contacts.cjs

@@ -0,0 +1,24 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, invalid, Failure } = require('./result.cjs');
+const { confirmMobile } = require('./contact-mobile.cjs');
+const gateway = require('./gateway.cjs');
+
+async function execute(args) {
+  const payload = options(args, ['id'], ['include_mobile', 'yes'], [], true);
+  requireArguments(payload, 'id');
+  if (payload.id.length > 200) throw invalid('--id 最多200字符。');
+  confirmMobile(payload);
+  const result = await gateway.execute('school:read', 'school/students/contacts', payload, {
+    tenant_id: required('string'), operator_id: required('string'),
+    student: required({ id: required('string'), name: required('string') }), include_mobile: required('boolean'),
+    items: required([{ id: nullable('string'), relationship: required('string'), relationship_name: required('string'),
+      ...(payload.include_mobile ? { mobile: nullable('string') } : {}) }]),
+  });
+  const d = result.value.data;
+  if (d.student.id !== payload.id || d.include_mobile !== payload.include_mobile
+      || d.items.some(row => !['self', 'parent', 'father', 'mother', 'grandpa', 'grandma', 'wai_grandpa', 'wai_grandma', 'other', 'guardian'].includes(row.relationship)))
+    throw new Failure(1, 'api', 'invalid_response', '学生联系人查询返回的学生、关系或手机号请求状态不一致。');
+  d.message = d.items.length ? `返回该学生的${d.items.length}条联系人关系。` : '该学生未登记联系人。';
+  return result;
+}
+module.exports = { execute };

package/lib/school-help.cjs

@@ -0,0 +1,53 @@
+const paging = '[--page <n>] [--page-size <1-100>]';
+const usage = {
+  'school students contacts': '--id <student-id> [--include-mobile] [--yes]',
+  'school departments search': '--name <text> [--department-id <id>] [--include-teachers] [--include-mobile] [--yes] ' + paging,
+  'school departments tree': '[--department-id <id>] [--depth <1-20>] [--include-teachers] [--include-mobile] [--yes] ' + paging,
+  'school departments members': '--department-id <id> [--department-id <id>...] [--include-descendants] ' + paging,
+  'school students search': '--name <text> [--department-id <id>...] [--include-descendants] ' + paging,
+};
+const summaries = {
+  'school students contacts': '查看学生登记的联系人',
+  school: '家校查询：找年级、班级和学生，查看负责人及任课教师',
+  'school departments': '查找家校部门、浏览结构和列出学生',
+  'school students': '查找在校学生及其联系人',
+  'school departments search': '按名称查找可见的年级、班级等家校部门',
+  'school departments tree': '查看校区、学段、年级和班级结构',
+  'school departments members': '查看班级或年级的学生名单',
+  'school students search': '按姓名找在校学生，可限定班级或年级',
+};
+const definitions = Object.fromEntries(Object.keys(usage).map(command => [command, {
+  purpose: summaries[command], scope: 'school:read', errors: 'read',
+}]));
+function render(command) {
+  if (!usage[command]) return null;
+  if (command === 'school students contacts') return contactsHelp(command);
+  const tree = command.endsWith(' tree'), members = command.endsWith(' members');
+  const students = members || command === 'school students search';
+  const params = [];
+  if (!tree && !members) params.push('--name  必填；' + (students ? '学生姓名' : '部门名称') + '文字片段，1到50字，按包含匹配；不解释为正则或通配符。');
+  params.push(students
+    ? '--department-id  ' + (members ? '必填' : '可选') + '；可重复指定不同班级或家校部门，最多200个，合并查询并去重；默认只查直属学生。'
+    : '--department-id  可选，只能指定一个；' + (tree ? '作为子树根节点并包含该节点。省略从当前可见顶层开始。' : '在该部门及其下级范围搜索。省略搜索当前学校可见家校部门。'));
+  if (students) params.push('--include-descendants  可选开关；包含所选部门的可见下级部门学生，必须同时指定部门。');
+  else params.push('--include-teachers  可选开关；展开班级、兴趣班、自定义班级的可见任课教师及任教学科。默认只返回负责人、班主任和其他非任课岗位。');
+  if (!students) params.push('--include-mobile  可选；仅老师明确要求或用途需要时，读取本次结果中可见人员的手机号。任课教师须同时用 --include-teachers 展开。',
+    '--yes  读取手机号时必填；先说明对象、范围和用途，等待老师二次确认后传入。首次提出需求不算二次确认；单独使用报错。');
+  if (tree) params.push('--depth  可选，默认2，范围1到20；查询根算第1层，省略根时可见顶层算第1层。');
+  params.push('--page  可选，从1开始，默认1。', '--page-size  可选，默认20，范围1到100。',
+    students ? '仅 --department-id 可重复传入；重复部门 ID 报错，其他参数不能重复。' : '所有参数均不能重复传入。');
+  const base = '部门含 id、name、type、type_name、parent_id、path（可见名称路径）、ancestors（可见祖先的 ID、名称和类型）、has_children、level。类型名称无法识别时为 null。隐藏祖先不返回，parent_id 指向最近可见祖先。';
+  const result = students
+    ? 'items：学生列表，每项含 id、name、student_number（学号，未填写为 null）、departments。\n  departments：所属部门。' + base + '指定部门时只返回本次所选范围内的部门关系，不展开任职人员。\n  一人多班只计一次；total 为筛选和权限过滤后的学生人数。'
+    : 'items：家校部门列表。\n  ' + base + '\n  部门另含 alias（别名，未配置为 null）、leaders（负责人）、head_teachers（班主任）、subject_teachers（按需展开的任课教师）、other_positions（其他实际岗位）。\n  人员含 id、name、role、role_code、subjects；subjects 含 code、name、source，同一老师可任教多个学科，未取得的岗位或学科名称为 null。\n  默认不返回 mobile；确认展开后人员项增加 mobile，未登记为 null。' + (tree
+      ? '\n  树为平铺节点列表，按 level、名称、ID 排序；指定根的 parent_id 为 null，level 从查询根开始。父节点可能在其他页。total 是当前深度内节点数；depth_limited=true 表示还有更深层节点。'
+      : '\n  精确名称匹配优先，再按名称、ID 排序；同名部门分别返回。level 为可见目录层数，total 为匹配部门数。');
+  const statuses = students ? '' : '\n  人员信息状态（*_status）：\n    complete：完整配置，空数组表示未配置。\n    visible_only：仅当前可见人员，空数组不代表未配置。\n    not_requested：未展开。\n    not_applicable：此部门类型不提供该项。\n  subject_teachers 未展开或不适用时为 null。负责人和班主任均为数组，自定义岗位保留实际名称。';
+  const example = tree ? '--depth 2' : members ? '--department-id <七年级ID> --include-descendants'
+    : students ? '--name 小明' : '--name 七年级一班 --include-teachers';
+  return `${summaries[command]}。\n\n用法：yunzhi-cli ${command} ${usage[command]}\n\n参数：\n  ${params.join('\n  ')}\n\n示例：\n  yunzhi-cli ${command} ${example}\n\n返回：\n  ${result}${statuses}\n  tenant_id、operator_id 为当前学校和操作人；name、department_ids 返回本次查询条件；${students ? 'include_descendants 表示是否包含下级。' + (members ? '按姓名、ID 排序。' : '精确姓名优先，再按姓名、ID 排序。') : 'include_teachers、include_mobile 表示是否展开任课教师及手机号。' + (tree ? 'depth 返回查询深度。' : 'depth 为 null，depth_limited 为 false。')}page、page_size、total、total_pages 为分页信息。\n\n限制：\n  ${students ? '仅查询当前学校可见的在校学生，不含毕业生或家长；联系人另用 school students contacts 查询。看见年级不代表能查其全部学生。' : '仅查询当前学校可见的家校部门及任职人员。'}指定不可见或不存在的部门整体报错；来源失败报错，不当作空结果。分页偏移不能超过2147483647。\n  ${students ? '学生搜索和名单不接受手机号参数。' : '任课信息是当前目录任教关系，不是当天课表或代课安排。手机号缺少 --yes 时退出码10，不发起查询。'}所需权限：school:read。默认输出 JSON，错误见 error.message/error.hint。\n`;
+}
+function contactsHelp(command) {
+  return `${summaries[command]}。默认只返回联系人关系；手机号需二次确认后获取。\n\n用法：yunzhi-cli ${command} ${usage[command]}\n\n参数：\n  --id  必填，学生查询返回的 ID，最多200字符。\n  --include-mobile  可选；仅老师明确要求手机号，或明确用途需要时使用。\n  --yes  读取手机号时必填；先说明对象、范围和用途，等待老师二次确认后传入。首次要求查电话不算二次确认；单独使用报错。\n\n示例：\n  yunzhi-cli ${command} --id <学生ID>\n  # 老师二次确认之后：\n  yunzhi-cli ${command} --id <学生ID> --include-mobile --yes\n\n返回：\n  student：学生的 id、name。\n  items：该学生登记的联系人，含 id（联系人ID，历史数据可能为空）、relationship、relationship_name。\n  关系包括本人、家长、父亲、母亲、爷爷、奶奶、外公、外婆、监护人、其他。保留每条登记关系。\n  不返回联系人姓名、身份证或关联的其他孩子。\n  默认不返回 mobile；确认展开后每项增加 mobile，未登记为 null。include_mobile 表示是否返回手机号，tenant_id、operator_id 为当前学校和操作人。\n  没有分页；空 items 表示未登记联系人，来源失败直接报错。\n\n限制：\n  仅查询当前老师可见的在校学生；确认不能扩大权限。请求手机号却缺少 --yes 时退出码10，不发起查询。所需权限：school:read。默认输出 JSON，错误见 error.message/error.hint。\n`;
+}
+module.exports = { usage, summaries, definitions, render };