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