competition-website/app/lib/adminPermissions.js

'use strict';

/**
 * 管理端权限点与「路由 → 权限」映射（R178·C 层唯一真相源）
 * ============================================================================
 *
 * 为什么需要这层：后端有 63 条 /api/admin/* 路由，原本全部只挂 adminAuth（role='admin'）。
 * 在本模块之前，「是管理员」等于「有全部权限」—— 无法做到「只给阅卷、不给发布」。
 *
 * 三条设计纪律（改动前必读）：
 *
 * 1. **默认拒绝**：`resolvePermission()` 匹配不到任何规则时返回 null，
 *    中间件对 null **直接 403**，而不是放行。
 *    ⇒ 新增路由若忘了登记规则，表现是「功能不可用」而非「静默成为人人可用的后门」。
 *
 * 2. **单一真相源**：路由的权限归属只在本文件声明，⛔ 不得在 router.js 逐条写权限参数
 *    （那会让 63 条路由各带一份权限字符串，与本表必然漂移，且无人能核对全集）。
 *    全集对齐由门禁 `scripts/verify_admin_rbac.py` 双向断言：
 *      「router.js 的 /api/admin 路由全集」== 「ROUTE_RULES 覆盖集」，两个方向差集都必须为空。
 *
 * 3. **多权限其一（anyOf）**：部分接口被两个菜单共用（如成绩复核页复用成绩列表），
 *    用 `perms: ['scores','review']` 表达「具备任一即可」。这不会降低安全性 ——
 *    任何一条都需被显式授予，只是避免「勾了复核却被 403」的误伤。
 *
 * 高危权限点单独成项（score.publish / data.reset / admins.manage），
 * 目的是把「能看成绩」与「能发布成绩」分开 —— 这两件事的责任人通常不同。
 */

const MODULE = 'module';
const HIGH_RISK = 'highRisk';

/**
 * 全部权限点。顺序即前端展示顺序。
 * ⚠️ 新增权限点必须同步：① 本数组；② ROUTE_RULES 至少一条规则；③ 前端 `can()` 使用处。
 */
const PERMISSIONS = [
  { key: 'dashboard', label: '数据总览', group: MODULE, desc: '查看各组账号数 / 提交数 / 激活率' },
  { key: 'accounts', label: '选手管理', group: MODULE, desc: '查看选手、导入报名表、编辑选手信息、标记测试数据' },
  { key: 'questions', label: '试卷管理', group: MODULE, desc: '客观题与综合大题题库维护、Word 模板' },
  { key: 'materials', label: '备赛资料', group: MODULE, desc: '上传 / 删除备赛资料' },
  { key: 'submissions', label: '作品管理', group: MODULE, desc: '查看作品与答题记录、下载作品文件' },
  { key: 'times', label: '时间设置', group: MODULE, desc: '考试起止时间、抽题数量、节点备份状态' },
  { key: 'scores', label: '成绩管理', group: MODULE, desc: '阅卷打分、导出成绩、生成公示表（不含发布）' },
  { key: 'review', label: '成绩复核', group: MODULE, desc: '按选手查验分项得分' },
  { key: 'news', label: '新闻管理', group: MODULE, desc: '新闻增删改、置顶、附件上传、发布 / 撤回' },
  { key: 'carousel', label: '轮播管理', group: MODULE, desc: '首页轮播图增删改与排序' },
  { key: 'score.publish', label: '发布 / 撤回成绩', group: HIGH_RISK, desc: '控制考生端能否看到成绩，并自动生成公示草稿' },
  { key: 'data.reset', label: '重置测试数据 / 删除选手', group: HIGH_RISK, desc: '会真实删除数据的操作，仅授予负责人' },
  { key: 'admins.manage', label: '管理员账号管理', group: HIGH_RISK, desc: '新增 / 删除管理员、分配权限、重置口令、禁用' },
];

