WhatIDo/PLAN_MULTI_BRANCH.md

План: Мультифилиальность и роли пользователей

Проблема

Сейчас приложение однофилиальное и одно-user-овое. Нужно поддержать:

• 5-20 филиалов
• Несколько тьюторов/админов
• Филиал студента определяется автоматически через его группу

---

1. База данных — схема

Новые таблицы

-- Филиалы
CREATE TABLE branches (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT now()
);

-- Пользователи системы
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(150) NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role VARCHAR(20) NOT NULL DEFAULT 'tutor', -- 'admin' или 'tutor'
    branch_id INT REFERENCES branches(id), -- NULL для супер-админа
    created_at TIMESTAMPTZ DEFAULT now()
);

Изменения в существующих таблицах

Таблица	Новое поле	Тип	Связь
groups	branch_id	INT	REFERENCES branches(id)
students	branch_id	INT	REFERENCES branches(id)
entries	branch_id	INT	REFERENCES branches(id)
group_photos	branch_id	INT	REFERENCES branches(id)

Логика определения филиала

• Студент → в группе → группа привязана к филиалу → филиал определён
• При отправке записи branch_id берётся из группы студента
• Студенту не нужно выбирать филиал — он определяется автоматически

---

2. Аутентификация

• Вход по имени + пароль (без email)
• Пароли хранятся в bcrypt хеше
• Токен (JWT) выдаётся при логине, хранится в sessionStorage
• requireAdmin заменяется на requireAuth + проверку роли

---

3. Роли

Роль	Возможности
admin	Всё: управление пользователями, филиалами, настройками, бэкапами + все данные
tutor	Управление записями, группами, студентами, файлами, ссылками — видит все группы

---

4. Публичная форма

• Ссылка на форму одна (как сейчас)
• Студент вводит имя → система находит студента → определяет группу → определяет филиал
• Если студент новый (нет в базе) — варианты на обсуждение:
  • Не пускать (только зарегистрированные студенты)
  • Автоматически создать в группе "Не распределён"

---

5. Фронтенд — изменения

Страница логина

• Поле "Имя" + "Пароль" вместо одного пароля

Админ-панель

• В хедере/сайдбаре выпадающий список филиалов для фильтрации
• Группы — отображение филиала у каждой группы
• Студенты — отображение филиала у каждого студента
• Журнал — фильтр по филиалу
• Настройки — управление пользователями и филиалами (только для admin)

---

6. API — новые эндпоинты

Метод	Путь	Описание
POST	/api/auth/login	Вход (имя + пароль → токен)
GET	/api/branches	Список филиалов
POST	/api/branches	Создать филиал (admin)
DELETE	/api/branches/:id	Удалить филиал (admin)
GET	/api/users	Список пользователей (admin)
POST	/api/users	Создать пользователя (admin)
DELETE	/api/users/:id	Удалить пользователя (admin)

---

7. Миграция данных

• Существующие группы/студенты/записи автоматически попадут в филиал "Основной" (или первый созданный)
• ADMIN_PASSWORD из .env конвертируется в запись users с ролью admin

---

8. Структура файлов (рефакторинг)

server.js → рефакторинг на модули:
├── routes/
│   ├── auth.js        (логин/аутентификация)
│   ├── branches.js    (CRUD филиалов)
│   ├── users.js       (CRUD пользователей)
│   ├── groups.js      (существующие + branch_id)
│   ├── students.js    (существующие + branch_id)
│   ├── entries.js     (существующие + branch_id)
│   └── ...
├── middleware/
│   ├── auth.js        (requireAuth, requireRole)
│   └── branch.js      (branch scoping)
└── db.js              (подключение к БД)

---

Порядок реализации

1. Миграция БД — создать таблицы branches, users, добавить branch_id к существующим
2. Миграция данных — создать филиал "Основной", перенести существующие данные
3. Бэкенд: аутентификация — auth.js (логин, JWT, middleware)
4. Бэкенд: CRUD филиалов и пользователей — новые роуты
5. Бэкенд: branch scoping — добавить branch_id ко всем существующим запросам
6. Фронтенд: логин — новая страница логина
7. Фронтенд: admin panel — добавить фильтр филиалов, страницы управления
8. Тестирование — проверить все сценарии