@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/member.js

@@ -0,0 +1,1341 @@
+// 成员域：`member --list|--search|--create|--role|--revoke-role|--remove`（契约 §2、§6.2），
+// 含 ORG-001 的部门归属三件套（`--set-dept` / `--unset-dept` / `--set-manager|--clear-manager`）、
+// ORG-002 的授权三动作（`--grant|--revoke-grant|--grants`，issue #82）、
+// ORG-004 的离职 / 移交四动作（issue #81）与 MEMBER-001 的 `--search`（issue #99）。
+//
+// ## 为什么这一域的动作判定要**自己做**（而不是看 `command.name`）
+//
+// Rust 版把 16 个动作塞进**同一个** `MemberArgs` 结构体（clap 的互斥组装不下
+// “`--role` 既是动词又是 `--create` 的参数”），动作由 `MemberArgs::action()` 在本地判；
+// `--search` / `--offboard` 这些动词的取值（`--offboard usr_x` 的 `usr_x`）也是
+// **动作名后面的位置词**，clap 把它们当成旗标取值。
+//
+// Node 侧的命令规格是“散文”（`schema --json` 的 `params`），`member --offboard usr_x`
+// 在规格里最长的前缀命中可能是别的兄弟命令（实测会落到 `member --transfer-list`）。
+// 所以这一域**不看 `command.name`**：`memberAction()` 是 `MemberArgs::action()` 的逐行移植，
+// 动作、必填、互斥、逐动词的参数面全在这一处判死 —— 这样"哪条候选赢"就与人无关了。
+//
+// ## 三条本地纪律（一个请求都不发，退出码 2）
+//
+// 1. **`--list` 只列举、不带条件**：`--name` / `--phone` / `--dept` 出现在它上面直接报错
+//    并指路 `--search`（MEMBER-001 的行为变更：过去前两个被静默忽略、`--dept` 只把过滤
+//    下推给部门归属那一半，人仍来自全量 `GET /admin/users` = 静默返回全公司的人）。
+// 2. **`--grant` 主体多态**：`--user` 与 `--dept` 互斥，都不给也是错；
+//    `--dept-scope CUSTOM` 没有 `--dept-id` 是错（服务端对“声明 CUSTOM_DEPTS 却没给 ID”
+//    回 400，契约要求在这里本地判死）；`--dept-scope` 用在非数据动作（grant / ddl / admin:*）
+//    上同样是错 —— 它是**行范围**，不是能力面。
+// 3. **ORG-004 的高风险写**：`--offboard` / `--transfer` / `--transfer-revert` 没有 `--yes`
+//    一律退出码 2；**`--offboard --dry-run` 是例外**（见 `offboard()` 的注释）。
+//
+// 退出码与错误分类由 `main.js` 统一收口；服务端的 `request.invalid /
+// transfer_target_required` 由 `core/http.js` 归到 2，这里**不覆盖**。
+
+import { CliError, Kind } from '../core/error.js';
+import { flagList, flagOn, flagValue, intFlag } from '../core/args.js';
+import { dataOf, idempotencyKey, requestSpec } from '../core/runtime.js';
+import { warn } from '../core/output.js';
+import { queryPairs } from '../core/values.js';
+
+/** 合法角色（与服务端 `ROLE_TEMPLATES` 对齐；`tenant_member` 是契约 §6.2 的业务员角色）。 */
+const ROLES = ['super_admin', 'tenant_owner', 'tenant_member', 'tenant_operator', 'investor'];
+
+/** `--dept-scope` 只对**数据动作**有意义（行范围）；能力面动作没有部门档位。 */
+const DATA_ACTIONS = ['read', 'write', 'export', 'delete'];
+
+/**
+ * 服务端 `GET /admin/users` 的硬上限（既有限举路径，客户端无法翻页）。
+ *
+ * 命中整整这么多条时 `--list` 会带 `truncated: true` —— 这是**下界**判断：
+ * 企业恰好有 500 人时也会报 `true`（宁可提示“可能被截断”，也不要静默漏人）。
+ */
+const LIST_PAGE_LIMIT = 500;
+
+/**
+ * `u32` 的上界（`--limit` / `--offset` 在 Rust 里就是 `Option<u32>`）。
+ *
+ * 超过它 clap 会在解析层拒掉（退出码 2）；这里补同一道上界，免得把一个
+ * 服务端必然 422 的值发出去。
+ */
+const U32_MAX = 4294967295;
+
+const OFFBOARD_EXAMPLE = 'xinhe-oa-cli member --offboard usr_tang --reason 离职交接 --yes';
+const TRANSFER_EXAMPLE =
+  'xinhe-oa-cli member --transfer usr_tang --to usr_owner --reason 岗位调整 --yes';
+const ACTION_HINT =
+  '例：xinhe-oa-cli member --create --phone 13800000001 --name 小唐 --role tenant_member --tenant kashu';
+
+/** 分发入口：先本地判动作（不发请求），再按动作走各自的端点。 */
+export async function handleMember({ args, runtime }) {
+  const action = memberAction(args);
+  switch (action.kind) {
+    case 'list':
+      // `--list --user <id>` = 看某人的角色与展开后的授权（另一条只读路径）。
+      return action.user === null ? list(runtime, args) : rolesOf(runtime, action.user);
+    case 'search':
+      return search(runtime, args, action);
+    case 'create':
+      return create(runtime, args);
+    case 'assign':
+      return assign(runtime, args, action.role, action.user);
+    case 'revoke-role':
+      return revokeRole(runtime, args, action.role, action.user);
+    case 'remove':
+      return removeMember(runtime, action.user, args);
+    case 'set-dept':
+      return setDept(runtime, args, action.user, action.deptId, action.primary);
+    case 'unset-dept':
+      return unsetDept(runtime, args, action.user, action.deptId);
+    case 'set-manager':
+      return setManager(runtime, args, action.user, action.manager);
+    case 'grant':
+      return grant(runtime, args, action);
+    case 'revoke-grant':
+      return revokeGrant(runtime, args, action.grantId);
+    case 'grants':
+      return listGrants(runtime, args, action.user, action.dept);
+    case 'offboard':
+      return offboard(runtime, args, action);
+    case 'transfer':
+      return transfer(runtime, args, action);
+    case 'transfer-list':
+      return transferList(runtime, args, action);
+    case 'transfer-revert':
+      return transferRevert(runtime, args, action.transferId, action.note);
+    default:
+      throw CliError.usage('`member` 必须给一个动作').withHint(ACTION_HINT);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 动作判定：`MemberArgs::action()` 的逐行移植（本地判定，退出码 2、不发请求）
+// ---------------------------------------------------------------------------
+
+/**
+ * 把一串旗标收成一个动作，并按 Rust 的顺序做完全部本地校验。
+ *
+ * 顺序是**行为的一部分**：同一个错误参数组合，Rust 先报哪一条，这里就得先报哪一条
+ * （否则错误文案与退出码相同、但 `error.message` 漂移，判卷与用户都会困惑）。
+ */
+function memberAction(args) {
+  const on = (flag) => flagOn(args, flag);
+  const val = (flag) => flagValue(args, flag);
+  const given = (flag) => flagValue(args, flag) !== null;
+
+  const picked = exactlyOne(
+    [
+      ['--list', on('--list')],
+      ['--create', on('--create')],
+      // `--role` 跟着 `--create` 时是参数，不是动词。
+      ['--role', given('--role') && !on('--create')],
+      ['--revoke-role', given('--revoke-role')],
+      ['--remove', given('--remove')],
+      ['--set-dept', given('--set-dept')],
+      ['--unset-dept', given('--unset-dept')],
+      ['--set-manager', given('--set-manager')],
+      ['--clear-manager', on('--clear-manager')],
+      ['--grant', on('--grant')],
+      ['--revoke-grant', given('--revoke-grant')],
+      ['--grants', on('--grants')],
+      ['--offboard', given('--offboard')],
+      ['--transfer', given('--transfer')],
+      ['--transfer-list', on('--transfer-list')],
+      ['--transfer-revert', given('--transfer-revert')],
+      ['--search', on('--search')],
+    ],
+    'member',
+    ACTION_HINT,
+  );
+
+  // MEMBER-001：`--list` **只列举、不带条件**。这一条是刻意的行为变更：
+  // 静默忽略一个“看起来生效了”的过滤条件，比报错危险得多（调用方会以为筛过了）。
+  if (picked === '--list') {
+    const wrong = [];
+    if (on('--name')) wrong.push('--name');
+    if (on('--phone')) wrong.push('--phone');
+    if (on('--dept')) wrong.push('--dept');
+    if (wrong.length > 0) {
+      throw CliError.usage(
+        `\`member --list\` 不接受 ${wrong.join(' / ')}：列举不带条件（过去 --name/--phone 被静默忽略、--dept 只标注不过滤）`,
+      ).withHint(
+        '按姓名 / 精确手机号 / 部门查人请用 `member --search`（例：member --search --name 小唐 --json）',
+      );
+    }
+  }
+
+  // 检索条件是 --name / --phone / --dept，`--user` 是“看某个人”，两回事。
+  if (picked === '--search' && on('--user')) {
+    throw CliError.usage(
+      '`member --search` 不接受 --user：检索条件用 --name / --phone / --dept',
+    ).withHint('要看某个人的角色与授权：member --list --user <USER_ID>');
+  }
+
+  // ORG-003：部门档位只属于 `--grant` 的数据动作；别的动词上出现 = 参数拼错。
+  if (
+    picked !== '--grant' &&
+    (on('--dept-scope') || flagList(args, '--dept-id').length > 0 || on('--include-sub') || on('--include-unassigned'))
+  ) {
+    throw CliError.usage(
+      `\`member ${picked}\` 不接受部门档位参数（--dept-scope / --dept-id / --include-sub / --include-unassigned）`,
+    ).withHint('部门档位只属于 `member --grant` 的数据动作（read / write / export / delete）');
+  }
+
+  // ORG-004：每个动词只接受自己的参数（`--dry-run` 是全局旗标，不在这里管）。
+  // 出现在别的动词上 = 参数拼错 —— 拼错的参数被忽略，等于让人以为它生效了。
+  const bad = [];
+  const check = (present, flag, allowed) => {
+    if (present && !allowed.includes(picked)) bad.push(flag);
+  };
+  check(given('--scope'), '--scope', ['--offboard', '--transfer']);
+  check(given('--personal'), '--personal', ['--offboard']);
+  check(given('--transfer-to'), '--transfer-to', ['--offboard']);
+  check(given('--to'), '--to', ['--transfer', '--transfer-list']);
+  check(given('--from'), '--from', ['--transfer-list']);
+  check(given('--status'), '--status', ['--transfer-list']);
+  check(given('--note'), '--note', ['--grant', '--transfer-revert']);
+  check(given('--name'), '--name', ['--create', '--search']);
+  check(given('--phone'), '--phone', ['--create', '--search']);
+  check(given('--dept'), '--dept', ['--grant', '--grants', '--search']);
+  check(given('--limit'), '--limit', ['--search']);
+  check(given('--offset'), '--offset', ['--search']);
+  check(on('--include-departed'), '--include-departed', ['--search']);
+  if (bad.length > 0) {
+    throw CliError.usage(`\`member ${picked}\` 不接受 ${bad.join(' / ')}`).withHint(
+      '跑 `xinhe-oa-cli schema member` 看每个动作的参数面',
+    );
+  }
+
+  const needUser = (verb) => {
+    const raw = val('--user');
+    const value = raw === null ? '' : String(raw);
+    if (value.trim().length === 0) {
+      throw CliError.usage(`\`member ${verb}\` 需要 --user <USER_ID>`).withHint(
+        '先看 user_id：xinhe-oa-cli member --list --json',
+      );
+    }
+    return value;
+  };
+  const needDept = (raw, verb) => {
+    const value = normalizeId(raw);
+    if (value === null) {
+      throw CliError.usage(`\`member ${verb}\` 需要 ${verb} <DEPT_ID>`).withHint(
+        '先看部门：xinhe-oa-cli org --tree --json',
+      );
+    }
+    return value;
+  };
+  const requiredId = (raw, what, example) => {
+    const value = normalizeId(raw);
+    if (value === null) {
+      throw CliError.usage(`\`member ${what}\` 需要 ${what} <ID>`).withHint(example);
+    }
+    return value;
+  };
+
+  // MEMBER-001：检索条件在这里**本地判一遍**（退出码 2、不发请求）。
+  // 服务端也判（它才是权威），本地判只是为了不让“拼错的检索”变成一次往返，
+  // 也让 `--dry-run` 不产生“看起来能跑”的假象。
+  const name = normalizeId(val('--name'));
+  const phone = normalizeId(val('--phone'));
+  const dept = normalizeId(val('--dept'));
+  if (picked === '--search') {
+    if (name === null && phone === null && dept === null) {
+      throw CliError.usage(
+        '`member --search` 至少要给一个条件：--name / --phone / --dept',
+      ).withHint('不带条件的列举用 `member --list`；只记得号码就用 `--phone <11 位号码>`');
+    }
+    if (name !== null) {
+      const size = charCount(name);
+      if (size < 2 || size > 32) {
+        throw CliError.usage(`\`--name\` 需要 2..=32 个字（当前 ${size} 个）`).withHint(
+          '单字会命中太多人；知道号码就用 `--phone` 精确查',
+        );
+      }
+    }
+    if (phone !== null && !isExactPhone(phone)) {
+      throw CliError.usage(`\`--phone\` 只支持精确号码（11 位）：${JSON.stringify(phone)}`).withHint(
+        '检索不做前缀 / 号段 / 模糊匹配；不确定号码就用 `--name` 或 `--dept`',
+      );
+    }
+  }
+
+  switch (picked) {
+    case '--list': {
+      // 刻意用**未去空白**的原值：Rust 这里就是 `self.user.clone()`，
+      // `--user ""` 会拼出 `/admin/users//roles`（保持逐字一致，不做“善意修正”）。
+      const raw = val('--user');
+      return { kind: 'list', user: raw === null ? null : String(raw) };
+    }
+    case '--search': {
+      // 分页在本地判范围：服务端 `Query(le=200)` 的 422 不该丢给调用方。
+      // 先按“无符号 32 位整数”解析（负数、小数、溢出都是 clap 的 `u32` 层面就拒的写法），
+      // 再判 1..=200 —— 这样 `--limit 0` 拿到的是 Rust 那句“必须在 1..=200 之间”。
+      const limit = intFlag(args, '--limit', { min: 0, max: U32_MAX });
+      if (limit !== null && (limit < 1 || limit > 200)) {
+        throw CliError.usage('`--limit` 必须在 1..=200 之间').withHint(
+          '缺省 20；翻页把响应里的 `next_offset` 喂给 `--offset`',
+        );
+      }
+      const offset = intFlag(args, '--offset', { min: 0, max: U32_MAX });
+      return { kind: 'search', name, phone, dept, limit, offset };
+    }
+    case '--create':
+      return { kind: 'create' };
+    case '--role':
+      return { kind: 'assign', role: String(val('--role')), user: needUser('--role') };
+    case '--revoke-role':
+      return {
+        kind: 'revoke-role',
+        role: String(val('--revoke-role')),
+        user: needUser('--revoke-role'),
+      };
+    case '--set-dept':
+      return {
+        kind: 'set-dept',
+        user: needUser('--set-dept'),
+        deptId: needDept(val('--set-dept'), '--set-dept'),
+        primary: on('--primary'),
+      };
+    case '--unset-dept':
+      return {
+        kind: 'unset-dept',
+        user: needUser('--unset-dept'),
+        deptId: needDept(val('--unset-dept'), '--unset-dept'),
+      };
+    case '--set-manager': {
+      const manager = normalizeId(val('--set-manager'));
+      if (manager === null) {
+        throw CliError.usage('`member --set-manager` 需要 --set-manager <USER_ID>').withHint(
+          '清空用：xinhe-oa-cli member --clear-manager --user <USER_ID>',
+        );
+      }
+      return { kind: 'set-manager', user: needUser('--set-manager'), manager };
+    }
+    case '--clear-manager':
+      return { kind: 'set-manager', user: needUser('--clear-manager'), manager: null };
+    case '--grant': {
+      // 主体二选一：人的授权带 user_id，部门的授权带 subject_type='dept' + subject_id。
+      // 互斥在这里判死 —— `--user` 与 `--dept` 同时给，服务端只会取一个，
+      // 而调用方以为自己两个都授了。
+      const subjectUser = normalizeId(val('--user'));
+      const subjectDept = normalizeId(val('--dept'));
+      if (subjectUser !== null && subjectDept !== null) {
+        throw CliError.usage('`member --grant` 的 --user 与 --dept 互斥（主体只能有一个）').withHint(
+          '给人的授权用 --user <USER_ID>；给部门的授权用 --dept <DEPT_ID>',
+        );
+      }
+      if (subjectUser === null && subjectDept === null) {
+        throw CliError.usage('`member --grant` 需要 --user 或 --dept 之一').withHint(
+          '给人的授权用 --user <USER_ID>；给部门的授权用 --dept <DEPT_ID>',
+        );
+      }
+      let deptScope = null;
+      const rawScope = normalizeId(val('--dept-scope'));
+      if (rawScope !== null) {
+        const action = normalizeId(val('--action'));
+        if (action === null) {
+          throw CliError.usage('`member --grant` 需要 --action <ACTION>').withHint(
+            '动作集与服务端一致：read / write / export / delete / ddl / grant …',
+          );
+        }
+        if (!DATA_ACTIONS.includes(action)) {
+          throw CliError.usage(
+            `--dept-scope 只对数据动作有意义（read / write / export / delete），${JSON.stringify(action)} 不是数据动作`,
+          ).withHint('部门档位是行范围，不是能力面：grant / ddl / admin:* 这类授权没有部门档位');
+        }
+        deptScope = parseDeptScope(
+          rawScope,
+          flagList(args, '--dept-id'),
+          on('--include-sub'),
+          on('--include-unassigned'),
+        );
+      }
+      return { kind: 'grant', subjectUser, subjectDept, deptScope };
+    }
+    case '--revoke-grant':
+      return {
+        kind: 'revoke-grant',
+        grantId: String(val('--revoke-grant') ?? ''),
+      };
+    case '--grants':
+      return { kind: 'grants', user: normalizeId(val('--user')), dept: normalizeId(val('--dept')) };
+    case '--offboard':
+      return {
+        kind: 'offboard',
+        user: requiredId(val('--offboard'), '--offboard', OFFBOARD_EXAMPLE),
+        transferTo: normalizeId(val('--transfer-to')),
+        scope: parseTransferScope(val('--scope')),
+        personal: parsePersonal(val('--personal')),
+        reason: normalizeId(val('--reason')),
+      };
+    case '--transfer':
+      return {
+        kind: 'transfer',
+        from: requiredId(val('--transfer'), '--transfer', TRANSFER_EXAMPLE),
+        to: requiredId(val('--to'), '--transfer --to', TRANSFER_EXAMPLE),
+        scope: parseTransferScope(val('--scope')),
+        reason: normalizeId(val('--reason')),
+      };
+    case '--transfer-list':
+      return {
+        kind: 'transfer-list',
+        from: normalizeId(val('--from')),
+        to: normalizeId(val('--to')),
+        status: parseTransferStatus(val('--status')),
+      };
+    case '--transfer-revert': {
+      const transferId = requiredId(
+        val('--transfer-revert'),
+        '--transfer-revert',
+        '例：xinhe-oa-cli member --transfer-revert xfr_01H --note 应移交给财务 --yes',
+      );
+      const note = val('--note') ?? '';
+      if (charCount(String(note).trim()) < 2) {
+        throw CliError.usage('`member --transfer-revert` 需要 --note（写进审计）').withHint(
+          `例：xinhe-oa-cli member --transfer-revert ${transferId} --note 应移交给财务 --yes`,
+        );
+      }
+      return { kind: 'transfer-revert', transferId, note: String(note) };
+    }
+    default:
+      return { kind: 'remove', user: String(val('--remove') ?? '') };
+  }
+}
+
+/** 0 个或多于 1 个动作都是用法错误（与 Rust `exactly_one` 同文案）。 */
+function exactlyOne(selected, what, hint) {
+  const picked = selected.filter(([, active]) => active).map(([name]) => name);
+  if (picked.length === 1) return picked[0];
+  if (picked.length === 0) {
+    throw CliError.usage(`\`${what}\` 必须给一个动作`).withHint(hint);
+  }
+  throw CliError.usage(
+    `\`${what}\` 一次只能给一个动作，收到 ${picked.length} 个：${picked.join(' / ')}`,
+  ).withHint(hint);
+}
+
+// ---------------------------------------------------------------------------
+// `member --list` / `--list --user <id>`
+// ---------------------------------------------------------------------------
+
+/**
+ * `member --list [--dept <DEPT_ID>]`：成员清单，并进部门归属 `departments`。
+ *
+ * 两个来源：`GET /admin/users`（人）+ `GET /org/members`（归属，login 能力）。
+ * `/org/members` 拿不到（比如后端还没升到 ORG-001）时**清单照出**，
+ * `departments` 落成空数组 —— 读清单不能被一张新表绑架。
+ */
+async function list(runtime, args) {
+  const orgQuery = listOrgQuery(args);
+  if (runtime.dryRun) {
+    // Rust 在这一处给的是**多请求清单**（`requests`），不是通用的单请求报告：
+    // 只打印第一个 GET 会让人以为“列举”只读一张表。
+    const requests = [
+      dryRunRequestOf(runtime, 'GET', '/admin/users', requestSpec()),
+      dryRunRequestOf(runtime, 'GET', '/org/members', requestSpec({ query: orgQuery })),
+    ];
+    runtime.finish({
+      dry_run: true,
+      requests,
+      note: '--dry-run：没有发出任何请求。真跑会读成员清单 + 部门归属两个 GET',
+    });
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', '/admin/users', requestSpec());
+  const data = dataOf(response);
+
+  // 部门归属：按 user_id 索引；这一段的任何失败都不该让清单读不出来。
+  const departmentsOf = new Map();
+  try {
+    const orgResponse = await runtime.sendAuthed(
+      'GET',
+      '/org/members',
+      requestSpec({ query: orgQuery }),
+    );
+    for (const item of asArray(pick(dataOf(orgResponse), 'items'))) {
+      const userId = pick(item, 'user_id');
+      if (typeof userId !== 'string') continue;
+      // 键在就是值（可能是 null —— 服务端说了“没有部门”与“字段缺失”不是一回事）。
+      departmentsOf.set(
+        userId,
+        isObject(item) && 'departments' in item ? item.departments : [],
+      );
+    }
+  } catch {
+    // 读清单不能被一张新表绑架（旧后端没有 /org/members）。
+  }
+
+  const members = asArray(pick(data, 'items')).map((item) => ({
+    user_id: pick(item, 'user_id'),
+    name: pick(item, 'name'),
+    status: pick(item, 'status'),
+    is_bootstrap: pick(item, 'is_bootstrap'),
+    identities: asArray(pick(item, 'identities')).map((row) => ({
+      identity_id: pick(row, 'id'),
+      phone_masked: pick(row, 'value_masked'),
+      tenant_id: pick(row, 'tenant_id'),
+      revoked_at: pick(row, 'revoked_at'),
+    })),
+    // ORG-001：[{dept_id, is_primary, title}]；“无部门”是合法状态（空数组）。
+    departments: departmentsOf.has(pick(item, 'user_id'))
+      ? departmentsOf.get(pick(item, 'user_id'))
+      : [],
+    grant_count: pick(item, 'grant_count'),
+    last_login_at: pick(item, 'last_login_at'),
+  }));
+  runtime.finishFrom(response, {
+    members,
+    // **不是**服务端的 total：服务端根本不给 total，这里的口径是“这一次拿到几条”。
+    total: members.length,
+    truncated: members.length >= LIST_PAGE_LIMIT,
+    note: pick(data, 'note'),
+    next_steps: [
+      'member --create --phone <号码> --name <姓名> --role tenant_member --tenant <企业>   建业务员',
+      'member --list --user <user_id>                                                    看某人的角色',
+      'member --search --name <姓名>                                                    按姓名/号码/部门检索（不受 500 条限制）',
+      'member --set-dept <DEPT_ID> --user <user_id>                                      把人挂进部门',
+    ],
+  });
+}
+
+/**
+ * `--list` 的部门过滤（`/org/members?dept_id=`）。
+ *
+ * MEMBER-001 起 `--list` 不再接受 `--dept`（上面已判死），所以这一段**恒为空** ——
+ * 保留它是为了与 Rust 的形状逐字一致（历史分支、以及将来若恢复过滤不必再改口径）。
+ */
+function listOrgQuery(args) {
+  const dept = normalizeId(flagValue(args, '--dept'));
+  return dept === null ? [] : [['dept_id', dept]];
+}
+
+/** `member --list --user <id>`：看某人的角色与展开后的授权（原样透传服务端数据）。 */
+async function rolesOf(runtime, userId) {
+  const response = await runtime.sendAuthed(
+    'GET',
+    `/admin/users/${userId}/roles`,
+    requestSpec(),
+  );
+  runtime.finishFrom(response, dataOf(response));
+}
+
+// ---------------------------------------------------------------------------
+// `member --search`（MEMBER-001 / issue #99）
+// ---------------------------------------------------------------------------
+
+/**
+ * 按姓名 / 精确手机号 / 部门检索成员。
+ *
+ * 服务端已经把每行装配成与 `--list` 同形的成员对象（含脱敏号与部门），**原样透传** ——
+ * 在客户端再拼一次只会多一处漂移点。条件的合法性在 `memberAction()` 里已判。
+ */
+async function search(runtime, args, action) {
+  const spec = requestSpec({
+    query: queryPairs([
+      ['name', action.name],
+      ['phone', action.phone],
+      ['dept_id', action.dept],
+      ['tenant', normalizeId(flagValue(args, '--tenant'))],
+      ['include_departed', flagOn(args, '--include-departed') ? 'true' : null],
+      ['limit', action.limit],
+      ['offset', action.offset],
+    ]),
+  });
+  if (runtime.dryRun) return dryRunReport(runtime, 'GET', '/admin/users/search', spec);
+  const response = await runtime.sendAuthed('GET', '/admin/users/search', spec);
+  const data = dataOf(response);
+  const duplicate = pick(data, 'duplicate_name') === true;
+  const nextSteps = [
+    '看某人的角色与授权：member --list --user <user_id>',
+    '翻页：把响应里的 next_offset 喂给 --offset',
+  ];
+  if (duplicate) {
+    nextSteps.push(
+      '同名多人：用 --dept <DEPT_ID> 或 --phone <11 位号码> 收窄（每行的 phone_masked 是脱敏号）',
+    );
+  }
+  runtime.finishFrom(response, {
+    members: asArray(pick(data, 'items')),
+    total: pick(data, 'total'),
+    count: pick(data, 'count'),
+    limit: pick(data, 'limit'),
+    offset: pick(data, 'offset'),
+    has_more: pick(data, 'has_more'),
+    next_offset: pick(data, 'next_offset'),
+    matched_by: pick(data, 'matched_by'),
+    duplicate_name: duplicate,
+    order: pick(data, 'order'),
+    scope_tenants: pick(data, 'scope_tenants'),
+    note: pick(data, 'note'),
+    next_steps: nextSteps,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// `--create` / `--role` / `--revoke-role` / `--remove`
+// ---------------------------------------------------------------------------
+
+/** 角色名单校验：不认识的角色本地判死（服务端 `ROLE_TEMPLATES` 是权威，但没必要往返一次）。 */
+function checkRole(role) {
+  if (!ROLES.includes(role)) {
+    throw CliError.usage(`不认识的角色 ${JSON.stringify(role)}`).withHint(
+      `角色只能是：${ROLES.join(' / ')}`,
+    );
+  }
+}
+
+/** 赋角的请求体（`--create` 与 `--role` 共用）。 */
+function roleBody(role, tenant, store, reason) {
+  return {
+    role,
+    // 没有企业只对 super_admin / investor 合理（服务端会再判一次）。
+    tenants: tenant === null || tenant === undefined ? ['*'] : [tenant],
+    store_id: store ?? null,
+    reason,
+  };
+}
+
+/**
+ * `member --create`：两步（加白名单 → 赋角），中途失败时**如实报告已经落了哪一步**。
+ *
+ * 不假装原子：人已经建出来、角没赋上时，报错里带 `identity_created: true` 与 `user_id`，
+ * 并给出补赋的那条命令 —— 否则调用方会以为“没建成”而重试，撞上 dup 白名单。
+ */
+async function create(runtime, args) {
+  const phone = flagValue(args, '--phone');
+  if (phone === null) {
+    throw CliError.usage('`member --create` 需要 --phone <手机号>').withHint(
+      '例：xinhe-oa-cli member --create --phone 13800000001 --name 小唐 --role tenant_member --tenant kashu',
+    );
+  }
+  const role = flagValue(args, '--role');
+  if (role === null) {
+    throw CliError.usage('`member --create` 需要 --role <角色>').withHint(
+      `角色只能是：${ROLES.join(' / ')}`,
+    );
+  }
+  checkRole(role);
+
+  // 企业：显式 --tenant > 你的唯一可见企业。super_admin 可以不点名企业。
+  // 注意：这一步在 `--dry-run` 里**也会发 GET /me**（Rust 就是先解析企业、再看 dry-run）——
+  // 保持逐字一致，而不是“顺手让它一条请求都不发”。
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'));
+  if (['tenant_member', 'tenant_owner', 'tenant_operator'].includes(role) && tenant === null) {
+    throw CliError.usage(`赋 ${role} 必须指明企业`).withHint(
+      '加 --tenant <TENANT_ID>；用 `xinhe-oa-cli tenant --list` 看有哪些企业',
+    );
+  }
+  const reason = flagValue(args, '--reason') ?? `member --create：建人并赋角 ${role}`;
+
+  // ① 加白名单（顺带建人）
+  const identitySpec = requestSpec({
+    body: { phone, name: flagValue(args, '--name'), tenant_id: tenant, note: reason },
+  });
+  const roleSpec = requestSpec({
+    body: roleBody(role, tenant, flagValue(args, '--store'), reason),
+  });
+  if (runtime.dryRun) {
+    dryRunReport(runtime, 'POST', '/admin/identities', identitySpec);
+    warn('（第二步会接着给这个人赋角）');
+    return dryRunReport(runtime, 'POST', '/admin/users/{user_id}/roles', roleSpec);
+  }
+  const identityResponse = await runtime.sendAuthed('POST', '/admin/identities', identitySpec);
+  const identity = dataOf(identityResponse);
+  const userId = pick(identity, 'user_id');
+  if (typeof userId !== 'string') {
+    throw new CliError(
+      Kind.Server,
+      'cli.bad_response',
+      '服务端没有回 user_id（建人失败？）',
+    ).withRequestId(identityResponse.request_id ?? null);
+  }
+
+  // ② 赋角
+  const path = `/admin/users/${userId}/roles`;
+  let roleResponse;
+  try {
+    roleResponse = await runtime.sendAuthed('POST', path, roleSpec);
+  } catch (err) {
+    // 人已经建出来了、角没赋上：如实说清，并给出补赋的那条命令。
+    const tenantFlag = tenant === null ? '' : ` --tenant ${tenant}`;
+    if (err instanceof CliError) {
+      err.details = {
+        identity_created: true,
+        identity_id: pick(identity, 'identity_id'),
+        user_id: userId,
+        server_details: err.details,
+      };
+      err.hint = `人已经建好了（user_id=${userId}），只是角色没赋上；补赋：xinhe-oa-cli member --role ${role} --user ${userId}${tenantFlag}`;
+      throw err;
+    }
+    throw err;
+  }
+  const assigned = dataOf(roleResponse);
+  runtime.finishFrom(roleResponse, {
+    user_id: userId,
+    identity_id: pick(identity, 'identity_id'),
+    phone_masked: pick(identity, 'phone_masked'),
+    created_user: pick(identity, 'created_user'),
+    tenant,
+    role,
+    grants: pick(assigned, 'grants'),
+    actions: pick(assigned, 'actions'),
+    // 这里刻意给**完整号码**：`--phone` 是调用方自己敲进来的，而下一步
+    // （让本人用短信登录）必须能原样照抄。日志与错误里仍然只有脱敏值。
+    next_step: `让这个人自己登录：xinhe-oa-cli login --phone ${phone}（收到验证码后再 --code <码>）`,
+  });
+}
+
+/** `member --role <ROLE> --user <id>`：给已有成员赋角（响应原样透传）。 */
+async function assign(runtime, args, role, userId) {
+  checkRole(role);
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'));
+  const reason = flagValue(args, '--reason') ?? `member --role：赋角 ${role}`;
+  const spec = requestSpec({
+    body: roleBody(role, tenant, flagValue(args, '--store'), reason),
+  });
+  const path = `/admin/users/${userId}/roles`;
+  if (runtime.dryRun) return dryRunReport(runtime, 'POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * `member --revoke-role <ROLE> --user <id> --reason <TEXT>`：撤角。
+ *
+ * `--reason` 必填（>=2 字，写进审计）—— 撤权不留原因，事后没人说得清是谁为什么撤的。
+ * 撤角**默认连带吊销该人的会话链**（服务端口径），所以 `result` 是原样透传的。
+ */
+async function revokeRole(runtime, args, role, userId) {
+  const reason = flagValue(args, '--reason') ?? '';
+  if (charCount(String(reason).trim()) < 2) {
+    throw CliError.usage('撤角必须给 --reason（写进审计）').withHint(
+      `例：xinhe-oa-cli member --revoke-role ${role} --user ${userId} --reason 离职`,
+    );
+  }
+  // `--tenant` 是**只撤这家企业的**那一个角色；这里照 Rust 用原值（不 trim）。
+  const tenant = flagValue(args, '--tenant');
+  const query = [['reason', String(reason)]];
+  if (tenant !== null) query.push(['tenant_id', String(tenant)]);
+  const spec = requestSpec({ query });
+  const path = `/admin/users/${userId}/roles/${role}`;
+  if (runtime.dryRun) return dryRunReport(runtime, 'DELETE', path, spec);
+  const response = await runtime.sendAuthed('DELETE', path, spec);
+  runtime.finishFrom(response, {
+    user_id: userId,
+    role,
+    result: dataOf(response),
+    note: '撤角默认连带吊销该人的会话链（服务端口径）',
+  });
+}
+
+/**
+ * `member --remove <USER_ID> --reason <TEXT>`：撤销白名单号码（移除成员）。
+ *
+ * 一个人可能有多条**未撤销**的白名单身份（多企业 / 换号），所以要先把它们全找出来
+ * 再逐条撤：只撤第一条会留下一个还能 OTP 登录的入口 —— 而调用方以为人已经移除了。
+ */
+async function removeMember(runtime, userId, args) {
+  const reason = flagValue(args, '--reason') ?? '';
+  if (charCount(String(reason).trim()) < 2) {
+    throw CliError.usage('`member --remove` 需要 --reason（写进审计）').withHint(
+      '例：xinhe-oa-cli member --remove usr_123 --reason 离职',
+    );
+  }
+  const response = await runtime.sendAuthed('GET', '/admin/users', requestSpec());
+  const item = asArray(pick(dataOf(response), 'items')).find(
+    (row) => pick(row, 'user_id') === userId,
+  );
+  const identities = asArray(item === undefined ? null : pick(item, 'identities')).filter((row) => {
+    // `revoked_at` 缺失也算“未撤销”（老后端不带这个字段）。
+    const revokedAt = pick(row, 'revoked_at');
+    return revokedAt === null;
+  });
+  if (identities.length === 0) {
+    throw CliError.usage(`${userId} 名下没有可撤销的白名单身份`)
+      .withDetails({ user_id: userId })
+      .withHint('用 `xinhe-oa-cli member --list --json` 核对 user_id');
+  }
+
+  const revoked = [];
+  for (const identity of identities) {
+    const identityId = pick(identity, 'id');
+    if (typeof identityId !== 'string') continue;
+    const spec = requestSpec({ query: [['reason', String(reason)]] });
+    const path = `/admin/identities/${identityId}`;
+    if (runtime.dryRun) {
+      dryRunReport(runtime, 'DELETE', path, spec);
+      continue;
+    }
+    const deleted = await runtime.sendAuthed('DELETE', path, spec);
+    revoked.push({ identity_id: identityId, result: dataOf(deleted) });
+  }
+  if (runtime.dryRun) return;
+  // 多请求命令：request_id 取不到单一个，这里刻意给 null（与 Rust 的 finish(out, None, None) 一致）。
+  runtime.finish({
+    user_id: userId,
+    revoked,
+    next_step:
+      '撤销白名单后该号码不能再走 OTP 登录；用 `member --list --user <id>` 复核他剩下的授权',
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 部门归属（ORG-001）：set-dept / unset-dept / set-manager
+// ---------------------------------------------------------------------------
+
+/**
+ * `member --set-dept <DEPT_ID> --user <id> [--primary] [--title] [--tenant <t>]`。
+ *
+ * 首个部门自动为主部门（不带 `--primary` 也是）；已有部门时 `--primary`
+ * 显式切主部门（旧主部门自动降级，同一事务内完成）。
+ */
+async function setDept(runtime, args, userId, deptId, primary) {
+  const body = { dept_id: deptId };
+  if (primary) body.primary = true;
+  const title = normalizeId(flagValue(args, '--title'));
+  if (title !== null) body.title = title;
+  const tenant = normalizeId(flagValue(args, '--tenant'));
+  if (tenant !== null) body.tenant = tenant;
+  const path = `/org/members/${userId}/dept`;
+  const spec = requestSpec({ body, idempotencyKey: idempotencyKey('member-set-dept') });
+  if (runtime.dryRun) return dryRunReport(runtime, 'POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  const data = dataOf(response);
+  if (isObject(data)) {
+    data.note = '一个人可以同时在多个部门（is_primary 只有一个）；撤主部门前要先切新主部门';
+  }
+  runtime.finishFrom(response, data);
+}
+
+/**
+ * `member --unset-dept <DEPT_ID> --user <id> [--tenant <t>]`。
+ *
+ * 撤的是主部门且还有别的部门时，服务端拒绝并要求先显式切主部门
+ * （`primary_requires_explicit_new_primary`，details 给 other_dept_ids）——
+ * CLI 不替人选新主部门，原样把服务端的 409 交给调用方。
+ * 撤到最后一个部门是允许的：“无部门”是合法状态（在职真相在 `user.status`）。
+ */
+async function unsetDept(runtime, args, userId, deptId) {
+  const body = { dept_id: deptId };
+  const tenant = normalizeId(flagValue(args, '--tenant'));
+  if (tenant !== null) body.tenant = tenant;
+  const path = `/org/members/${userId}/dept/unset`;
+  const spec = requestSpec({ body, idempotencyKey: idempotencyKey('member-unset-dept') });
+  if (runtime.dryRun) return dryRunReport(runtime, 'POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * `member --set-manager <USER_ID> --user <id>` / `--clear-manager --user <id>`。
+ *
+ * 直属上级写在**主部门行**上（没有主部门就没有“在哪条线上汇报”）；
+ * 清空时显式发 `manager_user_id: null` —— 服务端据此区分“清空”与“没给这个键”。
+ */
+async function setManager(runtime, args, userId, manager) {
+  const body = { manager_user_id: manager === null ? null : manager };
+  const tenant = normalizeId(flagValue(args, '--tenant'));
+  if (tenant !== null) body.tenant = tenant;
+  const path = `/org/members/${userId}/manager`;
+  const spec = requestSpec({ body, idempotencyKey: idempotencyKey('member-set-manager') });
+  if (runtime.dryRun) return dryRunReport(runtime, 'POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+// ---------------------------------------------------------------------------
+// ORG-002：授权主体多态（给人 / 给部门授权、按 id 收权、列授权）
+// ---------------------------------------------------------------------------
+
+/**
+ * 把 `--resource <type:id>` 拆成服务端的 `resource_type` / `resource_id`。
+ *
+ * 只按**第一个** `:` 拆：Base 表的 id 自带 `base.<bk>.<tk>` 形态（正好两段点号，
+ * 不含冒号），所以 `table:base.contracts.contract` 是 type=table、
+ * id=base.contracts.contract。`--dataset <d>` 是等价简写（type 恒为 dataset）。
+ */
+function splitResource(resource) {
+  const index = String(resource).indexOf(':');
+  if (index < 0) {
+    throw CliError.usage(
+      `--resource 需要是 <type>:<id> 形态，拿到 ${JSON.stringify(resource)}`,
+    ).withHint('例：--resource table:base.contracts.contract（type:id，只按第一个冒号拆）');
+  }
+  const kind = String(resource).slice(0, index).trim();
+  const id = String(resource).slice(index + 1).trim();
+  if (kind.length === 0 || id.length === 0) {
+    throw CliError.usage(
+      `--resource 需要是 <type>:<id> 形态，拿到 ${JSON.stringify(resource)}`,
+    );
+  }
+  return [kind, id];
+}
+
+/** `member --grant`：授一条资源授权（人主体 / 部门主体二选一，已在上层判死）。 */
+async function grant(runtime, args, action) {
+  const resource = flagValue(args, '--resource');
+  const dataset = flagValue(args, '--dataset');
+  let resourceType;
+  let resourceId;
+  if (resource !== null) {
+    if (dataset !== null) {
+      throw CliError.usage('--resource 与 --dataset 只能给一个');
+    }
+    [resourceType, resourceId] = splitResource(resource);
+  } else if (dataset !== null) {
+    resourceType = 'dataset';
+    resourceId = String(dataset).trim();
+  } else {
+    throw CliError.usage('`member --grant` 需要 --resource <TYPE:ID>（或 --dataset <数据集>）').withHint(
+      '例：--resource table:base.contracts.contract --action read',
+    );
+  }
+  const actionName = flagValue(args, '--action');
+  if (actionName === null) {
+    throw CliError.usage('`member --grant` 需要 --action <ACTION>').withHint(
+      '动作集与服务端一致：read / write / export / ddl / grant …',
+    );
+  }
+
+  // `--yes` 闸门（契约 §2：`--grant` 是 high-risk-write）。
+  //
+  // 位置刻意放在**本地校验之后、发请求之前**：这样"参数写错了"仍然先报参数错
+  // （与 Rust 的校验顺序一致），而"参数都对、只是没确认"才落到这里。
+  // `--dry-run` 不卡：那一条不落任何写（与 `--offboard --dry-run` 同一个道理）。
+  if (!runtime.dryRun) {
+    runtime.requireYes(
+      'member --grant（给一个人或一个部门加一条资源授权）',
+      'xinhe-oa-cli member --grant --user <USER_ID> --resource <TYPE:ID> --action <ACTION> --yes',
+    );
+  }
+
+  const body = {
+    resource_type: resourceType,
+    resource_id: resourceId,
+    action: actionName,
+    note: flagValue(args, '--note'),
+    expires_at: flagValue(args, '--expires-at'),
+  };
+  const tenant = flagValue(args, '--tenant');
+  if (action.subjectDept === null) {
+    // 人的授权带 `user_id`（与旧路径逐字一致），多一个键都会让老后端困惑。
+    body.user_id = action.subjectUser;
+    if (tenant !== null) body.tenant_id = tenant;
+  } else {
+    // 部门主体授权必须落企业：缺省让服务端按“你的唯一可见企业”收敛。
+    body.subject_type = 'dept';
+    body.subject_id = action.subjectDept;
+    if (tenant !== null) body.tenant_id = tenant;
+  }
+  const store = flagValue(args, '--store');
+  if (store !== null) body.store_id = store;
+  // ORG-003：部门档位只在 `--dept-scope` 给了的时候才出现（不给 = 请求体里
+  // 没有 `dept_scope` 键，行为与今天逐字不变：部门维度不限）。
+  if (action.deptScope !== null) {
+    body.dept_scope = {
+      declaration: action.deptScope.declaration,
+      dept_ids: action.deptScope.deptIds,
+      include_sub: action.deptScope.includeSub,
+      include_unassigned: action.deptScope.includeUnassigned,
+    };
+  }
+  const spec = requestSpec({ body, idempotencyKey: idempotencyKey('member-grant') });
+  if (runtime.dryRun) return dryRunReport(runtime, 'POST', '/admin/grants', spec);
+  const response = await runtime.sendAuthed('POST', '/admin/grants', spec);
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    grant_id: pick(data, 'grant_id'),
+    subject_type: pick(data, 'subject_type'),
+    subject_id: pick(data, 'subject_id'),
+    user_id: pick(data, 'user_id'),
+    resource_type: pick(data, 'resource_type'),
+    resource_id: pick(data, 'resource_id'),
+    action: pick(data, 'action'),
+    scope: pick(data, 'scope'),
+    note: 'high-risk-write 已执行；重复提交同一幂等键不会叠加（服务端幂等）',
+  });
+}
+
+/** `member --revoke-grant <GRANT_ID> --reason <TEXT>`：按 id 收权（人 / 部门同一条路径）。 */
+async function revokeGrant(runtime, args, grantId) {
+  const reason = flagValue(args, '--reason') ?? '';
+  if (charCount(String(reason).trim()) < 2) {
+    throw CliError.usage('`member --revoke-grant` 需要 --reason（写进审计）').withHint(
+      `例：xinhe-oa-cli member --revoke-grant ${grantId} --reason 调整权限`,
+    );
+  }
+  // `--yes` 闸门（契约 §2：`--revoke-grant` 是 high-risk-write）。
+  // 与 `--grant` 同口径：参数错先报参数错，真跑才要确认，`--dry-run` 不卡。
+  if (!runtime.dryRun) {
+    runtime.requireYes(
+      'member --revoke-grant（按 id 收权，人的与部门的走同一条路径）',
+      `xinhe-oa-cli member --revoke-grant ${grantId} --reason <原因> --yes`,
+    );
+  }
+  const spec = requestSpec({ body: { grant_id: grantId, reason: String(reason) } });
+  if (runtime.dryRun) return dryRunReport(runtime, 'POST', '/admin/grants/revoke', spec);
+  const response = await runtime.sendAuthed('POST', '/admin/grants/revoke', spec);
+  runtime.finishFrom(response, {
+    grant_id: grantId,
+    result: dataOf(response),
+    note: '按 id 收权；部门主体与人主体走同一条路径，权限下一请求即失效',
+  });
+}
+
+/** `member --grants [--user <id>] [--dept <id>] [--tenant <t>]`：列有效授权。 */
+async function listGrants(runtime, args, user, dept) {
+  const query = [];
+  if (user !== null) query.push(['user_id', user]);
+  if (dept !== null) {
+    // `--dept` 只列该部门主体的行（subject_type=dept + subject_id）。
+    query.push(['subject_type', 'dept']);
+    query.push(['subject_id', dept]);
+  }
+  // 照 Rust 用原值（`--tenant` 是筛选词，空串在这里等于“不筛”，交给服务端判）。
+  const tenant = flagValue(args, '--tenant');
+  if (tenant !== null) query.push(['tenant_id', String(tenant)]);
+  const spec = requestSpec({ query });
+  if (runtime.dryRun) return dryRunReport(runtime, 'GET', '/admin/grants', spec);
+  const response = await runtime.sendAuthed('GET', '/admin/grants', spec);
+  const data = dataOf(response);
+  const grants = asArray(pick(data, 'items')).map((item) => ({
+    grant_id: pick(item, 'id'),
+    subject_type: pick(item, 'subject_type'),
+    subject_id: pick(item, 'subject_id'),
+    user_id: pick(item, 'user_id'),
+    scope: pick(item, 'scope'),
+    resource_type: pick(item, 'resource_type'),
+    resource_id: pick(item, 'resource_id'),
+    action: pick(item, 'action'),
+    expires_at: pick(item, 'expires_at'),
+    revoked_at: pick(item, 'revoked_at'),
+  }));
+  runtime.finishFrom(response, {
+    grants,
+    // 服务端的 `count` 才是“符合条件的总数”（本页条数不是总数）。
+    total: pick(data, 'count'),
+    note: pick(data, 'note'),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// ORG-004：离职 / 移交
+// ---------------------------------------------------------------------------
+
+/** `--reason` 缺失或太短（<2 字）的用法错误（退出码 2）。 */
+function reasonUsage(verb, example) {
+  return CliError.usage(`\`member ${verb}\` 需要 --reason（写进审计）`).withHint(`例：${example}`);
+}
+
+/** 真跑必填的 `--reason`（去空白后 >=2 字）。 */
+function requiredReason(raw, verb, example) {
+  const value = normalizeId(raw);
+  if (value === null || charCount(value) < 2) throw reasonUsage(verb, example);
+  return value;
+}
+
+/**
+ * `member --offboard <USER_ID> [--tenant <t>] [--transfer-to <u>] [--scope ...]
+ * [--personal ...] --reason <TEXT> [--dry-run] --yes`。
+ *
+ * **一次事务**完成 状态 / 会话 / 身份 / 部门归属 / 移交（原子性在服务端）。
+ * `--dry-run` 走**同一个端点**（`?dry_run=true`）：服务端回同一形状的预演
+ * （`status: "preview"`、各类 `*_revoked: 0`、`transfer.status: "pending"`），
+ * **库里一行都不变** —— 所以它不需要 `--yes`（这一条的风险级别是 `read`，
+ * 契约 §2.1.4 的风险表把它单独列了一行）。
+ *
+ * 同理，`--reason` 在预演里可以不给：预演不写审计，逼人先编一个原因才能看代价，
+ * 只会让“先看看会发生什么”这件事变得昂贵。但**给了就必须合格**（>=2 字）——
+ * 半截原因在预演里被放行、真跑时被拒，那种不一致比直接报错更伤人。
+ */
+async function offboard(runtime, args, action) {
+  const dryRun = runtime.dryRun;
+  if (!dryRun) {
+    runtime.requireYes(
+      'member --offboard（一次可能改几十个对象的归属并停用一个人的登录）',
+      `xinhe-oa-cli member --offboard ${action.user} --reason "离职交接" --yes`,
+    );
+  }
+  let reason;
+  if (dryRun) {
+    if (action.reason === null) {
+      reason = null;
+    } else if (charCount(action.reason) >= 2) {
+      reason = action.reason;
+    } else {
+      throw reasonUsage('--offboard', OFFBOARD_EXAMPLE);
+    }
+  } else {
+    reason = requiredReason(action.reason, '--offboard', OFFBOARD_EXAMPLE);
+  }
+  const spec = requestSpec({
+    query: [['dry_run', dryRun ? 'true' : 'false']],
+    body: {
+      tenant: normalizeId(flagValue(args, '--tenant')),
+      transfer_to: action.transferTo,
+      // `--scope` 的缺省已在本地补成 all、`--personal` 补成 transfer：
+      // **永远显式带上这两个键**，免得服务端与 CLI 各有一套缺省。
+      scope: action.scope,
+      personal: action.personal,
+      reason,
+    },
+    // 真跑的请求带幂等键；dry-run 不带（它不写、也不该占幂等口径）。
+    idempotencyKey: dryRun ? null : idempotencyKey('member-offboard'),
+  });
+  const path = `/admin/members/${action.user}/offboard`;
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * `member --transfer <FROM_USER_ID> --to <USER_ID> [--tenant <t>] [--scope ...]
+ * --reason <TEXT> --yes`：独立移交（不离职）。
+ *
+ * 同一 `(from_user_id, scope, status='pending')` 重复发起 → 服务端回
+ * `deduped: true` 且**不产生第二批**（退出码 0）；CLI 把它显式标出来 ——
+ * 否则调用方看到第二次也“成功”，会以为自己发起了两批。
+ */
+async function transfer(runtime, args, action) {
+  runtime.requireYes(
+    'member --transfer（改的是归属，比权限更难挽回）',
+    `xinhe-oa-cli member --transfer ${action.from} --to ${action.to} --reason "岗位调整" --yes`,
+  );
+  // `--dry-run` 也要 `--reason`：预演的是**这次移交**，没有原因就没有可读的预演结果。
+  const reason = requiredReason(action.reason, '--transfer', TRANSFER_EXAMPLE);
+  const spec = requestSpec({
+    body: {
+      tenant: normalizeId(flagValue(args, '--tenant')),
+      from_user_id: action.from,
+      to_user_id: action.to,
+      scope: action.scope,
+      reason,
+    },
+    idempotencyKey: idempotencyKey('member-transfer'),
+  });
+  if (runtime.dryRun) return dryRunReport(runtime, 'POST', '/admin/transfers', spec);
+  const response = await runtime.sendAuthed('POST', '/admin/transfers', spec);
+  const out = dataOf(response);
+  if (isObject(out)) {
+    out.note =
+      out.deduped === true
+        ? '同一 (from_user_id, scope, status=pending) 已有待办移交：本次没有产生第二批（deduped: true）'
+        : '移交只改 owner_user_id：新所有者因此获得 can_manage 与 private 档可见性；文件上已有的 ACL 一条不动';
+  }
+  runtime.finishFrom(response, out);
+}
+
+/** `member --transfer-list [--from <u>] [--to <u>] [--status ...] [--tenant <t>]`（读）。 */
+async function transferList(runtime, args, action) {
+  const tenant = normalizeId(flagValue(args, '--tenant'));
+  const spec = requestSpec({
+    query: queryPairs([
+      ['from_user_id', action.from],
+      ['to_user_id', action.to],
+      ['status', action.status],
+      ['tenant_id', tenant],
+    ]),
+  });
+  if (runtime.dryRun) return dryRunReport(runtime, 'GET', '/admin/transfers', spec);
+  const response = await runtime.sendAuthed('GET', '/admin/transfers', spec);
+  const data = dataOf(response);
+  const items = asArray(hasKey(data, 'transfers') ? data.transfers : pick(data, 'items'));
+  // `transfers` / `total` 的**回退顺序**照抄 Rust 的 `Option::or_else`：
+  // 键存在但值为 null 时**不**回退到 `count`（只回退“键不存在”那种情况）。
+  const total = hasKey(data, 'total')
+    ? pick(data, 'total')
+    : hasKey(data, 'count')
+      ? pick(data, 'count')
+      : items.length;
+  runtime.finishFrom(response, {
+    transfers: items,
+    total,
+    filter: {
+      from_user_id: action.from,
+      to_user_id: action.to,
+      status: action.status,
+      // 照 Rust 用**原值**回显筛选（与 query 里那个 trim 过的值不是同一个来源）。
+      tenant_id: flagValue(args, '--tenant'),
+    },
+    note: pick(data, 'note'),
+  });
+}
+
+/**
+ * `member --transfer-revert <TRANSFER_ID> --note <TEXT> [--tenant <t>] --yes`。
+ *
+ * 只改**仍指向 `to_user_id`** 的行；对象在移交后又被转手的逐条跳过
+ * （`skipped[].reason = owner_changed_since_transfer`）。第二次 revert 服务端回
+ * 409 —— 由通用错误映射归到退出码 5，CLI 不做静默成功。
+ */
+async function transferRevert(runtime, args, transferId, note) {
+  runtime.requireYes(
+    'member --transfer-revert（把一批对象的归属改回去；已再次转手的逐条跳过）',
+    `xinhe-oa-cli member --transfer-revert ${transferId} --note "应移交给财务" --yes`,
+  );
+  const spec = requestSpec({
+    body: { note, tenant: normalizeId(flagValue(args, '--tenant')) },
+    idempotencyKey: idempotencyKey('member-transfer-revert'),
+  });
+  const path = `/admin/transfers/${transferId}/revert`;
+  if (runtime.dryRun) return dryRunReport(runtime, 'POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+// ---------------------------------------------------------------------------
+// 小工具（与 Rust 侧的语义逐条对齐）
+// ---------------------------------------------------------------------------
+
+/**
+ * 企业缺省值：显式 `--tenant` > 你的唯一可见企业（`GET /me` 的 `scope.tenants`）。
+ *
+ * 多个可见企业时**不猜**（猜错就是给别家企业建人 / 赋角），直接退出码 2
+ * 并把候选列进 `details.visible_tenants` —— 让调用方能照抄一个 `--tenant`。
+ */
+async function resolveTenant(runtime, requested) {
+  const explicit = normalizeId(requested);
+  if (explicit !== null) return explicit;
+  const response = await runtime.sendAuthed('GET', '/me', requestSpec());
+  const tenants = asArray(pick(pick(dataOf(response), 'scope'), 'tenants'));
+  if (tenants.length === 1) return pick(tenants[0], 'id');
+  if (tenants.length === 0) return null;
+  throw CliError.usage('你有多个可见企业，请用 --tenant <TENANT_ID> 指明').withDetails({
+    visible_tenants: tenants,
+    hint: 'xinhe-oa-cli tenant --list',
+  });
+}
+
+/**
+ * 解析 `--dept-scope`（大小写不敏感；`CUSTOM` → 服务端 `CUSTOM_DEPTS`）。
+ *
+ * `CUSTOM` 没有 `--dept-id` 是**用法错误**（退出码 2、不发请求）：服务端对
+ * “声明 CUSTOM_DEPTS 但没给 ID”回 400，而客户端完全能提前看出来 ——
+ * 一次注定失败的往返不该发生（契约 §2 把这条钉成了本地判定）。
+ */
+function parseDeptScope(raw, deptIds, includeSub, includeUnassigned) {
+  // 只做大写化，且只认 ASCII（对齐 Rust `to_ascii_uppercase`：
+  // 非 ASCII 字符的“大写”在各语言里语义不同，不能拿 JS 的 toUpperCase 顶替）。
+  const upper = String(raw).trim().replace(/[a-z]/g, (ch) => ch.toUpperCase());
+  let declaration;
+  if (upper === 'ALL') declaration = 'ALL';
+  else if (upper === 'DEPT') declaration = 'DEPT';
+  else if (upper === 'DEPT_AND_SUB') declaration = 'DEPT_AND_SUB';
+  else if (upper === 'CUSTOM' || upper === 'CUSTOM_DEPTS') declaration = 'CUSTOM_DEPTS';
+  else {
+    throw CliError.usage(`不认识的 --dept-scope ${JSON.stringify(upper)}`).withHint(
+      '档位只有：ALL / DEPT / DEPT_AND_SUB / CUSTOM',
+    );
+  }
+  const ids = deptIds.map((value) => String(value).trim()).filter((value) => value.length > 0);
+  if (declaration === 'CUSTOM_DEPTS' && ids.length === 0) {
+    throw CliError.usage('`--dept-scope CUSTOM` 至少需要一个 --dept-id <DEPT_ID>').withHint(
+      '例：--dept-scope CUSTOM --dept-id ou_1 --dept-id ou_2',
+    );
+  }
+  return { declaration, deptIds: ids, includeSub, includeUnassigned };
+}
+
+/** ORG-004：`--scope` 的枚举（缺省 `all`）。 */
+function parseTransferScope(raw) {
+  const value = normalizeId(raw) ?? 'all';
+  // 只折 ASCII（对齐 Rust `to_ascii_lowercase`）：非 ASCII 的“小写”各语言语义不同。
+  const lowered = value.replace(/[A-Z]/g, (ch) => ch.toLowerCase());
+  if (lowered === 'attachment' || lowered === 'skill' || lowered === 'all') return lowered;
+  throw CliError.usage(`不认识的 --scope ${JSON.stringify(lowered)}`).withHint(
+    '范围只有：attachment / skill / all（缺省 all）',
+  );
+}
+
+/** ORG-004：`--personal` 的枚举（缺省 `transfer`；`keep` 是**显式**选项）。 */
+function parsePersonal(raw) {
+  const value = normalizeId(raw) ?? 'transfer';
+  // 只折 ASCII（对齐 Rust `to_ascii_lowercase`）：非 ASCII 的“小写”各语言语义不同。
+  const lowered = value.replace(/[A-Z]/g, (ch) => ch.toLowerCase());
+  if (lowered === 'keep' || lowered === 'transfer') return lowered;
+  throw CliError.usage(`不认识的 --personal ${JSON.stringify(lowered)}`).withHint(
+    '个人文件处置只有：keep / transfer（缺省 transfer）',
+  );
+}
+
+/** ORG-004：`--transfer-list --status` 的枚举（缺省 = 不过滤）。 */
+function parseTransferStatus(raw) {
+  const value = normalizeId(raw);
+  if (value === null) return null;
+  // 只折 ASCII（对齐 Rust `to_ascii_lowercase`）：非 ASCII 的“小写”各语言语义不同。
+  const lowered = value.replace(/[A-Z]/g, (ch) => ch.toLowerCase());
+  if (['pending', 'applied', 'reverted', 'cancelled'].includes(lowered)) return lowered;
+  throw CliError.usage(`不认识的 --status ${JSON.stringify(lowered)}`).withHint(
+    '移交状态只有：pending / applied / reverted / cancelled（缺省不过滤）',
+  );
+}
+
+/** 去空白后为空一律当“没给”（空串不是筛选条件，也不是目标）。 */
+function normalizeId(raw) {
+  if (raw === null || raw === undefined) return null;
+  const text = String(raw).trim();
+  return text.length > 0 ? text : null;
+}
+
+/** 按**码点**计数（对齐 Rust `chars().count()`，否则 emoji/生僻字会被算多）。 */
+function charCount(text) {
+  return Array.from(String(text)).length;
+}
+
+/**
+ * `member --search --phone` 的本地校验：**只认精确号码**（11 位、1 开头）。
+ *
+ * 规范化（`+86` / 空格 / 横线）交给服务端 `normalize_phone` —— 这里只回答
+ * “这是不是一个号码”，因为检索**不做前缀 / 号段 / 模糊匹配**：号码是登录凭据本身，
+ * 开放模糊等于把全平台用户目录变成可探测面（MEMBER-001 §5.3）。
+ */
+function isExactPhone(raw) {
+  const digits = Array.from(String(raw))
+    .filter((ch) => ch >= '0' && ch <= '9')
+    .join('');
+  const national =
+    digits.startsWith('86') && digits.length - 2 === 11 ? digits.slice(2) : digits;
+  return national.length === 11 && national.startsWith('1');
+}
+
+/** `--dry-run`：把将发送的单个请求打印出来（**不发**）。 */
+function dryRunReport(runtime, method, path, spec) {
+  runtime.finish({
+    dry_run: true,
+    request: dryRunRequestOf(runtime, method, path, spec),
+    note: '--dry-run：没有发出任何请求，也没有写任何东西',
+  });
+}
+
+/**
+ * 单个请求的 dry-run 描述。
+ *
+ * `multipart` 这一栏**必须显式给 null**（没有附件时也一样）：Rust 侧的
+ * `serde_json` 对象恒带这个键，少一个键会让 `--dry-run` 的 `--json` 与 Rust 版
+ * 差一行 —— 而 `--dry-run` 的输出正是判卷拿来对齐“将发什么请求”的依据。
+ */
+function dryRunRequestOf(runtime, method, path, spec) {
+  const request = runtime.dryRunRequest(method, path, spec);
+  if (!Object.prototype.hasOwnProperty.call(request, 'multipart')) request.multipart = null;
+  return request;
+}
+
+/** Rust `Value::get` 的等价物：非对象 / 缺键都给 null（键必须在、值为 null）。 */
+function pick(value, key) {
+  if (!isObject(value)) return null;
+  const found = value[key];
+  return found === undefined ? null : found;
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 键**存在**的判定（Rust `Value::get` 是 Option：存在但为 null 与缺键不是一回事）。 */
+function hasKey(value, key) {
+  return isObject(value) && Object.prototype.hasOwnProperty.call(value, key);
+}
+
+/** Rust `Value::as_array` 的等价物：不是数组就是空数组。 */
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}