@xiaoyuanhao/yunzhi-cli 2.0.0 → 2.1.0

package/lib/teacher-own-leave-help.cjs

@@ -0,0 +1,134 @@
+// Help text only. Command parsing, execution and result validation remain in their existing modules.
+const formFields = [
+  'fields[]：field_key 为提交键，type 为字段类型，label/description 为学校说明。',
+  'editable/required/computed：只填写可见且可编辑的非计算字段；required 在显示时生效。计算结果和系统绑定字段由服务端填写。',
+  'value/default_value/display_value：当前值、默认值、展示值；null 表示未知或未提供。显式输入覆盖默认值，省略时按当前默认值和学校规则处理。',
+  'options[]：option_id 用于提交，code 用于显示条件，label 用于展示，default_selected 表示默认选择。候选来源读取失败不等于空列表。',
+  '显示结果读取 form_check，无需 AI 自行执行 visibility。CLI 按任一可见控制题满足即显示、隐藏控制题不触发下游、子表每行独立判断；循环依赖或失效的引用明确报错。',
+  'validation_rules：required、number、phone、identity_card、unique 等校验规则；unique 由服务端查重。number_range 的 minimum/maximum 为精确十进制字符串，null 表示该端无界，inclusive=true 包含端点。',
+  'format_rules：decimal_places、digits、rounding=half_up 为服务端格式规则；不要在本地舍入。规则列表 null 表示未知，[] 表示未列出规则，均不取消提交时的服务端检查。',
+  'candidate_users/candidate_departments/candidate_organizations：当前可选身份；null 为不可用，[] 为空集合。person_search_supported=true 才支持 form-people-search；固定范围使用已有候选。',
+  'attachment_upload_supported/file_type/attachment_limits：上传能力、文件类别和限制。upload_max_bytes 为单文件上限；图片 max_files=10，min_size_mib/max_size_mib 为精确十进制 MiB 边界，含端点。',
+  'groups/row_template：已有行与新行字段定义；单层子表的输入格式见 submit Help，嵌套子表写入不支持。',
+].join('\n  ');
+
+const fieldInput = [
+  '数组最多 100 项，每项为 {"field_key":"实际字段键","value":值}；value 直接使用 JSON 值，不再编码成字符串。',
+  '文本：字符串。数字：JSON 数字或数字文本。日期：YYYY-MM-DD；日期时间：YYYY-MM-DD HH:mm:ss，Asia/Shanghai，具体格式按表单。',
+  '单选/下拉/搜索下拉：option_id 字符串；多选：不重复的 option_id 字符串数组。不要用名称、code 或搜索词代替。',
+  '“其他”选项：仅当实际选项 code=attr-radio-other 且属于单选/下拉/搜索下拉时，可传 {"option_id":"实际选项ID","other_text":"补充说明"}；多选不支持该对象格式。',
+  '人员：[{"tenant_id":"学校ID","user_id":"人员ID"}]；部门：[{"tenant_id":"学校ID","department_id":"部门ID"}]；组织：[{"tenant_id":"组织ID"}]。使用表单或搜索返回的候选，姓名由服务端补齐；单选最多一项。',
+  '附件 files/images：{"local_files":["/本地路径/证明.pdf"]}，CLI 随提交完成上传。图片每字段每行最多 10 张，大小遵循当前表单限制；最大值未配置或为 0 时为 50 MiB，单文件仍受上传上限约束。',
+  '附件复用：确认已经上传的 object_key 字符串数组可按原申请、原字段上下文复用；不接受文件组 ID、media_id 或展示 URL。',
+  '子表 table：父字段 value 为行数组，如 [{"fields":[{"field_key":"实际子字段键","value":"内容"}]}]，至少一行，同一行字段不重复。子附件放在该行 fields 内；不传原生行 ID，不支持嵌套子表。',
+  '省略与清空：省略按服务端已有值/默认值处理；显式输入覆盖默认值。可选日期、单选、下拉清空用 ""；可选人员/部门/组织、多选、附件清空用 []。清空附件不恢复默认值。',
+  '隐藏、只读、计算、系统绑定字段及 link/separator 不提交；只填写计算所需来源。显式提交隐藏字段会被拒绝，联动和计算在服务端校验。',
+  '@文件：UTF-8 JSON 数组，可带 BOM。支持 "@/路径/表单.json" 或 "@C:/Users/Teacher/Documents/表单.json"。JSON 文件及 local_files 的相对路径都相对命令工作目录，不相对 JSON 文件所在目录。',
+].join('\n  ');
+
+const submissionResult = [
+  '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：附件局部异常。NOT_EXECUTED 不保证未产生文件，缺失回执不能当作未上传。',
+  '文件结果需按字段和行定位，不能只凭文件名合并。文件准备的 COMPLETED 只确认该步骤，verified 是另一次回读检查；未知文件结果不自动重传或删除。',
+].join('\n  ');
+
+function render(command, usage) {
+  const [space, action] = command.split(' ');
+  if (space !== 'leave') return null;
+  const resumed = action.startsWith('resumption-');
+  const kind = resumed ? action.slice('resumption-'.length) : action;
+  if (!['form', 'form-people-search', 'submit', 'list', 'show', 'remind', 'withdraw'].includes(kind)) return null;
+  const subject = resumed ? '销假' : '请假';
+  const prefix = resumed ? 'resumption-' : '';
+  const idParameter = `--id  必填；目标${subject}的提交或查询返回的 id。`;
+  const originalLeave = '--leave-id  必填；原请假提交或 leave list/show 返回的 id，不是销假 id。';
+  const process = `--workflow-code  必填；leave ${prefix}form 返回的流程编码。`;
+  let purpose, parameters, example, input = '', result, limits;
+  if (kind === 'form') {
+    purpose = `查看本人${subject}需要填写哪些内容，并一次列出当前答案中需要补充或修正的地方。`;
+    parameters = [...(resumed ? [originalLeave] : []), '--workflow-code  可选；省略时唯一流程自动选择，多个流程返回候选；指定时使用实际返回的 program_code。',
+      '--field-values  可选；当前完整答案，JSON 数组或 @文件路径；不是增量补丁，不保存草稿，不上传文件。编码见对应 submit 或 resumption-submit --help。',
+      ...(resumed ? ['--resumption-time  可选；已知实际返岗时间，YYYY-MM-DD HH:mm:ss，Asia/Shanghai；提交时必填。', '--reason  可选；当前销假说明，最多 100 字。'] : [])];
+    example = resumed ? '--leave-id <leave_id>' : '';
+    result = [
+      'status：ready 表示已选流程，返回 program_code、fields；selection_required 返回 choices[].name/program_code，选择后传 --workflow-code 重读；unavailable 且 choices=[] 表示没有可用流程。',
+      'form_check：仅已选流程时返回。status=complete 表示本地检查没有发现问题；needs_input 表示需要补充或修正答案；blocked 表示规则异常或必需能力不支持。均不代表服务端校验或审批通过。',
+      'form_check.visible_fields：当前显示字段的 field_key/label；子表带 parent_field_key、从 0 开始的 row_index，字段定义仍在 fields。form_check.issues 一次列出问题及位置、code/message；parameter 指向销假专用参数。隐藏输入报错，不会自动丢弃。',
+      ...(resumed ? ['原请假：leave_id、leave_start_time、leave_end_time（Asia/Shanghai）、人员及假种；field_mappings 为可见绑定字段映射，不能覆盖绑定事实。'] : []),
+      formFields,
+    ].join('\n  ');
+    limits = `读取失败不是空候选。本地仅判断显示联动、必填和基本输入结构；计算、精确数值规则、人员资格、文件内容和业务权限由服务端校验。回答控制题后可能出现新缺项。字段输入编码见 leave ${prefix}submit --help。`;
+  } else if (kind === 'form-people-search') {
+    purpose = `填写本人${subject}表单中的人员字段时，按姓名查找可选人员。`;
+    parameters = [process, '--field-key  必填；表单中允许自由搜索的可编辑人员字段，子表父字段也须可编辑。', '--keyword  必填；非空姓名线索。', ...(resumed ? [originalLeave] : [])];
+    example = `--workflow-code <program_code> --field-key <field_key> --keyword 李${resumed ? ' --leave-id <leave_id>' : ''}`;
+    result = 'candidates 返回人员及部门信息，未知部门为 null。选人输入取 candidates[].tenant_id/user_id；exhaustive=false，最多 10 人，不支持分页。';
+    limits = '仅用于 person_search_supported=true 的字段；固定范围使用表单候选。候选不是完整名单，提交时重新校验所选人员。';
+  } else if (kind === 'submit') {
+    purpose = `提交老师本人的${subject}申请${resumed ? '，支持假期结束后补办' : ''}。`;
+    parameters = [...(resumed ? [originalLeave] : []), process,
+      ...(resumed ? ['--resumption-time  必填；实际返岗时间，YYYY-MM-DD HH:mm:ss，Asia/Shanghai，不得晚于原有效假期结束时间。', '--reason  可选；销假说明，最多 100 字；学校要求时须填写。'] : []),
+      '--field-values  可选；内联 JSON 数组或 @文件路径。参数可省略不代表学校必填字段可缺失；具体格式见下方。'];
+    example = `${resumed ? '--leave-id <leave_id> ' : ''}--workflow-code <program_code>${resumed ? ' --resumption-time "2026-10-15 09:00:00"' : ''} --field-values "@表单.json"`;
+    input = '输入格式：\n  ' + fieldInput + '\n\n表单.json 示例（字段键仅演示，须替换为实际表单字段并补齐必填项）：\n' + JSON.stringify([
+      { field_key: '实际文本字段键', value: resumed ? '提前返岗' : '家中有事' },
+      { field_key: '实际附件字段键', value: { local_files: ['./证明.pdf'] } },
+    ], null, 2) + '\n\n';
+    result = `${resumed ? 'id 为新销假 ID，leave_id 为原请假 ID。' : 'id 为新请假 ID。'}\n  ${submissionResult}`;
+    limits = (resumed ? '原请假、本人、假种和有效日期由服务端绑定；返岗时间和说明使用专用参数。办理时间可晚于假期，所填返岗时间仍须满足限制。' : '') + '命令内部先读取最新表单并执行本地检查，再上传附件、提交服务端；无需先单独调用 form 检查。检查不通过时 error.form_check 返回全部当前问题，execution_status=NOT_EXECUTED，step=check_form_before_upload；本次尚未上传文件或提交。只检查填写内容时使用 form，不能调用本命令。提交成功不代表审批通过或考勤更新；不确定的提交或文件结果不得自动重试。';
+  } else if (kind === 'list') {
+    purpose = `查询本人${subject}申请和历史记录，包含尚未同步的申请。`;
+    parameters = [
+      '--start-date  可选；YYYY-MM-DD，与 --end-date 成对传入；均省略不限制日期。',
+      '--end-date  可选；YYYY-MM-DD，不得早于开始日期。',
+      '--leave-type  可选；非空的实际假种筛选值，省略不过滤。',
+      '--status  可选；draft 草稿、processing 处理中、completed 完成、returned 退回、rejected 历史不同意、withdrawn 撤回、unknown 未知；省略不过滤。',
+      '--reason  可选；非空的请假原因筛选文字，最多 250 字符。',
+      '--page  可选；从 1 开始，默认 1，最大 2147483647。',
+      '--page-size  可选；1..100，默认 20。',
+    ];
+    example = '--status processing --page 1 --page-size 20';
+    result = `items 包含 id、标题、状态、假种、时段、事由及来源可用标志；关联申请与业务记录合为一项。${resumed ? 'leave_id 为可空的原请假 ID。' : ''}\n  page/page_size/total/total_pages 为筛选后的分页；按创建时间倒序、id 稳定排序。`;
+    limits = '日期按北京时间业务时段重叠筛选；无业务记录时使用学校映射明确且可见的申请时段，缺失字段不匹配对应条件。' + (resumed ? '销假按其影响时段筛选；实际有效时段可能已缩短，原申请字段保留最初时段。' : '') + '\n  有工作流时 status 取工作流分类，否则取历史业务分类；workflow_status/business_status 分别使用流程状态与业务审批状态名称。completed 不表示考勤已更新，draft 不表示已提交。';
+    if (!resumed) {
+      purpose = '查询本人请假申请，或管理范围内教师已批准的有效请假时段。';
+      parameters.unshift('--scope  可选；mine 本人（默认），managed 当前学校教师考勤管理员范围。');
+      parameters[1] = '--start-date  mine 时可选，managed 时必填；YYYY-MM-DD，与 --end-date 成对传入。';
+      parameters[2] = '--end-date  与开始日期成对传入且不早于开始日期，包含结束日。';
+      parameters[4] += ' managed 仅允许省略或 completed。';
+      example = '--scope managed --start-date 2026-10-18 --end-date 2026-10-18';
+      result = 'mine：' + result;
+      limits = 'mine：' + limits;
+      result += '\n  managed：scope=managed，operator_id 为操作老师，items.teacher_id/teacher_name 为请假教师；period_basis=effective，start_time/end_time 为销假调整后的有效时段，resumption_status 为业务销假状态。按创建时间倒序、业务记录 ID 倒序排列；total 是请假记录数，不是人数。';
+      result += '\n  managed 不读取工作流详情，workflow_available=false、program_code/workflow_status=null 不表示没有申请；status=completed、business_status=approved 表示已批准业务记录。公开 id 与本人记录一致。';
+      limits += '\n  managed 需要当前学校教师考勤管理员资格，仅查询已同步到请假业务的批准记录。待审批、退回、撤回不计入；已批准销假会缩短时段，未批准销假不影响时段。按 [开始,结束) 重叠匹配，零时结束或零时长不算当日请假；所有筛选在计数及分页前完成。';
+      limits += '\n  查询整天表示当天曾有有效请假，不代表查询时刻仍在请假；按返回时段解释。尚未同步的工作流审批不能在此确认，也不代表考勤已更新。leave show、销假查询及写操作仍仅支持本人，不因管理列表可见而获得审批、附件或办理权限。';
+    }
+  } else if (kind === 'show') {
+    purpose = `读取本人${subject}详情、审批进度及附件链接。`;
+    parameters = [idParameter];
+    example = '--id <id>';
+    result = [
+      `id 为当前${subject} ID。${resumed ? 'leave_id 为可空的原请假 ID。' : ''}workflow_available/business_record_available 表示两类来源是否可用。`,
+      'fields 为可见申请内容，field_key/type/label 标识字段，value 为保存值，display_value 为展示值；本人详情只读，groups 为子表行。',
+      'status 为统一状态（draft/processing/completed/returned/rejected/withdrawn/unknown）；progress 为节点、处理人、办理时间和意见，节点 status 使用 pending/transferred/completed/returned/withdrawn、node_type 使用 start/normal/end；workflow_status/business_status 分别使用流程状态与业务审批状态名称。没有有效工作流的历史记录中 fields/progress/attachments 为 null。',
+      'start_time/end_time、leave_type/reason 为当前业务事实；没有业务记录时取学校映射的可见申请字段。created_at/updated_at 是来源时间，不是考勤同步时间。',
+      'attachments 提供文件名、类型、大小、字段/行标识、download_url、expires_at。链接可直接下载，无需业务认证头；过期后重查详情。历史图片也可能仅在 fields 的 value 中以 [{url,width?,height?}] 展示。',
+      ...(!resumed ? ['resumption_applications 为销假申请历史，status 使用 pending/approved/rejected 等业务审批状态；各项 id 可用于 resumption-show。resumption_status=resumed/not-resumed 表示已销假/未销假，resumption_source=workflow/automatic-clock 表示工作流/打卡自动销假。available_actions 表示当前可办理操作。原申请时段与销假后有效时段应分别理解。'] : []),
+    ].join('\n  ');
+    limits = 'null 表示未知或不可用；缺少业务记录不等于未提交，空销假历史不推翻已保存的销假状态。审批完成不证明考勤已同步。';
+  } else {
+    const urge = kind === 'remind';
+    purpose = `${urge ? '催办' : '撤回'}本人处理中${subject}申请。`;
+    parameters = [idParameter];
+    example = '--id <id>';
+    result = `id 为目标${subject}；event=${resumed ? 'resumption' : 'leave'}_${urge ? 'urged，notified_count 为实际通知人数。' : 'withdrawn，withdrawn=true 确认撤回。'}`;
+    limits = '仅本人当前可办理的处理中申请。' + (urge ? '催办间隔至少 30 分钟；成功不代表审批通过。' : resumed ? '撤回销假不会撤回原请假。' : '') + '结果不确定时不要自动重复操作。';
+  }
+  const scope = kind === 'submit' ? 'attendance-leave:read + attendance-leave:write' : ['remind', 'withdraw'].includes(kind) ? 'attendance-leave:write' : 'attendance-leave:read';
+  return `${purpose}\n\n用法：yunzhi-cli ${command}${usage ? ' ' + usage : ''}\n参数：\n  ${parameters.join('\n  ')}\n  参数均不可重复传入；必填参数无默认值。\n\n示例：\n  yunzhi-cli ${command}${example ? ' ' + example : ''}\n\n${input}返回：\n  ${result}\n\n限制：\n  ${limits}\n  所需权限：${scope}；服务端校验当前学校、查询范围及操作资格。\n默认输出 JSON；失败原因及处理提示见 error.message/error.hint。\n`;
+}
+
+module.exports = { render, formFields, fieldInput, submissionResult };

