@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/index.js

@@ -0,0 +1,78 @@
+// 命令分发表：命令标签 → 处理函数。
+//
+// 每条命令处理函数的签名统一是 `async ({ args, positional, runtime })`，
+// 自己负责把结果写出去（`runtime.finish(...)` / `runtime.finishWithHuman(...)`），
+// 失败就 `throw CliError`。**退出码由 `main.js` 统一收口**（契约 §3.2）。
+//
+// 为什么一张显式的表，而不是按域名动态 import：命令面是**冻结契约**（153 条），
+// 表里缺一条就是"这条命令在 Node 版上不存在"——显式的表能让这件事一眼可见，
+// 也方便 `test/surface.test.js` 断言"153 条命令每条都有处理函数"。
+
+import { handleLogin, handleLogout, handleMe } from './session.js';
+import { handleTenant } from './tenant.js';
+import { handleMember } from './member.js';
+import { handleInvestor } from './investor.js';
+import { handleOrg } from './org.js';
+import { handleBitable } from './bitable.js';
+import { handleApplication } from './application.js';
+import { handleDashboard } from './dashboard.js';
+import { handleWorkflow } from './workflow.js';
+import { handleAttachment } from './attachment.js';
+import { handleFile } from './file.js';
+import { handleEvent } from './event.js';
+import { handleSkills } from './skills.js';
+import { handleApproval } from './approval.js';
+import { handleReport } from './report.js';
+import { handleConfig } from './config.js';
+import { handleDoctor } from './doctor.js';
+import { handleSchema } from './schema.js';
+
+/** 命令标签 → 处理函数。 */
+export const HANDLERS = new Map([
+  ['login', handleLogin],
+  ['logout', handleLogout],
+  ['me', handleMe],
+  ['tenant', handleTenant],
+  ['member', handleMember],
+  ['investor', handleInvestor],
+  ['org', handleOrg],
+  ['bitable base', handleBitable],
+  ['bitable table', handleBitable],
+  ['bitable field', handleBitable],
+  ['bitable record', handleBitable],
+  ['bitable view', handleBitable],
+  ['bitable form', handleBitable],
+  ['application', handleApplication],
+  ['dashboard', handleDashboard],
+  ['workflow', handleWorkflow],
+  ['attachment', handleAttachment],
+  ['file', handleFile],
+  ['event', handleEvent],
+  ['skills', handleSkills],
+  ['approval', handleApproval],
+  ['report rule', handleReport],
+  ['report', handleReport],
+  ['config', handleConfig],
+  ['doctor', handleDoctor],
+  ['schema', handleSchema],
+]);
+
+/**
+ * 命令规格名 → `meta.command` 标签（对齐 Rust `main.rs::command_label`）。
+ *
+ * `meta.command` 是**域名**而不是整条命令：`bitable record --list` 与
+ * `bitable record --create` 的 `meta.command` 都是 `bitable record`。
+ * 判卷按这个字段对齐，所以它必须与 Rust 版逐字相同。
+ */
+export function commandLabel(specName) {
+  const tokens = specName.split(' ');
+  const domain = tokens[0];
+  if (domain === 'bitable') return `bitable ${tokens[1]}`;
+  if (domain === 'report' && tokens[1] === 'rule') return 'report rule';
+  return domain;
+}
+
+/** 命令规格名 → 处理函数。 */
+export function handlerFor(specName) {
+  return HANDLERS.get(commandLabel(specName)) ?? null;
+}

package/src/commands/investor.js

