@xiaoyuanhao/yunzhi-cli 2.0.0 → 2.1.0

package/lib/attendance-operation-result.cjs

@@ -0,0 +1,97 @@
+// Describe only confirmed receipt stages; application progress is a separate fact.
+function authorizationDescription(scopes) {
+  const names = { 'attendance-leave:read': '查看', 'attendance-leave:write': '办理', 'attendance-leave:approve': '审批' };
+  const labels = [...new Set((scopes || []).map(scope => names[scope]).filter(Boolean))];
+  return labels.length ? `本次考勤请假所需授权：${labels.join('、')}。` : undefined;
+}
+
+function describe(command, value) {
+  const action = command.split(' ')[1].replace(/^(resumption-|correction-)/, '');
+  const completed = {
+    submit: '申请已提交，不代表审批已经通过。',
+    approve: '当前审批节点已同意，不代表整张申请已经通过。',
+    reject: '当前审批节点已退回。',
+    withdraw: '申请已撤回。',
+    remind: '催办已完成，不代表审批已经通过。',
+    remark: '考勤备注已保存。',
+    'report-remark': '报表备注已保存。',
+    'manual-entry': '补签到记录已保存。',
+    'manual-entry-delete': '补签到记录已删除。',
+  }[action];
+  const execution = {
+    COMPLETED: completed || '本次操作已执行。',
+    NOT_EXECUTED: '本次操作未执行。',
+    UNCONFIRMED: '本次操作结果未知，不能认定成功或未执行；先查询结果，不要重复提交。',
+  }[value.execution_status];
+  if (!execution) return;
+  const processing = {
+    SUBMITTED: '后续处理任务已提交，尚不能据此确认考勤结果已更新。',
+    COMPLETED: '回执确认后续处理已完成；具体考勤判定以考勤查询结果为准。',
+    FAILED: '后续处理失败，不能据此否定已确认的操作结果。',
+    NOT_STARTED: '回执未确认后续处理已启动。',
+  }[value.post_processing_status];
+  return execution + (processing || '')
+    + (value.attachment_uploads?.length ? '附件上传结果单独保留，文件上传成功不等于申请或审批成功。' : '');
+}
+
+function project(command, envelope) {
+  const value = envelope.ok ? envelope.data : envelope.error;
+  if (!value) return;
+  const authorization = authorizationDescription(envelope.ok && /^auth (login|connect)$/.test(command)
+    ? value.requested_scopes : !envelope.ok ? value.required_scopes : undefined);
+  if (authorization) value.authorization_description = authorization;
+  if (!/^(leave|student-leave|attendance|student-attendance|dormitory-attendance) /.test(command)) return;
+  let executionStatus = value.execution_status || value.details?.execution_status;
+  if (!executionStatus && envelope.ok && /^(leave|student-leave) (resumption-)?(remind|withdraw)$/.test(command)) {
+    const prefix = command.includes('resumption-') ? 'resumption' : 'leave';
+    const remind = command.endsWith('remind');
+    if (value.event === prefix + (remind ? '_urged' : '_withdrawn')
+        && (remind ? Number.isInteger(value.notified_count) && value.notified_count >= 0 : value.withdrawn === true))
+      executionStatus = 'COMPLETED';
+  }
+  const explanation = describe(command, { ...value, execution_status: executionStatus });
+  if (explanation) value.operation_result_description = explanation;
+  if (envelope.ok && /^(student|dormitory)-attendance manual-entr(y|ies)$/.test(command)) {
+    value.time_description = '补签到确认的是所选考勤时段已到；时段起止不是实际到达时刻，创建时间是办理时间。本记录不提供真实到达时间。';
+  }
+  if (envelope.ok && /^(attendance|student-attendance|dormitory-attendance) show$/.test(command)) {
+    const day = value.day || value;
+    value.result_basis = { source: 'saved_attendance_results', description: '考勤结论来自已保存的考勤判定。更新时间表示记录保存时间；本响应未提供重算执行记录，不能仅凭更新时间判断是否重算或请假、销假是否同步。' };
+    if (day.attendance_results?.length === 0)
+      value.result_absence = { reason: null, description: '本次查询未返回已保存考勤判定，未查明原因；不能据此认定没有规则、正常出勤或缺勤。' };
+  }
+  if (envelope.ok && command === 'attendance correction-form' && value.status === 'ready' && value.form_check) {
+    const visible = new Set(value.form_check.visible_fields.map(field => field.field_key));
+    const textFields = [];
+    const collect = fields => {
+      for (const field of fields || []) {
+        if (!field.editable || field.computed || !visible.has(field.field_key)) continue;
+        if (['text', 'multiline_text'].includes(field.type)) textFields.push(field.label);
+        for (const group of field.groups || []) collect(group.fields);
+        collect(field.row_template);
+      }
+    };
+    collect(value.fields);
+    value.text_input = { available: textFields.length > 0, fields: [...new Set(textFields)],
+      description: textFields.length ? '这些是当前可填写的文字字段，填写用途以字段说明为准。'
+        : '当前显示的表单没有可填写的文字字段，不能随本次申请保存文字原因或补充说明。' };
+  }
+  if (envelope.ok && /^student-attendance report-(summary|class|tag)$/.test(command)) {
+    value.basis = { attendance: command.endsWith('summary') ? '保存的报表汇总' : '查询时按该报表范围读取的明细',
+      date: value.report.content_date, time_bucket: value.report.time_bucket,
+      description: '接收日期不是考勤日期；保存汇总与查询时明细可能不同，差异原因需另行核实。' };
+  }
+}
+
+function transportFailure(endpoint, failure) {
+  // Only the actual write request reaches this boundary, not its form/permission reads.
+  if (!/^(leave|student-leave)\/(submit|start|approve|reject|remind|urge|withdraw|resumption-(submit|start|approve|reject|remind|urge|withdraw))$/.test(endpoint)
+      && !/^attendance\/correction-(submit|start|approve|reject)$/.test(endpoint)) return;
+  const error = failure.result?.value?.error;
+  if (!error || error.execution_status) return;
+  if (error.type === 'network')
+    error.execution_status = error.subtype === 'connection_failed' ? 'NOT_EXECUTED' : 'UNCONFIRMED';
+  else if (error.type === 'api' && error.subtype === 'invalid_response') error.execution_status = 'UNCONFIRMED';
+}
+
+module.exports = { project, transportFailure };

