@xiaoyuanhao/yunzhi-cli 2.0.0 → 2.1.1

package/lib/school-schema.cjs

@@ -0,0 +1,38 @@
+const { required, nullable } = require('./result.cjs');
+const ref = { id: required('string'), name: required('string'), type: nullable('string'), type_name: nullable('string') };
+const summary = { ...ref, parent_id: nullable('string'), path: required([required('string')]),
+  has_children: required('boolean'), level: required('integer'), ancestors: required([ref]) };
+const staff = { id: required('string'), name: required('string'), role: nullable('string'), role_code: required('string'),
+  subjects: required([{ code: required('string'), name: nullable('string'), source: nullable('string') }]) };
+const department = { ...summary, alias: nullable('string'),
+  leaders: required([staff]), leaders_status: required('string'),
+  head_teachers: required([staff]), head_teachers_status: required('string'),
+  subject_teachers: nullable([staff]), subject_teachers_status: required('string'),
+  other_positions: required([staff]), other_positions_status: required('string') };
+
+function check(row, summaryOnly, includeTeachers, fail) {
+  if (row.ancestors.length !== row.path.length - 1
+      || new Set([row.id, ...row.ancestors.map(ref => ref.id)]).size !== row.ancestors.length + 1
+      || row.ancestors.some((ref, index) => ref.name !== row.path[index])
+      || row.parent_id !== null && row.parent_id !== row.ancestors.at(-1)?.id) fail();
+  if (summaryOnly) return;
+  const classNode = ['class', 'custom_class', 'interest_class'].includes(row.type);
+  for (const key of ['leaders', 'head_teachers', 'subject_teachers', 'other_positions']) {
+    const special = key === 'head_teachers' && !classNode ? 'not_applicable'
+      : key === 'subject_teachers' ? !classNode ? 'not_applicable' : !includeTeachers ? 'not_requested' : null : null;
+    const status = row[`${key}_status`], values = row[key];
+    if (special ? status !== special || values?.length : !['complete', 'visible_only'].includes(status) || values === null) fail();
+    if (values === null) continue;
+    if (new Set(values.map(person => JSON.stringify([person.id, person.role_code]))).size !== values.length) fail();
+    for (const person of values) {
+      if (new Set(person.subjects.map(subject => JSON.stringify([subject.source, subject.code]))).size !== person.subjects.length) fail();
+    }
+  }
+}
+function departmentWithMobile(include) {
+  if (!include) return department;
+  const withMobile = { ...staff, mobile: nullable('string') };
+  return { ...department, leaders: required([withMobile]), head_teachers: required([withMobile]),
+    subject_teachers: nullable([withMobile]), other_positions: required([withMobile]) };
+}
+module.exports = { summary, departmentWithMobile, check };

package/lib/student-application-help.cjs