const PERMISSION_KEYS = PERMISSIONS.map(p => p.key);
const PERMISSION_KEY_SET = new Set(PERMISSION_KEYS);

/**
 * 路径模式 → 正则。`:xxx` 段匹配任意单段（不含 `/`）。
 * 其余字符按字面转义，避免 `/api/admin/big-questions/:group/:id` 里的 `-` `.` 被当元字符。
 */
function toRegExp(pattern) {
  const src = pattern
    .split('/')
    .map((seg) => {
      if (seg.startsWith(':')) return '[^/]+';
      return seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
    })
    .join('/');
  return new RegExp('^' + src + '$');
}

/**
 * 路由规则表。**顺序敏感**：更具体的路径必须排在带 `:id` 的通配路径之前
 * （如 `/news/order` 必须在 `/news/:id` 之前），否则会被后者抢先匹配。
 *
 * ⚠️ 每条规则的 perms 至少一个；`perms` 语义 = 「具备其中之一即可」。
 */
const ROUTE_TABLE = [
  // ---------- 自助信息（登录即可，无需业务权限） ----------
  // 前端用它得知「我有哪些权限」以渲染菜单，并感知权限是否被他人改动。
  // ⚠️ perms 为空数组是本表唯一允许的「显式放行」写法，门禁会断言只有本行如此。
  ['GET', '/api/admin/me', []],

  // ---------- 管理员账号管理（高危） ----------
  ['GET', '/api/admin/admin-users', ['admins.manage']],
  ['POST', '/api/admin/admin-users', ['admins.manage']],
  ['PUT', '/api/admin/admin-users/:id/permissions', ['admins.manage']],
  ['PUT', '/api/admin/admin-users/:id/password', ['admins.manage']],
  ['PUT', '/api/admin/admin-users/:id/status', ['admins.manage']],
  ['DELETE', '/api/admin/admin-users/:id', ['admins.manage']],

  // ---------- 数据总览 ----------
  ['GET', '/api/admin/stats', ['dashboard']],

  // ---------- 选手管理 ----------
  ['GET', '/api/admin/accounts', ['accounts']],
  ['GET', '/api/admin/teams', ['accounts']],
  ['POST', '/api/admin/import-excel', ['accounts']],
  ['POST', '/api/admin/contestants/backfill-teacher', ['accounts']],
  ['PUT', '/api/admin/contestants/:id', ['accounts']],
  ['POST', '/api/admin/toggle-test-flag', ['accounts']],
  // 重置测试数据是真实删除，单列高危（不给「只做选手维护」的人）
  ['POST', '/api/admin/reset-test-data', ['data.reset']],

  // ---------- 作品管理 ----------
  // 成绩管理页的「考生答题记录」也读 submissions 接口 ⇒ 允许 scores 其一
  ['GET', '/api/admin/submissions/:group', ['submissions', 'scores']],
  ['GET', '/api/admin/submission-file/:group/:id', ['submissions']],
  ['GET', '/api/admin/submissions/:group/:id/word', ['submissions']],
  ['GET', '/api/admin/works/:group', ['submissions']],
  ['GET', '/api/admin/batch-download/:group', ['submissions']],
  // R190 单小组作品压缩包：与批量下载同属「作品管理」能力，同权限即可
  ['GET', '/api/admin/team-zip/:group', ['submissions']],

  // ---------- 成绩管理（阅卷/导出/公示表） ----------
  ['GET', '/api/admin/scores/:group', ['scores', 'review']],
  ['PUT', '/api/admin/scores/:group', ['scores']],
  ['GET', '/api/admin/export-csv/:group', ['scores']],
  ['GET', '/api/admin/export-excel/:group', ['scores']],
  ['GET', '/api/admin/export-publicity/:group', ['scores']],
  ['GET', '/api/admin/competition-item', ['scores']],
  ['PUT', '/api/admin/competition-item', ['scores']],
  ['GET', '/api/admin/big-answers/:group', ['scores', 'review']],
  ['GET', '/api/admin/big-answers/:group/export', ['scores']],
  ['GET', '/api/admin/big-answers/:group/import-template', ['scores']],
  ['POST', '/api/admin/big-answers/:group/import-preview', ['scores']],
  ['POST', '/api/admin/big-answers/:group/import-scores', ['scores']],
  ['PUT', '/api/admin/big-answers/:group/:uid/scores', ['scores']],
  ['GET', '/api/admin/publish-scores', ['scores', 'review']],
  // 发布 / 撤回 = 高危：能看成绩 ≠ 能公布成绩
  ['PUT', '/api/admin/publish-scores', ['score.publish']],

  // ---------- 时间设置 ----------
  ['GET', '/api/admin/times', ['times']],
  ['PUT', '/api/admin/times', ['times']],
  ['GET', '/api/admin/node-backup/status', ['times']],

  // ---------- 试卷管理 ----------
  ['GET', '/api/admin/exam/:group/questions', ['questions']],
  ['PUT', '/api/admin/exam/:group/questions', ['questions']],
  ['POST', '/api/admin/exam/:group/questions/import-excel', ['questions']],
  ['GET', '/api/admin/exam/:group/questions/template', ['questions']],
  ['PUT', '/api/admin/exam/:group/word-template', ['questions']],
  ['GET', '/api/admin/exam/:group/word-template', ['questions']],
  ['DELETE', '/api/admin/exam/:group/word-template', ['questions']],
  ['GET', '/api/admin/big-questions/:group', ['questions']],
  ['POST', '/api/admin/big-questions/:group', ['questions']],
  ['GET', '/api/admin/big-questions/:group/export', ['questions']],
  ['GET', '/api/admin/big-questions/:group/template', ['questions']],
  ['POST', '/api/admin/big-questions/:group/import-excel', ['questions']],
  ['PUT', '/api/admin/big-questions/:group/:id', ['questions']],
  ['DELETE', '/api/admin/big-questions/:group/:id', ['questions']],

  // ---------- 备赛资料 ----------
  ['GET', '/api/admin/materials/:group', ['materials']],
  ['POST', '/api/admin/materials/:group', ['materials']],
  ['DELETE', '/api/admin/materials/:group/:fileName', ['materials']],

  // ---------- 新闻管理 ----------
  // ⚠️ /news/order 必须排在 /news/:id 之前
  ['PUT', '/api/admin/news/order', ['news']],
  ['GET', '/api/admin/news', ['news']],
  ['POST', '/api/admin/news', ['news']],
  ['PUT', '/api/admin/news/:id', ['news']],
  ['DELETE', '/api/admin/news/:id', ['news']],
  ['POST', '/api/admin/upload/news-image', ['news']],
  ['POST', '/api/admin/upload/news-file', ['news']],

  // ---------- 轮播管理 ----------
  // ⚠️ /carousel/order 必须排在 /carousel/:id 之前
  ['PUT', '/api/admin/carousel/order', ['carousel']],
  ['GET', '/api/admin/carousel', ['carousel']],
  ['POST', '/api/admin/carousel', ['carousel']],
  ['PUT', '/api/admin/carousel/:id', ['carousel']],
  ['DELETE', '/api/admin/carousel/:id', ['carousel']],
  ['POST', '/api/admin/upload/image', ['carousel']],

  // ---------- 成绩复核 ----------
  ['GET', '/api/admin/review/search', ['review']],
  ['GET', '/api/admin/review/score/:group/:id', ['review']],
].map(([method, pattern, perms]) => ({ method, pattern, perms, re: toRegExp(pattern) }));

