## Правила оформления студенческих бэкендов в `multi-stub`

Этот документ описывает, как подключать новый студенческий бэкенд к общему серверу и как работать с JSON‑заглушками. Правила написаны так, чтобы их мог автоматически выполнять помощник Cursor.

### 1. Общая структура проекта студента

- **Размещение проекта**
  - Каждый студенческий бэкенд живёт в своей подпапке в `server/routers/<project-name>`.
  - В корне подпапки должен быть основной файл роутера `index.js` (или `index.ts`), который экспортирует `express.Router()`.
  - Подключение к общему серверу выполняется в `server/index.ts` через импорт и `app.use(<mountPath>, <router>)`.

- **Использование JSON‑заглушек**
  - Если проект переносится из фронтенд‑репозитория и должен только отдавать данные, то в подпапке проекта должна быть папка `json/` со всеми нужными `.json` файлами.
  - HTTP‑обработчики в роутере могут просто читать и возвращать содержимое этих файлов (например, через `require('./json/...')` или `import data from './json/...json'` с включённым `resolveJsonModule` / соответствующей конфигурацией bundler'а).

### 2. Правила для Cursor при указании директории заглушек

Когда пользователь явно указывает директорию с заглушками (например: `server/routers/<project-name>/json`), помощник Cursor должен последовательно выполнить следующие шаги.

- **2.1. Проверка валидности импортов JSON‑файлов**
  - Найти все `.js` / `.ts` файлы внутри подпапки проекта.
  - В каждом таком файле найти импорты/require, которые ссылаются на `.json` файлы (относительные пути вроде `'./json/.../file.json'`).
  - Для каждого такого импорта:
    - **Проверить, что файл реально существует** по указанному пути относительно файла-импортёра.
    - **Проверить расширение**: путь должен заканчиваться на `.json` (без опечаток).
    - **Проверить регистр и точное совпадение имени файла** (важно для кросс‑платформенности, даже если локально используется Windows).
  - Если найдены ошибки (файл не существует, опечатка в имени, неправильный относительный путь и т.п.):
    - Сформировать понятный список проблем: в каком файле, какая строка/импорт и что именно не так.
    - Предложить автоматически исправить пути (если по контексту можно однозначно угадать нужный `*.json` файл).

- **2.2. Проверка подключения основного роутера проекта**
  - Определить основной файл роутера проекта:
    - По умолчанию это `server/routers/<project-name>/index.js` (или `index.ts`).
  - Открыть `server/index.ts` и убедиться, что:
    - Есть импорт роутера из соответствующей подпапки, например:
      - `import <SomeUniqueName>Router from './routers/<project-name>'`
      - или `const <SomeUniqueName>Router = require('./routers/<project-name>')`
    - Имя переменной роутера **уникально** среди всех импортов роутеров (нет другого импорта с таким же именем).
    - Есть вызов `app.use('<mount-path>', <SomeUniqueName>Router)`:
      - `<mount-path>` должен быть осмысленным, совпадать с названием проекта или оговариваться пользователем.
  - Если импорт или `app.use` отсутствуют:
    - Сформировать предложение по добавлению корректного импорта и `app.use(...)`.
    - Убедиться, что используемое имя роутера не конфликтует с уже существующими.
  - Если обнаружен конфликт имён:
    - Предложить переименовать новый роутер в уникальное имя и обновить соответствующие места в `server/index.ts`.

### 3. Предложение «оживить» JSON‑заглушки

После того как проверка импортов и подключения роутера завершена, помощник Cursor должен **задать пользователю вопрос**, не хочет ли он превратить заглушки в полноценный бэкенд.

- **3.1. Формулировка предложения**
  - Спросить у пользователя примерно так:
    - «Обнаружены JSON‑заглушки в директории `<указанная-папка>`. Хотите, чтобы я попытался автоматически:
      1) построить модели данных (mongoose‑схемы) на основе структуры JSON;
      2) создать CRUD‑эндпоинты и/или более сложные маршруты, опираясь на существующие данные;
      3) заменить прямую отдачу `*.json` файлов на работу через базу данных?»

- **3.2. Поведение при согласии пользователя**
  - Проанализировать структуру JSON‑файлов:
    - Определить основные сущности и поля.
    - Выделить типы полей (строки, числа, даты, массивы, вложенные объекты и т.п.).
  - На основе анализа предложить:
    - Набор `mongoose`‑схем (`models`) с аккуратной сериализацией (виртуальное поле `id`, скрытие `_id` и `__v`).
    - Набор маршрутов `express` для работы с этими моделями (минимум: чтение списков и элементов; по возможности — создание/обновление/удаление).
  - Перед внесением изменений:
    - Показать пользователю краткий план того, какие файлы будут созданы/изменены.
    - Выполнить изменения только после явного подтверждения пользователя.

### 4. Минимальные требования к новому студенческому бэкенду

- **Обязательные элементы**
  - Подпапка в `server/routers/<project-name>`.
  - Основной роутер `index.js` / `index.ts`, экспортирующий `express.Router()`.
  - Подключение к общему серверу в `server/index.ts` (импорт + `app.use()` с уникальным именем роутера).

- **Если используются JSON‑заглушки**
  - Папка `json/` внутри проекта.
  - Все пути в импортирующих файлах должны указывать на реально существующие `*.json` файлы.
  - Не должно быть «магических» абсолютных путей; только относительные пути от файла до нужного JSON.

- **Если проект «оживлён»**
  - Папка `model/` с моделью(ями) данных (например, через `mongoose`).
  - Роуты, которые вместо прямой отдачи файлов работают с моделями и, при необходимости, с внешними сервисами.

Следуя этим правилам, можно подключать новые студенческие проекты в единый бэкенд, минимизировать типичные ошибки с путями к JSON и упростить автоматическое развитие заглушек до полноценного API.