cloudhouse-admin-cli 0.3.3

package/src/commands/extended.mjs

@@ -0,0 +1,96 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { register } from './index.mjs'
+import { flagString, flagOn, flagNumber, payloadFrom } from '../payload.mjs'
+import { idParam, textParam } from '../path.mjs'
+import { usageError } from '../errors.mjs'
+import { collectQuery, parseNumber } from '../query.mjs'
+import { runWithVersionRetry } from '../idempotent.mjs'
+
+register('second-round-choices page', {
+  summary: '分页查询二轮组别选择',
+  usage: 'ch second-round-choices page [--page N] [--size N]',
+  endpoints: ['GET /admin/second-round-choices/page'],
+  run: async ctx => (await ctx.client.request({ path: '/admin/second-round-choices/page', query: collectQuery(ctx, { page: { parse: parseNumber }, size: { parse: parseNumber } }) })).data,
+})
+register('slots attendance', {
+  summary: '查看场次到场名单', usage: 'ch slots attendance <slotId>',
+  endpoints: ['GET /admin/interview-slots/{slotId}/attendance'],
+  run: async ctx => (await ctx.client.request({ path: `/admin/interview-slots/${idParam(ctx.positionals[0])}/attendance` })).data,
+})
+for (const [name, summary, endpoint] of [
+  ['feishu backfill-absence', '补推当天缺勤通知（会向真人发送通知，仅全局管理员）', '/admin/feishu/notifications/backfill-today-absence'],
+  ['feishu refresh-document', '刷新飞书场次文档（外部写入，仅全局管理员）', '/admin/feishu/upcoming-slots-document/refresh'],
+]) register(name, { summary, usage: `ch ${name}`, permission: 'global-admin', endpoints: [`POST ${endpoint}`], run: async ctx => (await ctx.client.request({ method: 'POST', path: endpoint })).data })
+register('feishu deliveries', {
+  summary: '查询飞书投递队列（最多200条，仅全局管理员）', usage: 'ch feishu deliveries [--status QUEUED|SENDING|SENT|FAILED|SKIPPED|RETRY]', permission: 'global-admin',
+  endpoints: ['GET /admin/feishu/deliveries'],
+  run: async ctx => (await ctx.client.request({ path: '/admin/feishu/deliveries', query: collectQuery(ctx, { status: {} }) })).data,
+})
+register('feishu requeue', {
+  summary: '重放失败/跳过投递（可能向真人补发通知，仅全局管理员）', usage: 'ch feishu requeue [--ids 1,2] [--all]', permission: 'global-admin',
+  endpoints: ['POST /admin/feishu/deliveries/requeue'],
+  run: async ctx => {
+    const raw = flagString(ctx, 'ids')
+    const all = flagOn(ctx, 'all')
+    if ((raw === undefined) === !all) throw usageError('必须且只能指定 --ids 1,2 或 --all，避免误重放全部队列')
+    const ids = raw === undefined ? [] : raw.split(',').map(s => {
+      if (!/^[1-9]\d*$/.test(s.trim()) || !Number.isSafeInteger(Number(s))) throw usageError('--ids 必须是逗号分隔的正整数')
+      return Number(s)
+    })
+    return (await ctx.client.request({ method: 'POST', path: '/admin/feishu/deliveries/requeue', body: { ids } })).data
+  },
+})
+const pending = 'material-authoring backend (not included in this CLI release)'
+register('ai materials', {
+  summary: '上传/预览出题资料（需新版后端；上传不支持requestId去重）', backendRequirement: pending,
+  usage: 'ch ai materials upload <file>\nch ai materials get <materialId>',
+  endpoints: ['POST /admin/ai-coding/materials', 'GET /admin/ai-coding/materials/{id}'],
+  run: async ctx => {
+    const [action, value] = ctx.positionals
+    if (action === 'get') {
+      if (!/^[a-f0-9]{32}\.(md|txt)$/.test(String(value))) throw usageError('materialId 必须是服务器返回的资料 id')
+      return (await ctx.client.request({ path: `/admin/ai-coding/materials/${value}` })).data
+    }
+    if (action !== 'upload' || !value) throw usageError('用法：ch ai materials upload <file> 或 get <materialId>')
+    const ext = path.extname(value).toLowerCase()
+    if (!['.md', '.txt'].includes(ext)) throw usageError('资料仅支持 UTF-8 .md/.txt')
+    let bytes
+    try {
+      const stat = fs.statSync(value)
+      if (!stat.isFile() || stat.size === 0 || stat.size > 262144) throw usageError('资料须为非空文件，≤256 KiB')
+      bytes = fs.readFileSync(value)
+    } catch (err) { if (err.exitCode) throw err; throw usageError(`资料无法读取：${value}`) }
+    let text
+    try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes) } catch { throw usageError('资料必须为 UTF-8 编码') }
+    if (!text.trim() || text.includes('\0')) throw usageError('资料须为非空 UTF-8 文本且不能含 NUL')
+    const formData = new FormData()
+    formData.append('file', new Blob([bytes], { type: 'text/plain' }), path.basename(value))
+    return (await ctx.client.request({ method: 'POST', path: '/admin/ai-coding/materials', formData })).data
+  },
+})
+register('ai papers', {
+  summary: '创建出题任务/查询任务/确认题目（需新版后端）', backendRequirement: pending, requestId: true,
+  usage: 'ch ai papers generate <planId> <paperId> [--version N] [--request-id ID]\nch ai papers get-generation <planId> <paperId> <jobId>\nch ai papers confirm <planId> <paperId> [--version N] [--request-id ID]',
+  endpoints: ['POST /admin/ai-coding/plans/{planId}/papers/{paperId}/generations', 'GET /admin/ai-coding/plans/{planId}/papers/{paperId}/generations/{jobId}', 'POST /admin/ai-coding/plans/{planId}/papers/{paperId}/confirm'],
+  run: async ctx => {
+    const [action, planRaw, paperRaw, jobRaw] = ctx.positionals
+    if (!['generate', 'get-generation', 'confirm'].includes(action)) throw usageError('ai papers 子命令必须是 generate|get-generation|confirm')
+    const planId = idParam(planRaw, { label: 'planId' })
+    const paperId = textParam(paperRaw, { label: 'paperId' })
+    const base = `/admin/ai-coding/plans/${planId}/papers/${paperId}`
+    if (action === 'get-generation') return (await ctx.client.request({ path: `${base}/generations/${idParam(jobRaw, { label: 'jobId' })}` })).data
+    const original = payloadFrom(ctx, {})
+    const explicitVersion = flagNumber(ctx, 'version') ?? original.version
+    if (explicitVersion !== undefined && (!Number.isSafeInteger(Number(explicitVersion)) || Number(explicitVersion) < 0)) throw usageError('version 必须是非负整数')
+    return runWithVersionRetry({
+      explicitVersion, explicitRequestId: flagString(ctx, 'request-id') || original.requestId, log: ctx.log,
+      readVersion: async () => {
+        const { data } = await ctx.client.request({ path: `/admin/ai-coding/plans/${planId}` })
+        if (!Number.isSafeInteger(data?.version)) throw usageError('计划详情中缺少 version')
+        return data.version
+      },
+      run: async ({ version, requestId }) => (await ctx.client.request({ method: 'POST', path: `${base}/${action === 'generate' ? 'generations' : 'confirm'}`, body: { ...original, version, requestId } })).data,
+    })
+  },
+})