@@ -0,0 +1,76 @@
+// Help only. Keep shared field encodings intact without changing teacher commands.
+const { fieldInput } = require('./teacher-own-leave-help.cjs');
+function render(command, usage) {
+  const [space, action] = command.split(' ');
+  if (space !== 'student-leave') return null;
+  const resumed = action.startsWith('resumption-'), kind = resumed ? action.slice(11) : action;
+  if (!['form', 'form-people-search', 'submit'].includes(kind)) return null;
+  const subject = resumed ? '销假' : '请假', prefix = resumed ? 'resumption-' : '';
+  const context = resumed ? ['--leave-id  必填；原学生请假 ID，来自 list/show。', '--student-id  可选；原请假有多名可办理学生时，用于指定学生。']
+    : ['--class-id  必填；学生所属的办理班级。', '--student-id  必填；请假学生，来自 students。'];
+  const process = `--workflow-code  必填；${prefix}form 返回的已选流程编码。`;
+  let purpose, parameters, result, limits, extra = '', failure = '', example;
+  if (kind === 'form') {
+    purpose = `查看代学生办理${subject}需要填写哪些内容，并一次列出当前答案中需要补充或修正的地方。`;
+    parameters = [...context, '--workflow-code  可选；唯一流程自动选择，多个流程返回选项。',
+      `--field-values  可选；当前完整答案，JSON 数组或 @UTF-8 文件；不是增量补丁。格式见 ${prefix}submit --help。`,
+      ...(resumed ? ['--resumption-time  可选；实际返校时间，YYYY-MM-DD HH:mm:ss，北京时间；提交时必填。', '--reason  可选；销假说明，最多 100 字。'] : [])];
+    example = resumed ? '--leave-id <leave_id>' : '--class-id <class_id> --student-id <student_id>';
+    result = [
+      'status：ready=返回 program_code/fields；selection_required=从 choices[].name/program_code 选择后重读；unavailable 且 choices=[]=无可用流程。',
+      'form_check.status：complete=检查未发现问题；needs_input=需补充或修正；blocked=规则异常或能力不支持。',
+      'form_check.visible_fields：当前显示的字段。form_check.issues：全部当前问题的 code/message 和位置；子表用 parent_field_key/row_index（从 0 开始），专用参数用 parameter。',
+      resumed ? 'original_leave：原请假、学生班级、有效时段与状态；field_mappings 为系统绑定字段。'
+        : 'class_id/class_name、student_id/student_name：代办对象；student_field_key 为系统绑定的只读学生字段。',
+    ].join('\n  ');
+    extra = `字段说明：\n  ` + [
+      'field_key/type/label/description：字段键、类型及学校说明。按 visible_fields 填写 editable=true、computed=false 的字段；required 在显示时生效。',
+      'value/default_value/display_value：当前值、默认值、展示值；null 为未知或未提供。显式答案覆盖默认值。',
+      'options[]：提交 option_id，展示 label；code 为条件值，default_selected 为默认选择。联动结果直接读 form_check，无需自行计算。',
+      `candidate_users/candidate_departments/candidate_organizations：可选身份，null=不可用，[]=空集合。person_search_supported=true 才可用 ${prefix}form-people-search。`,
+      'validation_rules：必填、数字、手机、证件、unique 等规则；unique 由服务端查重。number_range.minimum/maximum 是精确十进制字符串，null=该端无界，inclusive=true=包含端点。',
+      'format_rules：decimal_places/digits/rounding=half_up，由服务端格式化，不自行舍入。规则列表 null=未知，[]=未列出；提交仍会校验。',
+      'attachment_upload_supported/file_type/attachment_limits：上传能力、类别和限制。upload_max_bytes 为单文件上限；图片 max_files=10，min_size_mib/max_size_mib 为十进制 MiB 边界，含端点。',
+      `groups/row_template：已有行和新行定义；子表输入格式见 ${prefix}submit --help，不支持嵌套子表写入。`,
+    ].join('\n  ') + '\n\n';
+    limits = '不保存、上传或提交。CLI 检查联动、必填及基本格式；修改控制题后可能出现新问题。计算、精确数值、人员资格和文件内容由服务端最终校验。'
+      + (!resumed ? '提供完整答案且无本地文件时，还会执行只读业务检查并合并问题。' : '')
+      + 'complete 不代表已提交或已批准。';
+  } else if (kind === 'form-people-search') {
+    purpose = `填写学生${subject}表单中的人员字段时，按姓名查找可选人员。`;
+    parameters = [...context, process, '--field-key  必填；可编辑且允许自由搜索的人员字段。', '--keyword  必填；非空姓名线索。'];
+    example = `${resumed ? '--leave-id <leave_id>' : '--class-id <class_id> --student-id <student_id>'} --workflow-code <program_code> --field-key <field_key> --keyword 李`;
+    result = 'candidates：人员与部门信息，提交时取 tenant_id/user_id；未知部门为 null。最多 10 人，exhaustive=false，无分页。';
+    limits = '仅 person_search_supported=true 时使用；固定范围直接使用表单候选。子表父字段须可编辑。此命令不选择请假学生，提交时仍会校验人员资格。';
+  } else {
+    purpose = `代学生提交${subject}，自动检查表单并上传本地附件。`;
+    parameters = [...context, process,
+      ...(resumed ? ['--resumption-time  必填；实际返校时间，YYYY-MM-DD HH:mm:ss，北京时间；不得晚于原有效假期结束。', '--reason  可选；销假说明，最多 100 字，学校要求时必填。'] : []),
+      '--field-values  可选；JSON 数组或 @UTF-8 文件，仍须满足学校必填项。'];
+    example = `${resumed ? '--leave-id <leave_id>' : '--class-id <class_id> --student-id <student_id>'} --workflow-code <program_code>${resumed ? ' --resumption-time "2026-10-15 09:00:00"' : ''} --field-values "@表单.json"`;
+    extra = '表单.json 示例（字段键按实际表单替换，并补齐必填项）：\n'
+      + '[\n  {"field_key":"实际事由字段键","value":"' + (resumed ? '已返校' : '身体不适') + '"},\n'
+      + '  {"field_key":"实际附件字段键","value":{"local_files":["./证明.pdf"]}}\n]\n\n'
+      + `字段输入格式：\n  ${fieldInput}\n\n`;
+    result = [
+      `id：新${subject} ID；` + (resumed ? 'leave_id 为原请假 ID。' : 'class_id/student_id 为代办对象。'),
+      'execution_status：COMPLETED=提交已确认；NOT_EXECUTED=未提交申请；UNCONFIRMED=结果不确定。',
+      'application_status：processing 处理中、completed 流程完成，仅提交确认后返回。next_task_id 为下一任务；null/0 表示未返回单一任务。',
+      'post_processing_status：SUBMITTED=后处理已提交、FAILED=后处理失败、NOT_STARTED=未开始；失败不撤销已确认的提交。message 为实际原因。',
+      'attachment_uploads/attachment_preparations：本次上传／文件准备结果及字段、行位置；attachment_preparation_error 为附件局部异常。',
+    ].join('\n  ');
+    failure = '异常处理：\n  ' + [
+      'step=check_form_before_upload：检查未通过，尚未上传或提交；error.form_check 汇总当前问题。',
+      ...(!resumed ? ['step=validate_form_before_submit：上传后的业务检查未通过，issue 为原因，回执保留已上传文件。'] : []),
+      'NOT_EXECUTED 只说明申请未提交，附件可能已上传；缺失回执不等于未上传。文件准备的 COMPLETED 只确认该步骤，verified 为另一次回读检查。',
+      '附件结果按字段和行识别；提交或文件结果未知时先核实，不自动重提、重传或删除。',
+    ].join('\n  ') + '\n\n';
+    limits = (resumed ? '原请假须可访问、已批准且尚未销假；允许假期结束后补办。学生、假种和原有效时段由服务端绑定。'
+      : '服务端复核当前班主任职责、班级和学生；不能覆盖绑定学生。')
+      + `签名或现场定位须本人完成。仅检查填写用 ${prefix}form；提交成功不代表审批通过或考勤已更新。`;
+  }
+  // Field encodings accompany start; form definitions follow the form response they describe.
+  const beforeResult = kind === 'form' ? '' : extra, afterResult = kind === 'form' ? extra : '';
+  return `${purpose}\n\n用法：yunzhi-cli ${command} ${usage}\n\n参数：\n  ${parameters.join('\n  ')}\n\n示例：\n  yunzhi-cli ${command} ${example}\n\n${beforeResult}返回：\n  ${result}\n\n${afterResult}${failure}注意：\n  ${limits}\n  所需权限：${kind === 'submit' ? 'attendance-leave:read + attendance-leave:write' : 'attendance-leave:read'}。\n`;
+}
+module.exports = { render };