/**
 * 解析请求需要哪些权限（任一即可）。
 *
 * @param {string} method - HTTP 方法（大小写不敏感）
 * @param {string} path - 请求路径（不含 query）
 * @returns {string[]|null} 权限点数组；null = 未登记（调用方必须拒绝）
 */
function resolvePermission(method, path) {
  const m = String(method || '').toUpperCase();
  const p = String(path || '').split('?')[0];
  for (const rule of ROUTE_TABLE) {
    if (rule.method !== m) continue;
    if (rule.re.test(p)) return rule.perms;
  }
  return null;
}

/**
 * 解析数据库里的 permissions 列（JSON 数组文本）。
 * 容错策略：解析失败 / 非数组 ⇒ 返回空数组（= 无权限），⛔ 绝不回落到「全权」。
 *
 * @param {string|null|undefined} raw
 * @returns {string[]}
 */
function parsePermissions(raw) {
  if (raw === null || raw === undefined || raw === '') return [];
  let arr = raw;
  if (typeof raw === 'string') {
    try {
      arr = JSON.parse(raw);
    } catch (e) {
      return [];
    }
  }
  if (!Array.isArray(arr)) return [];
  return arr.filter(k => typeof k === 'string' && PERMISSION_KEY_SET.has(k));
}

/**
 * 规整待写入的权限点：只保留已登记的 key，去重，按 PERMISSIONS 顺序排列。
 * ⛔ 必须过滤未知值 —— 否则前端传错一个字符串就会被存进库，
 *    将来某个新权限点恰好同名时会「凭空获得权限」。
 *
 * @param {string[]} list
 * @returns {string[]}
 */