package/src/commands/feishu.mjs

@@ -0,0 +1,31 @@
+import { register } from './index.mjs'
+
+register('feishu status', {
+  summary: '飞书签到集成状态',
+  usage: 'ch feishu status [--pretty]',
+  endpoints: ['GET /admin/feishu/status'],
+  run: async (ctx) => {
+    const { data } = await ctx.client.request({ method: 'GET', path: '/admin/feishu/status' })
+    return data
+  },
+})
+
+register('feishu reconcile', {
+  summary: '触发飞书场次双向对账',
+  usage: 'ch feishu reconcile',
+  endpoints: ['POST /admin/feishu/reconcile'],
+  run: async (ctx) => {
+    const { data } = await ctx.client.request({ method: 'POST', path: '/admin/feishu/reconcile' })
+    return data === null ? { reconciled: true } : data
+  },
+})
+
+register('feishu conflicts', {
+  summary: '飞书同步冲突列表',
+  usage: 'ch feishu conflicts [--pretty]',
+  endpoints: ['GET /admin/feishu/conflicts'],
+  run: async (ctx) => {
+    const { data } = await ctx.client.request({ method: 'GET', path: '/admin/feishu/conflicts' })
+    return data
+  },
+})

package/src/commands/groups.mjs

@@ -0,0 +1,66 @@
+import { register } from './index.mjs'
+import { usageError } from '../errors.mjs'
+import { flagString, payloadFrom } from '../payload.mjs'
+import { idParam } from '../path.mjs'
+
+const MAX_REQUIREMENT_LENGTH = 65
+
+function groupPayload(ctx, { requireName }) {
+  const base = {}
+  const groupName = flagString(ctx, 'group-name', { required: requireName, label: 'ch groups create --group-name 名称' })
+  if (groupName !== undefined) base.groupName = groupName
+  const introduction = flagString(ctx, 'introduction')
+  if (introduction !== undefined) base.introduction = introduction
+  const requirement = flagString(ctx, 'requirement')
+  if (requirement !== undefined) {
+    if (requirement.length > MAX_REQUIREMENT_LENGTH) {
+      throw usageError(`--requirement 不能超过 ${MAX_REQUIREMENT_LENGTH} 字（当前 ${requirement.length} 字）`)
+    }
+    base.requirement = requirement
+  }
+  return payloadFrom(ctx, base)
+}
+
+register('groups list', {
+  summary: '组别列表',
+  usage: 'ch groups list [--pretty]',
+  endpoints: ['GET /groups'],
+  run: async (ctx) => {
+    const { data } = await ctx.client.request({ method: 'GET', path: '/groups' })
+    return data
+  },
+})
+
+register('groups create', {
+  summary: '创建组别（SUPER/SYSTEM）',
+  usage: 'ch groups create --group-name 名称 [--introduction 简介] [--requirement 要求≤65字]',
+  endpoints: ['POST /groups'],
+  run: async (ctx) => {
+    const payload = groupPayload(ctx, { requireName: true })
+    const { data } = await ctx.client.request({ method: 'POST', path: '/groups', body: payload })
+    return data === null ? { created: true } : data
+  },
+})
+
+register('groups update', {
+  summary: '更新组别',
+  usage: 'ch groups update <id> --group-name 名称 [--introduction 简介] [--requirement 要求≤65字]',
+  endpoints: ['PUT /groups/{id}'],
+  run: async (ctx) => {
+    const id = idParam(ctx.positionals[0], { label: '组别 id' })
+    const payload = groupPayload(ctx, { requireName: true })
+    const { data } = await ctx.client.request({ method: 'PUT', path: `/groups/${id}`, body: payload })
+    return data === null ? { updated: true, id: Number(id) } : data
+  },
+})
+
+register('groups delete', {
+  summary: '删除组别（SUPER/SYSTEM）',
+  usage: 'ch groups delete <id>',
+  endpoints: ['DELETE /groups/{id}'],
+  run: async (ctx) => {
+    const id = idParam(ctx.positionals[0], { label: '组别 id' })
+    const { data } = await ctx.client.request({ method: 'DELETE', path: `/groups/${id}` })
+    return data === null ? { deleted: true, id: Number(id) } : data
+  },
+})