package/lib/student-leave-form.cjs

@@ -0,0 +1,108 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, optional, fields, invalid, Failure } = require('./result.cjs');
+const { teacherFormField, parseFieldValues, validateResumptionTime } = require('./leave.cjs');
+const { leaveRecord: record, validId } = require('./student-leave-query.cjs');
+const gateway = require('./gateway.cjs');
+
+async function execute(action, args) {
+  const resumption = action === 'resumption-form';
+  const payload = options(args, ['program_code', 'field_values', ...(resumption
+    ? ['leave_id', 'student_id', 'resumption_time', 'reason'] : ['class_id', 'student_id'])], [], [], true);
+  requireArguments(payload, ...(resumption ? ['leave_id'] : ['class_id', 'student_id']));
+  if (resumption) {
+    if (!validId(payload.leave_id, false)) throw invalid('--leave-id 必须是原请假提交或查询返回的 id。');
+    if (payload.resumption_time !== undefined) validateResumptionTime(payload.resumption_time);
+    if (payload.reason !== undefined && payload.reason.length > 100) throw invalid('--reason 最多 100 字。');
+  }
+  parseFieldValues(payload);
+  const result = await read(payload, resumption);
+  const form = result.value.data;
+  // Preserve the existing readonly business check when no file upload is needed.
+  // Local paths remain local; file content is checked after upload during submission.
+  const localFiles = values => (values || []).some(field => field.value?.local_files !== undefined
+    || Array.isArray(field.value) && field.value.some(row => row?.fields && localFiles(row.fields)));
+  if (!resumption && payload.field_values !== undefined && form.status === 'ready'
+      && form.form_check.status === 'complete' && !localFiles(payload.field_values)) {
+    const checked = (await require('./leave.cjs').validateStudentForm({ ...payload, program_code: form.program_code })).value.data;
+    if (!checked.valid) {
+      form.form_check.status = 'needs_input';
+      form.form_check.issues.push({ code: 'server_validation', ...checked.issue });
+    }
+  }
+  return result;
+}
+
+async function read(payload, resumption) {
+  const request = Object.fromEntries((resumption ? ['leave_id', 'student_id', 'program_code'] : ['class_id', 'student_id', 'program_code'])
+    .filter(key => payload[key] !== undefined).map(key => [key, payload[key]]));
+  const result = await gateway.execute('attendance-leave:read', 'student-leave/' + (resumption ? 'resumption-form' : 'form'), request,
+    (data, path) => project(data, path, request, resumption));
+  const data = result.value.data;
+  if (data.status === 'ready') {
+    const original = data.original_leave;
+    const form = resumption ? { ...data, leave_id: original.id, user_name: original.student_name,
+      leave_type: original.leave_type, leave_start_time: original.start_time, leave_end_time: original.end_time } : data;
+    data.form_check = require('./teacher-leave-form-check.cjs').evaluate(form, payload.field_values, payload);
+    for (const issue of data.form_check.issues) if (issue.parameter === 'resumption_time') issue.message = '请补充实际返校时间。';
+  }
+  return result;
+}
+
+function project(data, path, request, resumption) {
+  if (!data || !['ready', 'selection_required', 'unavailable'].includes(data.status)) throw new Error('学生表单返回了未知状态。');
+  if (data.status !== 'ready') {
+    const value = fields(data, { status: required('string'), ...(resumption ? { leave_id: required('string') } : {}),
+      choices: required([{ program_code: required('string'), name: required('string') }]) }, path);
+    if (request.program_code !== undefined || resumption && value.leave_id !== request.leave_id
+        || value.status === 'unavailable' && value.choices.length !== 0
+        || value.status === 'selection_required' && (value.choices.length < 2
+          || new Set(value.choices.map(item => item.program_code)).size !== value.choices.length)
+        || value.choices.some(item => !item.program_code.trim() || !item.name.trim()))
+      throw new Error('学生流程选择状态或候选不一致。');
+    return value;
+  }
+  const value = fields(data, {
+    status: required('string'), tenant_id: required('string'), teacher_id: required('string'), program_code: required('string'),
+    fields: required([teacherFormField]),
+    ...(resumption ? { original_leave: required(record), field_mappings: required(Object.fromEntries(
+      ['leaveId', 'userName', 'leaveType', 'askForLeaveTime', 'askForBackTime', 'revokeLeaveStartTime', 'revokeLeaveReason']
+        .map(key => [key, optional(required('string'))]))) }
+      : Object.fromEntries(['class_id', 'class_name', 'student_id', 'student_name', 'student_field_key'].map(key => [key, required('string')]))),
+  }, path);
+  if (!value.program_code.trim() || request.program_code !== undefined && value.program_code !== request.program_code)
+    throw new Error('学生表单与指定流程不一致。');
+  if (resumption) {
+    const keys = new Set(value.fields.map(field => field.field_key));
+    if (!Object.values(value.field_mappings).every(key => keys.has(key))) throw new Error('销假绑定字段不在当前可见表单中。');
+    const original = value.original_leave;
+    if (original.id !== request.leave_id || request.student_id !== undefined && original.student_id !== request.student_id || !validId(original.id, false) || !original.workflow_code?.trim()
+        || original.start_time == null || original.end_time == null || original.start_time >= original.end_time
+        || original.status !== '1' || original.resumption_status !== '0') throw new Error('学生销假的原请假或有效假期不一致。');
+  } else {
+    const subjects = value.fields.filter(field => field.field_key === value.student_field_key);
+    const subject = subjects[0], selected = subject?.value;
+    if (value.class_id !== request.class_id || value.student_id !== request.student_id || subjects.length !== 1
+        || subject.editable !== false || !['person', 'people'].includes(subject.type)
+        || !Array.isArray(selected) || selected.length !== 1 || selected[0]?.tenant_id !== value.tenant_id
+        || selected[0]?.user_id !== value.student_id) throw new Error('学生表单的班级、学生或只读绑定不一致。');
+  }
+  return value;
+}
+
+async function checkBeforeSubmit(payload, resumption) {
+  try {
+    const form = (await read(payload, resumption)).value.data;
+    if (form.status !== 'ready' || form.form_check.status !== 'complete')
+      throw new Failure(2, 'validation', 'form_input_required', '表单还有需要处理的信息，尚未上传附件或提交申请。',
+        { form_check: form.form_check, hint: '合并处理 form_check.issues；信息齐全后直接提交，无需再单独检查。' });
+  } catch (error) {
+    const details = error.result?.value?.error;
+    if (details) {
+      details.execution_status = 'NOT_EXECUTED'; details.step = 'check_form_before_upload';
+      if (['auth_required', 'missing_scope'].includes(details.subtype)) details.required_scopes = ['attendance-leave:read', 'attendance-leave:write'];
+    }
+    throw error;
+  }
+}
+
+module.exports = { execute, read, checkBeforeSubmit };

