@xiaoyuanhao/yunzhi-cli 2.0.0 → 2.1.0

package/lib/attendance.cjs

@@ -0,0 +1,404 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, present, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+
+const attendanceResult = { result_id: required('string'), rule_id: nullable('string'),
+      status: nullable('integer'), status_name: nullable('string'), period: nullable('integer'),
+      in_out_type: nullable('integer'), clock_time: nullable('string'), start_time: nullable('string'),
+      mark_time: nullable('string'), end_time: nullable('string'), remark: nullable('string'),
+      created_at: nullable('string'), updated_at: nullable('string') };
+
+const ruleShape = { rule_id: required('string'), name: nullable('string'), version_time: nullable('string'),
+      no_check: required('boolean'), shifts: required([{ period: nullable('integer'),
+        clock_in_required: nullable('boolean'), clock_out_required: nullable('boolean'),
+        clock_in_start_time: nullable('string'), clock_in_mark_time: nullable('string'), clock_in_end_time: nullable('string'),
+        clock_out_start_time: nullable('string'), clock_out_mark_time: nullable('string'), clock_out_end_time: nullable('string') }]) };
+
+const dormitoryRuleShape = { rule_id: required('string'), name: nullable('string'), version_time: nullable('string'),
+  no_check: required('boolean'), shifts: required([{ period: nullable('integer'), in_out_type: nullable('integer'),
+    start_time: nullable('string'), end_time: nullable('string'), polling: nullable('boolean') }]) };
+
+const dayShape = {
+    date: required('string'),
+    clock_records: required([{ record_id: required('string'), clock_time: nullable('string'),
+      in_out_type: nullable('string'), source: nullable('integer'), source_name: nullable('string'),
+      location: nullable('string'), device_id: nullable('string') }]),
+    attendance_results: required([attendanceResult]),
+    rules: required([ruleShape]),
+};
+
+function teacherQuery(args) {
+  const payload = options(args, ['date', 'scope', 'target_user_id'], [], [], true);
+  requireArguments(payload, 'date');
+  payload.scope ??= 'mine';
+  if (!['mine', 'managed'].includes(payload.scope)) throw invalid('--scope 只支持 mine 或 managed。');
+  if (payload.scope === 'managed') requireArguments(payload, 'target_user_id');
+  else if (payload.target_user_id != null) throw invalid('--scope mine 不能提供 --target-user-id。');
+  if (!validDate(payload.date)) throw invalid('--date 必须为有效的 YYYY-MM-DD 日期。');
+  return payload;
+}
+
+async function execute(args) {
+  const payload = teacherQuery(args);
+  const result = await gateway.execute('attendance-leave:read', 'attendance/show', payload, {
+    scope: required('string'), tenant_id: required('string'), operator_id: required('string'),
+    subject_id: required('string'), subject_name: nullable('string'), ...dayShape,
+  });
+  const data = result.value.data;
+  if (data.scope !== payload.scope || data.subject_id !== (payload.scope === 'mine' ? data.operator_id : payload.target_user_id)
+      || data.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;
+}
+
+const validDate = value => /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value))
+  && new Date(value).toISOString().slice(0, 10) === value;
+const positiveId = value => typeof value === 'string' && /^[1-9][0-9]*$/.test(value) && BigInt(value) <= 9223372036854775807n;
+const month = value => +value.slice(0, 4) * 12 + +value.slice(5, 7);
+const validTime = value => value == null || /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value)
+  && Number.isFinite(Date.parse(value.replace(' ', 'T') + 'Z'))
+  && new Date(value.replace(' ', 'T') + 'Z').toISOString().slice(0, 19).replace('T', ' ') === value;
+
+async function executeApplicableRule(args, context = 'own') {
+  const teacher = context === 'own';
+  const domain = context === 'dormitory' ? 'dormitory-attendance' : context === 'student' ? 'student-attendance' : 'attendance';
+  const payload = teacher ? teacherQuery(args) : options(args, ['date', 'target_user_id'], [], [], true);
+  requireArguments(payload, 'date', ...(!teacher ? ['target_user_id'] : []));
+  if (!validDate(payload.date)) throw invalid('--date 必须为有效的 YYYY-MM-DD 日期。');
+  const result = await gateway.execute('attendance-leave:read', domain + '/applicable-rule', payload, {
+    ...(teacher ? { scope: required('string') } : {}),
+    tenant_id: required('string'), operator_id: required('string'), subject_id: required('string'), subject_name: nullable('string'),
+    date: required('string'), read_at: required('string'), rule: present(context === 'dormitory' ? dormitoryRuleShape : ruleShape),
+  });
+  const data = result.value.data;
+  if (teacher && data.scope !== payload.scope || data.subject_id !== (teacher && payload.scope === 'mine' ? data.operator_id : payload.target_user_id) || data.date !== payload.date || !validTime(data.read_at) || !Object.hasOwn(data, 'rule')
+      || data.rule != null && !positiveId(data.rule.rule_id)) {
+    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 managedQuery(args, domain, paged = true) {
+  const students = domain === 'student-attendance';
+  const dormitory = domain === 'dormitory-attendance';
+  const payload = options(args, ['start_date', 'end_date', 'target_user_id', 'name', 'rule_id', 'status', ...(paged ? ['page', 'page_size'] : []),
+    ...(students || dormitory ? ['class_id'] : ['scope']), ...(students ? ['tag_id'] : []), ...(dormitory ? ['manage_id', 'period'] : [])], paged || dormitory ? ['abnormal'] : [], [], true);
+  return validateManagedQuery(payload, domain, paged);
+}
+function validateManagedQuery(payload, domain, paged) {
+  if (domain === 'attendance') {
+    payload.scope ??= 'mine';
+    if (!['mine', 'managed'].includes(payload.scope)) throw invalid('--scope 只支持 mine 或 managed。');
+    if (payload.scope === 'mine' && (payload.target_user_id != null || payload.name != null))
+      throw invalid('mine 范围不能提供 --target-user-id 或 --name；查询其他教师请使用 --scope managed。');
+  }
+  if (payload.abnormal != null && (!['attendance', 'student-attendance', 'dormitory-attendance'].includes(domain) || !paged && domain !== 'dormitory-attendance' || typeof payload.abnormal !== 'boolean'))
+    throw invalid('--abnormal 仅用于考勤列表或宿舍考勤统计。');
+  if (payload.abnormal && payload.status != null) throw invalid('--abnormal 与 --status 不能同时提供。');
+  const dormitory = domain === 'dormitory-attendance';
+  requireArguments(payload, 'start_date', 'end_date');
+  if (!validDate(payload.start_date) || !validDate(payload.end_date) || payload.start_date > payload.end_date
+      || (dormitory ? (Date.parse(payload.end_date) - Date.parse(payload.start_date)) / 86400000 >= 31
+        : month(payload.end_date) - month(payload.start_date) > 1))
+    throw invalid('--start-date 和 --end-date 必须为有效的YYYY-MM-DD，开始不能晚于结束，' + (dormitory ? '含首尾最多31天。' : '最多跨两个自然月。'));
+  if (paged) for (const [key, fallback, maximum] of [['page', 1, 2147483647], ['page_size', 20, 50]]) {
+    const value = payload[key] ?? fallback;
+    if (!/^[0-9]+$/.test(String(value)) || +value < 1 || +value > maximum) throw invalid(key + ' 必须为1到' + maximum + '的整数。');
+    payload[key] = +value;
+  }
+  if (paged && (payload.page - 1) * payload.page_size > 2147483647) throw invalid('分页偏移不能超过2147483647，请缩小查询条件。');
+  if (payload.tag_id != null && (domain !== 'student-attendance' || !paged || !payload.tag_id.trim() || payload.tag_id.length > 200)) throw invalid('--tag-id 须为 tags 返回的标签 ID，仅用于学生校门考勤列表。');
+  if (payload.rule_id != null && !positiveId(payload.rule_id)) throw invalid('--rule-id 必须为有效的规则ID。');
+  if (payload.name != null && payload.name.length > 50 || payload.class_id?.includes(',')) throw invalid('姓名最多50字，班级标识不能包含逗号。');
+  if (dormitory) {
+    if (payload.manage_id != null && (!positiveId(payload.manage_id) || payload.class_id != null)) throw invalid('--group-id 必须为真实管理组ID，不能与--class-id同时提供。');
+    if (payload.period != null) {
+      if (!/^[1-9][0-9]*$/.test(payload.period) || +payload.period > 2147483647 || payload.rule_id == null) throw invalid('--period 必须为正整数，并同时提供--rule-id。');
+      payload.period = +payload.period;
+    }
+  }
+  if (payload.status != null) {
+    const enums = require('./attendance-leave-enums.cjs');
+    payload.status = enums.encode(dormitory ? enums.dormitoryStatus : enums.gateStatus, payload.status, '--status');
+  }
+  return payload;
+}
+async function executeManaged(args, domain) {
+  const students = domain === 'student-attendance';
+  const dormitory = domain === 'dormitory-attendance';
+  const payload = managedQuery(args, domain);
+  const mine = domain === 'attendance' && payload.scope === 'mine';
+  const result = await gateway.execute('attendance-leave:read', domain + '/list', payload, {
+    tenant_id: required('string'), operator_id: required('string'), attendance_type: required('string'),
+    start_date: required('string'), end_date: required('string'), school_wide: required('boolean'),
+    scope_classes: required([{ class_id: required('string'), class_name: required('string') }]),
+    ...(domain === 'attendance' ? { scope: required('string') } : {}),
+    ...(students ? { tag_id: nullable('string'), tag_name: nullable('string') } : {}),
+    ...(dormitory ? { abnormal: required('boolean'), scope_manage_groups: required([{ manage_id: required('string'), manage_name: required('string'), building_id: nullable('string'),
+      bedrooms: required([{ bedroom_id: required('string'), bedroom_name: required('string') }]) }]) } : {}),
+    items: required([{ user_id: required('string'), user_name: nullable('string'), date: required('string'),
+      department_ids: nullable('string'), department_name: nullable('string'),
+      clock_record_id: nullable('string'), clock_method: nullable('integer'),
+      ...(dormitory ? { bedroom_id: nullable('string'), bedroom_name: nullable('string') } : {}), result: required(attendanceResult) }]),
+    page: required('integer'), page_size: required('integer'), total: required('integer'), total_pages: required('integer'),
+  });
+  const data = result.value.data;
+  const classes = new Set(data.scope_classes.map(row => row.class_id));
+  const ids = new Set(data.items.map(row => row.result.result_id));
+  const groups = dormitory ? data.scope_manage_groups : [];
+  const groupIds = new Set(groups.map(row => row.manage_id));
+  const rooms = new Set(groups.filter(row => payload.manage_id == null || row.manage_id === payload.manage_id).flatMap(row => row.bedrooms.map(room => room.bedroom_id)));
+  const valid = data.attendance_type === (dormitory ? '2' : students ? '1' : '4') && data.start_date === payload.start_date && data.end_date === payload.end_date
+    && (!students || data.tag_id === (payload.tag_id ?? null) && (payload.tag_id == null ? data.tag_name == null : !!data.tag_name?.trim()))
+    && 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))
+    && (students || dormitory || data.scope === payload.scope && data.school_wide === !mine)
+    && (data.school_wide || mine ? classes.size === 0 : classes.size > 0 || dormitory && groups.length > 0)
+    && (!dormitory || data.abnormal === Boolean(payload.abnormal) && groupIds.size === groups.length && (payload.manage_id == null || groupIds.has(payload.manage_id))
+      && groups.every(group => positiveId(group.manage_id) && (group.building_id == null || positiveId(group.building_id))
+        && new Set(group.bedrooms.map(room => room.bedroom_id)).size === group.bedrooms.length && group.bedrooms.every(room => positiveId(room.bedroom_id))))
+    && classes.size === data.scope_classes.length && data.scope_classes.every(row => !row.class_id.includes(',')) && ids.size === data.items.length
+    && (data.school_wide || payload.class_id == null || classes.has(payload.class_id))
+    && data.items.every(row => {
+      const departments = row.department_ids?.split(',') || [];
+      return validDate(row.date) && row.date >= payload.start_date && row.date <= payload.end_date
+        && (dormitory ? (row.bedroom_id == null || positiveId(row.bedroom_id))
+          && (payload.manage_id == null && (data.school_wide || classes.size > 0) || rooms.has(row.bedroom_id))
+          : (mine || data.school_wide || departments.some(id => classes.has(id))) && (payload.class_id == null || departments.includes(payload.class_id)))
+        && (!mine || row.user_id === data.operator_id)
+        && (payload.target_user_id == null || row.user_id === payload.target_user_id)
+        && (payload.name == null || row.user_name?.includes(payload.name)) && (payload.status == null || row.result.status === payload.status)
+        && (!payload.abnormal || (dormitory ? [13, 14, 15, 16] : [-1, -2, -3]).includes(row.result.status))
+        && (payload.period == null || row.result.period === payload.period)
+        && (row.result.rule_id == null || positiveId(row.result.rule_id)) && (payload.rule_id == null || row.result.rule_id === payload.rule_id)
+        && ['clock_time', 'start_time', 'mark_time', 'end_time', 'created_at', 'updated_at'].every(key => validTime(row.result[key]));
+    });
+  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;
+}
+
+async function executeTags(args) {
+  const payload = options(args, ['name'], [], [], true);
+  requireArguments(payload, 'name');
+  if (!payload.name.trim() || payload.name.length > 50) throw invalid('--name 须为1到50字的标签名称。');
+  const result = await gateway.execute('attendance-leave:read', 'student-attendance/tags', payload, {
+    tenant_id: required('string'), operator_id: required('string'), name: required('string'),
+    items: required([{ id: required('string'), name: required('string'), type: required('string') }]),
+  });
+  const data = result.value.data;
+  if (data.name !== payload.name || new Set(data.items.map(row => row.id)).size !== data.items.length
+      || data.items.some(row => !row.id.trim() || row.id.length > 200 || !row.name.includes(payload.name) || !['general', 'system'].includes(row.type))) {
+    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;
+}
+
+async function executeManagedDay(args, domain) {
+  const students = domain === 'student-attendance', dormitory = domain === 'dormitory-attendance';
+  const payload = options(args, ['target_user_id', 'date'], [], [], true);
+  requireArguments(payload, 'target_user_id', 'date');
+  if (!validDate(payload.date)) throw invalid('--date 必须为有效的 YYYY-MM-DD 日期。');
+  const result = await gateway.execute('attendance-leave:read', domain + '/show', payload, {
+    tenant_id: required('string'), operator_id: required('string'), subject_id: required('string'), subject_name: nullable('string'),
+    attendance_type: required('string'), day: required(dormitory ? { ...dayShape,
+      rules: required([dormitoryRuleShape]),
+    } : dayShape),
+  });
+  const data = result.value.data;
+  if (data.subject_id !== payload.target_user_id || data.attendance_type !== (dormitory ? '2' : students ? '1' : '4') || data.day.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;
+}
+async function executeRemark(args, kind = 'own') {
+  const student = kind === 'student', dormitory = kind === 'dormitory', teacher = !student && !dormitory;
+  const domain = dormitory ? 'dormitory-attendance' : student ? 'student-attendance' : 'attendance';
+  const payload = options(args, ['date', 'result_id', 'remark', 'target_user_id', ...(teacher ? ['scope'] : [])], ['clear'], ['remark'], true);
+  if (teacher) {
+    payload.scope ??= 'mine';
+    if (!['mine', 'managed'].includes(payload.scope)) throw invalid('--scope 只支持 mine 或 managed。');
+    if (payload.scope === 'mine' && payload.target_user_id != null) throw invalid('--scope mine 不能提供 --target-user-id。');
+  }
+  const managed = !teacher || payload.scope === 'managed';
+  requireArguments(payload, 'date', 'result_id', ...(managed ? ['target_user_id'] : []));
+  if (!validDate(payload.date) || (payload.remark != null) === (payload.clear === true))
+    throw invalid('--date 必须为有效的 YYYY-MM-DD；--remark <text> 与 --clear 必须且只能选择一项。');
+  if (payload.clear) payload.remark = '';
+  delete payload.clear;
+  try {
+    const result = await gateway.execute('attendance-leave:write', domain + '/remark', payload, {
+      tenant_id: required('string'), operator_id: required('string'), subject_id: required('string'),
+      ...(teacher ? { scope: required('string') } : {}),
+      date: required('string'), result_id: required('string'),
+      request_id: required('string'), execution_status: required('string'), message: required('string'),
+    });
+    const data = result.value.data;
+    if (data.date !== payload.date || data.result_id !== payload.result_id || data.subject_id !== (managed ? payload.target_user_id : data.operator_id) || teacher && data.scope !== payload.scope
+        || !['COMPLETED', 'NOT_EXECUTED', 'UNCONFIRMED'].includes(data.execution_status)
+        || result.value.request_id && result.value.request_id !== data.request_id) {
+      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 = error.type === 'network' && error.subtype !== 'connection_failed'
+        || error.type === 'api' && error.subtype === 'invalid_response';
+      error.details = { ...error.details, ...(teacher ? { scope: payload.scope } : {}), ...(managed ? { target_user_id: payload.target_user_id } : {}), date: payload.date, result_id: payload.result_id,
+        ...(unknown ? { execution_status: 'UNCONFIRMED' } : {}) };
+      if (unknown && !error.message.includes('不要自动重试')) error.message += dormitory ? '请查询目标学生宿舍考勤详情核实备注，不要自动重试。' : student ? '请查询目标学生校门考勤详情核实备注，不要自动重试。' : managed ? '请查询目标教师考勤详情核实备注，不要自动重试。' : '请查询本人考勤详情核实备注，不要自动重试。';
+    }
+    throw failure;
+  }
+}
+async function executeCorrectionForm(args) {
+  const payload = options(args, ['date', 'result_id', 'correction_time', 'field_values'], [], [], true);
+  requireArguments(payload, 'date', 'result_id');
+  require('./leave.cjs').parseFieldValues(payload);
+  if (payload.correction_time !== undefined) {
+    require('./leave.cjs').validateResumptionTime(payload.correction_time);
+    if (payload.correction_time.slice(0, 10) !== payload.date) throw invalid('补卡时间必须属于所选考勤日期。');
+  }
+  if (!validDate(payload.date)) throw invalid('--date 必须为有效的 YYYY-MM-DD 日期。');
+  try {
+    const result = await gateway.execute('attendance-leave:read', 'attendance/correction-form', { date: payload.date, result_id: payload.result_id }, {
+      tenant_id: required('string'), user_id: required('string'), date: required('string'), result: required(attendanceResult),
+      rule_name: nullable('string'), rule_version_time: nullable('string'), correction_enabled: required('boolean'),
+      times_per_month: nullable('integer'), day_delay: nullable('integer'), used_in_month: required('integer'),
+      status: required('string'), reason: nullable('string'), program_code: nullable('string'),
+      time_field_key: nullable('string'), fields: nullable([require('./leave.cjs').teacherFormField]),
+    });
+    const data = result.value.data;
+    if (data.date !== payload.date || data.result.result_id !== payload.result_id || !positiveId(data.result.rule_id)
+        || data.used_in_month < 0 || !data.correction_enabled && (data.times_per_month != null || data.day_delay != null)) {
+      const failure = new Failure(1, 'api', 'invalid_response', '补卡查询返回的日期、时段、规则、开关或用量不一致。');
+      if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+      throw failure;
+    }
+    if (data.status === 'unavailable') {
+      if (data.correction_enabled || !data.reason?.trim() || data.program_code != null || data.time_field_key != null || data.fields != null) {
+        const failure = new Failure(1, 'api', 'invalid_response', '补卡关闭状态与原因或表单字段不一致。');
+        if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+        throw failure;
+      }
+    } else {
+      const timeFields = data.time_field_key == null ? [] : (data.fields || []).filter(field => field.field_key === data.time_field_key);
+      if (data.status !== 'ready' || !data.correction_enabled || !data.program_code?.trim() || data.reason != null || !validCorrectionFields(data.fields)
+          || data.time_field_key != null && (timeFields.length !== 1
+            || !['date', 'datetime'].includes(timeFields[0].type))) {
+        const failure = new Failure(1, 'api', 'invalid_response', '本人补卡表单的开关、流程或可见时间字段不完整或不一致。');
+        if (result.value.request_id) failure.result.value.request_id = result.value.request_id;
+        throw failure;
+      }
+      data.form_check = require('./teacher-leave-form-check.cjs').evaluate({ ...data,
+        field_mappings: data.time_field_key ? { correctionTime: data.time_field_key } : {} }, payload.field_values, payload);
+      if (!payload.correction_time) {
+        data.form_check.issues.push({ code: 'missing_required', parameter: 'correction_time', message: '请补充实际需要补卡的时间。' });
+        if (data.form_check.status === 'complete') data.form_check.status = 'needs_input';
+      }
+    }
+    return result;
+  } catch (failure) {
+    if (failure instanceof Failure) {
+      const error = failure.result.value.error;
+      error.details = { ...error.details, date: payload.date, result_id: payload.result_id };
+    }
+    throw failure;
+  }
+}
+
+async function checkCorrectionBeforeSubmit(payload) {
+  try {
+    const args = ['--date', payload.date, '--result-id', payload.result_id, '--correction-time', payload.correction_time];
+    if (payload.field_values !== undefined) args.push('--field-values', JSON.stringify(payload.field_values));
+    const form = (await executeCorrectionForm(args)).value.data;
+    if (form.status === 'unavailable') throw new Failure(2, 'validation', 'correction_unavailable', form.reason);
+    if (form.form_check.status !== 'complete') throw new Failure(2, 'validation', 'form_input_required',
+      '补卡表单还有需要处理的信息，尚未上传文件或提交申请。', { form_check: form.form_check });
+  } 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;
+  }
+}
+function validCorrectionFields(fields) {
+  return Array.isArray(fields) && fields.every(field => field.field_key.trim() && field.type.trim()
+    && typeof field.editable === 'boolean' && (field.groups == null || field.groups.every(group => validCorrectionFields(group.fields))));
+}
+async function executeReportSummary(args) {
+  const payload = options(args, ['month', 'rule_id', 'keyword', 'page', 'page_size'], [], [], true);
+  for (const [key, fallback, maximum] of [['page', 1, 2147483647], ['page_size', 20, 100]]) {
+    if (payload[key] == null) payload[key] = fallback;
+    else if (!/^[1-9][0-9]*$/.test(payload[key]) || Number(payload[key]) > maximum) throw invalid('--' + key.replace('_', '-') + ' 超出有效分页范围。');
+    else payload[key] = Number(payload[key]);
+  }
+  validateReportQuery(payload);
+  const result = await gateway.execute('attendance-leave:read', 'attendance/report-summary', payload, reportShape);
+  validateReportSummary(result, payload);
+  return result;
+}
+const reportRowShape = {
+  user_id: required('string'), user_name: nullable('string'), department: nullable('string'), date: required('string'),
+  rule_id: required('string'), rule_name: nullable('string'), has_approved_leave: required('boolean'), result: required('string'), reasons: required(['string']),
+  slots: required([{ required: required('boolean'), period: required('integer'), direction: required('string'), start: required('integer'), threshold: required('integer'), end: required('integer') }]),
+  leaves: required([{ start: required('integer'), end: required('integer'), daily_start: required('integer'), daily_end: required('integer') }]),
+  events: required([{ time: required('integer'), direction: required('string') }]),
+};
+const reportShape = {
+    tenant_id: required('string'), operator_id: required('string'), month: required('string'), rule_id: nullable('string'), keyword: nullable('string'),
+    all_count: required('integer'), normal_count: required('integer'), abnormal_count: required('integer'), leave_count: required('integer'),
+    generated_at: required('integer'), scope_note: required('string'), rules: required([{ rule_id: required('string'), name: nullable('string') }]),
+    page: required('integer'), page_size: required('integer'), total: required('integer'), total_pages: required('integer'), items: required([reportRowShape]),
+};
+function validateReportQuery(payload) {
+  requireArguments(payload, 'month');
+  if (!validDate(payload.month + '-01') || payload.month < '2000-01') throw invalid('--month 必须为有效的 YYYY-MM，不能早于2000-01。');
+  if (payload.rule_id != null && !positiveId(payload.rule_id)) throw invalid('--rule-id 必须为有效的规则ID。');
+  if (payload.keyword != null && payload.keyword.length > 100) throw invalid('--keyword 最多100个字符。');
+}
+function validateReportSummary(result, payload) {
+  const data = result.value.data;
+  const ids = new Set(data.rules.map(rule => rule.rule_id));
+  const timestamp = value => Number.isSafeInteger(value) && value > 0;
+  const detailsValid = data.page === payload.page && data.page_size === payload.page_size && data.total === data.all_count
+    && 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 => JSON.stringify([row.user_id, row.date, row.rule_id]))).size === data.items.length
+    && data.items.every(row => row.user_id.trim() && validDate(row.date) && row.date.startsWith(payload.month + '-')
+      && ids.has(row.rule_id) && (payload.rule_id == null || row.rule_id === payload.rule_id)
+      && ['normal', 'abnormal', 'leave', 'pending'].includes(row.result) && row.has_approved_leave === (row.leaves.length > 0)
+      && row.slots.every(slot => slot.period > 0 && ['in', 'out'].includes(slot.direction)
+        && timestamp(slot.start) && timestamp(slot.threshold) && timestamp(slot.end) && slot.start <= slot.end)
+      && row.leaves.every(leave => [leave.start, leave.end, leave.daily_start, leave.daily_end].every(timestamp)
+        && leave.start <= leave.daily_start && leave.daily_start <= leave.daily_end && leave.daily_end <= leave.end)
+      && row.events.every(event => timestamp(event.time) && ['in', 'out', 'unknown'].includes(event.direction)));
+  if (!detailsValid || data.month !== payload.month || data.rule_id !== (payload.rule_id ?? null) || data.keyword !== (payload.keyword ?? null)
+      || ['all_count', 'normal_count', 'abnormal_count', 'leave_count'].some(key => data[key] < 0)
+      || data.normal_count + data.abnormal_count > data.all_count || data.leave_count > data.all_count || data.generated_at <= 0
+      || !data.scope_note.trim() || data.rules.some(rule => !positiveId(rule.rule_id)) || ids.size !== data.rules.length
+      || data.all_count > 0 && ids.size === 0 || payload.rule_id != null && !ids.has(payload.rule_id)) {
+    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 = { attendanceResult, validTime, validDate, executeTags, checkCorrectionBeforeSubmit, managedQuery, validateManagedQuery, execute, executeApplicableRule, executeManaged, executeManagedDay, executeRemark, executeCorrectionForm, executeReportSummary };

package/lib/auth.cjs

@@ -53,7 +53,7 @@ async function login(args, signal) {
       const failure = invalidAuthorization('Agent Gateway 返回了无效授权会话。', result);
       throw urlError ? attach(failure, urlError) : failure;
     }
-    output.value.data.message = '授权会话已创建。请向用户展示 authorization_url，等待用户明确确认网页授权完成后，使用 device_code 兑换登录态。';
+    output.value.data.message = '授权会话已创建。请将 authorization_url 展示为可点击的 Markdown 链接：[完整 URL](完整 URL)，两处保留完整原始地址，不使用行内代码或代码块。用用户的语言和业务名称说明所需权限，不直接展示权限代码。等待用户明确确认网页授权完成后，使用 device_code 兑换登录态。';
     return output;
   } catch (error) {
     if (token && error.result?.value.error.type === 'authentication' && error.result.value.error.subtype === 'auth_required') {

package/lib/business-schemas.cjs

@@ -1,4 +1,4 @@
-const { optionalFields, nullableFields, nullable, required } = require('./result.cjs');
+const { optionalFields, nullableFields, nullable, required, fields } = require('./result.cjs');
 const { snippet } = require('./lesson-prep.cjs');
 const resource = { ...optionalFields({ type: 'string', file_id: 'string', kind: 'string', space: 'string', name: 'string',
   path: 'string', file_ext: 'string', file_size: 'integer', label_ids: ['string'], updated_at: 'string', web_url: 'string' }), category_id: nullable('string') };
@@ -6,6 +6,8 @@ const folder = optionalFields({ event: 'string', folder_id: 'string', name: 'str
 const textbook = optionalFields({ event: 'string', textbook_id: 'string', folder_id: 'string', name: 'string', path: 'string' });
 module.exports = {
   errors: {
+    resumption_operation_unconfirmed: (value, path) => fields(value, { [Object.hasOwn(value, 'id') ? 'id' : 'application_id']: required('string'), action: required('string') }, path),
+    leave_operation_unconfirmed: { id: required('string'), action: required('string') },
     ...require('./report-schemas.cjs').errors,
     invalid_pattern: { syntax: ['string'], examples: ['string'] },
     file_report_pending: { report_id: 'string', report_status: 'string' },