package/src/commands/index.mjs

@@ -0,0 +1,101 @@
+/**
+ * 命令注册表。每个命令声明其覆盖的后端端点（契约守护测试的数据源）：
+ * api.ts 与后端 Controller 中的每个端点，必须被某条命令的 endpoints 声明，
+ * 或由通用兜底 `ch api` 覆盖（fallback: true 的命令不逐条声明）。
+ */
+
+const commands = new Map()
+
+export function register(name, spec) {
+  commands.set(name, Object.freeze({ name, ...spec }))
+  return commands.get(name)
+}
+
+export function getRegistry() {
+  return commands
+}
+
+/** 最长前缀匹配：`ch ai plans list` → 注册键 'ai plans' + 位置参数 ['list'] */
+export function resolveCommand(positionals) {
+  const maxLen = Math.min(positionals.length, 3)
+  for (let n = maxLen; n >= 1; n -= 1) {
+    const key = positionals.slice(0, n).join(' ')
+    const spec = commands.get(key)
+    if (spec) return { key, spec, args: positionals.slice(n) }
+  }
+  return null
+}
+
+/**
+ * 渲染帮助文本。
+ * @returns {{text:string, missing:boolean}} missing 时由入口转成 exit 2——
+ *   查不到子命令却 exit 0 会让 Agent 以为拿到了用法说明。
+ */
+export function renderHelp(subPath) {
+  if (subPath && subPath.length > 0) {
+    const key = subPath.join(' ')
+    const spec = commands.get(key)
+    if (spec) {
+      const lines = [
+        `${spec.name} — ${spec.summary}`,
+        '',
+        `用法：${spec.usage}`,
+      ]
+      if (spec.endpoints && spec.endpoints.length > 0) {
+        lines.push('', '覆盖端点：', ...spec.endpoints.map((e) => `  ${e}`))
+      }
+      return { text: lines.join('\n'), missing: false }
+    }
+    // `ch help candidates` 这类只给分组名的查询：列出该组的命令，而不是报「未找到」
+    const group = [...commands.values()].filter((s) => s.name.split(' ')[0] === subPath[0])
+    if (group.length > 0) {
+      const lines = [`[分组 ${subPath[0]}]`, ...group.map((s) => `  ${s.name.padEnd(28)} ${s.summary}`)]
+      return { text: lines.join('\n'), missing: false }
+    }
+    return { text: `未找到命令：${key}\n运行 ch help 查看全部命令`, missing: true }
+  }
+
+  const groups = new Map()
+  for (const spec of commands.values()) {
+    const group = spec.name.split(' ')[0]
+    if (!groups.has(group)) groups.set(group, [])
+    groups.get(group).push(spec)
+  }
+  const lines = [
+    `ch — CloudHouse 招新管理后台 CLI（Agent 优先：stdout 输出 JSON 信封，共 ${commands.size} 条命令）`,
+    '',
+    '用法：ch [--pretty|--json] [--profile local|prod] [--base-url <url>] <命令> [参数] [--flag 值]',
+    '',
+    '通用选项：',
+    '  --pretty                人类可读表格/键值输出（非 TTY 时默认为 JSON）',
+    '  --json                  强制单行 JSON 输出',
+    '  --no-pretty             强制单行 JSON（管道/重定向时同样生效）',
+    '  --profile <name>        环境 profile：local | prod（未知 profile 直接 exit 2）',
+    '  --base-url <url>        直接指定 API 根地址',
+    '  --timeout <ms>          单次请求超时，1000–600000，默认 30000（上传 120000）',
+    '  --out <path>            下载落盘位置（仅 uploads 的下载类命令）',
+    '  --force                 允许覆盖已存在的下载目标',
+    '  --allow-profile-mismatch 显式允许跨环境会话（默认拒绝）',
+    '  --help                  查看某命令用法，如 ch help candidates list；ch help <分组> 看分组',
+    '',
+    '参数严格性：',
+    '  取值型 flag 缺值（--keyword 后无内容）→ exit 2；未知或不适用 flag → exit 2，不发送请求。',
+    '  布尔 flag 接受 true|false|1|0|yes|no|y|n|on|off；--flag=值 可安全传递以 - 开头取值。',
+    '  多余位置参数 → exit 2；时间/路径/枚举/正整数在本地预检，不合法即 exit 2。',
+    '  --request-id 仅 capabilities 标注的 AI 写动作支持；资料上传/读操作不支持。',
+    '',
+    '退出码：',
+    '  0 成功  1 业务错误  2 用法错误  3 鉴权失效  4 权限不足  5 限流',
+    '  6 版本冲突重试耗尽  7 网络不可达/超时  8 功能开关未开  9 端点未实现',
+    '',
+    '命令：',
+  ]
+  for (const [group, specs] of groups) {
+    lines.push(`  [${group}]`)
+    for (const spec of specs) lines.push(`    ${spec.name.padEnd(28)} ${spec.summary}`)
+  }
+  lines.push('', '任一未被语义化的端点均可用兜底命令调用：', '  ch api <METHOD> <path> [-q k=v] [-d <json|@file>] [-H "Name: value"] [--public]')
+  lines.push('', 'ch api 为逃生舱：flag 解析保持宽松，-d @file 直发文件内容，不做本地预检。')
+  lines.push('')
+  return { text: lines.join('\n'), missing: false }
+}