package/lib/student-leave-operations.cjs

@@ -0,0 +1,24 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+async function execute(action, args) {
+  const payload = options(args, ['id'], [], [], true);
+  requireArguments(payload, 'id');
+  if (!require('./student-leave-query.cjs').validId(payload.id, false, true))
+    throw invalid('使用带申请关联的学生请假提交或查询返回的 id。');
+  const urge = action === 'remind';
+  const result = await gateway.execute('attendance-leave:write', 'student-leave/' + action, payload, {
+    id: required('string'), event: required('string'),
+    ...(urge ? { notified_count: required('integer') } : { withdrawn: required('boolean') }),
+  });
+  const data = result.value.data;
+  if (data.id !== payload.id || data.event !== (urge ? 'leave_urged' : 'leave_withdrawn')
+      || (urge ? data.notified_count <= 0 : data.withdrawn !== true)) {
+    const failure = new Failure(1, 'api', 'invalid_response', '学生请假操作回执无效，请查询目标申请，不要自动重试。',
+      { details: { id: payload.id, action } });
+    if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+    throw failure;
+  }
+  return result;
+}
+module.exports = { execute };

package/lib/student-leave-query.cjs

@@ -0,0 +1,75 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, optional, fields, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+function validId(id, resumption, applicationOnly = false) {
+  const prefix = resumption ? 'student_resumption_' : 'student_leave_';
+  return typeof id === 'string' && new RegExp('^' + prefix + (applicationOnly ? 'a' : '[ar]') + '_[1-9][0-9]{0,18}$').test(id)
+    && BigInt(id.slice(prefix.length + 2)) <= 9223372036854775807n;
+}
+const times = { start_time: nullable('string'), end_time: nullable('string'), created_at: nullable('string'), updated_at: nullable('string') };
+const step = { 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 resumptionRecord = { id: required('string'), status: nullable('string'), status_name: nullable('string'), reason: nullable('string'), ...times,
+  workflow_status: optional(nullable('integer')), progress: optional(nullable([step])) };
+const leaveRecord = { id: required('string'), student_id: required('string'), student_name: required('string'),
+  class_id: required('string'), class_name: nullable('string'), workflow_code: nullable('string'), ...times,
+  leave_type: nullable('string'), reason: nullable('string'), status: nullable('string'), status_name: nullable('string'),
+  resumption_status: nullable('string'), resumption_status_name: nullable('string'), resumption_source: nullable('integer'),
+  workflow_status: optional(nullable('integer')), progress: optional(nullable([step])), resumptions: optional(required([resumptionRecord])) };
+function item(resumption, detail) {
+  return (source, at) => {
+    const data = fields(source, { id: required('string'), owned: required('boolean'), title: nullable('string'),
+      workflow_status: nullable('integer'), workflow_status_name: nullable('string'), created_at: nullable('string'),
+      records: nullable([resumption ? { ...resumptionRecord, leave_id: required('string'), original_leave: required(leaveRecord) } : leaveRecord]),
+      ...(detail ? { fields: nullable([require('./leave.cjs').formField]), progress: nullable([step]),
+        progress_unavailable_reason: optional(nullable('string')),
+        attachments: nullable([require('./teacher-leave-files.cjs').attachment]) } : {}) }, at);
+    if (!validId(data.id, resumption) || (data.records || []).some(row => !validId(row.id, resumption)
+        || resumption && (!validId(row.leave_id, false) || row.original_leave.id !== row.leave_id)
+        || !resumption && row.resumptions?.some(r => !validId(r.id, true)))) throw new Error('学生请假身份或关联无效。');
+    if ((detail || !data.owned) && data.records === null || !detail && data.owned && data.records !== null) throw new Error('学生业务关联加载状态不一致。');
+    if (detail && (data.owned ? data.fields === null || (data.progress === null ? !data.progress_unavailable_reason?.trim() : data.progress_unavailable_reason != null) || data.attachments === null
+        : data.fields !== null || data.progress !== null || data.progress_unavailable_reason != null || data.attachments !== null)) throw new Error('学生请假字段与可读范围不一致。');
+    if (detail) require('./teacher-leave-files.cjs').displayAttachments(data);
+    return data;
+  };
+}
+async function execute(action, args) {
+  const resumption = action.startsWith('resumption-'), detail = action.endsWith('show');
+  const payload = options(args, detail ? ['id'] : ['scope', 'class_id', 'student_id', 'start_date', 'end_date', 'submitted_start_date', 'submitted_end_date', 'status', 'page', 'page_size'], [], [], true);
+  requireArguments(payload, detail ? 'id' : 'scope');
+  if (detail && !validId(payload.id, resumption)) throw invalid('--id 使用对应请假或销假提交/查询返回的 id。');
+  if (!detail) {
+    if (!['mine', 'managed'].includes(payload.scope)) throw invalid('--scope 必须为 mine（本人代办）或 managed（职责内学生）。');
+    if (payload.scope !== 'mine' && ['submitted_start_date', 'submitted_end_date'].some(k => payload[k] !== undefined))
+      throw invalid('提交日期筛选仅用于 mine 本人代办范围。');
+    for (const [key, fallback, max] of [['page', 1, 2147483647], ['page_size', 20, 50]]) {
+      const value = payload[key] ?? fallback;
+      if (!/^\d+$/.test(String(value)) || +value < 1 || +value > max) throw invalid('--' + key.replaceAll('_', '-') + ' 超出范围。');
+      payload[key] = +value;
+    }
+    if (payload.status !== undefined) {
+      const enums = require('./attendance-leave-enums.cjs');
+      payload.status = enums.encode(payload.scope === 'mine' ? enums.workflowStatus : enums.studentBusinessStatus, payload.status, '--status');
+    }
+    const date = value => /^\d{4}-\d{2}-\d{2}$/.test(value) && +value.slice(0,4) > 0 && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0,10) === value;
+    for (const [start, end, label] of [['start_date', 'end_date', '业务时段'], ['submitted_start_date', 'submitted_end_date', '提交']]) {
+      if ((payload[start] === undefined) !== (payload[end] === undefined) || payload[start] !== undefined
+        && (!date(payload[start]) || !date(payload[end]) || payload[start] > payload[end]))
+        throw invalid(label + '起止日期须成对提供有效 YYYY-MM-DD，开始不晚于结束。');
+    }
+  }
+  const identity = { tenant_id: required('string'), teacher_id: required('string') };
+  const shape = detail ? (value, at) => ({ ...fields(value, identity, at), ...item(resumption, true)(value, at) }) : {
+    ...identity, scope: required('string'), items: required([item(resumption, false)]), page: required('integer'),
+    page_size: required('integer'), total: required('integer'), total_pages: required('integer') };
+  const result = await gateway.execute('attendance-leave:read', 'student-leave/' + action, payload, shape);
+  const data = result.value.data;
+  if (detail ? data.id !== payload.id : data.scope !== payload.scope || 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(x=>x.id)).size !== data.items.length || data.items.some(x=>x.owned !== (payload.scope === 'mine')))
+    throw new Failure(1, 'api', 'invalid_response', '学生请假返回的身份、范围或分页不一致。');
+  return result;
+}
+module.exports = { execute, validId, leaveRecord };

