rules

rules.md

@@ -0,0 +1,87 @@
+## Правила оформления студенческих бэкендов в `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.
+
+