package/lib/attendance-report-inbox.cjs

@@ -0,0 +1,42 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+const { currentReport } = require('./dormitory-report-id.cjs');
+function validDate(value) {
+  return /^\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;
+}
+async function execute(args, domain) {
+  const payload = options(args, ['delivery_date', 'start_date', 'end_date'], [], [], true);
+  const single = payload.delivery_date !== undefined;
+  if (single && (payload.start_date !== undefined || payload.end_date !== undefined)) throw invalid('--delivery-date 与 --start-date/--end-date 不能混用。');
+  if (!single) requireArguments(payload, 'start_date', 'end_date');
+  const start = single ? payload.delivery_date : payload.start_date, end = single ? payload.delivery_date : payload.end_date;
+  if (!validDate(start) || !validDate(end) || start > end) throw invalid('接收日期必须为有效的 YYYY-MM-DD，开始日期不能晚于结束日期。');
+  try {
+    const result = await gateway.execute('attendance-leave:read', domain + '/reports', payload, {
+      tenant_id: required('string'), user_id: required('string'), delivery_date: nullable('string'), start_date: required('string'), end_date: required('string'), attendance_type: required('string'), total: required('integer'),
+      reports: required([{ report_id: required('string'), content_date: nullable('string'), delivery_date: required('string'), time_bucket: nullable('string'),
+        scope_type: nullable('string'), scope_id: nullable('string'), scope_name: nullable('string'), snapshot_missing_count: nullable('integer'),
+        configuration_name: nullable('string'), calculation_time: nullable('string'), direction: nullable('string') }]),
+    });
+    const data = result.value.data;
+    if (data.delivery_date !== (single ? start : null) || data.start_date !== start || data.end_date !== end || data.attendance_type !== (domain === 'dormitory-attendance' ? '2' : '1')
+        || data.total !== data.reports.length || new Set(data.reports.map(row => row.report_id)).size !== data.reports.length
+        || data.reports.some(row => !(domain === 'dormitory-attendance' && currentReport(row.report_id)
+          ? row.content_date === row.report_id.slice(17, 25).replace(/^(\d{4})(\d{2})(\d{2})$/, '$1-$2-$3')
+            && ['school', 'class', 'rooms'].includes(row.scope_type) && ['in', 'out'].includes(row.direction)
+            && typeof row.time_bucket === 'string' && row.time_bucket.trim().length > 0 && row.snapshot_missing_count === null
+            && (row.scope_type === 'class' ? typeof row.scope_id === 'string' && row.scope_id.trim().length > 0 : row.scope_id === null)
+          : /^[1-9][0-9]*$/.test(row.report_id) && BigInt(row.report_id) <= 2147483647n && row.snapshot_missing_count !== null)
+          || !validDate(row.delivery_date) || row.delivery_date < start || row.delivery_date > end || row.content_date != null && !validDate(row.content_date)
+          || row.snapshot_missing_count < 0)) {
+      const failure = new Failure(1, 'api', 'invalid_response', '考勤报告返回的日期、类型、数量或报告记录缺失或不一致。');
+      if (result.value.request_id) failure.result.value.request_id = result.value.request_id; throw failure;
+    }
+    return result;
+  } catch (failure) {
+    if (failure instanceof Failure) failure.result.value.error.details = { ...failure.result.value.error.details, ...payload };
+    throw failure;
+  }
+}
+module.exports = { execute };