package/lib/student-leave-resumption.cjs

@@ -0,0 +1,2 @@
+// Student resumption preparation shares the application form/check contract.
+module.exports = { execute: (action, args) => require('./student-leave-form.cjs').execute(action, args) };

package/lib/student-leave-start.cjs

@@ -0,0 +1,34 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, Failure } = require('./result.cjs');
+const { parseFieldValues } = require('./leave.cjs');
+const gateway = require('./leave-start-receipt.cjs');
+
+async function execute(action, args) {
+  const payload = options(args, ['class_id', 'student_id', 'program_code', 'field_values'], [], [], true);
+  requireArguments(payload, 'class_id', 'student_id', 'program_code');
+  parseFieldValues(payload);
+  await require('./student-leave-form.cjs').checkBeforeSubmit(payload, false);
+  return require('./teacher-leave-files.cjs').submit(action, payload, async () => {
+    try {
+      const checked = (await require('./leave.cjs').validateStudentForm(payload)).value.data;
+      if (!checked.valid) throw new Failure(2, 'validation', 'form_validation_failed', checked.issue.message, { issue: checked.issue });
+    } catch (error) {
+      const details = error.result?.value?.error;
+      if (details) { details.execution_status = 'NOT_EXECUTED'; details.step = 'validate_form_before_submit'; }
+      throw error;
+    }
+    const result = await gateway.execute('attendance-leave:write', 'student-leave/' + action, payload, {
+      class_id: required('string'), student_id: required('string'), program_code: required('string'), request_id: required('string'),
+      execution_status: required('string'),
+      id: nullable('string'), application_status: nullable('integer'), message: required('string'),
+      post_processing_status: required('string'), next_task_id: nullable('string'),
+    }, '申请');
+    if (['class_id', 'student_id', 'program_code'].some(key => result.value.data[key] !== payload[key])) {
+      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;
+  }, 'student-leave');
+}
+module.exports = { execute };

package/lib/student-leave.cjs

@@ -0,0 +1,51 @@
+const { options } = require('./arguments.cjs');
+const { required, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+
+const classroom = { class_id: required('string'), class_name: required('string') };
+const identity = { tenant_id: required('string'), teacher_id: required('string') };
+async function execute(action, args) {
+  if (['remind', 'withdraw'].includes(action)) return require('./student-leave-operations.cjs').execute(action, args);
+  if (['resumption-remind', 'resumption-withdraw'].includes(action)) return require('./leave.cjs').executeResumptionOperation(action, args, 'student-leave');
+  if (['resumption-submit'].includes(action)) return require('./leave.cjs').executeStart(action, args, 'student-leave');
+  if (['resumption-form'].includes(action)) return require('./student-leave-resumption.cjs').execute(action, args);
+  if (['approvals', 'approval', 'approve', 'reject', 'resumption-approvals', 'resumption-approval', 'resumption-approve', 'resumption-reject'].includes(action)) return require('./leave.cjs').executeApproval(action, args, 'student-leave');
+  if (['submit'].includes(action)) return require('./student-leave-start.cjs').execute(action, args);
+  if (['form'].includes(action)) return require('./student-leave-form.cjs').execute(action, args);
+  if (['list', 'show', 'resumption-list', 'resumption-show'].includes(action)) return require('./student-leave-query.cjs').execute(action, args);
+  const payload = options(args, action === 'classes' ? [] : ['class_id', 'name', 'page', 'page_size'], [], [], true);
+  if (action === 'students') {
+    if (payload.name != null && payload.name.length > 10) throw invalid('--name 为1到10字的姓名片段。');
+    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;
+    }
+  }
+  const result = await gateway.execute('attendance-leave:read', 'student-leave/' + action, payload,
+    action === 'classes' ? { ...identity, items: required([classroom]) } : {
+      ...identity, scope_classes: required([classroom]),
+      items: required([{ student_id: required('string'), student_name: required('string'), classes: required([classroom]) }]),
+      page: required('integer'), page_size: required('integer'), total: required('integer'), total_pages: required('integer'),
+    });
+  const data = result.value.data;
+  const unique = (rows, key) => new Set(rows.map(row => row[key])).size === rows.length;
+  let valid = action === 'classes' ? unique(data.items, 'class_id') :
+    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))
+      && unique(data.scope_classes, 'class_id') && unique(data.items, 'student_id')
+      && (data.scope_classes.length > 0 || data.total === 0)
+      && (payload.class_id == null || (data.scope_classes.length === 1 && data.scope_classes[0].class_id === payload.class_id))
+      && data.items.every(row => (payload.name == null || row.student_name.includes(payload.name)) && row.classes.length > 0
+        && unique(row.classes, 'class_id') && row.classes.every(entry => data.scope_classes.some(scope =>
+          scope.class_id === entry.class_id && scope.class_name === entry.class_name)));
+  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/student-query-help.cjs