package/src/commands/interviews.mjs

@@ -0,0 +1,151 @@
+import { register } from './index.mjs'
+import { usageError } from '../errors.mjs'
+import { collectQuery, parseNumber } from '../query.mjs'
+import { flagEnum, flagString, flagNumber, payloadFrom } from '../payload.mjs'
+import { optionalReason } from '../sensitive.mjs'
+import { idParam } from '../path.mjs'
+
+register('interviews list', {
+  summary: '面试名单（按轮次/组别/场次/结果筛选）',
+  usage: 'ch interviews list --round 1|2|3 [--group-id N] [--slot-id N] [--result 1|2|3] [--pretty]',
+  endpoints: ['GET /admin/interviews'],
+  run: async (ctx) => {
+    const query = collectQuery(ctx, {
+      round: { parse: parseNumber },
+      'group-id': { key: 'groupId', parse: parseNumber },
+      'slot-id': { key: 'slotId', parse: parseNumber },
+      result: { parse: parseNumber },
+    })
+    if (!new Map(query).has('round')) {
+      throw usageError('缺少 --round', '面试名单按轮次查询：ch interviews list --round 1')
+    }
+    const { data } = await ctx.client.request({ method: 'GET', path: '/admin/interviews', query })
+    return data
+  },
+})
+
+register('interviews search', {
+  summary: '跨轮次搜索面试记录与面评关键词',
+  usage: 'ch interviews search [--keyword 关键词] [--round N] [--group-id N] [--result 1|2|3] [--pretty]',
+  endpoints: ['GET /admin/interviews/search'],
+  run: async (ctx) => {
+    const query = collectQuery(ctx, {
+      keyword: {},
+      round: { parse: parseNumber },
+      'group-id': { key: 'groupId', parse: parseNumber },
+      result: { parse: parseNumber },
+    })
+    const { data } = await ctx.client.request({ method: 'GET', path: '/admin/interviews/search', query })
+    return data
+  },
+})
+
+register('interviews statistics', {
+  summary: '按轮次/组别的面试统计',
+  usage: 'ch interviews statistics [--round N] [--group-id N] [--pretty]',
+  endpoints: ['GET /admin/interviews/statistics'],
+  run: async (ctx) => {
+    const query = collectQuery(ctx, {
+      round: { parse: parseNumber },
+      'group-id': { key: 'groupId', parse: parseNumber },
+    })
+    const { data } = await ctx.client.request({ method: 'GET', path: '/admin/interviews/statistics', query })
+    return data
+  },
+})
+
+register('interviews reschedule-options', {
+  summary: '管理员改约候选项（可改约的场次）',
+  usage: 'ch interviews reschedule-options <interviewId>',
+  endpoints: ['GET /admin/interviews/{interviewId}/reschedule-options'],
+  run: async (ctx) => {
+    const interviewId = idParam(ctx.positionals[0], { label: 'interviewId' })
+    const { data } = await ctx.client.request({ method: 'GET', path: `/admin/interviews/${interviewId}/reschedule-options` })
+    return data
+  },
+})
+
+register('interviews result', {
+  summary: '录入/修改单条面试结果',
+  usage: 'ch interviews result <interviewId> --result 1|2|3 [--remark 备注]',
+  endpoints: ['PATCH /admin/interviews/{interviewId}/result'],
+  run: async (ctx) => {
+    const interviewId = idParam(ctx.positionals[0], { label: 'interviewId' })
+    const result = flagEnum(ctx, 'result', ['1', '2', '3'], { required: true, label: 'ch interviews result <interviewId> --result 1|2|3' })
+    const remark = flagString(ctx, 'remark')
+    const base = { result: Number(result) }
+    if (remark !== undefined) base.remark = remark
+    const payload = payloadFrom(ctx, base)
+    const { data } = await ctx.client.request({
+      method: 'PATCH',
+      path: `/admin/interviews/${interviewId}/result`,
+      body: payload,
+    })
+    return data
+  },
+})
+
+const ATTENDANCE_STATUSES = ['ARRIVED', 'LATE', 'NO_SHOW', 'NOT_CHECKED_IN', 'CANCELLED']
+
+register('interviews attendance', {
+  summary: '补录/修正面试到场状态',
+  usage: 'ch interviews attendance <interviewId> --status ARRIVED|LATE|NO_SHOW|NOT_CHECKED_IN|CANCELLED [--reason 原因]',
+  endpoints: ['POST /admin/interviews/{interviewId}/attendance'],
+  run: async (ctx) => {
+    const interviewId = idParam(ctx.positionals[0], { label: 'interviewId' })
+    const status = flagEnum(ctx, 'status', ATTENDANCE_STATUSES, { required: true, label: `--status ${ATTENDANCE_STATUSES.join('|')}` })
+    const reason = optionalReason(ctx, { label: '--reason 到场状态修改原因（≤200 字，可省略）' })
+    const base = { status }
+    if (reason !== undefined) base.reason = reason
+    const payload = payloadFrom(ctx, base)
+    const { data } = await ctx.client.request({
+      method: 'POST',
+      path: `/admin/interviews/${interviewId}/attendance`,
+      body: payload,
+    })
+    return data
+  },
+})
+
+register('interviews reschedule', {
+  summary: '管理员为候选人改约场次',
+  usage: 'ch interviews reschedule <interviewId> --slot <slotId>',
+  endpoints: ['PUT /admin/interviews/{interviewId}/slot'],
+  run: async (ctx) => {
+    const [interviewId] = ctx.positionals
+    if (!interviewId) throw usageError('缺少 interviewId', '用法：ch interviews reschedule <interviewId> --slot 102')
+    const slotId = flagNumber(ctx, 'slot', { required: true, label: 'ch interviews reschedule <interviewId> --slot <slotId>' })
+    const payload = payloadFrom(ctx, { slotId })
+    const { data } = await ctx.client.request({
+      method: 'PUT',
+      path: `/admin/interviews/${interviewId}/slot`,
+      body: payload,
+    })
+    return data
+  },
+})
+
+register('interviews batch-result', {
+  summary: '批量录入面试结果',
+  usage: 'ch interviews batch-result -d <json|@file>   # {"round":1,"groupId":2,"results":[{"interviewId":11,"result":1,"remark":"..."}]}',
+  endpoints: ['POST /admin/interviews/batch-result'],
+  run: async (ctx) => {
+    const payload = payloadFrom(ctx, {})
+    if (!Number.isFinite(Number(payload.round))) throw usageError('batch-result 载荷缺少数字字段 round')
+    if (!Number.isFinite(Number(payload.groupId))) throw usageError('batch-result 载荷缺少数字字段 groupId')
+    if (!Array.isArray(payload.results) || payload.results.length === 0) {
+      throw usageError('batch-result 载荷的 results 必须是非空数组', '每项：{"interviewId":11,"result":1,"remark":"可选"}')
+    }
+    for (const item of payload.results) {
+      if (!item || !Number.isFinite(Number(item.interviewId)) || ![1, 2, 3].includes(Number(item.result))) {
+        throw usageError('results 每项必须包含数字 interviewId 与 result(1|2|3)')
+      }
+    }
+    const { data } = await ctx.client.request({
+      method: 'POST',
+      path: '/admin/interviews/batch-result',
+      body: payload,
+    })
+    return data
+  },
+})

