Статические файлы и дизайн
Cuento позволяет администраторам заменять стили форума, иконку и статические файлы прямо из панели управления — без доступа к серверу. Система черновиков дизайна позволяет предварительно просмотреть изменения CSS в живом браузере перед публикацией.
Как статические файлы попадают в браузер
Фронтенд Angular раздаётся как статические файлы из /var/www/frontend. В index.html прописаны жёсткие ссылки:
<link rel="stylesheet" href="/main_style.css">
<link rel="stylesheet" href="/custom_style.css">
<link rel="icon" href="favicon.ico">
Загрузка нового CSS-файла или иконки заменяет файл на диске по этому пути. Никакой динамической инъекции нет — браузер просто подхватывает новый файл при следующей загрузке.
Отслеживаемые статические файлы
Три канонических типа файлов хранятся с версионированием: main_style.css, custom_style.css и favicon.ico.
Загрузка (POST /static-file/upload): multipart-форма с полем file и полем file_type (должно быть одним из трёх канонических имён). Бэкенд:
- Архивирует текущий активный файл, переименовывая его с временны́м суффиксом (например,
main_style_2026-01-15_14-30-00.css). - Записывает новый файл в
/var/www/frontendи добавляет запись в таблицуstatic_files. - Публикует событие
StaticFileUploaded, которое удаляет старые версии — хранятся только 3 последних на каждый тип файла.
Список (GET /static-file/list/:file_type): возвращает 3 последних версии.
Откат (POST /static-file/revert): принимает { file_name } архивной версии и делает её активной, архивируя текущую.
Все три эндпоинта требуют роль 3 (администратор).
Черновики дизайна
Черновики дизайна позволяют редактировать CSS и мгновенно видеть результат в живой вкладке браузера — не затрагивая опубликованные файлы.
Создание и редактирование черновика
POST /admin/design-draft/create делает снимок текущих main_style.css и custom_style.css с диска в новую строку таблицы design_drafts (колонки main_css TEXT, custom_style_css TEXT). Для черновика генерируется случайный 12-символьный hex session_key.
Редактор черновика (компонент admin-design-draft-edit) имеет режим автосохранения: изменения откладываются на 3 секунды, затем отправляются через POST /admin/design-draft/update/:id. При изменении CSS бэкенд рассылает WebSocket-событие draft_updated всем вкладкам браузера, просматривающим этот черновик.
Живой предпросмотр
Откройте /?draft=<session_key> в любой вкладке браузера. Приложение обнаруживает параметр draft и заменяет hrefs в тегах <link> на:
GET /draft/<session_key>/main_style.css
GET /draft/<session_key>/custom_style.css
Эти эндпоинты отдают колонки main_css / custom_style_css из БД напрямую как text/css. К каждому href добавляется бастер кэша ?t=<timestamp>, который обновляется при каждом WebSocket-сообщении draft_updated — браузер перезагружает только изменённую таблицу стилей, не всю страницу. Параметр draft сохраняется при переходах по маршрутам Angular.
Вкладка предпросмотра отправляет WebSocket-хартбит { type: "draft_mode", draft_id: session_key } каждые 30 секунд, чтобы оставаться зарегистрированной как подписчик. Фоновая горутина удаляет подписчиков, не объявлявшихся более 60 секунд.
Эндпоинты CSS черновика публичны (аутентификация не требуется). Единственный механизм контроля доступа — session_key.
Публикация
POST /admin/design-draft/publish/:id запускает ту же логику архивирования и замены, что и прямая загрузка: архивирует текущие активные CSS-файлы и записывает содержимое CSS черновика на диск, запуская очистку версий.
Ассеты
Ассеты — произвольные статические файлы, раздаваемые из /assets/. Версионирование для них не предусмотрено.
Загрузка (POST /asset/upload): сохраняет файл в /var/www/frontend/assets/ под оригинальным именем (директорные компоненты отрезаются для защиты от path traversal). Файлы доступны в CSS и шаблонах как /assets/<имя файла>.
Список (GET /asset/list): читает директорию ассетов и возвращает [{ name, mod_time }].
Удаление (POST /asset/delete): принимает { name } и удаляет файл.
Серверная фильтрация по типу файла и ограничение размера отсутствуют.
Вариации дизайна
Вариации дизайна — это CSS-классы, хранимые в базе данных, которые пользователи могут выбирать в настройках аккаунта. При выборе вариации её class_name сохраняется в users.interface_design. Корневой элемент <app-root> получает этот класс через Angular-декоратор @HostBinding('class'), поэтому любое CSS-правило, ограниченное .my-variation-class, переопределяет базовые стили для этого пользователя глобально.
Администраторы управляют вариациями через POST /design-variation/create, POST /design-variation/update/:id и DELETE /design-variation/delete/:id. Имена классов значимы только при наличии соответствующих правил в main_style.css или custom_style.css.
Ключевые файлы
| Файл | Роль |
|---|---|
cuento-backend/src/Controllers/static_file.go |
Загрузка, список, откат, вспомогательная функция publishCssFile |
cuento-backend/src/Controllers/design_draft.go |
CRUD черновиков, публикация, отдача CSS |
cuento-backend/src/Controllers/asset.go |
Загрузка, список, удаление ассетов |
cuento-backend/src/Controllers/design_variation.go |
CRUD вариаций |
cuento-backend/src/EventHandlers/static_file_event_handlers.go |
Очистка версий по событию StaticFileUploaded |
cuento-frontend/src/app/admin/admin-design/admin-design.component.ts |
UI для CSS, иконки, ассетов и вариаций |
cuento-frontend/src/app/admin/admin-design-draft-edit/admin-design-draft-edit.component.ts |
Редактор черновика с автосохранением и модалью публикации |
cuento-frontend/src/app/app.component.ts |
Определение режима черновика, замена ссылок, WS-подписка |