package/lib/attendance-report-remarks.cjs

@@ -0,0 +1,62 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+
+function parse(args, write) {
+  const payload = options(args, ['target_user_id', 'date', ...(write ? ['time_bucket', 'remark'] : [])], write ? ['clear'] : [], ['time_bucket', 'remark'], true);
+  requireArguments(payload, 'target_user_id', 'date', ...(write ? ['time_bucket'] : []));
+  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 ((payload.remark != null) === (payload.clear === true)) throw invalid('--remark <text> 与 --clear 必须且只能选择一项。');
+    if (payload.clear) payload.remark = '';
+    delete payload.clear;
+  }
+  return payload;
+}
+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, target_user_id: payload.target_user_id, date: payload.date,
+      ...(write ? { time_bucket: payload.time_bucket } : {}), ...(unknown ? { execution_status: 'UNCONFIRMED' } : {}) };
+    if (unknown && !error.message.includes('不要自动重试')) error.message += '请查询该学生当日旧报告备注核实，不要自动重试。';
+  }
+  throw failure;
+}
+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;
+}
+async function save(args, domain = 'student-attendance') {
+  const payload = parse(args, true);
+  try {
+    const result = await gateway.execute('attendance-leave:write', domain + '/report-remark', payload, {
+      tenant_id: required('string'), operator_id: required('string'), subject_id: required('string'), date: required('string'),
+      time_bucket: required('string'), request_id: required('string'), execution_status: required('string'), message: required('string'),
+    });
+    const data = result.value.data;
+    if (data.subject_id !== payload.target_user_id || data.date !== payload.date || data.time_bucket !== payload.time_bucket
+        || !['COMPLETED', 'UNCONFIRMED'].includes(data.execution_status)
+        || result.value.request_id && result.value.request_id !== data.request_id) throw invalidReply(result);
+    return result;
+  } catch (failure) { preserve(failure, payload, true); }
+}
+async function read(args, domain = 'student-attendance') {
+  const payload = parse(args, false);
+  try {
+    const result = await gateway.execute('attendance-leave:read', domain + '/report-remarks', payload, {
+      tenant_id: required('string'), operator_id: required('string'), subject_id: required('string'), date: required('string'),
+      remarks: required([{ remark_id: required('string'), time_bucket: nullable('string'), remark: nullable('string'),
+        created_by: nullable('string'), created_at: nullable('integer'), modified_by: nullable('string'), modified_at: nullable('integer') }]),
+    });
+    const data = result.value.data;
+    if (data.subject_id !== payload.target_user_id || data.date !== payload.date
+        || new Set(data.remarks.map(note => note.remark_id)).size !== data.remarks.length
+        || data.remarks.some(note => !/^[1-9][0-9]*$/.test(note.remark_id) || BigInt(note.remark_id) > 2147483647n)) throw invalidReply(result);
+    return result;
+  } catch (failure) { preserve(failure, payload, false); }
+}
+module.exports = { read, save };

