@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/tenant.js

@@ -0,0 +1,202 @@
+// 企业：`tenant --list|--create|--show`（契约 §2、§6.2）。
+//
+// 对应服务端 `GET|POST /admin/tenants`。三件事在这里定：
+//
+// 1. **动作由旗标判**（`--list` / `--create` / `--show`），不靠命令名 —— Node 的解析器
+//    是"按参数面挑最合适的那条候选命令"，`investor --endorse --reason r` 这种组合
+//    甚至会被判成兄弟命令的候选（见 investor.js 的说明）。Rust 侧同样是**一个扁平
+//    struct + `action()`**，所以两条实现都以 args 里的动作旗标为准。
+// 2. **缺必填、多动作、空门店编码都在本地判死**（退出码 2、一个请求都不发）——
+//    与 Rust 的 `CliError::usage` 逐条对齐。
+// 3. **接口没上线时不伪装成功**：`POST /admin/tenants` 在旧服务端上是 404/500，
+//    这时给"服务端未就绪 + 替代路径"，而不是让客户以为自己的参数写错了。
+
+import { CliError, Kind, exactlyOne } from '../core/error.js';
+import { flagList, flagOn, flagValue } from '../core/args.js';
+import { dataOf, idempotencyKey, requestSpec } from '../core/runtime.js';
+
+/** `tenant --list|--create|--show` 的分发。 */
+export async function handleTenant({ args, positional, runtime, command }) {
+  const action = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--create', flagOn(args, '--create')],
+      ['--show', flagOn(args, '--show')],
+    ],
+    'tenant',
+    '例：xinhe-oa-cli tenant --list --json',
+  );
+  if (action === '--list') return list(runtime);
+  if (action === '--create') return create(runtime, args);
+  return show(runtime, flagValue(args, '--show') ?? '');
+}
+
+/**
+ * `POST /admin/tenants` 还没有时的说明（Agent B 的接口）。
+ *
+ * 判据照抄 Rust：**404**，或 **500 + `internal.error`** —— 后者是"旧服务端没挂这条
+ * 路由、框架兜底报 500"的常见样子。命中时保留原 code 与 request_id（排障要），
+ * 但换掉 message/hint：这不是调用方的参数错，而是服务端版本不对。
+ */
+function notReady(err) {
+  if (
+    err instanceof CliError &&
+    (err.httpStatus === 404 || (err.httpStatus === 500 && err.code === 'internal.error'))
+  ) {
+    const out = new CliError(
+      Kind.Server,
+      err.code,
+      '服务端还没有 `POST /admin/tenants`（建企业接口未就绪）',
+    );
+    out.hint =
+      '先让服务端升级到带队建企业接口的版本；或在服务端机器上跑 ' +
+      '`python scripts/add_tenant.py` 建企业，再用 `xinhe-oa-cli tenant --list` 确认';
+    out.requestId = err.requestId ?? null;
+    out.httpStatus = err.httpStatus;
+    return out;
+  }
+  return err;
+}
+
+/** 已认证请求 + 未就绪说明（`tenant` 三个动作共用）。 */
+async function sendTenant(runtime, method, path, spec) {
+  try {
+    return await runtime.sendAuthed(method, path, spec);
+  } catch (err) {
+    throw notReady(err);
+  }
+}
+
+async function list(runtime) {
+  const response = await sendTenant(runtime, 'GET', '/admin/tenants', requestSpec());
+  const data = dataOf(response);
+  // 服务端可能回 `{data: {tenants: [...]}}`，也可能把清单直接塞在 `data` 里：
+  // Rust 是 `tenants → items → 整个 data` 三级兜底，这里逐级照抄（顺序不能换，
+  // `items` 只是旧版形状的兼容）。
+  const tenants = hasKey(data, 'tenants')
+    ? data.tenants
+    : hasKey(data, 'items')
+      ? data.items
+      : data;
+  // `total` 优先信服务端；它没给就数一数（数不出来算 0）——
+  // "列表被截断了"这件事只有服务端知道，本地数字不能反过来覆盖它。
+  const total = hasKey(data, 'total')
+    ? data.total
+    : Array.isArray(tenants)
+      ? tenants.length
+      : 0;
+  runtime.finishFrom(response, { tenants, total });
+}
+
+async function create(runtime, args) {
+  // `--id` 与 `--name` 都在本地判：它们是"这条命令能不能成立"的前提，
+  // 交给服务端去报 422 只会把一次用法错误变成一次网络往返。
+  const tenantId = flagValue(args, '--id');
+  if (tenantId === null) {
+    throw CliError.usage('`tenant --create` 需要 --id <TENANT_ID>').withHint(
+      '例：xinhe-oa-cli tenant --create --id kashu --name 开叔企业 --store S01:总院',
+    );
+  }
+  const name = flagValue(args, '--name');
+  if (name === null) {
+    throw CliError.usage('`tenant --create` 需要 --name <显示名>').withHint(
+      '例：xinhe-oa-cli tenant --create --id kashu --name 开叔企业',
+    );
+  }
+
+  // `--store S01:总院` → `[{"code": "S01", "name": "总院"}]`；**不带冒号就只给 code**
+  // （显示名由服务端兜底）。
+  //
+  // 为什么按**第一个冒号**拆：门店编码是 `S01` 这种大写字母+数字的短码，里面不会
+  // 有冒号；而显示名（`总院:东区`）里可能有 —— 所以 `split_once(':')`（JS 里就是
+  // 第一个 `indexOf(':')`）才是对的，从右边拆会把名字切碎。
+  //
+  // 字段名是 **`code` 不是 `id`**：服务端拿它拼门店 id `<tenant>-<CODE>`
+  // （`services/tenants.py` 的 `normalize_stores` / `store_id_for`）。发 `id` 会得到
+  // 一个空 code 的 `request.invalid`，而错误信息只说"门店编码只能是大写字母…"，
+  // 看不出是字段名错了 —— 这是两条并行线真实踩过的一次集成失败。
+  //
+  // `--store` 可重复（clap 的 `ArgAction::Append`）：一家企业开业就有多个门店，
+  // 一次建企业要把它们一起写进去，否则得再补一次调用（而 `--create` 幂等键会变）。
+  const stores = [];
+  for (const raw of flagList(args, '--store')) {
+    const text = String(raw);
+    const colon = text.indexOf(':');
+    const code = (colon >= 0 ? text.slice(0, colon) : text).trim();
+    const label = colon >= 0 ? text.slice(colon + 1).trim() : null;
+    // 空编码等于让服务端去拼一个 `<tenant>-` 出来 —— 本地就拦，别让它变成脏数据。
+    if (code.length === 0) {
+      throw CliError.usage(`--store 里的门店编码不能为空（${JSON.stringify(text)}）`);
+    }
+    stores.push(label !== null && label.length > 0 ? { code, name: label } : { code });
+  }
+
+  const body = {
+    id: tenantId,
+    name,
+    stores,
+    note: flagValue(args, '--description'),
+  };
+  // 写操作必带幂等键（契约 §3.4）：网络抖动重发不会建出第二家企业。
+  // `--idempotency-key` 只是覆盖口（当前命令面还没登记这个旗标，取到的恒为 null）。
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('tenant --create', flagValue(args, '--idempotency-key')),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', '/admin/tenants', spec);
+
+  const response = await sendTenant(runtime, 'POST', '/admin/tenants', spec);
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    tenant: hasKey(data, 'tenant') ? data.tenant : data,
+    // 建企业只是第一步：没人有权限的话，这家企业谁都看不见。
+    // 下一步写成可直接照抄的一条命令，省掉一次翻文档。
+    next_step:
+      '给企业负责人赋角：xinhe-oa-cli member --create --phone <号码> --name <姓名> ' +
+      `--role tenant_owner --tenant ${tenantId}`,
+  });
+}
+
+async function show(runtime, tenantId) {
+  // 与 Rust 一致：**不做 URL 编码**。租户 id 的字符集由服务端校验
+  // （小写字母/数字/下划线），本地擅自转义只会让路径与服务端审计里的那一行对不上。
+  const response = await sendTenant(runtime, 'GET', `/admin/tenants/${tenantId}`, requestSpec());
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * 把 `--tenant` 的缺省值处理成"你的唯一可见企业"：先 `GET /me` 拿 `scope.tenants`。
+ *
+ * 为什么要有它：`member` / `file` / `investor --endorse` 这些命令都要求"给哪家企业办事"，
+ * 而绝大多数用户只有一家可见企业 —— 每次都逼人写 `--tenant` 是纯粹的摩擦。
+ * 但**多企业时必须报错**，不能替用户挑一个：挑错了就是往别人的企业里写数据。
+ *
+ * 三种结果：显式 `--tenant`（trim 后非空）> 唯一可见企业 > `null`（没有可见企业）。
+ * 多个可见企业是**用法错误**（退出码 2、不发写请求），并把清单塞进 `details`
+ * 让调用方（或 LLM）能直接挑一个。
+ */
+export async function resolveTenant(runtime, requested) {
+  const trimmed = requested === null || requested === undefined ? '' : String(requested).trim();
+  if (trimmed.length > 0) return trimmed;
+
+  const response = await runtime.sendAuthed('GET', '/me', requestSpec());
+  const data = dataOf(response);
+  const tenants = Array.isArray(data?.scope?.tenants) ? data.scope.tenants : [];
+  if (tenants.length === 1) {
+    const id = tenants[0]?.id;
+    return typeof id === 'string' ? id : null;
+  }
+  if (tenants.length === 0) return null;
+  throw CliError.usage('你有多个可见企业，请用 --tenant <TENANT_ID> 指明').withDetails({
+    visible_tenants: tenants,
+    hint: 'xinhe-oa-cli tenant --list',
+  });
+}
+
+/** 键存在就取（`null` 也算存在）—— 对齐 Rust `Value::get`：**不能**用 `??` 兜底，
+ * 否则服务端显式回的 `null` 会被当成"没这个键"而套上默认值。 */
+function hasKey(value, key) {
+  return (
+    value !== null && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, key)
+  );
+}

