Гайдлайны Технопарка: рубежные контроли командного проекта

Ожидания преподавателей Технопарка (VK Education, курс по веб-разработке, 2-й семестр) к рубежным контролям командного проекта. Команда из четырёх студентов — два фронтенда и два бэкенда — делает фуллстек-аналог сервиса. На каждом рубежном контроле (РК) проверяют, что работает и что команда понимает, как это устроено.

Для кого

• Студенты — что обязательно сделать к РК, объяснение, как это устроено, самопроверка и подготовка к вопросам на защите.
• Менторы и преподаватели — чек-лист приёмки и вопросы с критериями ответа.

Обе аудитории видят все файлы. Критерии ответов спрятаны под раскрывающимся блоком, чтобы вопросы можно было прочитать без подсказки.

Рубежные контроли

РК	Тема	С чего начать
РК1	Аутентификация, сессия и доступ к данным	rk1/README.md

Пока есть только РК1; материалы следующих РК появятся рядом, в своих папках.

Как читать

Начните с README.md папки своего РК. В нём требования, обязательный минимум (невыполнение любого пункта — РК не сдан), варианты реализации и маршрут чтения: что читать студенту по порядку и что нужно ментору. Остальные файлы ссылаются друг на друга, поэтому читать подряд всё не обязательно.

Сайт

Материалы читаются и на сайте: https://tp-prepare.github.io/technopark-guidelines/. Он собирается из этих же файлов при каждом merge в main, отдельного контента у сайта нет. Версии расширения «Все cookie» и описание изменений — в GitHub Releases.

Как предложить правку

Нашли ошибку, устаревший пример или непонятное место — напишите. Студенты тоже могут: если вопрос возник у вас, он возникнет и у следующего потока.

• Issue — если хотите сообщить о проблеме или задать вопрос. Укажите файл и раздел.
• Pull request — если знаете, как исправить. PR идёт в main, в описании — разделы «Что», «Решения», «Проверка». main защищён: сливается только PR с зелёным CI.

Правила текста:

• язык — русский, термины — в оригинале (SameSite, preflight, CSRF);
• примеры обезличенные: example.ru, api.example.ru, avatars.example.ru, evil.example; без названий проектов и команд, реальных адресов, IP и токенов;
• утверждение о поведении браузера или стандарта сверяется с источником (MDN, OWASP, RFC 6265bis, спецификация Fetch), каждый файл заканчивается разделом ## Источники;
• заголовки только через # (#, ##, …): проверка ссылок не понимает подчёркнутые заголовки.

Для авторов правок: схемы и проверки

Нужны Bun 1.3 или новее и, для рендера схем, Docker.

bun install

Схемы бывают двух видов:

• Mermaid — sequenceDiagram прямо в Markdown. Участники с короткими ASCII-алиасами (participant B as Браузер), без ; и # в сообщениях, одна диаграмма — одно событие.
• Eraser — JSON в rk*/diagrams/, рядом с ним PNG и .png.sha256. Правятся только по скиллу .claude/skills/eraser-diagrams/SKILL.md: формат, цвета, раскладка и цикл bun run validate → bun run check → bun run warm → bun run render → осмотр PNG → bun run fresh. PNG и .png.sha256 коммитятся вместе с JSON: CI схемы не рендерит, а только проверяет, что PNG не устарел.

bun run render и bun run mermaid идут в Docker-образе из Dockerfile, как в CI. Без Docker — DIAGRAMS_NATIVE=1 и путь к Chrome в CHROMIUM_PATH перед командой.

Перед PR:

bun run typecheck && bun run test && bun run validate && bun run check \
  && bun run fresh && bun run links && bun run mermaid && bun run ext:build && bun run ext:zip \
  && bun run site:build && bun run site:check

links проверяет относительные ссылки и якоря между .md, mermaid — что каждая диаграмма собирается. ext:build собирает расширение в tools/cookie-viewer/dist/, ext:zip кладёт архив в public/cookie-viewer.zip (сайт отдаёт его по адресу /cookie-viewer.zip). site:build собирает сайт, site:check проверяет собранное: ссылки, якоря и картинки, в том числе ссылку на архив.

Сайт на VitePress. Локально:

bun run site:dev      # http://localhost:5173/technopark-guidelines/
bun run site:build && bun run site:check
bun run site:preview  # http://localhost:4173/technopark-guidelines/, после site:build

Как добавить РК:

1. Создайте папку rkN/ с README.md и остальными файлами.
2. Добавьте запись в .vitepress/rk.ts: dir, title, nav, pages; первая страница — README. Элемент pages — имя страницы, { page, text } (короткая подпись в меню) или группа { text, link?, items } (один уровень; link вроде README#якорь).
3. Добавьте строку в таблицу «Рубежные контроли» в этом файле.

Расширение «Все cookie» для DevTools лежит в tools/cookie-viewer/ (TypeScript, Manifest V3), страницы раздела «Инструменты» — tools/*.md. Для разработки выполните bun run ext:build, откройте chrome://extensions, включите режим разработчика и загрузите распакованное расширение из tools/cookie-viewer/dist; после правок снова bun run ext:build и «Обновить» на карточке расширения. В tools/cookie-viewer/ нет .md: иначе файл станет страницей сайта.

Изменили tools/cookie-viewer/ — поднимите version в manifest.json: CI выпустит релиз cookie-viewer-v<version> после мержа. Без смены версии релиза не будет.

Папка, которой нет в реестре, на сайт не попадает: черновики можно держать в main. Страница, не перечисленная в pages, роняет bun test.

Правила для авторов страниц:

• Опубликованная страница не ссылается на РК, которого ещё нет в реестре: сборка падает на битой ссылке.
• На файлы репозитория не в Markdown (JSON, скрипты) ссылайтесь полным адресом GitHub, иначе site:check найдёт битую ссылку.

Подробнее о правилах репозитория — в CLAUDE.md.