@@ -0,0 +1,179 @@
+// 投资人：`investor --list|--endorse|--revoke`（契约 §2、§6.2）。
+//
+// **两道门缺一不可（BASE-012）**：
+//
+// - **平台声明**（`member --create --role investor`）= **能力面**：super_admin 说
+//   "这个人是投资人"，他能进 CLI、能看 `me`，但**还看不到任何一家企业的数据**；
+// - **企业背书**（本命令的 `--endorse`）= **数据面**：企业负责人点头"我这家企业给
+//   他看"，服务端才把这家企业写进他的 `scope.tenants`。
+//
+// 这个命令只管第二道门。为什么必须分开：投资关系是**双边**事实 —— 平台知道他是
+// 投资人，不等于开叔企业愿意让他看自己的流水。把两者合成一个动作，等于任何一次
+// 平台赋角都会自动打开所有企业的数据。
+//
+// 与 Rust 版逐条对齐的三个细节：
+// 1. `--list` 的 `status` **永远在 query 里**（clap 的 `default_value = "all"`）；
+// 2. `--endorse` 的企业缺省值走一次 `GET /me`，`--revoke` **不走**（收回背书时要能
+//    明确指向某一家，绝不替用户猜）；
+// 3. 收回背书的 `--reason` 至少 2 个字（写进审计，"1" 这种原因等于没写）。
+
+import { CliError, exactlyOne } from '../core/error.js';
+import { flagOn, flagValue } from '../core/args.js';
+import { dataOf, idempotencyKey, requestSpec } from '../core/runtime.js';
+import { queryPairs } from '../core/values.js';
+import { resolveTenant } from './tenant.js';
+
+/** `investor --list|--endorse|--revoke` 的分发。 */
+export async function handleInvestor({ args, positional, runtime, command }) {
+  // 动作按**旗标**判，不按 `command.name`：Node 的解析器可能把
+  // `investor --endorse --reason r` 判成兄弟候选（`--reason` 只登记在 `--revoke` 上），
+  // 但 args 里的动作旗标永远是用户真正敲的那个 —— Rust 的 `action()` 也是这么判的。
+  const action = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--endorse', flagOn(args, '--endorse')],
+      ['--revoke', flagOn(args, '--revoke')],
+    ],
+    'investor',
+    '例：xinhe-oa-cli investor --list --status pending --json',
+  );
+  if (action === '--list') return list(runtime, args);
+  if (action === '--endorse') return endorse(runtime, args);
+  return revoke(runtime, args);
+}
+
+async function list(runtime, args) {
+  // `--status` 缺省是 `all`（Rust clap 的 `default_value`）：**不筛**也要显式发出去，
+  // 因为服务端把"不筛"与"筛 all"当同一件事，缺了这个参数反而会走另一条分支。
+  const status = flagValue(args, '--status') ?? 'all';
+  // `--user` / `--tenant`：Rust 的扁平结构里 `--list` 也认这两个过滤条件
+  // （query 名是 `investor_user_id` / `tenant_id`）。空值不进 query（`queryPairs`）。
+  const query = queryPairs([
+    ['status', status],
+    ['investor_user_id', flagValue(args, '--user')],
+    ['tenant_id', flagValue(args, '--tenant')],
+  ]);
+  const response = await runtime.sendAuthed(
+    'GET',
+    '/admin/investor-endorsements',
+    requestSpec({ query }),
+  );
+  const data = dataOf(response);
+
+  // 服务端 `GET /admin/investor-endorsements` 返回的是**一个合并清单**：
+  // `{items, count, summary, tenants}` —— `items` 已经把「平台声明（pending）」与
+  // 「已签发的背书（active/revoked/expired）」按 `status` 合成一列。这正是调用方需要
+  // 的形状，所以**如实透传**。
+  //
+  // 早先这里按 `declarations` / `endorsements` 两个键去取，结果永远是空数组：企业
+  // 负责人看到"没有待确认的投资人"，于是**没有任何办法拿到投资人 user_id 去签发
+  // 背书**（`--endorse` 正需要它）。两条并行线各自单测都绿，只有真接起来才暴露 ——
+  // 同 `tenant --create` 的 `stores[].code` 字段名错位是同一类问题。
+  const items = hasKey(data, 'items') ? data.items : [];
+  const summary = hasKey(data, 'summary')
+    ? data.summary
+    : { pending: 0, active: 0, revoked: 0, expired: 0 };
+  const count = Number.isInteger(data?.count) && data.count >= 0
+    ? data.count
+    : Array.isArray(items)
+      ? items.length
+      : 0;
+  // `pending_count` 是本地数的：服务端的 `summary` 有的版本里没有 `pending` 这一项，
+  // 而"有几条等我点头"恰恰是这条命令最常见的用途（企业负责人据此决定签不签）。
+  const pendingCount = Array.isArray(items)
+    ? items.filter((item) => item !== null && typeof item === 'object' && item.status === 'pending')
+        .length
+    : 0;
+
+  runtime.finishFrom(response, {
+    items,
+    count,
+    pending_count: pendingCount,
+    summary,
+    tenants: hasKey(data, 'tenants') ? data.tenants : null,
+    note: '投资人只看得到「平台声明」∩「企业背书」两家企业；status=pending 就是等本企业点头的那些',
+    next_step:
+      '签发背书：xinhe-oa-cli investor --endorse --user <投资人 user_id> --tenant <企业> --reason <原因>',
+  });
+}
+
+async function endorse(runtime, args) {
+  const userId = flagValue(args, '--user');
+  if (userId === null) {
+    throw CliError.usage('`investor --endorse` 需要 --user <投资人 user_id>').withHint(
+      '先看待确认清单：xinhe-oa-cli investor --list --status pending --json',
+    );
+  }
+  // 原因不传就给一条**可审计**的默认值（不是空串）：这条记录日后要能回答
+  // "当年为什么给他看"。用户显式给的空串则原样发（不替用户改主意）。
+  const reason = flagValue(args, '--reason') ?? '企业背书：确认投资人对本企业只读';
+  // 企业：显式 `--tenant` > 你的唯一可见企业（企业负责人只能给自己企业背书）。
+  // ⚠️ 这一步可能在 `--dry-run` 下**真的发一次 `GET /me`** —— 与 Rust 一致：
+  // 它是读，不是写；不知道要给哪家企业背书，连"将发送什么"都打印不出来。
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'));
+
+  const body = {
+    investor_user_id: userId,
+    tenant_id: tenant,
+    expires_at: flagValue(args, '--expires-at'),
+    reason,
+  };
+  // 写操作必带幂等键：重发不会签出两条背书（服务端按幂等键去重）。
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('investor --endorse', flagValue(args, '--idempotency-key')),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', '/admin/investor-endorsements', spec);
+
+  const response = await runtime.sendAuthed('POST', '/admin/investor-endorsements', spec);
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    endorsement: hasKey(data, 'endorsement') ? data.endorsement : data,
+    // 背书签完 ≠ 立刻生效到客户端：让对方自己 `me --json` 看一眼 `scope.tenants`，
+    // 这是唯一能证明"数据面真的开了"的证据（能力面早就有了）。
+    next_step:
+      '确认投资人能看到数据：让他跑 xinhe-oa-cli me --json' +
+      `（scope.tenants 里应出现 ${tenant ?? '<本企业>'}）`,
+  });
+}
+
+async function revoke(runtime, args) {
+  const userId = flagValue(args, '--user');
+  if (userId === null) {
+    throw CliError.usage('`investor --revoke` 需要 --user <投资人 user_id>');
+  }
+  const reason = flagValue(args, '--reason') ?? '';
+  // 收回背书是**降险动作**（契约 §2.1.2b 的四条口径）：不卡 `--yes`，
+  // 但原因必须写清楚 —— 卡确认会让"发现给错了赶紧收回"变慢，而审计不能没有理由。
+  if (reason.trim().length < 2) {
+    throw CliError.usage('收回背书需要 --reason（写进审计）').withHint(
+      '例：xinhe-oa-cli investor --revoke --user usr_qin --reason 投资关系结束',
+    );
+  }
+  // ⚠️ 与 `--endorse` 的**刻意不对称**（照抄 Rust）：这里不解析"唯一可见企业"。
+  // 收回背书要能明确指向某一家企业（`tenant_id: null` 由服务端按你的企业兜底）；
+  // 本地猜一个等于把"收回哪一家"这件事交给运气。
+  const body = {
+    investor_user_id: userId,
+    tenant_id: flagValue(args, '--tenant'),
+    reason,
+  };
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('investor --revoke', flagValue(args, '--idempotency-key')),
+  });
+  if (runtime.dryRun) {
+    return runtime.dryRunReport('POST', '/admin/investor-endorsements/revoke', spec);
+  }
+
+  const response = await runtime.sendAuthed('POST', '/admin/investor-endorsements/revoke', spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** 键存在就取（`null` 也算存在）—— 对齐 Rust `Value::get`：**不能**用 `??` 兜底，
+ * 否则服务端显式回的 `null` 会被当成"没这个键"而套上默认值。 */
+function hasKey(value, key) {
+  return (
+    value !== null && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, key)
+  );
+}