package/lib/workflow-entry.cjs

@@ -0,0 +1,42 @@
+const { options, required: requireArguments } = require('./arguments.cjs');
+const { required, Failure, invalid } = require('./result.cjs');
+const { positiveId } = require('./attendance-leave-ids.cjs');
+const gateway = require('./gateway.cjs');
+
+async function execute(domain, action, args) {
+  const idKey = 'task_id';
+  const urlKey = 'taskId';
+  const payload = options(args, [idKey], [], [], true);
+  requireArguments(payload, idKey);
+  if (!positiveId(payload[idKey])) throw invalid('--task-id 必须是本人当前待办的有效任务 ID。');
+  let requestId;
+  try {
+    const result = await gateway.execute('attendance-leave:read', domain + '/' + action, payload, {
+      task_id: required('string'),
+      tenant_id: required('string'), user_id: required('string'), application_id: required('string'),
+      program_code: required('string'), purpose: required('string'), kind: required('string'), url: required('string'), message: required('string'),
+    });
+    requestId = result.value.request_id;
+    const data = result.value.data;
+    const purpose = domain === 'attendance' ? 'TEACHER_CORRECTION' : (domain === 'leave' ? 'TEACHER_' : 'STUDENT_') + (action.startsWith('resumption-') ? 'RESUMPTION' : 'LEAVE');
+    try {
+      const url = new URL(data.url);
+      const keys = [...url.searchParams.keys()].sort();
+      if (!data.tenant_id.trim() || !data.user_id.trim() || !data.program_code.trim() || !data.message.trim()
+          || data[idKey] !== payload[idKey] || !require('./attendance-leave-ids.cjs').applicationId(data.application_id, purpose) || data.purpose !== purpose
+          || data.kind !== 'APPROVAL_CONTINUATION'
+          || url.protocol !== 'https:' || !url.hostname || url.username || url.password || url.hash
+          || url.pathname !== '/micro/app/workFlow/form' || keys.join(',') !== 'corpid,flowCode,taskId'
+          || url.searchParams.get(urlKey) !== payload[idKey] || url.searchParams.get('flowCode') !== data.program_code
+          || !url.searchParams.get('corpid').trim()) throw new Error();
+    } catch { throw new Failure(1, 'api', 'invalid_response', '原客户端续办入口的标识、业务范围或网页地址无效，未提供可用入口。'); }
+    return result;
+  } catch (failure) {
+    if (failure instanceof Failure) {
+      if (requestId) failure.result.value.request_id = requestId;
+      failure.result.value.error.details = { ...failure.result.value.error.details, domain, ...payload };
+    }
+    throw failure;
+  }
+}
+module.exports = { execute };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiaoyuanhao/yunzhi-cli",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Yunzhi Campus CLI for lesson preparation and school library workflows",
   "bin": {
     "yunzhi-cli": "yunzhi-cli.cjs"