> For the complete documentation index, see [llms.txt](https://vitrina-blogerov.gitbook.io/bloggers-showcase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vitrina-blogerov.gitbook.io/bloggers-showcase/arkhitektura/frontend-vitriny.md).

# Frontend витрины

Фронтенд витрины - это публичный интерфейс каталога. Его видит клиент в браузере, Telegram mini app на телефоне, Telegram Desktop и Telegram Web.

{% hint style="info" %}
Витрина не является отдельным frontend-приложением с отдельной сборкой. Она поставляется внутри каждой языковой версии как HTML, CSS, JavaScript и медиафайлы.
{% endhint %}

### Где находится

Основные файлы витрины находятся внутри каждой языковой версии.

<table data-search="false"><thead><tr><th>Файл или папка</th><th>Назначение</th></tr></thead><tbody><tr><td><mark style="background-color:$info;">templates/base.html</mark></td><td>Основная HTML-страница витрины.</td></tr><tr><td><mark style="background-color:$info;">assets/style.css</mark></td><td>Стили, адаптивность, анимации, темы, glass-эффекты.</td></tr><tr><td><mark style="background-color:$info;">assets/scrypt.js</mark></td><td>Клиентская логика витрины.</td></tr><tr><td><mark style="background-color:$info;">assets/logo.png</mark></td><td>Логотип по умолчанию.</td></tr><tr><td><mark style="background-color:$info;">assets/bg.mp4</mark></td><td>Видеофон по умолчанию.</td></tr><tr><td><mark style="background-color:$info;">assets/photos</mark></td><td>Фото карточек.</td></tr><tr><td><mark style="background-color:$info;">assets/icons</mark></td><td>Иконки тегов, площадок и тем.</td></tr></tbody></table>

После установки файлы находятся в папках языковых версий:

```
/opt/bloggers_platform/apps/ru/
/opt/bloggers_platform/apps/en/
/opt/bloggers_platform/apps/zh/
/opt/bloggers_platform/apps/ar/
```

### Как открывается витрина

```mermaid
flowchart TB
    A["Пользователь открывает домен"] --> B["Caddy"]
    B --> C["Маршрут /bloggers/{lang}/"]
    C --> D["FastAPI backend языковой версии"]
    D --> E["templates/base.html"]
    E --> F["assets/style.css и assets/scrypt.js"]
    F --> G["Запросы к /api/bloggers, /api/tags, /api/appearance"]
```

Фронтенд получает HTML-страницу от backend, а затем сам запрашивает данные через API текущей языковой версии.

Например, англоязычная витрина использует:

```
https://example.com/bloggers/en/api/bloggers
https://example.com/bloggers/en/api/tags
https://example.com/bloggers/en/api/appearance
```

### Что делает JavaScript

<details>

<summary>Основная логика витрины</summary>

`assets/scrypt.js` отвечает за загрузку карточек, фильтры, поиск, сортировку, пагинацию, корзину, профиль пользователя, открытие карточек, работу с Telegram WebApp API и AI-поиск.

Он также вычисляет текущий base path, чтобы одна и та же логика работала по адресам вида:

```
/bloggers/ru/
/bloggers/en/
/bloggers/zh/
/bloggers/ar/
```

</details>

<details>

<summary>Связь с Telegram mini app</summary>

Если витрина открыта внутри Telegram, frontend вызывает Telegram WebApp API: сообщает Telegram, что mini app готов, разворачивает окно и использует данные Telegram-пользователя там, где это нужно интерфейсу.

</details>

<details>

<summary>Загрузка оформления</summary>

При открытии витрина запрашивает `/api/appearance`. Из этого ответа она получает логотип, видеофон, цветовую схему, текст кнопки связи и настройки визуальных эффектов.

</details>

### Какие данные получает витрина

| Метод                                                            | Для чего используется                      |
| ---------------------------------------------------------------- | ------------------------------------------ |
| <mark style="background-color:$info;">GET /api/appearance</mark> | Оформление витрины.                        |
| <mark style="background-color:$info;">GET /api/tags</mark>       | Категории и теги фильтра.                  |
| <mark style="background-color:$info;">GET /api/bloggers</mark>   | Карточки, пагинация, фильтры и сортировка. |
| <mark style="background-color:$info;">POST /api/ai-search</mark> | AI-подбор карточек.                        |

{% tabs %}
{% tab title="Обычный поиск" %}
Пользователь вводит текст, выбирает теги, цены, подписчиков и сортировку. Витрина отправляет параметры в `/api/bloggers`, а backend возвращает подходящие карточки.
{% endtab %}

{% tab title="AI-поиск" %}
Пользователь пишет запрос обычным языком. Витрина отправляет его в <mark style="background-color:$info;">/api/ai-search</mark>, получает список ID подходящих карточек и затем показывает их в каталоге.
{% endtab %}

{% tab title="Корзина" %}
Выбранные карточки сохраняются на стороне браузера. Это легкая клиентская корзина для дальнейшей связи с агентством.
{% endtab %}
{% endtabs %}

### Полезно

{% hint style="success" %}
Оформление витрины меняется через админ-панель: логотип, видеофон, цветовая схема, зерно и кнопка связи. Для обычной эксплуатации не нужно редактировать base.html, style.css или scrypt.js.
{% endhint %}

{% hint style="warning" %}
Если вручную заменить файлы в assets, проверяйте права доступа. Контейнер приложения работает не от root-пользователя, поэтому файлы должны быть доступны для чтения и записи приложению.
{% endhint %}

### Не является задачей фронтенда

Фронтенд не хранит базу карточек, не управляет Telegram-токеном, не публикует посты в канал и не принимает решения AI. Он только отображает интерфейс и вызывает API текущей языковой версии.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://vitrina-blogerov.gitbook.io/bloggers-showcase/arkhitektura/frontend-vitriny.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.