@@ -0,0 +1,57 @@
+// Help only; query and operation contracts stay in their execution modules.
+function render(command, usage) {
+  const [space, action] = command.split(' ');
+  if (space !== 'student-leave' || !['list', 'show', 'remind', 'withdraw', 'resumption-list', 'resumption-show', 'resumption-remind', 'resumption-withdraw'].includes(action)) return null;
+  const resumption = action.startsWith('resumption-'), list = action.endsWith('list'), show = action.endsWith('show'), urge = action.endsWith('remind');
+  const subject = resumption ? '销假' : '请假', prefix = resumption ? 'resumption-' : '';
+  const purpose = list ? `查询职责内学生${subject}，或本人代办的${subject}申请。`
+    : show ? `查看学生${subject}详情、进度和可读附件。`
+    : `${urge ? '催办' : '撤回'}本人代学生提交、仍在处理的${subject}申请。`;
+  const parameters = list ? [
+    '--scope  必填；mine=本人代办申请（含未同步申请）；managed=职责内已同步记录。',
+    '--student-id / --class-id  可选；两个范围均支持，同时填写须匹配同一名学生及其班级。',
+    resumption ? '--start-date / --end-date  可选；销假时段与查询日期重叠。销假时段是实际返校至原假期结束，不是仅返校当天。'
+      : '--start-date / --end-date  可选；请假时段与查询日期重叠。mine 查表单时段，managed 查已同步的有效假期。',
+    '--submitted-start-date / --submitted-end-date  可选，仅 mine；最近一次提交日期，重提会更新，未提交草稿不匹配。',
+    '两组日期各自成对填写 YYYY-MM-DD，开始不晚于结束；按北京时间自然日，包含首尾日。全部条件取交集。',
+    '--status  可选，按 scope 使用以下业务状态：',
+    '  mine：withdrawn 撤回、returned 已退回、draft 草稿、processing 处理中、completed 已完成。',
+    '  managed：not-started 未轮到审核、handled-by-peer 同级人已处理、pending 待审核、approved 已同意、rejected 不同意、withdrawn 被撤销。',
+    '--page  可选，默认 1，范围 1..2147483647。', '--page-size  可选，默认 20，范围 1..50。',
+  ] : [`--id  必填；${show ? '' : '本人代办的'}学生${subject} ID，来自 ${prefix}submit、${prefix}list 或 ${prefix}show。`];
+  const result = list ? [
+    'scope、items、page、page_size、total、total_pages；先筛选再分页，total 按申请或独立历史记录计数，一份申请多人不重复计数。',
+    'items[]：id、owned、title、workflow_status/workflow_status_name、created_at。owned 表示按本人代办读取；没有对应申请信息时相关字段为 null。',
+    'items[].records：managed 返回符合条件的可见学生记录；mine 为 null（未加载），需看明细时查详情。',
+  ] : show ? [
+    'id、owned、title、workflow_status/workflow_status_name、created_at、records、fields、progress、attachments。',
+    'records：可见学生、班级、业务时段、状态和进度；一份申请可含多人。[] 表示没有可见业务关联，不代表没有提交。',
+    resumption ? 'records[].id 标识本次销假；records[].leave_id 和 records[].original_leave.id 指向原请假。'
+      : 'records[].id 标识本次请假；records[].resumptions 为关联销假。',
+    'progress 节点 status 使用 pending/transferred/completed/returned/withdrawn，node_type 使用 start/normal/end。本人代办详情返回 fields、progress、attachments；其他申请这三个顶层字段为 null，只返回职责允许的业务记录与进度。',
+    'attachments：文件名、字段位置、download_url、expires_at。链接过期重查详情；历史 URL 图片保留在 fields 中。',
+  ] : urge ? [`id、event=${resumption ? 'resumption' : 'leave'}_urged、notified_count（实际通知人数）。`]
+    : [`id、event=${resumption ? 'resumption' : 'leave'}_withdrawn、withdrawn=true。`];
+  if (list || show) result.push('resumption_status=resumed/not-resumed 表示已销假/未销假；resumption_source=workflow/automatic-clock 表示工作流/打卡自动销假。未识别的状态返回 unknown，并在 status_code 或 workflow_status_code 保留原码；null 保持未知或未加载。');
+  const limits = list ? [
+    'mine 的班级取申请保存的班级；销假取绑定原请假的班级，不使用学生当前班级。',
+    '筛选所需映射、可读字段或关联缺失时明确报错。managed 不包含尚未同步的记录。',
+    'workflow_status 使用 mine 的流程状态名称，records[].status 使用 managed 的业务状态名称；列表和详情一致，未知或未加载仍为 null。流程“已完成”不一定是同意，也不代表考勤已经更新。',
+  ] : show ? [
+    'workflow_status 为流程状态名称，records[].status 为业务状态名称，与 list --help 的状态一致；流程状态、业务状态和考勤结果分别判断。' + (resumption ? '历史或自动销假可能没有流程进度。' : ''),
+  ] : [
+    '仅本人提交且仍在处理的申请；不支持家长或其他老师的申请，以及无申请关联的历史记录。',
+    urge ? '催办间隔 30 分钟；成功只说明已通知待处理人。' : resumption ? '撤回本次销假申请，原请假不会因此撤回。' : '撤回终止本次请假申请；结束已批准假期应办理销假。',
+    `结果不确定时查 ${prefix}show 核实，不自动重试。`,
+  ];
+  const examples = list ? [
+    '# 本人代办：按学生和提交日期查询',
+    `yunzhi-cli ${command} --scope mine --student-id <student_id> --submitted-start-date 2026-10-01 --submitted-end-date 2026-10-07`,
+    '# 本人代办：按班级和业务时段查询',
+    `yunzhi-cli ${command} --scope mine --class-id <class_id> --start-date 2026-10-08 --end-date 2026-10-10`,
+    '# 职责内：按班级和业务时段查询',
+    `yunzhi-cli ${command} --scope managed --class-id <class_id> --start-date 2026-10-08 --end-date 2026-10-10`,
+  ] : [`yunzhi-cli ${command} --id <id>`];
+  return `${purpose}\n\n用法：yunzhi-cli ${command} ${usage}\n\n参数：\n  ${parameters.join('\n  ')}\n\n示例：\n  ${examples.join('\n  ')}\n\n返回：\n  ${result.join('\n  ')}\n\n注意：\n  ${limits.join('\n  ')}\n  所需权限：attendance-leave:${list || show ? 'read' : 'write'}。\n`;
+}
+module.exports = { render };

