multy-stub/rules.md

Правила оформления студенческих бэкендов в 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.