@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/approval.js

@@ -0,0 +1,275 @@
+// 审批：`approval --list|--show|--approve|--reject|--cancel|--revert`（docs/34 §5）
+// —— 第 15 个顶层域。
+//
+// 通用审批（`base.approval`）今天只服务两个 kind：`skill_share`（技能分享到企业）与
+// `file_permission`（文件读写权申请，FILE-006）。设计成通用类型是为了后面的报销 / 合同 ——
+// 那些只加一个 `kind` 与一条策略映射，不再动表结构，也不再加命令。
+//
+// 四条刻意的行为：
+//
+// 1. **`--approve` / `--reject` / `--revert` 是 `high-risk-write`**：没有 `--yes`
+//    就本地退出码 2、**不发请求**（审批是不可撤销的组织动作，误点一次要有人去擦屁股）。
+// 2. **`--reject` / `--revert` 的 `--note` 必填**：驳回与收回权限都要说清理由
+//    （写进 `approval_event`，事后能复盘）。理由先校验、`--yes` 后校验 ——
+//    缺理由时连"确认"都不该鼓励先敲：敲了 `--yes` 就会以为自己已经想清楚了。
+// 3. **`--list --to-review` 在非审批人身份下返回空列表是正常的**，不是错误、更不是 403
+//    （docs/34 §6.7：他确实没有待审项）。CLI 把它渲染成"你现在没有待审项"并**退出 0** ——
+//    把它当错误会让"我确实没有待审的"变成一条吓人的红线，而它只是今天的实情。
+// 4. **`--revert` 只收回"能反向收回"的 subject**：`file_permission` 批准时写的 ACL
+//    会被撤销；`skill_share` 这类没有可撤销 ACL 的审批会回 400
+//    `approval.revert_not_supported` —— CLI 不替服务端表态，原样透传。
+
+import { CliError, exactlyOne } from '../core/error.js';
+import { flagOn, flagValue } from '../core/args.js';
+import { approvalStatusFilter } from '../core/values.js';
+import { dataOf, requestSpec } from '../core/runtime.js';
+
+/** `approval` 的分发（动作按旗标判定，理由同 `skills.js` 的说明）。 */
+export async function handleApproval({ args, runtime }) {
+  const action = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--show', flagOn(args, '--show')],
+      ['--approve', flagOn(args, '--approve')],
+      ['--reject', flagOn(args, '--reject')],
+      ['--cancel', flagOn(args, '--cancel')],
+      ['--revert', flagOn(args, '--revert')],
+    ],
+    'approval',
+    '例：xinhe-oa-cli approval --list --to-review --json',
+  );
+  switch (action) {
+    case '--list':
+      return list(runtime, args);
+    case '--show':
+      return show(runtime, args, requiredValue(args, '--show', '--show <APPROVAL_ID>'));
+    case '--approve':
+      return approve(runtime, args, requiredValue(args, '--approve', '--approve <APPROVAL_ID>'));
+    case '--reject':
+      return reject(runtime, args, requiredValue(args, '--reject', '--reject <APPROVAL_ID>'));
+    case '--cancel':
+      return cancel(runtime, args, requiredValue(args, '--cancel', '--cancel <APPROVAL_ID>'));
+    default:
+      return revert(runtime, args, requiredValue(args, '--revert', '--revert <APPROVAL_ID>'));
+  }
+}
+
+/** `approval --list [--to-review | --mine] [--status ...] [--kind ...]`。 */
+async function list(runtime, args) {
+  const toReview = flagOn(args, '--to-review');
+  const mine = flagOn(args, '--mine');
+  if (toReview && mine) {
+    throw CliError.usage('`--to-review`（待我审）与 `--mine`（我提交的）只能给一个').withHint(
+      '两个视角是两份清单，不能混在一起看',
+    );
+  }
+  const role = toReview ? 'reviewer' : mine ? 'requester' : null;
+  const status = statusFilter(flagValue(args, '--status'));
+  const kind = nonEmpty(flagValue(args, '--kind'));
+
+  const query = [];
+  if (role !== null) query.push(['role', role]);
+  if (status !== null) query.push(['status', status]);
+  if (kind !== null) query.push(['kind', kind]);
+  const spec = requestSpec({ query });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', '/approvals', spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', '/approvals', spec);
+  const data = dataOf(response);
+  const approvals = Array.isArray(data?.approvals)
+    ? data.approvals
+    : Array.isArray(data?.items)
+      ? data.items
+      : [];
+  const total = data?.total ?? approvals.length;
+  const view =
+    role === 'reviewer'
+      ? 'to-review（待我审）'
+      : role === 'requester'
+        ? 'mine（我提交的）'
+        : 'all（服务端默认视角）';
+  let note;
+  if (approvals.length === 0) {
+    if (role === 'reviewer') {
+      // docs/34 §6.7：业务员看到空列表是设计如此，不是权限问题。
+      note =
+        '你现在没有待审项（这是正常的：只有企业负责人（admin:member 持有者）才有待审项，不是权限错误）';
+    } else if (role === 'requester') {
+      note = '你还没有提交过审批：xinhe-oa-cli skills --publish <SKILL> --visibility tenant';
+    } else {
+      note = '这里现在什么都没有（换 --to-review / --mine 看另一个视角）';
+    }
+  } else {
+    note = '待审的用 xinhe-oa-cli approval --approve <ID> --yes 或 --reject <ID> --note "..." --yes';
+  }
+  runtime.finishFrom(response, {
+    approvals,
+    total,
+    view,
+    role,
+    status,
+    kind,
+    note,
+    next_step: '看一条的详情与轨迹：xinhe-oa-cli approval --show <APPROVAL_ID> --json',
+  });
+}
+
+/** `approval --show <id>`：详情 + 轨迹（`submit` / `approve` / `reject` …）。 */
+async function show(runtime, args, id) {
+  rejectFilters(args, '--show <APPROVAL_ID>');
+  const target = `/approvals/${id}`;
+  const spec = requestSpec();
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', target, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', target, spec);
+  const data = dataOf(response);
+  const status = typeof data?.status === 'string' ? data.status : '';
+  const out = data;
+  if (isPlainObject(out)) {
+    out.approval_id = id;
+    out.next_step =
+      status === 'pending'
+        ? '批准：xinhe-oa-cli approval --approve <ID> --yes；驳回：xinhe-oa-cli approval --reject <ID> --note "理由" --yes；撤回：xinhe-oa-cli approval --cancel <ID>'
+        : status === 'approved'
+          ? '要收回这份批准：xinhe-oa-cli approval --revert <ID> --note "理由" --yes（只对 file_permission 这类批准时写了权限的有效）'
+          : '看清单：xinhe-oa-cli approval --list --to-review --json';
+    out.note = '轨迹（events）就是复盘用的：谁提交、谁批、什么时候、什么理由';
+  }
+  runtime.finishFrom(response, out);
+}
+
+/** `approval --approve <id> [--note "..."]`：**高风险写操作，必须 `--yes`**。 */
+async function approve(runtime, args, id) {
+  runtime.requireYes(
+    'approval --approve（批准后技能立刻对企业内所有人可见）',
+    `xinhe-oa-cli approval --approve ${id}`,
+  );
+  const note = nonEmpty(flagValue(args, '--note'));
+  const body = note === null ? {} : { note };
+  return decide(runtime, args, 'approve', id, body);
+}
+
+/** `approval --reject <id> --note "..."`：**高风险写操作，必须 `--yes`；`--note` 必填**。 */
+async function reject(runtime, args, id) {
+  // note 先校验：缺理由的驳回连 --yes 都不该鼓励先敲。
+  const note = requireNote(args, '--reject', '名字和企业已有技能重了');
+  runtime.requireYes(
+    'approval --reject（驳回后技能退回草稿/私有）',
+    `xinhe-oa-cli approval --reject ${id} --note "${note}"`,
+  );
+  return decide(runtime, args, 'reject', id, { note });
+}
+
+/** `approval --cancel <id>`：提交人撤回（不是高风险：撤的是自己提交的东西）。 */
+async function cancel(runtime, args, id) {
+  return decide(runtime, args, 'cancel', id, {});
+}
+
+/**
+ * `approval --revert <id> --note "..."`：**高风险写操作，必须 `--yes`；`--note` 必填**。
+ *
+ * FILE-006：只对批准时确实写出权限的 kind（`file_permission`）有意义 ——
+ * 收回后不可再改回，要重新授权只能提一条新申请。对没有可撤销 subject 的审批，
+ * 服务端回 400 `approval.revert_not_supported`，CLI 原样透传（不替服务端表态）。
+ */
+async function revert(runtime, args, id) {
+  // note 先校验：缺理由的收回连 --yes 都不该鼓励先敲（与 reject 同序）。
+  const note = requireNote(args, '--revert', '跨部门授权不符合归档规则');
+  runtime.requireYes(
+    'approval --revert（撤销已批准的权限，收回后不可再改回）',
+    `xinhe-oa-cli approval --revert ${id} --note "${note}"`,
+  );
+  return decide(runtime, args, 'revert', id, { note });
+}
+
+async function decide(runtime, args, action, id, body) {
+  rejectFilters(args, `--${action} <APPROVAL_ID>`);
+  const target = `/approvals/${id}/${action}`;
+  const spec = requestSpec({ body });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', target, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('POST', target, spec);
+  const data = dataOf(response);
+  const status = typeof data?.status === 'string' ? data.status : '';
+  const out = data;
+  if (isPlainObject(out)) {
+    out.approval_id = id;
+    out.action = action;
+    out.next_step =
+      action === 'approve'
+        ? '企业内其他人现在才读得到：xinhe-oa-cli skills --read <SKILL> --json'
+        : action === 'reject'
+          ? '提交人改完可以重新提交：xinhe-oa-cli skills --publish <SKILL> --visibility tenant'
+          : action === 'revert'
+            ? '权限已收回；要重新授权只能提一条新申请：xinhe-oa-cli file --permission-request <FILE> --action read|write --json'
+            : '看还剩什么：xinhe-oa-cli approval --list --mine --json';
+    // `status` **永远在**（Revert 的响应把状态包在 `approval` 里，顶层没有 status）——
+    // 形状固定的字段比"有时有有时没有"好判：脚本不需要先判断键在不在。
+    out.status = status.length === 0 ? null : status;
+  }
+  runtime.finishFrom(response, out);
+}
+
+// ---------------------------------------------------------------------------
+// 本地校验（与 Rust `ApprovalArgs` 逐条对齐）
+// ---------------------------------------------------------------------------
+/** `--to-review` / `--mine` / `--status` / `--kind` 只对 `--list` 有意义。 */
+function rejectFilters(args, what) {
+  if (flagOn(args, '--to-review') || flagOn(args, '--mine')) {
+    throw CliError.usage(
+      `--to-review / --mine 只对 \`approval --list\` 有意义，不属于 \`${what}\``,
+    ).withHint('看清单：xinhe-oa-cli approval --list --to-review --json');
+  }
+  if (flagOn(args, '--status') || flagOn(args, '--kind')) {
+    throw CliError.usage(
+      `--status / --kind 只对 \`approval --list\` 有意义，不属于 \`${what}\``,
+    ).withHint('看清单：xinhe-oa-cli approval --list --status pending --json');
+  }
+}
+
+function requireNote(args, action, sample) {
+  const note = nonEmpty(flagValue(args, '--note'));
+  if (note === null) {
+    throw CliError.usage(`\`approval ${action}\` 必须给 --note <理由>`).withHint(
+      `例：xinhe-oa-cli approval ${action} apr_123 --note "${sample}" --yes`,
+    );
+  }
+  return note;
+}
+
+/**
+ * `--status` 的取值面。
+ *
+ * core 的 `approvalStatusFilter` 认的是最常写的那几个；Rust 的口径还多三条：
+ * `all` / 空串 = 不带 status 参数、`canceled` 是 `cancelled` 的别拼、`expired` 合法。
+ * 这里补齐三条再交给 core，报错口径与验收面都保持一处实现。
+ */
+function statusFilter(raw) {
+  const value = String(raw ?? '').trim().toLowerCase();
+  if (value.length === 0 || value === 'all') return null;
+  if (value === 'canceled') return 'cancelled';
+  if (value === 'expired') return 'expired';
+  return approvalStatusFilter(value);
+}
+
+function requiredValue(args, flag, what) {
+  const value = nonEmpty(flagValue(args, flag));
+  if (value === null) throw CliError.usage(`\`approval\` 需要 ${what}`);
+  return value;
+}
+
+function nonEmpty(raw) {
+  if (raw === null || raw === undefined) return null;
+  const text = String(raw).trim();
+  return text.length > 0 ? text : null;
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/commands/attachment.js

@@ -0,0 +1,202 @@
+// 附件：`attachment --upload|--show|--download|--link|--unlink|--delete`（契约 §2）。
+//
+// 三件事在这里收口：
+//
+// - **上传**：`POST /attachments`（multipart）——`--tenant` 不传就用当前唯一可见企业；
+// - **下载**：先 `POST /attachments/{id}/download-url` 拿签名 URL，再用它**匿名**
+//   GET（签名即授权），落盘时校验服务端给的 `content_hash`（sha256）——
+//   传输坏了要当场发现。这一段与 `file --download` 共用（`file.js` 的
+//   `downloadWithSignedUrl`）：文件与附件是同一条版本链，各写一遍迟早漂移；
+// - **关联**：`POST|DELETE /attachments/{id}/links`（`record` 类型）——
+//   关联留在 attachment 域（`file` 域刻意不做 `--link` / `--unlink`）。
+//
+// 本地判定的顺序照抄 Rust：**先**校验必填/读文件，**再**解析企业（后者才可能联网）。
+
+import { CliError, exactlyOne } from '../core/error.js';
+import { flagOn, flagValue } from '../core/args.js';
+import { multipartBody, requestSpec } from '../core/http.js';
+import { dataOf, idempotencyKey, readFileBytes } from '../core/runtime.js';
+import { fileNameOf, queryPairs } from '../core/values.js';
+import { downloadWithSignedUrl, resolveTenant } from './file.js';
+
+/**
+ * `attachment` 的动作分发。
+ *
+ * 与 Rust 的 clap `ArgGroup(action, multiple=false)` 同义：六个动作**恰好一个**。
+ * 规格驱动的解析器不替我们做这件事（`--upload` 这类动作旗标只在 `extra_flags` 里，
+ * 不在它的互斥检查范围内），所以 `attachment --upload --delete att_1` 这种命令行
+ * 在这里必须自己拒掉 —— Rust 会拒（退出码 2、不发请求），不能替调用方挑一个执行。
+ */
+export async function handleAttachment({ args, runtime }) {
+  const picked = exactlyOne(
+    [
+      ['--upload', flagOn(args, '--upload')],
+      ['--download', args['--download'] !== undefined],
+      ['--link', flagOn(args, '--link')],
+      ['--unlink', flagOn(args, '--unlink')],
+      ['--delete', args['--delete'] !== undefined],
+      ['--show', args['--show'] !== undefined],
+    ],
+    'attachment',
+    '例：xinhe-oa-cli attachment --upload --file ./单据.csv --tenant kashu',
+  );
+  if (picked === '--upload') return upload(runtime, args);
+  if (picked === '--download') return download(runtime, args);
+  if (picked === '--link') return link(runtime, args);
+  if (picked === '--unlink') return unlink(runtime, args);
+  if (picked === '--delete') return remove(runtime, args);
+  return show(runtime, args);
+}
+
+/**
+ * 上传一个本地文件并返回服务端的 `data`（`bitable record --attach` 也用它）。
+ *
+ * `--name` 缺省时用文件名；`--tenant` 缺省时**才**去问 `GET /me` 挑唯一可见企业
+ * （多企业会明确报错，不替调用方猜）。
+ */
+export async function uploadFile(runtime, sourcePath, tenantRaw, nameRaw) {
+  const bytes = readFileBytes(sourcePath);
+  const uploadName = fileNameOf(sourcePath);
+  let tenant = tenantRaw === null || tenantRaw === undefined ? '' : String(tenantRaw).trim();
+  if (tenant.length === 0) tenant = await resolveTenant(runtime, null, '上传附件');
+  const form = multipartBody(
+    [
+      ['tenant', tenant],
+      ['name', nameRaw === null || nameRaw === undefined ? uploadName : nameRaw],
+    ],
+    ['file', uploadName, bytes],
+  );
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', '/attachments', requestSpec({ multipart: form }));
+    return { dry_run: true };
+  }
+  const response = await runtime.sendUpload(
+    '/attachments',
+    form,
+    idempotencyKey('attachment-upload'),
+  );
+  return dataOf(response);
+}
+
+async function upload(runtime, args) {
+  const sourcePath = flagValue(args, '--file');
+  if (sourcePath === null) {
+    throw CliError.usage('`attachment --upload` 需要 --file <路径>').withHint(
+      '例：xinhe-oa-cli attachment --upload --file ./公账流水.csv --tenant kashu',
+    );
+  }
+  const data = await uploadFile(
+    runtime,
+    sourcePath,
+    flagValue(args, '--tenant'),
+    flagValue(args, '--name'),
+  );
+  if (runtime.dryRun) return;
+  // 与 Rust 一致：这里的 `meta.request_id` **不**取服务端回显（`finish` 而不是
+  // `finish_from`）—— 上传的幂等键才是这条命令的重放凭据。
+  runtime.finish({
+    attachment: data,
+    next_step: '挂到记录上：xinhe-oa-cli attachment --link <attachment_id> --resource-id <record_id>',
+  });
+}
+
+/**
+ * `attachment --show <ATTACHMENT_ID>`：元数据（含 versions / links）。
+ *
+ * **刻意没有 `--dry-run` 分支**（与 Rust 逐条一致）：Rust 侧漏了这一支，
+ * Node 版照抄而不是"顺手修好"—— 两边行为必须一样。
+ */
+async function show(runtime, args) {
+  const attachmentId = String(args['--show'] ?? '');
+  const response = await runtime.sendAuthed(
+    'GET',
+    `/attachments/${attachmentId}`,
+    requestSpec(),
+  );
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `attachment --download <ATTACHMENT_ID> [--output <PATH>]`。 */
+async function download(runtime, args) {
+  const attachmentId = String(args['--download'] ?? '');
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', `/attachments/${attachmentId}/download-url`, requestSpec());
+    return;
+  }
+  const { response, data } = await downloadWithSignedUrl(
+    runtime,
+    attachmentId,
+    null,
+    flagValue(args, '--output'),
+  );
+  runtime.finishFrom(response, data);
+}
+
+/** `attachment --link --id <附件 id> --resource-id <记录 id> [--field <字段>]`。 */
+async function link(runtime, args) {
+  const attachmentId = flagValue(args, '--id');
+  if (attachmentId === null) {
+    throw CliError.usage('`attachment --link` 需要 --id <附件 id>').withHint(
+      '例：xinhe-oa-cli attachment --link --id att_123 --resource-id rec_123',
+    );
+  }
+  const resourceId = flagValue(args, '--resource-id');
+  if (resourceId === null) {
+    throw CliError.usage('`attachment --link` 需要 --resource-id <记录 id>');
+  }
+  // `--resource-type` 的缺省是 `record`（Rust 侧是 clap 的 `default_value`）。
+  const body = {
+    resource_type: flagValue(args, '--resource-type') ?? 'record',
+    resource_id: resourceId,
+    field_id: flagValue(args, '--field'),
+  };
+  const spec = requestSpec({ body });
+  const requestPath = `/attachments/${attachmentId}/links`;
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('POST', requestPath, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `attachment --unlink --id <附件 id> --resource-id <记录 id>`。 */
+async function unlink(runtime, args) {
+  const attachmentId = flagValue(args, '--id');
+  if (attachmentId === null) {
+    throw CliError.usage('`attachment --unlink` 需要 --id <附件 id>').withHint(
+      '例：xinhe-oa-cli attachment --unlink --id att_123 --resource-id rec_123',
+    );
+  }
+  const resourceId = flagValue(args, '--resource-id');
+  if (resourceId === null) {
+    throw CliError.usage('`attachment --unlink` 需要 --resource-id <记录 id>');
+  }
+  const spec = requestSpec({
+    query: [
+      ['resource_type', flagValue(args, '--resource-type') ?? 'record'],
+      ['resource_id', resourceId],
+    ],
+  });
+  const requestPath = `/attachments/${attachmentId}/links`;
+  if (runtime.dryRun) {
+    runtime.dryRunReport('DELETE', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('DELETE', requestPath, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `attachment --delete <ATTACHMENT_ID> [--reason <TEXT>]`（高风险：必须 `--yes`）。 */
+async function remove(runtime, args) {
+  const attachmentId = String(args['--delete'] ?? '');
+  runtime.requireYes('attachment --delete', `xinhe-oa-cli attachment --delete ${attachmentId}`);
+  const spec = requestSpec({ query: queryPairs([['reason', flagValue(args, '--reason')]]) });
+  const requestPath = `/attachments/${attachmentId}`;
+  if (runtime.dryRun) {
+    runtime.dryRunReport('DELETE', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('DELETE', requestPath, spec);
+  runtime.finishFrom(response, dataOf(response));
+}