package/lib/student-replenishment.cjs

@@ -0,0 +1,64 @@
+const { replenishmentId } = require('./attendance-leave-ids.cjs');
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+const identity = { tenant_id: required('string'), operator_id: required('string'), subject_id: required('string'), class_id: required('string'), date: required('string') };
+function validWindow(value) {
+  return typeof value === 'string' && /^[0-9]{1,2}:[0-9]{2}-[0-9]{1,2}:[0-9]{2}$/.test(value)
+    && value.split('-').every(time => { const [h, m] = time.split(':').map(Number); return h < 24 && m < 60 || h === 24 && m === 0; });
+}
+function parse(args) {
+  const keys = ['target_user_id', 'class_id', 'date', 'time_bucket', 'direction'];
+  const payload = options(args, keys, [], ['time_bucket'], true); requireArguments(payload, 'target_user_id', 'class_id', 'date');
+  if ((payload.time_bucket !== undefined) !== (payload.direction !== undefined))
+    throw invalid('--time-window 和 --direction 必须同时提供才能提交；两项都省略时只查询可补选项。');
+  const write = payload.time_bucket !== undefined;
+  if (!/^\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 日期；服务端只允许业务当天补签到。');
+  if (write) {
+    if (!validWindow(payload.time_bucket)) throw invalid('--time-window 必须使用可补选项中的时段，不能指定任意打卡时间。');
+    const enums = require('./attendance-leave-enums.cjs');
+    payload.direction = enums.encode(enums.direction, payload.direction, '--direction');
+  }
+  return payload;
+}
+function invalidReply(result) {
+  const failure = new Failure(1, 'api', 'invalid_response', '校门补签到返回的学生、班级、时段、规则或执行阶段缺失或不一致。');
+  if (result.value.request_id) failure.result.value.request_id = result.value.request_id; return failure;
+}
+function preserve(failure, payload, write) {
+  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', notification_status: 'UNCONFIRMED' } : {}) };
+    if (unknown) error.message += '补签到及通知结果待核实，请保留目标和请求标识，按需要查询当天打卡，不要自动重试。';
+  }
+  throw failure;
+}
+async function execute(args) {
+  const payload = parse(args);
+  const write = payload.time_bucket !== undefined;
+  try {
+    const result = await gateway.execute('attendance-leave:' + (write ? 'write' : 'read'), 'student-attendance/' + (write ? 'replenish' : 'replenishment-context'), payload, {
+      ...identity,
+      ...(write ? { id: nullable('string'), time_bucket: required('string'), direction: required('string'), request_id: required('string'), execution_status: required('string'), notification_status: nullable('string'), recorded_time: nullable('string'), handled_at: nullable('integer'), message: required('string') }
+        : { subject_name: required('string'), class_name: required('string'), rule_id: required('string'), rule_name: nullable('string'), options: required([{ time_bucket: required('string'), direction: required('string') }]) }),
+    });
+    const d = result.value.data;
+    if (d.subject_id !== payload.target_user_id || d.class_id !== payload.class_id || d.date !== payload.date) throw invalidReply(result);
+    if (write) {
+      if (d.execution_status === 'COMPLETED' ? !replenishmentId(d.id, '1', payload.date) : d.id != null) throw invalidReply(result);
+      if (d.time_bucket !== payload.time_bucket || d.direction !== payload.direction || result.value.request_id && result.value.request_id !== d.request_id
+          || d.handled_at != null && d.handled_at < 0
+          || (d.execution_status === 'COMPLETED' ? d.recorded_time !== payload.time_bucket.split('-')[1] + ':00' || d.handled_at == null
+            : d.execution_status !== 'UNCONFIRMED' || !['NOT_SUBMITTED', 'UNCONFIRMED'].includes(d.notification_status) || d.recorded_time != null)) throw invalidReply(result);
+      if (d.execution_status === 'COMPLETED' && !['SUBMITTED', 'UNCONFIRMED'].includes(d.notification_status)) {
+        d.notification_status = 'UNCONFIRMED';
+        d.message = '补签到记录已保存，后续家长通知状态无法核实；不要重复补签到。';
+      }
+    } else if (!/^[1-9][0-9]{0,9}$/.test(d.rule_id) || Number(d.rule_id) > 2147483647 || !d.options.length || d.options.some(o => !validWindow(o.time_bucket) || !['1', '2'].includes(o.direction))) throw invalidReply(result);
+    if (!write) d.message = '已查询可补签到的时段和方向，本次未提交补签到；需要办理时同时提供 --time-window 和 --direction。';
+    return result;
+  } catch (failure) { preserve(failure, payload, write); }
+}
+module.exports = { execute };

