web-start

Русский · English

Стартовый набор для веб-проектов: бэкенд на Django + FastAPI и фронт на Nuxt 4.

Две роли

• Движок похожих сайтов. У сайтов разный дизайн и меню, а блог, страницы, формы, SEO и карта сайта — общие. Общее живёт здесь и выходит версиями, у каждого сайта — свой репозиторий с дизайном.
• Старт отдельного проекта — большого приложения со своей логикой. Копируешь back/ и front/, дальше проект живёт сам: обновления отсюда переносишь вручную, если нужны.

Что внутри

Папка	Что	Подробно
back/	бэкенд: Django — модели, миграции, админка; FastAPI — API; модули user, page, form, log	back/readme.md
front/	движок сайтов на Nuxt 4 и Nuxt UI: слои core, form, page, user и демо-сайт	front/readme.md

Модуль бэкенда и слой фронта с одним именем — пара: page ↔ page, form ↔ form. Меняются они вместе, поэтому и живут в одном репозитории под одной версией.

Как это работает

Посетитель сайта (браузер)
├─ открыл страницу ──→ сервер сайта: Nuxt + движок ──→ кэш /_page-api ──→ API /api/page/…
├─ переходы по сайту, формы, вход, кабинет ───────────────────────────→ API /api/…
└─ картинки /media/… ──→ сервер сайта ────────────────────────────────→ бэкенд /media/…

Редактор (браузер) ──→ админка /admin

Бэкенд: /api/* — FastAPI и Tortoise ORM, остальное — Django; база одна, PostgreSQL.
Письма и другое долгое — фоновые задачи: в процессе API или через Redis и воркер.

• Страницу сайт рендерит на своём сервере, а данные берёт через свой кэш: иначе запросы всех посетителей шли бы к API с одного адреса — слой page.
• Вход и кабинет — из браузера прямо в API, refresh-токен — в куке бэкенда, поэтому бэкенд живёт на поддомене сайта — слой user.
• Как бэкенд делит запросы и зачем ему две ORM — back/docs/architecture.md.

Сайт на web-start

Где	Что
репозиторий сайта	дизайн: шапка, подвал, главная, свои страницы, цвета; версия движка
сервер сайта	бэкенд той же версии web-start, что и фронт; свой .env и своя база
база бэкенда сайта	контент: страницы, статьи, формы, заявки

• Фронт сайта подключает движок одной строкой в nuxt.config.ts: extends: [['gh:mcnickbronx/web-start/front#v1.0.0', { install: true }]]. Подробно — front/readme.md.
• Бэкенд сайта — образ того же коммита: DEPLOY_IMAGE=…/web-start-back:<хеш> в .env сервера. Сменили хеш — сервер выложит новую версию сам. Подробно — back/docs/deploy.md.
• Новый сайт — свой репозиторий на Nuxt с этой строкой extends и бэкенд на своём сервере: что нужно от сервера — back/docs/deploy.md.

Версии

Одна версия на обе части — тег репозитория: v1.4.0 = мажорная.минорная.патч. Что изменилось — CHANGELOG.md.

• Мажорная (v2.0.0) — при обновлении сайту придётся что-то сделать руками:
  • бэкенд: новая обязательная настройка в .env, из API убрали или переименовали эндпоинт или поле, ручные шаги кроме migrate;
  • фронт: изменился «договор» с сайтом — то, что описано в readme слоёв: composables, имена и свойства компонентов, адреса страниц, настройки app.config, переменные окружения.
• Минорная (v1.5.0) — новое без поломок: эндпоинт, поле, модуль, миграции, компонент, настройка. Обновлять смело; есть миграции — так и пишем в CHANGELOG.
• Патч (v1.4.1) — исправления.

Сайт стоит на одной версии движка, а не на ветке: фронт — #v1.4.0 или полный хеш коммита в extends, бэкенд — полный хеш того же коммита в DEPLOY_IMAGE. Новое в web-start само на сайт не попадает: сайт обновляют, когда решат, — меняют хеш в обоих местах.

Бэкенд сайта и движок во фронте — всегда одной версии, обновляются вместе: клиент API в движке собран по бэкенду своего же коммита (npm run api:types берёт схему из кода back/). Порядок — сначала бэкенд, потом фронт: прежний фронт с новым бэкендом работает, пока из API ничего не убрали (а убрать — это мажорная версия), новый фронт со старым бэкендом не найдёт новых полей и адресов.

Пока сайт один, версии выпускаются редко, пачкой изменений, а между выпусками сайт ставят на хеш коммита main — он так же неизменен, как тег. Ветка (#main, :main) — нельзя: сайт менялся бы от каждого push. Исключение — бэкенд dev-проекта: он сам идёт за веткой dev, на нём движок проверяют до сайтов.

Как выпустить версию

Работа идёт в ветке dev (push — выкладка на dev-проект), выпуск — dev целиком в main и тег на нём. Push в main сайты не меняет: они переходят на версию, когда их обновят.

1. В CHANGELOG.md раздел «Не выпущено» переименовать в ## 1.5.0 — 29.09.2026.
2. Слить, поставить тег и отправить:

   git switch main && git merge --ff-only dev
   git tag -a v1.5.0 -m "Коротко: что в версии"
   git push origin main v1.5.0
   git switch dev

Недоделанное лежит в dev и сайтам не мешает: каждый сайт стоит на своём коммите. --ff-only не даст слить, если в main есть коммиты мимо dev. Тег не переносить и не удалять — ошибся в выпуске, выпускай следующий патч.

Срочное исправление, когда в dev уже лежит недоделанное, — прямо в main:

git switch main
# исправить, закоммитить
git tag -a v1.5.1 -m "Что исправлено"
git push origin main v1.5.1
git switch dev && git merge main && git push origin dev   # исправление — и в dev

Затем сайты — на этот коммит, как при обычном обновлении.

Документация

Новому человеку — по порядку:

1. этот readme — роли, части, как всё работает вместе, версии;
2. как устроен бэкенд — путь запроса по файлам, две ORM, что легко сломать;
3. правила кода — бэкенда и фронта: структура модуля и слоя, имена, ошибки API;
4. readme модуля бэкенда или слоя фронта, с которым работаешь, — список в readme части.

Все документы:

• Правила работы — где правила каждой части и что у них общего
• Изменения по версиям — что нового и что сделать сайту при обновлении
• Бэкенд — устройство, запуск, модули, деплой; оглавление его документов — там же
• Фронт — движок сайтов, сайт на движке, слои; оглавление — там же

Лицензия

MIT: можно брать, менять и использовать в своих и коммерческих проектах, сохранив строку об авторских правах.