function sanitizePermissions(list) {
  if (!Array.isArray(list)) return [];
  const set = new Set(list.filter(k => PERMISSION_KEY_SET.has(k)));
  return PERMISSION_KEYS.filter(k => set.has(k));
}

/**
 * 判断某管理员是否满足给定权限（任一命中即可）。
 *
 * ⚠️ 三种返回语义必须严格区分：
 *   required === null        ⇒ 未登记路由（由 resolvePermission 返回，调用方必须拒绝）
 *   required === []          ⇒ **显式声明**「登录即可，无需业务权限」（如 /api/admin/me）
 *   required === ['a','b']   ⇒ 具备任一即可
 *
 * @param {{is_super?:number|boolean, permissions?:string[]|string}} admin
 * @param {string[]|null} required
 * @returns {boolean}
 */
function canAccess(admin, required) {
  if (!admin) return false;
  // 🔴 顺序不可换（R178 运行期判据 P3-2 抓到）：**未登记路由对任何人都是拒绝**，
  //    包括最高管理员。若把 is_super 判在前面，`canAccess(super, null)` 会返回 true ——
  //    中间件虽然另有 `required === null ⇒ 403` 的前置分支，但那样「默认拒绝」就只活在
  //    一处调用约定里：任何新调用方（例如前端按钮显隐的服务端预判）漏判即成后门。
  //    此处作为第二道兜底，保证 null 永远不构成授权。
  if (!Array.isArray(required)) return false;
  if (Number(admin.is_super) === 1) return true;
  // 空数组 = 显式放行（仅限登记为「登录即可」的接口）
  if (required.length === 0) return true;
  const owned = Array.isArray(admin.permissions)
    ? admin.permissions
    : parsePermissions(admin.permissions);
  return required.some(k => owned.includes(k));
}

/**
 * 账号是否可被管理（改权限 / 重置口令 / 禁用 / 删除）。
 * 最高管理员一律不可变动 —— 这是用户明确裁定的硬约束，集中在单点判断，
 * ⛔ 不得在各接口里各写一遍 `id === 1`。
 *
 * @param {{is_super?:number|boolean}} admin
 * @returns {boolean}
 */
function isManageable(admin) {
  return !!admin && Number(admin.is_super) !== 1;
}

module.exports = {
  PERMISSIONS,
  PERMISSION_KEYS,
  PERMISSION_KEY_SET,
  ROUTE_TABLE,
  resolvePermission,
  parsePermissions,
  sanitizePermissions,
  canAccess,
  isManageable,
  MODULE,
  HIGH_RISK,
};