package/src/commands/workflow.js

@@ -0,0 +1,176 @@
+// 工作流：`workflow --list|--runs|--create|--run`（契约 §2）。
+//
+// `--run` 是 `high-risk-write`：它**按触发人（就是你）的身份真的执行动作** ——
+// 建记录、改记录、发通知、跑 Skill，都会留下真实的写入与审计（docs/26 §3）。
+// 定时/事件触发的运行有 `(workflow_id, trigger_event_id)` 唯一约束兜底，手动触发没有
+// "事件"可去重，所以必须 `--yes`；不给就本地退出码 2，一个请求都不发。
+//
+// 另外两条刻意如此的口径：
+//
+// 1. **触发器与动作只收 JSON 字面量，CLI 不发明 DSL**：服务端登记的就是五类触发器
+//    （record_created / record_updated / status_changed / manual_confirmed / schedule）
+//    与四类动作（create_record / update_record / notify / run_skill），CLI 自己再抄一份
+//    枚举只会随时间漂移。合法性在**本地**只判两件事：是不是合法 JSON、清单空不空。
+// 2. `--run` 的执行身份是**自然人**，不是"CLI 这个程序"：越权会记 `failed` 且没有任何
+//    写入（`workflow.permission_denied`）—— 这条写进响应的 note，因为调用方（尤其是
+//    Agent）需要知道"失败了不等于什么都没发生"的边界在哪。
+
+import { CliError, exactlyOne } from '../core/error.js';
+import { flagList, flagOn, flagValue } from '../core/args.js';
+import { dataOf, idempotencyKey, requestSpec } from '../core/runtime.js';
+import { randomHex, sortKeysDeep } from '../core/util.js';
+import { queryPairs } from '../core/values.js';
+
+/** `workflow --list|--runs|--create|--run` 的分发。 */
+export async function handleWorkflow({ args, runtime }) {
+  const action = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--runs', flagValue(args, '--runs') !== null],
+      ['--run', flagValue(args, '--run') !== null],
+      ['--create', flagOn(args, '--create')],
+    ],
+    'workflow',
+    '例：xinhe-oa-cli workflow --list --json',
+  );
+  if (action === '--list') return list(runtime, args);
+  if (action === '--runs') return runs(runtime, flagValue(args, '--runs'));
+  if (action === '--run') return runOnce(runtime, args, flagValue(args, '--run'));
+  return create(runtime, args);
+}
+
+async function list(runtime, args) {
+  // `--base` 空值不进 query，非空值原样发（与 Rust 的 `query_pair` 同义）。
+  const query = queryPairs([['base_id', flagValue(args, '--base')]]);
+  const response = await runtime.sendAuthed('GET', '/workflows', requestSpec({ query }));
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    workflows: hasKey(data, 'workflows') ? data.workflows : [],
+    total: hasKey(data, 'total') ? data.total : null,
+    next_step: '看运行历史：xinhe-oa-cli workflow --runs <WORKFLOW_ID> --json',
+  });
+}
+
+async function runs(runtime, workflowId) {
+  const response = await runtime.sendAuthed(
+    'GET',
+    `/workflows/${workflowId}/runs`,
+    requestSpec(),
+  );
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    runs: hasKey(data, 'runs') ? data.runs : [],
+    total: hasKey(data, 'total') ? data.total : null,
+    // 失败原因在每条 run 的 `error` 里，最常见的两条语义差别很大，所以写在 note 里：
+    // `workflow.permission_denied` 是**触发人没权限**（没有任何写入副作用）。
+    note: '失败的原因在 error 里：workflow.permission_denied = 触发人对目标表没写权限（**没有任何写入副作用**）',
+  });
+}
+
+/** 手动跑一次（高风险：必须 `--yes`）。 */
+async function runOnce(runtime, args, workflowId) {
+  runtime.requireYes(
+    'workflow --run（会按你的身份真的执行工作流动作）',
+    `xinhe-oa-cli workflow --run ${workflowId}`,
+  );
+  const path = `/workflows/${workflowId}/run`;
+  // 写操作必带幂等键：手动触发重发两次不会跑出两条运行（服务端按幂等键去重）。
+  const spec = requestSpec({
+    idempotencyKey: idempotencyKey('workflow --run', flagValue(args, '--idempotency-key')),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, {
+    run: dataOf(response),
+    note: '工作流用**触发它的自然人**的身份执行；越权会记 failed 且没有任何写入',
+  });
+}
+
+async function create(runtime, args) {
+  const baseId = flagValue(args, '--base');
+  if (baseId === null) {
+    throw CliError.usage('`workflow --create` 需要 --base <BASE_ID>');
+  }
+  const name = flagValue(args, '--name');
+  if (name === null) {
+    throw CliError.usage('`workflow --create` 需要 --name <工作流名>');
+  }
+  const triggers = flagList(args, '--trigger');
+  if (triggers.length === 0) {
+    throw CliError.usage('`workflow --create` 需要至少一个 --trigger <JSON>').withHint(
+      '触发器五类之一：{"type":"record_created","table_id":"tbl_1"} / {"type":"record_updated",...} / {"type":"status_changed",...} / {"type":"manual_confirmed"} / {"type":"schedule","cron":"0 9 * * *","timezone":"Asia/Shanghai"}',
+    );
+  }
+  const actions = flagList(args, '--action-json');
+  if (actions.length === 0) {
+    throw CliError.usage('`workflow --create` 需要至少一个 --action-json <JSON>').withHint(
+      '动作四类之一：create_record / update_record / notify / run_skill（都是 {"type":...} 的对象）',
+    );
+  }
+  // 两个清单都先**整体**校验再发请求：触发器合法、动作非法时不该产生半个工作流。
+  const parsedTriggers = parseJsonList(triggers, '--trigger');
+  const parsedActions = parseJsonList(actions, '--action-json');
+  // 机器名创建后不可变：显式 `--key` 优先，否则从显示名推导，推不出来用 `w<8 位 hex>`。
+  const key = flagValue(args, '--key') ?? deriveKey(name) ?? `w${randomHex().slice(0, 8)}`;
+  // 键序按字典序（serde_json 是 BTreeMap），连请求体的字节面都与 Rust 对齐。
+  const body = {
+    actions: parsedActions,
+    base_id: baseId,
+    key,
+    name,
+    triggers: parsedTriggers,
+  };
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('workflow --create', flagValue(args, '--idempotency-key')),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', '/workflows', spec);
+
+  const response = await runtime.sendAuthed('POST', '/workflows', spec);
+  runtime.finishFrom(response, { workflow: dataOf(response) });
+}
+
+/**
+ * `--trigger` / `--action-json` 的 JSON 字面量解析（Rust `parse_json_list` 同义）。
+ *
+ * 只在这里判"是不是 JSON"：**任何**合法 JSON 都收（对象、字符串、数字……），
+ * 因为它们原样进请求体，形状合不合法是服务端的事（五类触发器/四类动作是它的枚举）。
+ */
+function parseJsonList(items, flag) {
+  return items.map((item) => {
+    let value;
+    try {
+      value = JSON.parse(String(item));
+    } catch (err) {
+      throw CliError.usage(`${flag} 里不是合法 JSON：${err.message}`).withHint(
+        `例：${flag} '{"type":"record_created","table_id":"tbl_1"}'`,
+      );
+    }
+    // 键序与 Rust 的 serde_json 一致（它反序列化成 BTreeMap，再序列化就是字典序）。
+    return sortKeysDeep(value);
+  });
+}
+
+/**
+ * 由显示名推导机器名 —— 与 Rust `bitable::derive_key` 逐条同义（详见 dashboard.js 的同名函数：
+ * 那边已经解释了"为什么中文名推不出来时宁可随机也不硬编"）。
+ */
+function deriveKey(name) {
+  let key = '';
+  for (const ch of String(name ?? '')) {
+    if (/^[A-Za-z0-9]$/.test(ch)) key += ch.toLowerCase();
+    else if (ch.codePointAt(0) < 128) key += '_';
+  }
+  key = key.replace(/_{2,}/g, '_').replace(/^_+|_+$/g, '');
+  if (key.length > 48) key = key.slice(0, 48);
+  if (key.length === 0 || !/^[a-z]/.test(key)) return null;
+  return key;
+}
+
+/** 键存在就取（`null` 也算存在）—— 对齐 Rust `Value::get`。 */
+function hasKey(value, key) {
+  return (
+    value !== null && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, key)
+  );
+}