package/src/commands/load.mjs

@@ -0,0 +1,27 @@
+/**
+ * 命令装配：导入所有命令模块完成注册。
+ * 注册表本体在 index.mjs（不依赖任何命令模块，避免 ESM 循环初始化）。
+ * 新增命令模块时在此追加一行 import。
+ */
+import './api.mjs'
+import './auth.mjs'
+import './dashboard.mjs'
+import './groups.mjs'
+import './candidates.mjs'
+import './plans.mjs'
+import './slots.mjs'
+import './interviews.mjs'
+import './evaluations.mjs'
+import './notifications.mjs'
+import './assistant.mjs'
+import './uploads.mjs'
+import './accounts.mjs'
+import './applies.mjs'
+import './profile.mjs'
+import './ai.mjs'
+import './feishu.mjs'
+import './checkin.mjs'
+import './extended.mjs'
+import './agent.mjs'
+
+import './analysis.mjs'

package/src/commands/notifications.mjs

@@ -0,0 +1,131 @@
+import { register } from './index.mjs'
+import { usageError } from '../errors.mjs'
+import { collectQuery } from '../query.mjs'
+import { flagEnum, flagString, flagNumber, payloadFrom, camelCase } from '../payload.mjs'
+import { normalizeLocalTime } from '../time.mjs'
+import { idParam } from '../path.mjs'
+
+const NOTICE_LEVELS = ['INFO', 'WARNING', 'URGENT']
+const SCOPE_TYPES = ['ALL', 'ROUND', 'GROUP', 'ROUND_GROUP', 'SLOT']
+/** 生效窗口两端；写成常量而非内联字面量，flag 词表守护测试才扫得到 */
+const WINDOW_TIME_FLAGS = ['start-time', 'end-time']
+
+/** scopeType 决定哪些 target 字段有意义；缺取值当场报错 */
+function applyScopeTargets(ctx, base, scopeType) {
+  if (scopeType === 'ROUND' || scopeType === 'ROUND_GROUP') {
+    base.targetRound = flagNumber(ctx, 'target-round', { required: true, label: '--target-round N' })
+  }
+  if (scopeType === 'GROUP' || scopeType === 'ROUND_GROUP') {
+    base.targetGroupId = flagNumber(ctx, 'target-group-id', { required: true, label: '--target-group-id N' })
+  }
+  if (scopeType === 'SLOT') {
+    base.targetSlotId = flagNumber(ctx, 'target-slot-id', { required: true, label: '--target-slot-id N' })
+  }
+}
+
+/**
+ * 创建通知：未用到的 target / 时间显式置 null（INSERT 需要把这些列写成空值）。
+ */
+function createPayload(ctx) {
+  const base = { targetRound: null, targetGroupId: null, targetSlotId: null }
+  base.title = flagString(ctx, 'title', { required: true, label: 'ch notifications create --title 标题' })
+  base.content = flagString(ctx, 'content', { required: true, label: 'ch notifications create --content 内容' })
+  base.noticeLevel = flagEnum(ctx, 'notice-level', NOTICE_LEVELS, { required: true, label: `--notice-level ${NOTICE_LEVELS.join('|')}` })
+  base.scopeType = flagEnum(ctx, 'scope-type', SCOPE_TYPES, { required: true, label: `--scope-type ${SCOPE_TYPES.join('|')}` })
+  applyScopeTargets(ctx, base, base.scopeType)
+  for (const flag of WINDOW_TIME_FLAGS) {
+    const value = flagString(ctx, flag)
+    base[camelCase(flag)] = value === undefined ? null : normalizeLocalTime(value)
+  }
+  const status = flagEnum(ctx, 'status', ['1', '2'])
+  if (status !== undefined) base.status = Number(status)
+  return payloadFrom(ctx, base)
+}
+
+/**
+ * 编辑通知：只带显式给出的字段。
+ * 后端 InterviewNotificationServiceImpl:179-200 对每个字段都是「非空才 set」，
+ * 传 null 等于不传；所以旧写法无 flag 时发出的那五个 null 既清不掉任何东西，
+ * 也不会更新任何列——一条纯粹的空写请求。
+ */
+function updatePayload(ctx) {
+  const base = {}
+  const title = flagString(ctx, 'title')
+  if (title !== undefined) base.title = title
+  const content = flagString(ctx, 'content')
+  if (content !== undefined) base.content = content
+  const noticeLevel = flagEnum(ctx, 'notice-level', NOTICE_LEVELS)
+  if (noticeLevel !== undefined) base.noticeLevel = noticeLevel
+  const scopeType = flagEnum(ctx, 'scope-type', SCOPE_TYPES)
+  if (scopeType !== undefined) base.scopeType = scopeType
+  applyScopeTargets(ctx, base, scopeType)
+  for (const flag of WINDOW_TIME_FLAGS) {
+    const value = flagString(ctx, flag)
+    if (value !== undefined) base[camelCase(flag)] = normalizeLocalTime(value)
+  }
+  const status = flagEnum(ctx, 'status', ['1', '2'])
+  if (status !== undefined) base.status = Number(status)
+  const payload = payloadFrom(ctx, base)
+  if (Object.keys(payload).length === 0) {
+    throw usageError('至少提供一个修改字段', '--title / --content / --notice-level / --scope-type / --target-* / --start-time / --end-time / --status')
+  }
+  return payload
+}
+
+register('notifications list', {
+  summary: '横幅通知列表',
+  usage: 'ch notifications list [--scope-type ALL|ROUND|GROUP|ROUND_GROUP|SLOT] [--status 1|2] [--pretty]',
+  endpoints: ['GET /admin/notifications'],
+  run: async (ctx) => {
+    const query = collectQuery(ctx, { 'scope-type': { key: 'scopeType' }, status: {} })
+    const { data } = await ctx.client.request({ method: 'GET', path: '/admin/notifications', query })
+    return data
+  },
+})
+
+register('notifications create', {
+  summary: '发布横幅通知',
+  usage: 'ch notifications create --title 标题 --content 内容 --notice-level INFO|WARNING|URGENT --scope-type ALL|ROUND|GROUP|ROUND_GROUP|SLOT [--target-round N] [--target-group-id N] [--target-slot-id N] [--start-time "..."] [--end-time "..."] [--status 1|2]',
+  endpoints: ['POST /admin/notifications'],
+  run: async (ctx) => {
+    const payload = createPayload(ctx)
+    const { data } = await ctx.client.request({ method: 'POST', path: '/admin/notifications', body: payload })
+    return data
+  },
+})
+
+register('notifications update', {
+  summary: '编辑横幅通知',
+  usage: 'ch notifications update <id> [--title ...] [--content ...] [--notice-level ...] [--scope-type ...] [--start-time ...] [--end-time ...]',
+  endpoints: ['PUT /admin/notifications/{id}'],
+  run: async (ctx) => {
+    const id = idParam(ctx.positionals[0], { label: '通知 id' })
+    const payload = updatePayload(ctx)
+    const { data } = await ctx.client.request({ method: 'PUT', path: `/admin/notifications/${id}`, body: payload })
+    return data === null ? { updated: true, id: Number(id) } : data
+  },
+})
+
+register('notifications status', {
+  summary: '上/下线路横幅通知',
+  usage: 'ch notifications status <id> --status 1|2',
+  endpoints: ['PATCH /admin/notifications/{id}/status'],
+  run: async (ctx) => {
+    const id = idParam(ctx.positionals[0], { label: '通知 id' })
+    const status = flagEnum(ctx, 'status', ['1', '2'], { required: true, label: 'ch notifications status <id> --status 1|2' })
+    const payload = payloadFrom(ctx, { status: Number(status) })
+    const { data } = await ctx.client.request({ method: 'PATCH', path: `/admin/notifications/${id}/status`, body: payload })
+    return data === null ? { updated: true, id: Number(id) } : data
+  },
+})
+
+register('notifications delete', {
+  summary: '删除横幅通知',
+  usage: 'ch notifications delete <id>',
+  endpoints: ['DELETE /admin/notifications/{id}'],
+  run: async (ctx) => {
+    const id = idParam(ctx.positionals[0], { label: '通知 id' })
+    const { data } = await ctx.client.request({ method: 'DELETE', path: `/admin/notifications/${id}` })
+    return data === null ? { deleted: true, id: Number(id) } : data
+  },
+})