package/lib/student-report-detail.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 { reportSchema, validReportContext } = require('./saved-report-summary.cjs');
+const rowSchema = Object.fromEntries(['record_id', 'user_name', 'date', 'status', 'time_bucket', 'at_time', 'direction', 'site', 'remark',
+  'replenish_at_time', 'replenish_user_role', 'replenish_user_name', 'pic_url', 'video_url'].map(name => [name, nullable('string')]));
+rowSchema.user_id = required('string'); rowSchema.leave_ids = nullable(['string']);
+function shape(label = false) {
+  return {
+    tenant_id: required('string'), user_id: required('string'), ...(label ? {} : { class_id: required('string'), class_name: nullable('string') }),
+    report: required({ ...reportSchema }),
+    groups: required([{ type: required('string'), count: required('integer'), rows: required([rowSchema]) }]),
+  };
+}
+function validateQuery(payload, label = false) {
+  requireArguments(payload, ...(label ? ['report_id'] : ['report_id', 'class_id']));
+  if (!/^[1-9][0-9]{0,9}$/.test(payload.report_id) || Number(payload.report_id) > 2147483647 || !label && !payload.class_id.trim()) throw invalid(label ? '必须提供有效的标签报告 --report-id。' : '必须提供有效的 --report-id 和明确的 --class-id。');
+}
+function validate(result, payload, label = false) {
+  const d = result.value.data;
+  if ((label ? !d.report.scope_id?.trim() : d.class_id !== payload.class_id) || !validReportContext(d.report, payload.report_id, label ? ['6'] : ['1', '2', '3'])
+       || !d.groups.length
+      || new Set(d.groups.map(g => g.type)).size !== d.groups.length
+      || d.groups.some(g => !g.type.trim() || g.count < 0 || g.rows.some(r => !r.user_id.trim()
+        || r.leave_ids != null && r.leave_ids.some(id => !require('./student-leave-query.cjs').validId(id, false))))) {
+    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;
+}
+function addContext(failure, payload, label = false) {
+  if (failure instanceof Failure) failure.result.value.error.details = { ...failure.result.value.error.details, report_id: payload.report_id, ...(label ? {} : { class_id: payload.class_id }) };
+}
+async function execute(args, label = false) {
+  const payload = options(args, label ? ['report_id'] : ['report_id', 'class_id'], [], [], true); validateQuery(payload, label);
+  try { return validate(await gateway.execute('attendance-leave:read', 'student-attendance/report-' + (label ? 'label' : 'class'), payload, shape(label)), payload, label); }
+  catch (failure) { addContext(failure, payload, label); throw failure; }
+}
+module.exports = { execute };