package/lib/attendance-statistics.cjs

@@ -0,0 +1,49 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, nullable, invalid, Failure } = require('./result.cjs');
+const gateway = require('./gateway.cjs');
+const validDate = value => typeof value === 'string' && /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/.test(value)
+  && +value.slice(0, 4) > 0 && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+const validTime = value => value == null || typeof value === 'string' && /^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$/.test(value)
+  && Number.isFinite(Date.parse(value.replace(' ', 'T') + 'Z'))
+  && new Date(value.replace(' ', 'T') + 'Z').toISOString().slice(0, 19).replace('T', ' ') === value;
+const countKeys = ['normal_count', 'late_count', 'early_count', 'missing_count'];
+const counts = Object.fromEntries(countKeys.map(key => [key, nullable('integer')]));
+const shape = {
+    tenant_id: required('string'), user_id: required('string'), month: required('string'), queried_at: required('string'),
+    recorded_date_count: required('integer'), leave_date_count: nullable('integer'), ...counts,
+    items: required([{ record_id: required('string'), date: required('string'), rule_id: nullable('string'), ...counts,
+      leave_flag: nullable('integer'), created_at: nullable('string'), updated_at: nullable('string') }]),
+};
+function validateMonth(payload) {
+  requireArguments(payload, 'month');
+  if (!validDate(payload.month + '-01')) throw invalid('--month 必须为有效的 YYYY-MM 月份，无默认月份。');
+}
+async function execute(args) {
+  const payload = options(args, ['month'], [], [], true); validateMonth(payload);
+  return validate(await gateway.execute('attendance-leave:read', 'attendance/statistics', payload, shape), payload);
+}
+function validate(result, payload) {
+  const data = result.value.data;
+  const dates = new Set(data.items.map(row => row.date));
+  const leaveDates = new Set(data.items.filter(row => row.leave_flag === 1).map(row => row.date));
+  const valid = data.month === payload.month && validTime(data.queried_at)
+    && data.recorded_date_count === dates.size
+    && data.leave_date_count === (data.items.some(row => row.leave_flag == null) ? null : leaveDates.size)
+    && new Set(data.items.map(row => row.record_id)).size === data.items.length
+    && new Set(data.items.map(row => row.date + ':' + row.rule_id)).size === data.items.length
+    && data.items.every(row => validDate(row.date) && row.date.startsWith(payload.month + '-')
+      && row.record_id.trim() !== '' && (row.rule_id == null || /^[1-9][0-9]*$/.test(row.rule_id) && BigInt(row.rule_id) <= 9223372036854775807n)
+      && [null, 0, 1].includes(row.leave_flag) && validTime(row.created_at) && validTime(row.updated_at)
+      && countKeys.every(key => row[key] == null || Number.isSafeInteger(row[key]) && row[key] >= 0 && row[key] <= 2147483647))
+    && countKeys.every(key => {
+      if (data.items.some(row => row[key] == null)) return data[key] === null;
+      return Number.isSafeInteger(data[key]) && data[key] === data.items.reduce((sum, row) => sum + row[key], 0);
+    });
+  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 };