@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/report.js

@@ -0,0 +1,908 @@
+// 汇报域：`report rule …`（规则配置面）+ `report --…`（报告面）—— docs/38 §9、契约 §2「汇报」。
+//
+// CLI 在这条链路上只是**薄封装**：模板校验、收件人解析、周期开窗、状态机全在服务端
+// （`services/report_*`）。所以这一层只做三件事：
+//
+// 1. **参数即约束**：动作与组合约束本地判定，拼错就是退出码 2、**一个请求都不发**；
+// 2. **参数形状**：JSON 旗标只校验"是不是合法 JSON"（语义错误由服务端
+//    `report.content_invalid` 原样展示 —— CLI 不重复实现模板校验，否则两套语义）；
+// 3. **写操作带幂等键**：建规则 / 存草稿 / 提交 / 催交由 CLI 自动生成
+//    （`report --submit` 同周期重跑返回首次结果，不会产生第二份）。
+//
+// ## 为什么 `report rule --create` 会顺手开当期（服务端行为，CLI 只如实带出）
+//
+// 开窗原本只有服务端 `report_tick`（cron）能做，而部署面没有任何调度配置 ——
+// 症状是"规则建好了、命令全返回成功，但 `report --due` 永远为空、`--save/--submit`
+// 一律 `report.period_not_open`"，排障的人只会以为"日报功能是坏的"（docs/05 决策 74①）。
+// 服务端从 2026-10-15 起在 `POST /reports/rules` 之后调用 `_open_current_period`，
+// 于是响应多出一段 `period: {period_key, due_at, assignments_created, opened}`：
+//
+// - `period_key` 可以直接喂给 `report --save/--submit`，所以 CLI 把它写进 `next_step`，
+//   省掉"自己猜周期键"这一步；
+// - **只开当期、不补开历史**（`backfill_max=1`：刚建的规则补 30 期等于让全公司补写
+//   一个月前的工作日志），历史补开仍归 tick；
+// - `assignments_created=0` 是**要紧的信号**：说明 `fillers` 没展开出任何人
+//   （这条规则"谁都不该交"），十有八九是 `fillers` 写窄了。CLI **不额外造字段**
+//   去解释它（`--json` 的 `data` 形状必须与 Rust 版逐字一致），只保证原样带出。
+//
+// ## 为什么显式旗标要覆盖 `--from` 的同名字段
+//
+// `--from` 是"一次给一整块 JSON"的便捷写法，`--template` / `--fillers` /
+// `--recipients` / `--deadline` 是逐字段写法，两者**同时给时更具体的那个赢**
+// （参数面与 `--update` 逐条对齐）。反过来的话，`--create --from '{…}' --fillers '{…}'`
+// 会静默发出 `--from` 里的旧 `fillers` —— 而 `fillers` 决定"谁该交"，
+// 发错的症状同样是"员工 `report --due` 永远为空、看起来像功能坏了"，命令却一个错都不报
+// （docs/05 决策 74⑤ 修的就是这类静默失效）。写入顺序因此是刻意的：
+// 先铺 `--from`，再写三个骨架字段（`key`/`name`/`cadence`，永远以旗标为准），
+// 最后盖四个 JSON 旗标。
+//
+// ## 为什么 `--confirm` / `--reject` 与 `approval --approve/--reject` 是同一底座
+//
+// 报告的"确认"不是汇报域自己的状态机：服务端用的是通用审批 `base.approval`
+// （`kind=report_confirm`，RPT-004），报告详情里的 `approval_id` 就是那一行。
+// 所以这两条命令是**语义糖**：先 `GET /reports/{id}` 取 `approval_id`，再走
+// `POST /approvals/{id}/approve|reject` —— 与 `approval --approve/--reject` 打的是
+// 同一行、同一组端点。两条入口因此天然一致（一边确认了，另一边立刻看得到），
+// 也不会出现"CLI 自己造一套确认语义、与服务端的审批状态打架"。
+// 拿不到 `approval_id`（比如规则的 `require_confirm` 没开）时**不猜**：
+// 回 `cli.report_not_confirmable`（退出码 5）并指路 `report --show`。
+
+import fs from 'node:fs';
+
+import { CliError, Kind, exactlyOne } from '../core/error.js';
+import { flagValue, intFlag } from '../core/args.js';
+import { dataOf, idempotencyKey, requestSpec } from '../core/runtime.js';
+import { rustIoErrorText } from '../core/util.js';
+import { sortKeysDeep } from '../core/util.js';
+
+/**
+ * 报告实例状态（与 `args.rs` 的 `REPORT_STATUSES` / `base.report_instance` 一致；`all` 单独处理）。
+ *
+ * 注意：`core/values.js` 里的同名常量是**起草期**的旧值
+ * （`pending|filled|…|waived`、cadence 缺 `half_yearly|yearly`），与 0.1.7 的 Rust
+ * 行为不一致 —— 那组词其实更像 `report_assignment` 的状态。本域要求"与 Rust 逐字等价"，
+ * 所以这里按 Rust 的 `args.rs` 重建；`core/` 不在本域可改范围内。
+ */
+const REPORT_STATUSES = ['draft', 'submitted', 'late', 'missing', 'confirmed', 'rejected', 'reopened'];
+/** 周期档（与 `services/report_periods.CADENCES` / `args.rs` 一致）。 */
+const REPORT_CADENCES = ['daily', 'weekly', 'monthly', 'quarterly', 'half_yearly', 'yearly'];
+
+/** `report --<动作>` 这一层能出现的"非动作"旗标（Rust `ReportArgs::only` 的检查清单，顺序照抄）。 */
+const REPORT_SIDE_FLAGS = [
+  '--rule',
+  '--period',
+  '--content',
+  '--cc',
+  '--mine',
+  '--team',
+  '--dept',
+  '--status',
+  '--with-children',
+  '--include-sub',
+  '--note',
+];
+
+/** `report rule --<动作>` 这一层能出现的"非动作"旗标（Rust `ReportRuleArgs::reject_extra`，顺序照抄）。 */
+const RULE_SIDE_FLAGS = [
+  '--key',
+  '--name',
+  '--from',
+  '--rule',
+  '--period',
+  '--template',
+  '--fillers',
+  '--recipients',
+  '--deadline',
+  '--version',
+];
+
+/**
+ * `report rule …` 与 `report --…` 共用一个处理函数（命令表把两者都指到这里）。
+ *
+ * 分支判据是**命令名**（`report rule` 是第一层子命令），不是"args 里有没有 `--rule`"：
+ * 报告面也用 `--rule`（指定规则），拿它当开关会把 `report --due --rule x` 误判成规则面。
+ */
+export async function handleReport({ args, command, runtime }) {
+  const domain = command.name.split(' ')[1];
+  if (domain === 'rule') return ruleDomain(args, runtime);
+  return reportDomain(args, runtime);
+}
+
+// ---------------------------------------------------------------------------
+// 参数面（Rust `args.rs` 的 `ReportRuleArgs::validate` / `ReportArgs::action` 逐条对齐）
+// ---------------------------------------------------------------------------
+
+/**
+ * `report rule` 的动作分派 + 组合约束。
+ *
+ * 顺序照抄 Rust：**先本地校验完，再发请求**。错误提示先报哪一条是有讲究的
+ * （`--show "" --key k` 报的是"不接受 --key"而不是"值不能为空"），照抄才不会
+ * 让判卷拿到的 `message` 漂移。
+ */
+async function ruleDomain(args, runtime) {
+  const action = exactlyOne(
+    [
+      ['--list', isGiven(args, '--list')],
+      ['--show', flagValue(args, '--show') !== null],
+      ['--create', isGiven(args, '--create')],
+      ['--update', flagValue(args, '--update') !== null],
+      ['--archive', flagValue(args, '--archive') !== null],
+      ['--preview', isGiven(args, '--preview')],
+    ],
+    'report rule',
+    '六选一：--list | --show <RULE_ID|KEY> | --create | --update <RULE_ID> | --archive <RULE_ID> | --preview',
+  );
+
+  if (action === '--list') {
+    cadenceValue(args); // 非法档位本地就挡下（不发请求）
+    rejectExtra(args, 'report rule --list', ['--cadence']);
+    return ruleList(runtime, args);
+  }
+  if (action === '--show') {
+    rejectExtra(args, 'report rule --show', []);
+    return ruleShow(runtime, requiredValue(flagValue(args, '--show'), '--show <RULE_ID|KEY>'));
+  }
+  if (action === '--create') {
+    if (isBlank(flagValue(args, '--key'))) {
+      throw CliError.usage('`report rule --create` 必须给 --key <KEY>').withHint(
+        '例：xinhe-oa-cli report rule --create --key work_daily --name 工作日报 --cadence daily',
+      );
+    }
+    if (isBlank(flagValue(args, '--name'))) {
+      throw CliError.usage('`report rule --create` 必须给 --name <NAME>').withHint(
+        '例：xinhe-oa-cli report rule --create --key work_daily --name 工作日报 --cadence daily',
+      );
+    }
+    if (cadenceValue(args) === null) {
+      throw CliError.usage('`report rule --create` 必须给 --cadence <CADENCE>').withHint(
+        '例：--cadence daily',
+      );
+    }
+    // 四个 JSON 旗标与 `--from` 的互斥面**不**在这里拦：它们是 `--create` 的合法参数，
+    // 更具体的写法覆盖 `--from`（见文件头）。Rust 0.1.7 的 `validate()` 忘了把这四个
+    // 旗标加进白名单（`apply_rule_json_flags` 与 `schema` 自描述都是按"接受"写的），
+    // 于是那边会把 `--create --fillers …` 判成用法错误 —— 这是 Rust 侧的漏项，
+    // 本实现按契约 docs/31「汇报」行与 `schema report --json` 的参数面接受它们。
+    rejectExtra(args, 'report rule --create', [
+      '--key',
+      '--name',
+      '--from',
+      '--cadence',
+      '--template',
+      '--fillers',
+      '--recipients',
+      '--deadline',
+    ]);
+    return ruleCreate(runtime, args);
+  }
+  if (action === '--update') {
+    const id = requiredValue(flagValue(args, '--update'), '--update <RULE_ID>');
+    const touched =
+      ['--template', '--fillers', '--recipients', '--deadline'].some(
+        (flag) => flagValue(args, flag) !== null,
+      ) || flagValue(args, '--version') !== null;
+    if (!touched) {
+      throw CliError.usage(
+        '`report rule --update` 至少要给一个要改的字段：--template / --fillers / --recipients / --deadline',
+      ).withHint(
+        '例：xinhe-oa-cli report rule --update rrl_123 --deadline \'{"anchor":"period_end","offset":"PT10H"}\'',
+      );
+    }
+    rejectExtra(args, 'report rule --update', [
+      '--template',
+      '--fillers',
+      '--recipients',
+      '--deadline',
+      '--version',
+    ]);
+    return ruleUpdate(runtime, id, args);
+  }
+  if (action === '--archive') {
+    const id = requiredValue(flagValue(args, '--archive'), '--archive <RULE_ID>');
+    rejectExtra(args, 'report rule --archive', []);
+    return ruleArchive(runtime, id);
+  }
+  // `--preview`：Rust 只看"有没有给 --rule"（不看空白），空白时拼出的路径是
+  // `/reports/rules//preview` —— 服务端会拒，但那是服务端的事实，CLI 不替它猜。
+  if (args['--rule'] === undefined) {
+    throw CliError.usage('`report rule --preview` 必须给 --rule <RULE_ID|KEY>').withHint(
+      '例：xinhe-oa-cli report rule --preview --rule work_daily --period D:2026-10-07',
+    );
+  }
+  rejectExtra(args, 'report rule --preview', ['--rule', '--period']);
+  return rulePreview(runtime, args);
+}
+
+/** `report --<动作>` 的动作分派 + 组合约束（Rust `ReportArgs::action`）。 */
+async function reportDomain(args, runtime) {
+  const picked = exactlyOne(
+    [
+      ['--due', isGiven(args, '--due')],
+      ['--save', isGiven(args, '--save')],
+      ['--submit', isGiven(args, '--submit')],
+      ['--list', isGiven(args, '--list')],
+      ['--show', flagValue(args, '--show') !== null],
+      ['--stats', isGiven(args, '--stats')],
+      ['--remind', isGiven(args, '--remind')],
+      ['--reopen', flagValue(args, '--reopen') !== null],
+      ['--waive', flagValue(args, '--waive') !== null],
+      ['--confirm', flagValue(args, '--confirm') !== null],
+      ['--reject', flagValue(args, '--reject') !== null],
+    ],
+    'report',
+    '例：xinhe-oa-cli report --due --json（配置规则用 `report rule --list`）',
+  );
+
+  if (picked === '--due') {
+    only(args, 'report --due', ['--rule', '--period']);
+    return due(runtime, args);
+  }
+  if (picked === '--save') {
+    only(args, 'report --save', ['--rule', '--period', '--content']);
+    requireRule(args, 'report --save');
+    requirePeriod(args, 'report --save');
+    requireContent(args, 'report --save');
+    return save(runtime, args);
+  }
+  if (picked === '--submit') {
+    only(args, 'report --submit', ['--rule', '--period', '--content', '--cc']);
+    requireRule(args, 'report --submit');
+    requirePeriod(args, 'report --submit');
+    requireContent(args, 'report --submit');
+    return submit(runtime, args);
+  }
+  if (picked === '--list') {
+    only(args, 'report --list', ['--rule', '--period', '--mine', '--team', '--dept', '--status']);
+    // 三份清单不能混看：`--mine` 是我自己的、`--team` 是我的汇报子树、`--dept` 是整个部门。
+    const views = [isGiven(args, '--mine'), isGiven(args, '--team'), isGiven(args, '--dept')].filter(
+      Boolean,
+    ).length;
+    if (views > 1) {
+      throw CliError.usage('`--mine` / `--team` / `--dept` 只能给一个（三份清单，不能混看）').withHint(
+        '例：xinhe-oa-cli report --list --team --period M:2026-10 --json',
+      );
+    }
+    statusFilter(args);
+    return list(runtime, args);
+  }
+  if (picked === '--show') {
+    only(args, 'report --show', ['--with-children']);
+    return show(runtime, requiredValue(flagValue(args, '--show'), '--show <RPT_ID>'), args);
+  }
+  if (picked === '--stats') {
+    only(args, 'report --stats', ['--rule', '--period', '--dept', '--include-sub']);
+    requireRule(args, 'report --stats');
+    requirePeriod(args, 'report --stats');
+    return stats(runtime, args);
+  }
+  if (picked === '--remind') {
+    only(args, 'report --remind', ['--rule', '--period']);
+    requireRule(args, 'report --remind');
+    requirePeriod(args, 'report --remind');
+    return remind(runtime, args);
+  }
+  if (picked === '--reopen') {
+    only(args, 'report --reopen', ['--note']);
+    requireNote(args, 'report --reopen');
+    return reopen(runtime, requiredValue(flagValue(args, '--reopen'), '--reopen <RPT_ID>'), args);
+  }
+  if (picked === '--waive') {
+    only(args, 'report --waive', ['--note']);
+    requireNote(args, 'report --waive');
+    return waive(
+      runtime,
+      requiredValue(flagValue(args, '--waive'), '--waive <RPT_ID|ASSIGNMENT_ID>'),
+      args,
+    );
+  }
+  if (picked === '--confirm') {
+    only(args, 'report --confirm', []);
+    return decide(
+      runtime,
+      'approve',
+      requiredValue(flagValue(args, '--confirm'), '--confirm <RPT_ID>'),
+      null,
+    );
+  }
+  only(args, 'report --reject', ['--note']);
+  // 顺序照抄 Rust：先判理由（"驳回不给理由"是最常见的手误），再判 id 是不是空的。
+  const rejectNote = requireNote(args, 'report --reject');
+  return decide(
+    runtime,
+    'reject',
+    requiredValue(flagValue(args, '--reject'), '--reject <RPT_ID>'),
+    rejectNote,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// report rule …
+// ---------------------------------------------------------------------------
+
+/** `report rule --list [--cadence C]` → `GET /reports/rules[?cadence=]`。 */
+async function ruleList(runtime, args) {
+  const query = [];
+  const cadence = cadenceValue(args);
+  if (cadence !== null) query.push(['cadence', cadence]);
+  const spec = requestSpec({ query });
+  if (runtime.dryRun) return runtime.dryRunReport('GET', '/reports/rules', spec);
+  const response = await runtime.sendAuthed('GET', '/reports/rules', spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `report rule --show <rule_id|key>` → `GET /reports/rules/{id}`（收件人名已由服务端展开）。 */
+async function ruleShow(runtime, id) {
+  const path = `/reports/rules/${id}`;
+  const spec = requestSpec();
+  if (runtime.dryRun) return runtime.dryRunReport('GET', path, spec);
+  const response = await runtime.sendAuthed('GET', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * 规则配置的四个 JSON 旗标 → 请求体字段（`--create` 与 `--update` **共用一处**）。
+ *
+ * 为什么必须共用：`--create` 原本只读 `--from`，这四个旗标**静默失效** ——
+ * `report rule --create --fillers '{…}'` 建出一条"谁都不该交"的规则，症状是
+ * 员工 `report --due` 永远为空、日报功能看起来是坏的，而命令不报任何错。
+ * 静默忽略一个明确给出来的参数，是这里最贵的坑（docs/05 决策 74⑤）。
+ */
+function applyRuleJsonFlags(body, args) {
+  for (const [flag, field] of [
+    ['--template', 'template'],
+    ['--fillers', 'fillers'],
+    ['--recipients', 'recipients'],
+    ['--deadline', 'deadline'],
+  ]) {
+    const raw = flagValue(args, flag);
+    if (raw !== null) body[field] = parseJsonFlag(raw, flag);
+  }
+}
+
+/**
+ * `report rule --create --key <k> --name <n> --cadence <c> [--from <json>]
+ *  [--template <json>] [--fillers <json>] [--recipients <json>] [--deadline <json>]`
+ *  → `POST /reports/rules`（幂等键自动生成）。
+ */
+async function ruleCreate(runtime, args) {
+  const fromRaw = flagValue(args, '--from');
+  const body = fromRaw !== null ? { ...parseJsonObject(fromRaw, '--from') } : {};
+  // 三个"骨架字段"永远以旗标为准（`--from` 只补其余字段）—— 顺序敏感：
+  // 必须在 `--from` 之后、四个 JSON 旗标之前。
+  body.key = trimmed(flagValue(args, '--key'));
+  body.name = trimmed(flagValue(args, '--name'));
+  body.cadence = cadenceValue(args) ?? '';
+  applyRuleJsonFlags(body, args);
+
+  const spec = requestSpec({
+    body: sortKeysDeep(body),
+    idempotencyKey: idempotencyKey('report-rule-create'),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', '/reports/rules', spec);
+  const response = await runtime.sendAuthed('POST', '/reports/rules', spec);
+  const data = dataOf(response);
+  if (isPlainObject(data)) {
+    // 服务端建规则时会**自动开当前周期**，所以预览要用它回的 `period.period_key`；
+    // 拿不到（老服务端）才退回让调用方自己给 —— 兼容路径，不是默认路径。
+    const period = data.period;
+    const periodKey =
+      isPlainObject(period) && typeof period.period_key === 'string' ? period.period_key : null;
+    data.next_step =
+      periodKey !== null
+        ? `解析预演一下：xinhe-oa-cli report rule --preview --rule <KEY> --period ${periodKey}`
+        : '解析预演一下再发：xinhe-oa-cli report rule --preview --rule <KEY> --period <PERIOD_KEY>';
+  }
+  runtime.finishFrom(response, data);
+}
+
+/** `report rule --update <rule_id> [--template] [--fillers] [--recipients] [--deadline] [--version N]`。 */
+async function ruleUpdate(runtime, id, args) {
+  const body = {};
+  applyRuleJsonFlags(body, args);
+  // 乐观锁：不传 = 不带 version（由服务端判定）；传了就原样带上（撞车 = write.version_conflict → 5）。
+  const version = intFlag(args, '--version', {
+    min: -9223372036854775808,
+    max: 9223372036854775807,
+    fallback: null,
+  });
+  if (version !== null) body.version = version;
+  const path = `/reports/rules/${id}`;
+  const spec = requestSpec({ body: sortKeysDeep(body) });
+  if (runtime.dryRun) return runtime.dryRunReport('PATCH', path, spec);
+  const response = await runtime.sendAuthed('PATCH', path, spec);
+  const data = dataOf(response);
+  if (isPlainObject(data)) {
+    data.note =
+      '改版只对**下个周期**生效：在途周期已开窗，实例冻结的是当时的规则版本（docs/38 §4.5）';
+  }
+  runtime.finishFrom(response, data);
+}
+
+/** `report rule --archive <rule_id>`：**高风险写，必须 `--yes`**。 */
+async function ruleArchive(runtime, id) {
+  runtime.requireYes(
+    'report rule --archive（归档后不再开新周期；有未关窗周期时服务端会拒绝）',
+    `xinhe-oa-cli report rule --archive ${id}`,
+  );
+  const path = `/reports/rules/${id}/archive`;
+  const spec = requestSpec();
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `report rule --preview --rule <r> [--period <p>]`：解析预演，**不落库**。 */
+async function rulePreview(runtime, args) {
+  const rule = trimmed(flagValue(args, '--rule'));
+  const body = {};
+  const period = flagValue(args, '--period');
+  if (!isBlank(period)) body.period_key = trimmed(period);
+  const path = `/reports/rules/${rule}/preview`;
+  const spec = requestSpec({ body: sortKeysDeep(body) });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+// ---------------------------------------------------------------------------
+// 报告面
+// ---------------------------------------------------------------------------
+
+/**
+ * `report --due [--rule <r>] [--period <p>]`：待我填（含 `pending` 与 `draft`）。
+ *
+ * 走 `/reports/assignments`（"该交而没交"是**一个事实**，`report_assignment` 是它的
+ * 真相源），`mine=true` 把它夹到"我"身上 —— 规则详情与草稿由服务端在这个视角里并进来。
+ */
+async function due(runtime, args) {
+  const query = [['mine', 'true']];
+  pushQuery(query, 'rule_id', flagValue(args, '--rule'));
+  pushQuery(query, 'period_key', flagValue(args, '--period'));
+  const spec = requestSpec({ query });
+  if (runtime.dryRun) return runtime.dryRunReport('GET', '/reports/assignments', spec);
+  const response = await runtime.sendAuthed('GET', '/reports/assignments', spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `report --save --rule <r> --period <p> --content <json>`：存草稿。 */
+async function save(runtime, args) {
+  const rule = requireRule(args, 'report --save');
+  const period = requirePeriod(args, 'report --save');
+  const content = parseJsonFlag(requireContent(args, 'report --save'), '--content');
+  const path = `/reports/${rule}/${period}`;
+  const spec = requestSpec({
+    body: sortKeysDeep({ content }),
+    idempotencyKey: idempotencyKey('report-save'),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('PUT', path, spec);
+  const response = await runtime.sendAuthed('PUT', path, spec);
+  const data = dataOf(response);
+  if (isPlainObject(data)) {
+    data.next_step = `提交：xinhe-oa-cli report --submit --rule ${rule} --period ${period} --content <JSON>`;
+  }
+  runtime.finishFrom(response, data);
+}
+
+/** `report --submit --rule <r> --period <p> --content <json> [--cc <uids>]`：提交（幂等）。 */
+async function submit(runtime, args) {
+  const rule = requireRule(args, 'report --submit');
+  const period = requirePeriod(args, 'report --submit');
+  const content = parseJsonFlag(requireContent(args, 'report --submit'), '--content');
+  const body = { content };
+  const cc = ccUserIds(args);
+  if (cc.length > 0) body.cc = cc;
+  const path = `/reports/${rule}/${period}/submit`;
+  const spec = requestSpec({
+    body: sortKeysDeep(body),
+    // 幂等键必填：同周期重复提交返回首次结果，不产生第二份。
+    idempotencyKey: idempotencyKey('report-submit'),
+  });
+  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 = '提交后作者不可改：要改只能由上级/管理员 report --reopen（理由必填、留痕）';
+  }
+  runtime.finishFrom(response, data);
+}
+
+/**
+ * `report --list [--mine|--team|--dept <d>] [--rule] [--period] [--status]`。
+ *
+ * 三条路各自一个端点：`--team` → `/reports/team?scope=managed`，
+ * `--dept` → `/reports/team?scope=dept&dept_id=`，其余 → `/reports`。
+ */
+async function list(runtime, args) {
+  const status = statusFilter(args);
+  let path;
+  const query = [];
+  const dept = flagValue(args, '--dept');
+  if (isGiven(args, '--team')) {
+    path = '/reports/team';
+    query.push(['scope', 'managed']);
+  } else if (!isBlank(dept)) {
+    path = '/reports/team';
+    query.push(['scope', 'dept']);
+    query.push(['dept_id', trimmed(dept)]);
+  } else {
+    path = '/reports';
+    if (isGiven(args, '--mine')) query.push(['mine', 'true']);
+  }
+  pushQuery(query, 'rule_id', flagValue(args, '--rule'));
+  pushQuery(query, 'period_key', flagValue(args, '--period'));
+  if (status !== null) query.push(['status', status]);
+  const spec = requestSpec({ query });
+  if (runtime.dryRun) return runtime.dryRunReport('GET', path, spec);
+  const response = await runtime.sendAuthed('GET', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `report --show <rpt_id> [--with-children]`：详情（可选带汇总引用的子报告）。 */
+async function show(runtime, id, args) {
+  const withChildren = isGiven(args, '--with-children');
+  const path = `/reports/${id}`;
+  const childrenPath = `/reports/${id}/children`;
+  const plain = requestSpec();
+  if (runtime.dryRun) {
+    if (!withChildren) return runtime.dryRunReport('GET', path, plain);
+    // 真跑是两步，dry-run 必须把两步都列出来（只列第一个会让人以为只发一次）。
+    return runtime.finish(
+      {
+        dry_run: true,
+        requests: [
+          runtime.dryRunRequest('GET', path, plain),
+          runtime.dryRunRequest('GET', childrenPath, plain),
+        ],
+        note: '--dry-run：没有发出任何请求。真跑会读详情 + 子报告引用两个 GET',
+      },
+      null,
+      null,
+    );
+  }
+  const response = await runtime.sendAuthed('GET', path, plain);
+  const data = dataOf(response);
+  if (withChildren) {
+    const children = await runtime.sendAuthed('GET', childrenPath, plain);
+    const childrenData = dataOf(children);
+    // 服务端给的是 `{children: [...]}`；并进详情时把它铺平成一个数组，形状更稳。
+    const merged =
+      isPlainObject(childrenData) && childrenData.children !== undefined
+        ? childrenData.children
+        : childrenData;
+    if (isPlainObject(data)) data.children = merged;
+  }
+  runtime.finishFrom(response, data);
+}
+
+/** `report --stats --rule <r> --period <p> [--dept <d>] [--include-sub]`：应交 / 已交 / 未交。 */
+async function stats(runtime, args) {
+  const rule = requireRule(args, 'report --stats');
+  const period = requirePeriod(args, 'report --stats');
+  const query = [
+    ['rule_id', rule],
+    ['period_key', period],
+  ];
+  pushQuery(query, 'dept_id', flagValue(args, '--dept'));
+  if (isGiven(args, '--include-sub')) query.push(['include_sub', 'true']);
+  const spec = requestSpec({ query });
+  if (runtime.dryRun) return runtime.dryRunReport('GET', '/reports/assignments', spec);
+  const response = await runtime.sendAuthed('GET', '/reports/assignments', spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `report --remind --rule <r> --period <p>`：手动催交（**只发事件**）。 */
+async function remind(runtime, args) {
+  const rule = requireRule(args, 'report --remind');
+  const period = requirePeriod(args, 'report --remind');
+  const spec = requestSpec({
+    body: sortKeysDeep({ rule_id: rule, period_key: period }),
+    idempotencyKey: idempotencyKey('report-remind'),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', '/reports/remind', spec);
+  const response = await runtime.sendAuthed('POST', '/reports/remind', spec);
+  const data = dataOf(response);
+  if (isPlainObject(data)) {
+    data.note =
+      '平台只发事件（report.reminded），送达交给企业自己的工作流；同一 (rule, period, actor) 1 小时内只发一条';
+  }
+  runtime.finishFrom(response, data);
+}
+
+/** `report --reopen <rpt_id> --note <n>`：**高风险写，必须 `--yes`；理由必填**。 */
+async function reopen(runtime, id, args) {
+  const note = requireNote(args, 'report --reopen');
+  runtime.requireYes(
+    'report --reopen（退回后作者可重写，已提交版本留痕）',
+    `xinhe-oa-cli report --reopen ${id} --note "${note}"`,
+  );
+  const path = `/reports/${id}/reopen`;
+  const spec = requestSpec({ body: sortKeysDeep({ note }) });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * `report --waive <rpt_id|assignment_id> --note <n>`：**高风险写，必须 `--yes`；理由必填**。
+ *
+ * 两种 id 走各自的子资源：`ras_*` 是 `report_assignment`（应交行），`rpt_*` 是报告实例。
+ * 免交是"该交而免交"的事实，落在 assignment 上；报告实例上则回填 `waived`。
+ */
+async function waive(runtime, id, args) {
+  const note = requireNote(args, 'report --waive');
+  runtime.requireYes(
+    'report --waive（免交必须留理由：谁免的、为什么）',
+    `xinhe-oa-cli report --waive ${id} --note "${note}"`,
+  );
+  const path = id.startsWith('ras_')
+    ? `/reports/assignments/${id}/waive`
+    : `/reports/${id}/waive`;
+  const spec = requestSpec({ body: sortKeysDeep({ note }) });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * `report --confirm` / `--reject`：读详情的 `approval_id` → 走 `base.approval`。
+ *
+ * `action` 就是审批端点上的那一段（`approve` / `reject`），与
+ * `approval --approve/--reject` 打的是同一行 `base.approval`，两条入口互不冲突。
+ */
+async function decide(runtime, action, id, note) {
+  if (action === 'reject') {
+    runtime.requireYes(
+      'report --reject（驳回后实例回 reopened，理由写进 confirm_note）',
+      `xinhe-oa-cli report --reject ${id} --note "<理由>"`,
+    );
+  } else {
+    runtime.requireYes(
+      'report --confirm（确认后报告进入 confirmed，不可再改）',
+      `xinhe-oa-cli report --confirm ${id}`,
+    );
+  }
+  const reportPath = `/reports/${id}`;
+  const plain = requestSpec();
+  if (runtime.dryRun) {
+    // 真跑是两步：先读详情拿 approval_id，再走审批端点。dry-run 把两步都列出来。
+    const approvalPath = `/approvals/<从详情取 approval_id>/${action}`;
+    const body = note !== null ? { note } : {};
+    return runtime.finish(
+      {
+        dry_run: true,
+        requests: [
+          runtime.dryRunRequest('GET', reportPath, plain),
+          runtime.dryRunRequest('POST', approvalPath, requestSpec({ body: sortKeysDeep(body) })),
+        ],
+        note: `--dry-run：没有发出任何请求。真跑会先 GET 详情取 approval_id，再 POST /approvals/<id>/${action}（与 approval --${action === 'approve' ? 'approve' : 'reject'} 同一底座）`,
+      },
+      null,
+      null,
+    );
+  }
+  const detail = await runtime.sendAuthed('GET', reportPath, plain);
+  const detailData = dataOf(detail);
+  const rawApprovalId = isPlainObject(detailData) ? detailData.approval_id : null;
+  const approvalId =
+    typeof rawApprovalId === 'string' && rawApprovalId.trim().length > 0
+      ? rawApprovalId.trim()
+      : null;
+  if (approvalId === null) {
+    // 不猜、也不退化成"直接改报告状态"：没有待确认的审批 = 这份报告现在不该被确认。
+    throw new CliError(
+      Kind.Conflict,
+      'cli.report_not_confirmable',
+      '这份报告没有待确认的审批（approval_id 为空）',
+    )
+      .withDetails({ report_id: id, approval_id: null })
+      .withHint(
+        '只有 require_confirm 的规则提交后才需要确认；用 `xinhe-oa-cli report --show <RPT_ID> --json` 看 status',
+      );
+  }
+  const body = note !== null ? { note } : {};
+  const response = await runtime.sendAuthed(
+    'POST',
+    `/approvals/${approvalId}/${action}`,
+    requestSpec({ body: sortKeysDeep(body) }),
+  );
+  const data = dataOf(response);
+  if (isPlainObject(data)) {
+    // 审批端点的响应只说审批，补回"这是哪份报告"的两个 id，脚本才不用自己记。
+    data.report_id = id;
+    data.approval_id = approvalId;
+  }
+  runtime.finishFrom(response, data);
+}
+
+// ---------------------------------------------------------------------------
+// 小工具（与 Rust 的 `trim_of` / `push_query` / `required_value` 逐条对齐）
+// ---------------------------------------------------------------------------
+
+/** `str::trim()`：旗标取值一律先去空白（`--rule " x "` 与 `--rule x` 是同一件事）。 */
+function trimmed(raw) {
+  return raw === null || raw === undefined ? '' : String(raw).trim();
+}
+
+/** 旗标"给没给"：`--x ""` 也算给了（Rust 的 `Option::is_some`）。 */
+function isGiven(args, flag) {
+  return args[flag] !== undefined;
+}
+
+/** 取值缺失或全空白（Rust 的 `required_value` 判据）。 */
+function isBlank(raw) {
+  return raw === null || raw === undefined || String(raw).trim().length === 0;
+}
+
+/** 旗标的值不能是空白（`--show ""` 这种等于没给）。 */
+function requiredValue(raw, what) {
+  if (isBlank(raw)) throw CliError.usage(`${what} 的值不能为空`);
+  return trimmed(raw);
+}
+
+/** 查询参数：空白值不进 query（`--rule "  "` 与没给一样）。 */
+function pushQuery(query, key, value) {
+  if (value === null || value === undefined) return;
+  const text = trimmed(value);
+  if (text.length > 0) query.push([key, text]);
+}
+
+/** `--cadence` 的白名单校验（非法值本地判定 = 用法错误，退出码 2、不发请求）。 */
+function cadenceValue(args) {
+  const raw = flagValue(args, '--cadence');
+  if (isBlank(raw)) return null;
+  const text = trimmed(raw);
+  if (REPORT_CADENCES.includes(text)) return text;
+  throw CliError.usage(
+    `--cadence 只认 ${REPORT_CADENCES.join(' | ')}，收到 ${JSON.stringify(text)}`,
+  ).withHint('例：--cadence weekly');
+}
+
+/** `--status`：`all` = 不带过滤；非法值本地出口 2。 */
+function statusFilter(args) {
+  const raw = flagValue(args, '--status');
+  if (raw === null) return null;
+  const text = trimmed(raw);
+  if (text.length === 0) return null;
+  if (text.toLowerCase() === 'all') return null;
+  if (REPORT_STATUSES.includes(text)) return text;
+  throw CliError.usage(
+    `--status 只认 ${REPORT_STATUSES.join(' | ')}(或 all)，收到 ${JSON.stringify(text)}`,
+  ).withHint('例：xinhe-oa-cli report --list --status missing --json');
+}
+
+/** `--cc <uids>`：可重复，也接受逗号分隔；去空、去重（保序）。 */
+function ccUserIds(args) {
+  const raw = args['--cc'];
+  const out = [];
+  const values = raw === undefined || raw === true ? [] : Array.isArray(raw) ? raw : [raw];
+  for (const item of values) {
+    for (const piece of String(item).split(',')) {
+      const text = piece.trim();
+      if (text.length > 0 && !out.includes(text)) out.push(text);
+    }
+  }
+  return out;
+}
+
+function requireRule(args, what) {
+  const raw = flagValue(args, '--rule');
+  if (isBlank(raw)) {
+    throw CliError.usage(`\`${what}\` 必须给 --rule <RULE_ID|KEY>`).withHint(
+      '先看有哪些规则：xinhe-oa-cli report rule --list --json',
+    );
+  }
+  return trimmed(raw);
+}
+
+function requirePeriod(args, what) {
+  const raw = flagValue(args, '--period');
+  if (isBlank(raw)) {
+    throw CliError.usage(`\`${what}\` 必须给 --period <PERIOD_KEY>`).withHint(
+      '周期键形如 D:2026-10-07 / W:2026-W41 / M:2026-10；看周期：xinhe-oa-cli report --list --rule <RULE> --json',
+    );
+  }
+  return trimmed(raw);
+}
+
+function requireContent(args, what) {
+  const raw = flagValue(args, '--content');
+  if (isBlank(raw)) {
+    throw CliError.usage(`\`${what}\` 必须给 --content <JSON>`).withHint(
+      '例：--content \'{"done":"走访 3 家"}\'；长正文用 `--content @-` 从 stdin 读',
+    );
+  }
+  return trimmed(raw);
+}
+
+function requireNote(args, what) {
+  const raw = flagValue(args, '--note');
+  if (isBlank(raw)) {
+    throw CliError.usage(`\`${what}\` 必须给 --note <理由>`).withHint(
+      '理由会写进审计与事件（事后复盘用），不能省',
+    );
+  }
+  return trimmed(raw);
+}
+
+/** 只允许 `allowed` 里的旗标（其余给了就是用法错误，本地出口 2、不发请求）。 */
+function only(args, what, allowed) {
+  const bad = REPORT_SIDE_FLAGS.filter(
+    (flag) => (flag === '--cc' ? ccUserIds(args).length > 0 : isGiven(args, flag)) && !allowed.includes(flag),
+  );
+  if (bad.length === 0) return;
+  throw CliError.usage(`\`${what}\` 不接受 ${bad.join(' / ')}`).withHint(
+    `跑 \`xinhe-oa-cli schema ${what}\` 看这个动作的参数面`,
+  );
+}
+
+/** `report rule` 侧的同一件事（旗标清单不同，Rust 里也是两份实现）。 */
+function rejectExtra(args, what, allowed) {
+  const bad = RULE_SIDE_FLAGS.filter((flag) => isGiven(args, flag) && !allowed.includes(flag));
+  if (bad.length === 0) return;
+  throw CliError.usage(`\`${what}\` 不接受 ${bad.join(' / ')}`).withHint(
+    `跑 \`xinhe-oa-cli schema ${what}\` 看这个动作的参数面`,
+  );
+}
+
+/**
+ * 读 `--content` / `--from` 的取值：`@-` = 从 stdin 读（避开 argv 长度上限）。
+ *
+ * 只认**整个取值**就是 `@-` 的那种写法（`"--content @-"`），不做前缀展开 ——
+ * 与 Rust 一致。
+ */
+function jsonInput(raw) {
+  if (trimmed(raw) !== '@-') return raw;
+  let buffer;
+  try {
+    buffer = fs.readFileSync(0, 'utf8'); // fd 0 = stdin；同步读，命令是一次性的
+  } catch (err) {
+    throw CliError.usage(`读不了 stdin：${rustIoErrorText(err)}`);
+  }
+  if (buffer.trim().length === 0) {
+    throw CliError.usage('`@-` 表示从 stdin 读 JSON，但 stdin 是空的').withHint(
+      '把 JSON 管进来：echo \'{"done":"走访 3 家"}\' | xinhe-oa-cli report --save --rule work_daily --period D:2026-10-07 --content @-',
+    );
+  }
+  return buffer;
+}
+
+/**
+ * 参数形状校验：**只判"是不是合法 JSON"**（语义校验在服务端，CLI 不重复实现）。
+ *
+ * 提示里必须带 `@-`：报告正文动辄上千字，命令行长度上限是现场最常撞的墙。
+ */
+function parseJsonFlag(raw, flag) {
+  const text = jsonInput(raw);
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw CliError.usage(`${flag} 不是合法 JSON：${err.message}`).withHint(
+      `例：${flag} '{"done":"走访 3 家"}'；长 JSON 用 \`${flag} @-\` 从 stdin 读`,
+    );
+  }
+}
+
+/** `--from` 这类"整块规则字段"必须是 JSON **对象**（数组/标量给不出字段，早点报错）。 */
+function parseJsonObject(raw, flag) {
+  const value = parseJsonFlag(raw, flag);
+  if (!isPlainObject(value)) {
+    throw CliError.usage(`${flag} 要一个 JSON 对象，收到 ${jsonKind(value)}`).withHint(
+      `例：${flag} '{"template":[],"recipients":[{"type":"direct_leader"}]}'`,
+    );
+  }
+  return value;
+}
+
+/** JSON 值的类型名（与 Rust `json_kind` 逐字对齐，报错里给人看）。 */
+function jsonKind(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return '数组';
+  if (typeof value === 'boolean') return '布尔值';
+  if (typeof value === 'number') return '数字';
+  if (typeof value === 'string') return '字符串';
+  return '对象';
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}