@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/org.js

@@ -0,0 +1,399 @@
+// 组织架构：`org --tree|--show|--create|--move|--rename|--leader-set|--archive|--explain-scope`
+// （ORG-001 issue #80 / ORG-003 issue #83）—— Rust 侧 `commands/org.rs` 的逐条移植。
+//
+// 与 `report` 同一取向：CLI 是**薄封装**。树的一致性（`path` / 闭包表 / `depth`）全在
+// 服务端与数据库触发器上，这里只做三件事：
+//
+// 1. **参数即约束**：动作与组合在本地判定，拼错 = 退出码 2、**一个请求都不发**
+//    （`--depth 0`、`--create` 缺 `--name`、`--tree` 带着 `--key` 都是这一类）；
+// 2. **高风险闸门**：`--move`（整棵子树换父）与 `--archive`（组织行为不可逆）必须 `--yes`；
+// 3. **写操作带幂等键**：建 / 移 / 改名 / 设负责人由 CLI 自动生成 —— 只有 `--archive`
+//    例外（Rust 侧就是 `RequestSpec::default()`：既没有 body 也没有幂等键，逐字照抄）。
+//
+// 几处"为什么"（这些口径只在 Rust 源码里有，契约表里写不下）：
+//
+// * **`--key` 是身份不是属性**：建部门时能指定，之后没有任何命令能改它（服务端也没有
+//   这个口子），`--rename` 只动显示名。所以本文件里找不到任何写 `key` 的路径 —— 不是漏了。
+// * **`--move` 为什么是高风险**：移动 = 重算继承、**不保留原权限**（决策 63），整棵子树的
+//   `path` / `depth` / 闭包一起变，协同方按租户级 `org_revision` 对齐。它不是"改个字段"，
+//   而是"这批人的可见范围当场变了"，所以要 `--yes` + 服务端回 `affected_subtree_size`。
+// * **`--archive` 为什么还有子部门 / 成员时是 409 而不是硬删**：平台**没有物理删除**部门的
+//   口子 —— 历史行、审批记录、审计还要指着它（软删除口径：`--show` 仍取得到，带 `status`）。
+//   归档也**不级联**：先把人挪走、子部门移走，服务端把"还剩几个"放进
+//   `details.remaining_children / remaining_members` 回给调用方（这是 409 → 退出码 5）。
+// * **`--explain-scope` 为什么只回"声明 + 锚点 + 子树节点数"**：展开结果**不落库、不出网**
+//   （ORG-003 §2.6）。回完整部门 ID 列表等于把整份授权拓扑吐给任何一个登录用户，而
+//   "他为什么看得到"这个问题用 声明 + 锚点 + 规模 就已经答完了。
+// * **`--tenant` 在 `--move` 上只是"允许"而不是"要发"**：服务端从 `dept_id` 自己解析归属
+//   企业（跨企业的 `parent` 一律按"不存在"处理），所以 body 里只有 `parent` 一个字段。
+// * **`--show` / `--tree` 是读**：只要 login，可见企业由服务端 `resolve_tenants` 夹紧 ——
+//   点名看不见的企业是 403（不是空树），跨企业 `dept_id` 与"不存在"逐字同一响应。
+
+import { flagOn, flagValue, intFlag } from '../core/args.js';
+import { CliError } from '../core/error.js';
+import { dataOf, idempotencyKey, requestSpec } from '../core/runtime.js';
+import { sortKeysDeep } from '../core/util.js';
+import { queryPairs } from '../core/values.js';
+
+/**
+ * 8 个动作旗标，顺序与 Rust `OrgArgs::action()` 里 `exactly_one` 的候选表**逐字一致**
+ * （多动作报错时列名字的顺序取自它）。
+ */
+const ACTIONS = [
+  '--tree',
+  '--show',
+  '--create',
+  '--move',
+  '--rename',
+  '--leader-set',
+  '--archive',
+  '--explain-scope',
+];
+
+/** `exactly_one` 的 hint（Rust 原文，含那个"建部门"的例子）。 */
+const ACTION_HINT = '例：xinhe-oa-cli org --tree --json（建部门：org --create --name 全科 --tenant kashu）';
+
+/** `--move` 的 `--yes` 闸门文案（Rust 原文，一个字都不改）。 */
+const MOVE_WHAT = 'org --move（整棵子树换父：路径 / 深度 / 闭包全重算，协同方按 org_revision 对齐）';
+/** `--archive` 的 `--yes` 闸门文案。 */
+const ARCHIVE_WHAT = 'org --archive（归档后不再出现在默认树里；有子部门/成员时服务端会拒绝）';
+
+/** `--create` 成功后在 `data` 上补的一句"下一步"（Rust 原文）。 */
+const CREATE_NEXT_STEP =
+  '把人挂进来：xinhe-oa-cli member --set-dept <DEPT_ID> --user <USER_ID>（首个部门自动为主部门）';
+/** `--move` 成功后在 `data` 上补的一句"为什么 dept_id 不用跟着改"（Rust 原文）。 */
+const MOVE_NOTE = '移动后子树内部门的 dept_id 不变（身份不动），只有 path/depth 变';
+
+/** `org` 的分发：先定动作（本地，退出码 2），再按动作发一个请求。 */
+export async function handleOrg({ args, positional, runtime, command }) {
+  // 数值旗标先于动作分发解析：Rust 侧 `--sort` / `--depth` 是 clap 的类型化字段，
+  // 报错发生在 `OrgArgs::action()` **之前**（`--sort abc` 是 clap 的"值不合法"，
+  // 而不是"这个动作不接受 --sort"）。顺序照抄，错误分类才一致。
+  const sort = intFlag(args, '--sort');
+  const depth = intFlag(args, '--depth', { min: 0 });
+
+  const action = pickAction(args, positional, command);
+  rejectExtra(action, args);
+
+  switch (action) {
+    case '--tree':
+      return tree(runtime, args, depth);
+    case '--show':
+      return show(runtime, requiredValue(flagValue(args, '--show'), '--show <DEPT_ID>'));
+    case '--create':
+      return create(runtime, args, sort);
+    case '--move': {
+      const deptId = requiredValue(flagValue(args, '--move'), '--move <DEPT_ID>');
+      const parent = requiredValue(flagValue(args, '--parent'), '--move 的 --parent <DEPT_ID>');
+      return move(runtime, deptId, parent);
+    }
+    case '--rename': {
+      const deptId = requiredValue(flagValue(args, '--rename'), '--rename <DEPT_ID>');
+      requiredValue(flagValue(args, '--name'), '--rename 的 --name <NAME>');
+      return rename(runtime, args, deptId);
+    }
+    case '--leader-set': {
+      const deptId = requiredValue(flagValue(args, '--leader-set'), '--leader-set <DEPT_ID>');
+      requiredValue(flagValue(args, '--leader'), '--leader-set 的 --leader <USER_ID>');
+      return leaderSet(runtime, args, deptId);
+    }
+    case '--archive':
+      return archive(runtime, requiredValue(flagValue(args, '--archive'), '--archive <DEPT_ID>'));
+    default: {
+      // `--explain-scope`（ORG-003）：`--user` 必填，`--action` 缺省 read。
+      const user = requiredValue(flagValue(args, '--user'), '--explain-scope 的 --user <USER_ID>');
+      const dataset = trimNonEmpty(flagValue(args, '--dataset'));
+      const scopeAction = trimNonEmpty(flagValue(args, '--action')) ?? 'read';
+      return explainScope(runtime, user, dataset, scopeAction);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 本地判定（一律**不发请求**）
+// ---------------------------------------------------------------------------
+
+/**
+ * 用户到底给了哪个动作（Rust `OrgArgs::action()` 的 `exactly_one`）。
+ *
+ * 动作旗标有两个来源，缺一不可：
+ *
+ * 1. **`args`**：解析器会把写在命令名里的动作旗标补回 `args`（`org --tree` → `--tree: true`），
+ *    这是主来源；
+ * 2. **命令名**：留着当兜底（`org --tree` 这类名字本身就是"动作即命令名"）。
+ *
+ * 但有一处必须小心，否则会把 `--move` 的 `--yes` 提示顶掉成"两个动作"：解析器在首选候选
+ * 解析失败时会**回退到最宽松的兄弟命令**，而回退时命令名并没有真的从 argv 里被消费掉 ——
+ * 那个域名 token 会漏进 `positional`。例如 `org --move ou_1 --parent ou_2`（没给 `--yes`）
+ * 落到这里时 `command.name` 是 `org --explain-scope`（结构体里必填项最少的那个），可用户
+ * 根本没敲 `--explain-scope`。判据：`positional` 里出现域名 token ⇒ 命令名是回退产物，
+ * 只认 `args` —— 这样"没给 `--yes`"才会走到 `require_yes`，给出与 Rust 一致的高风险提示。
+ */
+function pickAction(args, positional, command) {
+  const on = new Set();
+  for (const flag of ACTIONS) {
+    if (flagOn(args, flag)) on.add(flag);
+  }
+  const nameConsumed = !positional.includes('org');
+  if (nameConsumed) {
+    const nameTokens = (command?.name ?? '').split(' ');
+    const fromName = ACTIONS.find((flag) => nameTokens.includes(flag));
+    if (fromName !== undefined) on.add(fromName);
+  }
+  const picked = ACTIONS.filter((flag) => on.has(flag));
+  if (picked.length === 1) return picked[0];
+  if (picked.length === 0) {
+    throw CliError.usage('`org` 必须给一个动作').withHint(ACTION_HINT);
+  }
+  throw CliError.usage(
+    `\`org\` 一次只能给一个动作，收到 ${picked.length} 个：${picked.join(' / ')}`,
+  ).withHint(ACTION_HINT);
+}
+
+/** 每个动作只接受自己的参数；给了别人的 = 用法错误（Rust `OrgArgs::reject_extra`）。 */
+function rejectExtra(action, args) {
+  const allowed = {
+    '--tree': ['--tenant', '--dept', '--depth'],
+    '--show': [],
+    '--create': ['--parent', '--name', '--key', '--leader', '--sort', '--tenant'],
+    '--move': ['--parent', '--tenant'],
+    '--rename': ['--name'],
+    '--leader-set': ['--leader'],
+    '--explain-scope': ['--user', '--dataset', '--action'],
+    '--archive': [],
+  }[action];
+  // 检查顺序 = Rust 的顺序（报错时列出来的次序也是它）。
+  const candidates = [
+    '--parent',
+    '--name',
+    '--key',
+    '--leader',
+    '--sort',
+    '--tenant',
+    '--dept',
+    '--depth',
+    '--user',
+    '--dataset',
+    '--action',
+  ];
+  const bad = candidates.filter((flag) => flagOn(args, flag) && !allowed.includes(flag));
+  if (bad.length === 0) return;
+  throw CliError.usage(`\`org ${action}\` 不接受 ${bad.join(' / ')}`).withHint(
+    `跑 \`xinhe-oa-cli schema org ${action}\` 看这个动作的参数面`,
+  );
+}
+
+/**
+ * 必填取值：**trim 之后为空 = 没给**（`--name ""` 与 `--name "  "` 都是用法错误）。
+ * 文案与 hint 照抄 Rust 的 `required_value`，包括那个把整段 `what` 拼进 schema 命令的怪 hint。
+ */
+function requiredValue(raw, what) {
+  const value = trimNonEmpty(raw);
+  if (value === null) {
+    throw CliError.usage(`\`org ${what}\` 缺这个必填值`).withHint(
+      `跑 \`xinhe-oa-cli schema org ${what}\` 看参数面`,
+    );
+  }
+  return value;
+}
+
+/** `Option<&str>` 的 trim：空白 → null（Rust `trim_non_empty`）。 */
+function trimNonEmpty(raw) {
+  if (raw === null || raw === undefined) return null;
+  const text = String(raw).trim();
+  return text.length > 0 ? text : null;
+}
+
+/** 往 body 里塞一个"trim 后非空"的字符串字段（Rust `insert_trim`）。 */
+function insertTrim(body, field, raw) {
+  const value = trimNonEmpty(raw);
+  if (value !== null) body[field] = value;
+}
+
+/**
+ * 收尾：`data` 先按**字典序**递归排键，再交给 runtime 渲染。
+ *
+ * 为什么在命令层排一次：Rust 那边 `data` 是 `serde_json::Map`，也就是 `BTreeMap` ——
+ * 键序**永远是字典序**。人类可读面（`--format table|md`）的列序/行序直接取自键序，
+ * 而 Node 的 `JSON.parse` 保留服务端下发的顺序，于是同一份数据会渲染出不同的列序
+ * （`--json` 无此问题：`renderSuccess` 自己会排）。这里排一次，`table` / `md` 也与
+ * Rust 逐字符一致；core 若日后统一在渲染层排序，这一句是幂等的、可以删。
+ */
+function finish(runtime, response, data) {
+  runtime.finishFrom(response, sortKeysDeep(data));
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// ---------------------------------------------------------------------------
+// 读
+// ---------------------------------------------------------------------------
+
+/**
+ * `org --tree [--tenant <t>] [--dept <d>] [--depth <n>]`：部门树。
+ *
+ * 三个 query 参数的**顺序**与 Rust 一致（tenant → dept_id → depth）：服务端不依赖顺序，
+ * 但抓包对拍时顺序也是"同一个请求"的一部分。
+ */
+async function tree(runtime, args, depth) {
+  if (depth === 0) {
+    // `--depth 0` 是"什么都看不到"，属于参数没意义，不是服务端该接的活。
+    throw CliError.usage('--depth 必须 ≥ 1（0 层 = 什么都看不到）').withHint(
+      '例：xinhe-oa-cli org --tree --depth 2 --json',
+    );
+  }
+  const query = queryPairs([
+    ['tenant', trimNonEmpty(flagValue(args, '--tenant'))],
+    ['dept_id', trimNonEmpty(flagValue(args, '--dept'))],
+    ['depth', depth === null ? null : String(depth)],
+  ]);
+  const spec = requestSpec({ query });
+  if (runtime.dryRun) return runtime.dryRunReport('GET', '/org/tree', spec);
+  const response = await runtime.sendAuthed('GET', '/org/tree', spec);
+  finish(runtime, response, dataOf(response));
+}
+
+/**
+ * `org --show <DEPT_ID>`：部门详情。**含已归档**（软删除口径：`status` / `archived_at`
+ * 仍在，取得到才答得了"这个部门当时叫什么"）。
+ */
+async function show(runtime, deptId) {
+  const path = `/org/units/${deptId}`;
+  const spec = requestSpec();
+  if (runtime.dryRun) return runtime.dryRunReport('GET', path, spec);
+  const response = await runtime.sendAuthed('GET', path, spec);
+  finish(runtime, response, dataOf(response));
+}
+
+/**
+ * `org --explain-scope --user <uid> [--dataset <slug>] [--action read]`（ORG-003）。
+ *
+ * 输出就是服务端 `data` 原样（与 `--show` 同口径，不做二次加工）：声明 + 锚点 +
+ * 子树节点数。`--dataset` 缺省 = 该人全部数据集的声明；`--action` 缺省 `read`。
+ */
+async function explainScope(runtime, userId, dataset, action) {
+  const query = queryPairs([
+    ['user_id', userId],
+    ['dataset', dataset],
+    ['action', action],
+  ]);
+  const spec = requestSpec({ query });
+  if (runtime.dryRun) {
+    return runtime.dryRunReport('GET', '/admin/grants/scope-explain', spec);
+  }
+  const response = await runtime.sendAuthed('GET', '/admin/grants/scope-explain', spec);
+  finish(runtime, response, dataOf(response));
+}
+
+// ---------------------------------------------------------------------------
+// 写
+// ---------------------------------------------------------------------------
+
+/**
+ * `org --create --name <n> [--parent <p>] [--key <k>] [--leader <u>] [--sort <n>] [--tenant <t>]`。
+ *
+ * `--parent` 缺省 = 该租户根部门；首个部门自动补根（服务端的事）。
+ * `--leader` 在这里**只落值不做成员校验**（校验归 `--leader-set`：负责人须为该部门或其后代
+ * 的在职成员）—— 建部门时人可能还没挂进来，先卡校验会让"先建部门再挂人"这条路走不通。
+ */
+async function create(runtime, args, sort) {
+  requiredValue(flagValue(args, '--name'), '--create 的 --name <NAME>');
+  const body = {};
+  insertTrim(body, 'name', flagValue(args, '--name'));
+  insertTrim(body, 'parent', flagValue(args, '--parent'));
+  insertTrim(body, 'key', flagValue(args, '--key'));
+  insertTrim(body, 'leader', flagValue(args, '--leader'));
+  insertTrim(body, 'tenant', flagValue(args, '--tenant'));
+  if (sort !== null) body.sort = sort;
+  const spec = requestSpec({
+    // 键序对齐 Rust：`serde_json::Map` 是 BTreeMap，请求体在线上是**字典序**的。
+    body: sortBodyKeys(body),
+    idempotencyKey: idempotencyKey('org-create', null),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', '/org/units', spec);
+  const response = await runtime.sendAuthed('POST', '/org/units', spec);
+  const data = dataOf(response);
+  if (isPlainObject(data)) data.next_step = CREATE_NEXT_STEP;
+  finish(runtime, response, data);
+}
+
+/**
+ * `org --move <DEPT_ID> --parent <DEPT_ID>`：**高风险写，必须 `--yes`**。
+ *
+ * 服务端回 `affected_subtree_size`（整棵子树多少个部门跟着动）与新的 `org_revision`
+ * （跨部门协同的租户级水位）—— 这两个数就是"这次移动影响了多少人"的答案。
+ *
+ * body 只有 `parent`：服务端从 `dept_id` 自己解析归属企业，跨企业的 `parent` 一律按
+ * "不存在"处理，所以 `--tenant` 允许写、但**不发**（Rust 也是这么做的）。
+ */
+async function move(runtime, deptId, parent) {
+  runtime.requireYes(MOVE_WHAT, `xinhe-oa-cli org --move ${deptId} --parent ${parent}`);
+  const path = `/org/units/${deptId}/move`;
+  const spec = requestSpec({
+    body: { parent },
+    idempotencyKey: idempotencyKey('org-move', null),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  const data = dataOf(response);
+  if (isPlainObject(data)) data.note = MOVE_NOTE;
+  finish(runtime, response, data);
+}
+
+/**
+ * `org --rename <DEPT_ID> --name <n>`：只改显示名。
+ *
+ * `key` / `path` 一个字都不动 —— 它们是**身份**（授权、审计、外部系统都按 key / path 指过来），
+ * 允许改名顺带换 key 等于让所有既有引用静默指空。所以这里连参数都没有。
+ */
+async function rename(runtime, args, deptId) {
+  const path = `/org/units/${deptId}/rename`;
+  const spec = requestSpec({
+    body: { name: trimNonEmpty(flagValue(args, '--name')) },
+    idempotencyKey: idempotencyKey('org-rename', null),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  finish(runtime, response, dataOf(response));
+}
+
+/** `org --leader-set <DEPT_ID> --leader <USER_ID>`：负责人须为本子树在职成员（服务端判）。 */
+async function leaderSet(runtime, args, deptId) {
+  const path = `/org/units/${deptId}/leader`;
+  const spec = requestSpec({
+    // 字段名是 `user_id` 而不是 `leader`：服务端这个口子收的是"人"，不是"leader 这个角色"。
+    body: { user_id: trimNonEmpty(flagValue(args, '--leader')) },
+    idempotencyKey: idempotencyKey('org-leader', null),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  finish(runtime, response, dataOf(response));
+}
+
+/**
+ * `org --archive <DEPT_ID>`：**高风险写，必须 `--yes`**。
+ *
+ * 还有子部门 / 在职成员时服务端拒绝（409 `org.dept_not_empty`，details 给
+ * `remaining_children` / `remaining_members`）—— 先把人挪走、子部门移走，再归档。
+ *
+ * 这个口子**既没有 body 也没有幂等键**（Rust 侧就是 `RequestSpec::default()`）：
+ * 归档是"把状态置为 archived"的幂等语义，重放一次结果相同，不需要服务端去重。
+ * 不照抄这一点的话，抓包对拍会多出一个 `Idempotency-Key` 头。
+ */
+async function archive(runtime, deptId) {
+  runtime.requireYes(ARCHIVE_WHAT, `xinhe-oa-cli org --archive ${deptId}`);
+  const path = `/org/units/${deptId}/archive`;
+  const spec = requestSpec();
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  finish(runtime, response, dataOf(response));
+}
+
+/** 浅排对象键（对齐 serde_json 的 BTreeMap；`sort` 是数字，不受影响）。 */
+function sortBodyKeys(body) {
+  const out = {};
+  for (const key of Object.keys(body).sort()) out[key] = body[key];
+  return out;
+}