feat(permissions): C-1 — фундамент кастомных ролей (roles table + наследование гейтов)

Phase C, Stage C-1 (ветка feature/custom-roles): таблица roles (name, label,
base_roles JSON, is_builtin) + засев встроенных. auth.effectiveRoles(role) —
кастомная роль наследует base_roles (какие встроенные гейты проходит); встроенные
— быстрый путь без БД. requireRole() теперь проверяет пересечение allowed с
effectiveRoles → 111 существующих гейтов не задеты (встроенные ведут себя как
прежде). Дизайн: PHASE_C_DESIGN.md. Тест effectiveRoles 5/5; полный backend pass.

ВАЖНО (обнаружено): users.role в канон-схеме имеет CHECK (admin/teacher/student/
free_student), безопасно пересобрать users (FK от многих таблиц, миграции в txn)
нельзя → присвоение кастомной роли пользователю пойдёт через users.custom_role (C-2).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

backend/src/db/migrations/054_roles.sql

@@ -0,0 +1,22 @@
+-- 054_roles.sql
+-- Phase C (кастомные роли), Stage C-1 — реестр ролей.
+-- Модель: роль наследует «базовые роли» (base_roles) — какие встроенные гейты
+-- requireRole она проходит. Встроенные роли наследуют сами себя. Кастомную роль
+-- админ создаёт со своим набором base_roles (доступ) и набором прав (см. C-2).
+--
+-- users.role хранит ИМЯ роли (CHECK на users.role нет — новое имя допустимо).
+-- requireRole() расширяет роль пользователя до effectiveRoles по этой таблице.
+
+CREATE TABLE IF NOT EXISTS roles (
+  name        TEXT PRIMARY KEY,
+  label       TEXT NOT NULL,
+  base_roles  TEXT NOT NULL DEFAULT '[]',   -- JSON-массив встроенных ролей, чьи гейты проходит
+  is_builtin  INTEGER NOT NULL DEFAULT 0,
+  created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT OR IGNORE INTO roles (name, label, base_roles, is_builtin) VALUES
+  ('admin',        'Администратор',     '["admin"]',                  1),
+  ('teacher',      'Учитель',           '["teacher"]',                1),
+  ('student',      'Ученик',            '["student"]',                1),
+  ('free_student', 'Свободный ученик',  '["free_student","student"]', 1);

backend/src/middleware/auth.js

@@ -32,13 +32,30 @@ function authMiddleware(req, res, next) {
   }
 }
 
+/* Кастомные роли наследуют «базовые роли» (какие встроенные гейты проходят).
+   Встроенные роли — быстрый путь без обращения к БД. */
+const BUILTIN_ROLES = new Set(['admin', 'teacher', 'student', 'free_student']);
+let _roleBaseStmt = null;
+function effectiveRoles(role) {
+  if (!role) return [];
+  if (BUILTIN_ROLES.has(role)) return [role];
+  try {
+    if (!_roleBaseStmt) _roleBaseStmt = db.prepare('SELECT base_roles FROM roles WHERE name = ?');
+    const row = _roleBaseStmt.get(role);
+    if (row && row.base_roles) {
+      const arr = JSON.parse(row.base_roles);
+      if (Array.isArray(arr) && arr.length) return arr.indexOf(role) >= 0 ? arr : arr.concat(role);
+    }
+  } catch (_e) { /* таблицы roles может не быть на старом инстансе — деградация к самой роли */ }
+  return [role];
+}
+
 function requireRole(...roles) {
   return (req, res, next) => {
-    if (!roles.includes(req.user?.role)) {
-      if (req.user) logDenied(req, 'forbidden', `роль ${req.user.role}; требуется ${roles.join('/')}`);
-      return res.status(403).json({ error: 'Forbidden' });
-    }
-    next();
+    const eff = effectiveRoles(req.user?.role);
+    if (eff.some(r => roles.includes(r))) return next();
+    if (req.user) logDenied(req, 'forbidden', `роль ${req.user.role}; требуется ${roles.join('/')}`);
+    return res.status(403).json({ error: 'Forbidden' });
   };
 }
 
@@ -130,4 +147,4 @@ function optionalAuth(req, res, next) {
   next();
 }
 
-module.exports = { authMiddleware, requireAuth, optionalAuth, requireRole, requirePermission, perm, parentAuth };
+module.exports = { authMiddleware, requireAuth, optionalAuth, requireRole, requirePermission, perm, parentAuth, effectiveRoles };