ЯлАрба: AI-чат с Арбой

Инструкция: AI-чат «Арба» и семантический поиск (B2C)

1. Как это устроено

Арба — AI-помощник ЯлАрба. Плавающая кнопка в правом нижнем углу (панель 380×560px). Умеет: находить объекты, отвечать на вопросы о туризме, давать рекомендации. Поддерживает контекст диалога (сессию).

Связанные возможности:

Семантический поиск — на странице /search сортировка «по релевантности» использует AI-эмбеддинги.
RAG по документации — AI отвечает с опорой на документы платформы (/rag/docs в llm-svc).

2. Использование чата

1. Нажмите плавающую кнопку «Арба» (правый нижний угол).
2. Задайте вопрос. Быстрые подсказки: «Что посмотреть в Уфе?», «Где отдохнуть на природе?», «Недорогие гостиницы», «Что нужно для регистрации?».
3. Получайте ответ. Диалог запоминается (сессия).
4. «Очистить историю» — сбрасывает сессию и начинает заново.

Требуется авторизация (POST /chat — auth). Если AI-сервис недоступен — ответ 503, повторите позже.

3. Семантический поиск

На странице поиска:

1. Введите запрос обычным языком (например, «тихое место у озера»).
2. Выберите сортировку «по релевантности» — результаты будут ранжированы AI по смысловой близости, а не только по ключевым словам.
3. Для точного семантического режима есть параметр mode=semantic (используется из чата/API).

История последних 5 запросов участвует в контексте семантического поиска.

4. Возможные вопросы Арбе

Поиск: «Где остановиться в Уфе недорого?»
Маршруты: «Составь план на 3 дня»
Объекты: «Что есть рядом с Мелеузом?»
Правила: «Как оставить отзыв?»

5. Ограничения

Ответ зависит от данных в базе и документации — при отсутствии объектов по запросу Арба может не найти подходящее.
Блок «источники» со ссылками на объекты предусмотрен в интерфейсе (ответ API сейчас содержит только reply).

6. API (для разработчиков)

Метод	Путь	Кто
POST	`/chat`	auth. Тело `{session_id, message}` → `{session_id, reply}`

message — обязателен.
session_id — идентификатор диалога (передаётся обратно для продолжения).
Если llm-svc недоступен — 503.

7. Где код

Фронт: yalarba-nuxt/app/components/chat/ChatBot.vue
API: api_yalarba/internal/domain/chat/
LLM-сервис: llm/app/routers/chat.py, llm/app/services/rag.py

ЯлАрба: избранное и отзывы

Инструкция: избранное и отзывы на ЯлАрба (B2C)

1. Как это устроено

Действие	URL	Требования
Избранное	`/favorites`	авторизация
Мои отзывы	`/reviews`	авторизация
Отзывы объекта	на деталке объекта `/objects/[id]`	—
Оценка рейтингом	кнопка на деталке	авторизация + подтверждённый email

Рейтинг объекта — агрегат из одобренных отзывов (платформа «турист»). Модерация отзывов автоматическая (ML-проверка токсичности) + вручную админами.

2. Избранное

1. На странице объекта /objects/[id] нажмите «В избранное» (сердечко).
2. Список сохранённого — /favorites (пагинация по 20).
3. Удаление — кнопка на карточке в списке или повторное нажатие на деталке.

Ограничения:

Нужна авторизация (кнопка скрыта для гостей).
Тарифный лимит favorites_max (баннер при заполнении 80%).
Офлайн-кэш списка в IndexedDB.

API: GET /favorites?offset=&limit=, POST /favorites/{objectId}, DELETE /favorites/{objectId}.

3. Написание отзыва

1. Откройте объект → блок «Отзывы» → «Написать отзыв».
2. Заполните:

- Оценка 1–5 (обязательно),

- Текст — обязательно, до 2000 символов; при оценке ≤ 2 текст обязателен и минимум 10 символов,

- Фото — до N файлов (до 10 МБ каждый).

3. Отправьте. Отзыв публикуется:

- сразу — если ML не нашёл токсичности (score < 0.7),

- уходит на пре-модерацию — при score 0.7–0.95,

- отклоняется — при score ≥ 0.95 или стоп-словах.

Владелец объекта получает уведомление (в т.ч. в MAX-бот).

4. Управление отзывами

Мои отзывы — /reviews: редактирование (PUT /reviews/{id}) и удаление (DELETE /reviews/{id}) — только собственные.
Голосование рейтингом (отдельно от отзыва): кнопка оценки + комментарий; требуется подтверждённый email.
Список отзывов объекта: сортировка «Новые» / «Высокий рейтинг».

5. Частые ошибки

Ошибка	Причина	Решение
«Оценка ≤ 2 требует текст»	валидация	добавьте текст от 10 символов
«Требуется подтверждение email»	голосование рейтингом	подтвердите email
Отзыв не появился сразу	пре-модерация	дождитесь проверки (статус pending)
Отзыв отклонён	токсичность/стоп-слова	переформулируйте

6. API (для разработчиков)

Метод	Путь	Кто
GET	`/reviews/object/{objectId}`	публично
GET	`/reviews/my`	auth
POST	`/reviews`	auth (rate limit)
PUT/DELETE	`/reviews/{id}`	владелец
POST	`/ratings/{objectId}/vote`	auth + verified email
GET	`/ratings/object/{objectId}`	публично
GET	`/ratings/{objectId}/my-vote`	auth

7. Где код

Фронт: yalarba-nuxt/app/components/FeedbackForm.vue, FeedbackList.vue, pages/favorites.vue, pages/reviews/
API: api_yalarba/internal/domain/review/, api_yalarba/internal/domain/rating/, api_yalarba/internal/domain/favorite/

ЯлАрба: профиль и уведомления

Инструкция: профиль, уведомления, согласия и обратная связь (B2C)

1. Как это устроено

Профиль (/profile) — вкладки: Обзор, Избранное, 💎 Подписка, ⚙️ Настройки, Мои отзывы, Мои маршруты, Уведомления, Выход. Настройки — карточки: Обращения, Реферальная программа, Маркетинг, Соцсети, Согласия, Администрирование.

2. Профиль и настройки

Аватар — загрузка фото до 5 МБ.
Личные данные: full_name, phone, city.
Смена пароля: old_password + new_password (мин. 8 символов).
2FA (TOTP): включение через QR-код, вход с 6-значным кодом; отключение — ввод кода.
Экспорт данных (152-ФЗ ст.20): выгрузка персональных данных в JSON.
Удаление аккаунта: ввод слова «УДАЛИТЬ» → подтверждение (требуется подтверждённый email).

API: GET/PUT /me, GET /me/stats, GET /me/export, DELETE /me, POST /change-password, GET/POST /me/2fa/*.

3. Уведомления

Список — /notifications (вкладки Все/Непрочитанные, «прочитать»).
Настройки (ProfileNotifications) — 8 тумблеров: moderation_status, new_review, new_feedback, new_inquiry, subscription_expiring, marketing, blog_subscription, notification_bot.
MAX-бот: привязка через бот https://max.ru/id0234009584_bot — /start → «Привязать аккаунт» → email → код из письма; отвязка /unlink. Уведомления дублируются в бот при включённом notification_bot.
Push (PWA): подписка на браузерные уведомления.

API: GET /notifications, PUT /notifications/{id}/read, GET/PUT /notification-preferences, POST/DELETE /push-subscriptions.

4. Согласия (152-ФЗ)

4 типа согласий: personal_data, terms, offer, cookies.

/profile/consents — дать/отозвать каждое.
После отзыва повторно «дать» можно не раньше чем через 5 минут.
При отзыве всех согласий доступ к функциям блокируется (баннер на /profile).

API: GET /consents, PUT /consents/{type} {action: give|revoke}.

5. Обращения в поддержку

/appeals — форма: Тип (question/complaint/suggestion/wish/other), Тема, Сообщение, Приоритет (low/medium/high/critical). Статусы: new → in_progress → resolved/rejected/closed.

API: POST /appeals (публично), GET /appeals/me (auth).

6. Реферальная программа

/profile/referral: ваш реферальный код, статистика переходов/регистраций, конверсии (clicked → registered → subscribed → paid → credited). Бонус: 200 ₽ за регистрацию + VIP-статус на месяц.

API: POST /referrals/generate, GET /referrals/my/stats, GET /referrals/my/conversions, POST /referral/track.

7. Маркетинг (рассылки)

/profile/marketing: частота дайджеста (daily/weekly/never), тумблеры marketing_email, marketing_bot. Отписка — по ссылке из письма.

API: GET/PUT /marketing/subscription, GET /marketing/unsubscribe.

8. Частые ошибки

Ошибка	Причина	Решение
«Согласие можно дать позже»	cooldown 5 мин после отзыва	подождите 5 минут
«Доступ ограничен»	отозваны все согласия	верните согласия в /profile/consents
Не приходят уведомления в бот	выключен тумблер / не привязан бот	включите `notification_bot`, привяжите MAX-бот

9. Где код

Фронт: yalarba-nuxt/app/pages/profile/, notifications.vue, appeals.vue
API: api_yalarba/internal/domain/account/, notification/, notificationpref/, consent/, appeal/, referral/, marketing/, twofa/, push/

ЯлАрба: регистрация и вход

Инструкция: регистрация и вход на ЯлАрба (B2C)

Раздел для туристов: создание аккаунта, вход, подтверждение email, восстановление пароля.

1. Как это устроено

Действие	URL	API
Регистрация	`/auth/register`	`POST /auth/register`
Вход	`/auth/login`	`POST /auth/login`
Подтверждение email	`/auth/verify-email` (по ссылке из письма)	`GET /auth/verify-email?token=`
Восстановление пароля	`/auth/reset-password` → `/auth/reset-password/confirm`	`POST /auth/reset-password`, `POST /auth/reset-password/confirm`
OAuth (VK / Яндекс)	`/auth/oauth/{provider}`	`GET /auth/oauth/{provider}/login?redirect_uri=`

Аккаунт нужен для: избранного, отзывов, маршрутов, AI-чата, подписки, заявок на объекты.

2. Регистрация

1. Откройте https://yalarba.ru/auth/register.
2. Заполните:

- Имя и Фамилия (складываются в ФИО),

- Email — на него придёт письмо подтверждения,

- Пароль — минимум 8 символов (и при регистрации, и при смене/сбросе),

- Подтверждение пароля — должно совпадать,

- Согласие с условиями — обязательно (без него регистрация не завершится).

3. Опционально: реферальный код подставляется автоматически из ссылки ?ref=....
4. Нажмите Зарегистрироваться.
5. Вы попадёте на страницу «Подтверждение email». Перейдите по ссылке из письма — без этого нельзя голосовать рейтингом и часть функций будет ограничена.

Ошибки: 400 — неверный email/короткий пароль (мин. 8) / пустое имя; 409 — email уже зарегистрирован.

3. Вход

1. https://yalarba.ru/auth/login — введите email и пароль.
2. Если у вас включён 2FA (TOTP) — введите 6-значный код.
3. Если email не подтверждён — появится баннер с кнопкой «Отправить повторно» (повторная отправка письма).
4. Можно войти через VK ID или Яндекс ID (кнопки OAuth).

Сессия: access-токен живёт 15 минут, refresh — 7 дней (автопродление). Выход — кнопка «Выход» в профиле.

4. Восстановление пароля

1. /auth/reset-password — введите email → получите письмо со ссылкой.
2. Перейдите по ссылке → /auth/reset-password/confirm → введите новый пароль (мин. 8 символов).
3. Ссылка для сброса действительна 1 час.

5. OAuth

Привязка VK / Яндекс: профиль → Соцсети (/profile/social). Отвязка — там же. Лимит попыток OAuth-входа: 10/мин на IP.

6. Частые ошибки

Ошибка	Причина	Решение
Пароль < 8 символов	валидация	придумайте пароль от 8 символов
«Email не подтверждён» при голосовании	нет подтверждения	перейдите по ссылке из письма или «Отправить повторно»
«Пароль неверный»	опечатка	сброс пароля
Письмо не пришло	спам/задержка	«Отправить повторно», проверьте спам

7. API (для разработчиков)

Метод	Путь	Кто
POST	`/auth/register`	публично
POST	`/auth/login`	публично
POST	`/auth/refresh`	cookie
POST	`/auth/logout`	auth
GET	`/auth/verify-email?token=`	публично
POST	`/auth/resend-verification`	auth
POST	`/auth/reset-password`	публично
POST	`/auth/reset-password/confirm`	публично
GET	`/auth/oauth/available`, `/auth/oauth/providers`	публично
GET	`/auth/oauth/{provider}/login`	публично

8. Где код

Фронт: yalarba-nuxt/app/pages/auth/
API: api_yalarba/internal/domain/auth/
OAuth: api_yalarba/internal/domain/auth/oauth/

ЯлАрба: маршруты

Инструкция: маршруты на ЯлАрба (B2C)

1. Как это устроено

Страница	URL	Требования
Список маршрутов	`/routes`	публично (вкладки: Популярные / 🤖 AI-маршруты / Мои)
Создать свой	`/routes/new`	авторизация
AI-маршрут	`/routes/ai`	авторизация + тариф «Стандарт 500»
Карточка маршрута	`/routes/[id]`	публично
Редактирование	`/routes/[id]/edit`	владелец

Маршрут = набор точек (объектов) с порядком, временем в каждой точке и днём. Автоматически считаются: общее расстояние (км), общая длительность, бюджет. Экспорт в GPX.

2. Создание маршрута вручную

1. /routes/new → заполните Название, Дней (мин. 1), описание (необязательно).
2. Добавьте точки маршрута: через поиск объектов (попап) или клик по карте.
3. Точку можно отредактировать: Название, Адрес, Заметка, Время (мин), День.
4. Порядок точек меняется drag-and-drop.
5. Сохраните:

- «💾 Сохранить» — приватный (виден только вам),

- «📤 Опубликовать» — публичный (попадает на /routes).

Переход с деталки объекта: кнопка «добавить в маршрут» → /routes/new?add_object=<slug> (точка подставляется автоматически).

3. AI-маршрут

1. /routes/ai — заполните параметры:

- Регион (по умолчанию «Республика Башкортостан»),

- Дней: 1 / 2 / 3 / 5 / 7 / 14,

- Бюджет: слайдер 3 000 – 100 000 ₽ (шаг 1000),

- Интересы: до 5 из 15 (природа, история, поход, города, сплав, горы, гастротур, здоровье, лыжи, пещеры, озёра, фототур, семейный, экстрим, паломничество),

- Транспорт: автомобиль / пешком / автобус / смешанный,

- Начальная точка: один из 10 городов РБ (Уфа, Стерлитамак, Салават, Нефтекамск, Белорецк, Сибай, Октябрьский, Туймазы, Ишимбай, Мелеуз),

- Сезон: лето / осень / зима / весна,

- Сложность: лёгкий / средний / сложный,

- «С детьми» — чекбокс.

2. «Сгенерировать» — AI (Ollama t-lite-it-2.1) составляет маршрут, расстояния — через OSRM. Кэш ответа 1 час.
3. Полученный маршрут можно перегенерировать или сохранить в свои.

⚠️ AI-маршруты доступны только с подпиской «Стандарт 500 ₽/мес» (пока тарифы туриста — целевая модель, доступ может включаться пилотно).

4. Просмотр и шаринг

Карточка маршрута: список точек, карта, расстояние/время/бюджет, счётчик просмотров.
Экспорт: /routes/[id]/export.gpx (для навигаторов).
Поделиться: кнопка «Поделиться» (копирует ссылку).

5. Частые ошибки

Ошибка	Причина	Решение
«Доступно только со Стандарт»	AI-маршрут без тарифа	оформите подписку или создайте вручную
Нет точек	не добавили ни одной точки	добавьте через поиск или клик по карте
Ошибка геокодинга точки	адрес не найден	введите адрес вручную/координаты

6. API (для разработчиков)

Метод	Путь	Кто
GET	`/routes`	публично
GET	`/routes/{id}`, `/routes/slug/{slug}`	публично (id — optional auth)
GET	`/routes/ai/popular`	публично
GET	`/routes/mine`	auth
POST	`/routes`	auth
PUT/DELETE	`/routes/{id}`	владелец
POST	`/routes/{id}/share`, `/routes/{id}/recalculate`	владелец
POST	`/routes/ai/generate`, `/routes/ai/regenerate/{id}`	auth + тариф
GET	`/routes/{id}/export.gpx`	публично

Тело создания: {title, description, duration_days, is_public, waypoints:[{object_id, sort_order, title, address, latitude, longitude, note, stay_duration_min, day_number}]}.

7. Где код

Фронт: yalarba-nuxt/app/pages/routes/, components/RouteBuilder.vue
API: api_yalarba/internal/domain/route/

ЯлАрба: поиск и фильтры

Инструкция: поиск, фильтры и карта на ЯлАрба (B2C)

Раздел для туристов: как находить объекты, применять фильтры, пользоваться картой с кластерами.

1. Как это устроено

Страница поиска: /search (yalarba-nuxt/app/pages/search/index.vue).
Поиск: полнотекстовый (query) + расширенный семантический через AI (сортировка «по релевантности»).
Результаты и фильтры сохраняются в sessionStorage (результаты 5 мин, гео 30 мин), история — последние 5 запросов.
На карте — кластеры (Leaflet + markercluster), до 1000 объектов, центр по умолчанию — Уфа.

2. Поиск

Введите запрос в поле поиска. Ищется по названию, описанию, городу, владельцу.

Фильтры (сайдбар)

Фильтр	Что делает
Категория	тип объекта (комбобокс с поиском), мультивыбор, авто-расширение на подтипы
Город	фильтр по городу
Владелец	имя/название владельца
Цена	от/до
Мин. рейтинг	4.5 / 4 / 3.5 / 3 / 2 / 1
Даты	доступность объекта на даты (от/до)
Удобства	мультиселект (Wi-Fi, парковка и т.п.)
Локация	«рядом со мной» (геолокация) или координаты + радиус 1–100 км

Сортировка

по релевантности (AI), по рейтингу, цена ↑/↓, по расстоянию, новые, по названию.

Пагинация

По умолчанию 12 объектов на страницу (максимум 100 на запрос). Кнопки «Назад/Вперёд» + номера страниц.

3. Карта

1. На странице поиска включите переключатель «Карта».
2. Маркеры объектов + кластеры (круги с числом) для близких точек.
3. Увеличение → кластеры «распадаются» на отдельные маркеры.
4. Клик по маркеру → карточка объекта (название, цена).

Кластеры считаются сервером: POST /objects/map-cluster с границами {north, south, east, west, zoom}.

4. Сохранение поиска

Фильтры и гео не сбрасываются при перезагрузке (5/30 мин).
Последние запросы доступны в истории поиска (до 5).

5. Частые ошибки

Ситуация	Причина	Решение
Пустая выдача	слишком узкие фильтры	уберите фильтры, расширьте радиус
Карта не загрузилась	сеть/Leaflet	обновите страницу
Много объектов на карте	без кластеров	уменьшите масштаб (кластеры включаются автоматически)

6. API (для разработчиков)

Метод	Путь	Описание
GET	`/objects/search`	поиск: `query, category_id, city, owner_name, price_min, price_max, rating_min, amenity_ids, date_from, date_to, lat, lng, radius, sort_by, sort_order, page, per_page, mode`
POST	`/objects/map-cluster`	кластеры: `{north, south, east, west, zoom}`
GET	`/objects/map-cluster`	то же GET-версией

Параметры поиска: sort_by=relevance → гибридный AI-поиск; mode=semantic → чистый семантический; rating_min 0–5; category_id — CSV, расширяется на подтипы и группы (stay/sport/culture/health).

7. Где код

Фронт: yalarba-nuxt/app/pages/search/index.vue, stores/search.ts, utils/constants.ts
API: api_yalarba/internal/domain/object/, api_yalarba/internal/domain/maplink/

EasySite102: аналитика и экспорт

Инструкция: аналитика и экспорт на EasySite (B2B)

1. Как это устроено

Страница	URL	Тариф
Дашборд аналитики	`/profile/analytics`	`has_analytics` (budget+)
Аналитика объекта	на дашборде, выбор объекта	то же
Экспорт	`/profile/export`	`has_export` (business+)

Данные собираются автоматически (события просмотров/кликов с сайта, ЯлАрбы и виджета) и агрегируются по дням (object_daily_stats).

2. Дашборд (по всем объектам)

total_views — просмотры,
total_unique_visitors — уникальные посетители,
avg_views_per_day — среднее в день,
total_contact_clicks — клики по контактам,
top_object — самый просматриваемый объект,
daily_stats — динамика за 30 дней,
traffic_sources — источники трафика.

3. Аналитика по объекту

Выберите объект — дополнительные метрики:

returning_visitors / returning_share — вернувшиеся посетители,
клики: total_phone_clicks, total_site_clicks, total_email_clicks,
click_conversion_rate — конверсия в клик,
inquiries_count, favorites_count, reviews_count,
traffic_sources + source_breakdown (easysite / yalarba / widget),
geo — города/регионы посетителей,
inquiry_trend, recent_inquiries,
competitors — сравнение с категорией.

4. Экспорт

/profile/export → выберите формат (CSV — с BOM для Excel / JSON) и период (1–365 дней):

Выгрузка	Что содержит
Объекты	ID, название, категория, тип, город, адрес, координаты, цена, контакты, статус, просмотры, отзывы
Аналитика	агрегаты по дням
Аналитика объекта	по конкретному объекту
Отзывы	фидбек по объекту
Персональные данные	по 152-ФЗ ст.20 (JSON)

Экспорт доступен при tariff.has_export (business, vip, municipal, nko). Иначе — «экспорт недоступен на вашем тарифе».

5. Частые ошибки

Ошибка	Причина	Решение
Аналитика пустая	мало событий / агрегация не запущена	дождитесь данных (агрегация по дням, backfill 90 дней)
«Экспорт недоступен»	тариф без `has_export`	повысьте тариф (business+)
CSV кривой в Excel	без BOM	открывайте CSV (BOM уже добавляется автоматически)

6. API (для разработчиков)

Метод	Путь	Кто
GET	`/analytics/dashboard`	auth + verified
GET	`/analytics/objects/{id}`	владелец
GET	`/analytics/objects/{id}/competitors`	владелец
POST	`/analytics/events`	публично (rate limit)
POST	`/analytics/internal/events`	только Docker-сеть
GET	`/analytics/admin/dashboard?days=`	admin
GET	`/analytics/admin/objects`	admin
GET	`/export/objects?format=csv\	json`	auth + `has_export`
GET	`/export/analytics?format=&days=`	auth + `has_export`
GET	`/export/analytics/objects/{id}`	владелец
GET	`/export/feedbacks?object_id=`	auth + `has_export`

7. Где код

Фронт: easySite/app/pages/profile/analytics.vue, export.vue, components/ObjectAnalyticsPanel.vue
API: api_easysite/internal/domain/analytics/, export/
Агрегация: планировщик в cmd/main.go (backfill 90 дней + тикер ежечасно, object_daily_stats)

EasySite102: CRM-интеграции

Инструкция: CRM-интеграции на EasySite (B2B)

1. Как это устроено

Заявки с объектов (из виджета, страницы объекта, ЯлАрбы) и заказы автоматически превращаются в лиды в вашей CRM. Поддерживаются AmoCRM (OAuth v4) и Bitrix24 (webhook/rest). Доступно на тарифе с флагом has_crm (VIP).

Страница	URL
Интеграции	`/profile/crm`

2. Подключение AmoCRM (OAuth v4)

1. В AmoCRM: создайте приложение (настройки → приложения) → получите client_id, client_secret.
2. Укажите redirect_uri — например https://ваш-сайт.ru/crm/amocrm/callback.
3. В /profile/crm заполните:

- client_id, client_secret, redirect_uri,

- subdomain — поддомен аккаунта (без .amocrm.ru).

4. Пройдите OAuth-флоу → EasySite получит access_token и будет автоматически его обновлять (401 → retry).
5. Проверьте кнопкой «🧪 Отправить тестовую заявку» — в AmoCRM должен появиться тестовый лид.

3. Подключение Bitrix24

1. В Bitrix24: «Разработчикам» → «Входящий вебхук» → создайте вебхук (по умолчанию права) → скопируйте URL вида:

   https://портал.bitrix24.ru/rest/1/xxxx/

2. Вставьте webhook_url в /profile/crm.
3. «🧪 Отправить тестовую заявку» → в Bitrix24 появится лид (crm.lead.add.json).

4. Как работают лиды

Заявки (inquiry) — с виджета, страницы объекта, из ЯлАрбы.
Заказы (object_orders) — при онлайн-заказе/бронировании.
Архитектура: producer-consumer — события ставятся в очередь и отправляются в CRM; при успехе ставится флаг crm_sent (повторно не отправляются).
Статусы интеграции: active | error | disabled. При ошибке — проверьте токены/права.

5. Управление

Список интеграций, редактирование, удаление, тест — /profile/crm.
Поля: у AmoCRM — OAuth-креды + subdomain; у Bitrix24 — webhook_url.

6. Частые ошибки

Ошибка	Причина	Решение
«Интеграция недоступна»	тариф без `has_crm`	повысьте до VIP
Лиды не создаются	неверные креды/правa	проверьте `client_secret`, права вебхука
OAuth-токен протух	интеграция отключена	переподключите, refresh автоматический
Статус `error`	ошибка отправки	нажмите «Тест», исправьте параметры

7. API (для разработчиков)

Метод	Путь	Кто
GET/POST	`/crm/integrations`	auth + `has_crm`
PUT/DELETE	`/crm/integrations/{id}`	владелец
POST	`/crm/integrations/{id}/test`	владелец

8. Где код

Фронт: easySite/app/pages/profile/crm.vue
API: api_easysite/internal/domain/crm/ (AmoCRM OAuth v4, Bitrix24 webhook/rest, producer-consumer, crm_sent)

EasySite102: редактирование и удаление

Инструкция: редактирование, расширения, удаление и batch-операции (B2B)

1. Как это устроено

Действие	URL/API
Редактирование	`/objects/[id]/edit`
Расширения (extension)	в форме редактирования, ExtensionForm
Акции	блок «Акции и новости» на `/objects/[id]/edit`
События	блок «События»
Удаление	кнопка 🗑️ на карточке (`DELETE /objects/{id}`)
Batch-операции	`/objects/my-objects` (галочки + массовые действия)

2. Редактирование

Откройте /objects/[id]/edit. Доступно:

Основное: short_name*, long_name, title, description, short_description, status (draft/moderation/active).
Классификаторы: тип + 7 списков (удобства, транспорт, возраст, группы, наследие, риски, tourism-типы).
Местоположение (LocationPicker), цены prices[], контакты (phone, email, site), время работы.
Приём платежей (только VIP, has_payments): enabled, method (link|sbp|manual), payment_link, СБП-реквизиты (sbp_bank/inn/bik/account/tsp/city/mcc).
Фото по блокам: general (лимит тарифа), title (до 3), description (до 5, с подписью).
publish_to_b2c — публикация на YalArba.ru (B2C-витрину).
Расширения — ExtensionForm: поля по типу объекта (text/number/select/checkbox/multiselect) + произвольные extra_attrs key-value.

3. Акции и события

На странице редактирования:

Акции: тип sale (скидка 🔥) / notice (уведомление ℹ️), discount_percent, valid_from/until, is_featured. Лимиты тарифа: max_sales, max_notices.
События: название, описание, начало/окончание, повтор (none|daily|weekly|monthly|yearly, при повторе обязательно «повторять до»), «весь день». Лимит max_events.

Оба раздела привязаны к объекту и попадают в календарь B2C (yalarba.ru) — только для объектов с publish_to_b2c=true, is_active=true, status=active.

4. Заказы, брони, слоты, клиенты (VIP)

Заказы: GET /objects/{id}/orders, смена статуса (paid/cancelled).
Брони «шахматка»: GET /objects/{id}/bookings, создание POST /objects/{id}/bookings/manual, статусы requested/confirmed/cancelled (проверка пересечений дат).
Слоты онлайн-записи (для услуг): GET/POST /objects/{id}/slots/admin, PUT/DELETE .../slots/admin/{slotId}.
Клиенты + рассылка: GET /objects/{id}/customers?segment=, POST /objects/{id}/customers/mail (тема+сообщение, SMTP).

5. Batch-операции (массовое изменение)

На /objects/my-objects выберите объекты галочками → массовые действия:

POST /objects/batch/update — массовое обновление полей (например, цены),
POST /objects/batch/update-extensions — массовое обновление расширений,
POST /objects/batch/change-type — смена типа,
POST /objects/batch/delete — массовое удаление.

Лимит: до 100 объектов за раз.

6. Удаление

Кнопка 🗑️ на карточке (или DELETE /objects/{id}). Мягкое удаление (GORM DeletedAt) — объект скрывается, данные сохраняются в БД.

7. История изменений

GET /update-history/model/object/{objectId} — журнал изменений объекта.

8. Частые ошибки

Ошибка	Причина	Решение
403 при сохранении	вы не владелец	проверьте права
Лимит событий/акций	превышен `max_events`/`max_sales`	повысьте тариф
Фото цены не загружается	>1 МБ	сожмите фото до 1 МБ
Batch > 100	лимит	разделите на части

9. Где код

Фронт: easySite/app/pages/objects/[id]/edit.vue, easySite/app/components/ObjectForm.vue, ExtensionForm.vue, my-objects.vue
API: api_easysite/internal/domain/object/, promotion/, event/, objectpayment/, booking/, slot/, batchops/, updatehistory/

EasySite102: модерация

Инструкция: модерация объекта на EasySite (B2B)

1. Как это устроено

После создания объект проходит автоматическую + ручную модерацию. Статусы: draft → moderation → active, или inactive (скрыт), rejected (отклонён).

Статус	Значение
`draft`	черновик (виден только владельцу)
`moderation`	на проверке модератором
`active`	опубликован (виден всем, в т.ч. на B2C при `publish_to_b2c`)
`inactive`	скрыт владельцем/системой
`rejected`	отклонён (причина — комментарий модератора)

Статус виден на бейджах /objects/my-objects (draft=серый, moderation=жёлтый, active=зелёный, rejected=красный) и счётчиками в профиле.

2. Критерии модерации (13)

#	Критерий	Вес	Авто-проверка
1	Фотографии	critical	≥1 фото
2	Контакты	critical	phone или email
3	Описание	high	≥500 символов
4	Адрес и координаты	high	address или lat/lng
5	Цена	high	price > 0
6	Категория	high	object_type_id задан
7	Удобства	medium	≥1 amenity
8	Грамотность	medium	только человек
9	Доп. классификаторы	low	любой из 6 списков
10	Сайт и соцсети	low	site задан
11	Нет дубликатов	high	авто (похожее название+город)
12	Нет стоп-слов	high	авто
13	Нет токсичности (ML)	medium	авто (moderation-svc)

Автоматические проверки выполняются сразу; человеческая — модератором в /admin/objects → review/[id] (сводка по весам critical/high/medium/low, авто-индикаторы ✅/❌).

3. Что нужно для прохождения (владельцу)

Чтобы объект одобрили, проверьте перед отправкой:

1. Фото — минимум 1 (лучше 3+).
2. Контакты — телефон или email.
3. Описание — от 500 символов.
4. Адрес — полный адрес и/или координаты.
5. Цена — стоимость больше 0 (даже «бесплатно» укажите 0 с пояснением).
6. Категория — выбран тип объекта.
7. Удобства — хотя бы одно.
8. Классификаторы — заполните релевантные списки.
9. Сайт/соцсети — укажите, если есть.
10. Уникальность и корректность — без стоп-слов, токсичности, дублей с другими объектами.

4. Как отправить на модерацию

В мастере создания: последний шаг — «Отправить на проверку» (статус → moderation).
В редактировании: сменить статус на moderation.

5. После модерации

active — объект публикуется; при publish_to_b2c=true попадает на yalarba.ru (поиск, каталог, карта). Создаётся новость «Объект добавлен» (авто-публикация).
rejected — исправьте замечания (комментарий модератора) и отправьте снова.
SLA модерации зависит от тарифа (moderation_hours): у VIP — быстрее (24 ч), у free — стандартный.

6. API (для разработчиков)

Метод	Путь	Кто
GET	`/admin/objects/moderation`	модератор
GET	`/admin/objects/{id}/review`	модератор
PUT	`/admin/objects/{id}/review` `{results:[{criteria_id, passed, comment}]}`	модератор
PATCH	`/admin/objects/{id}/approve`	модератор
PATCH	`/admin/objects/{id}/reject`	модератор
GET	`/admin/objects/content-review`	модератор

7. Где код

Фронт: easySite/app/pages/admin/objects/, my-objects.vue
API: api_easysite/internal/domain/moderation/, object/ (статусы), news/ (авто-публикация)

EasySite102: создание объекта

Инструкция: создание объекта на EasySite (B2B)

1. Как это устроено

Страница	URL
Мастер создания	`/objects/create`
Пошаговая инструкция	`/objects/add-guide`
Мои объекты	`/objects/my-objects`

Объект создаётся в мастере из 9 шагов. На первом шаге создаётся черновик (status=draft), остальные шаги дополняют его. При отправке на модерацию статус → moderation.

2. Шаги мастера

Шаг	Что заполняете
0. Название и тип	`short_name`* (≤100), `long_name`, `title`, тип объекта (ClassifierSelect), tourism-типы
1. Параметры	ExtensionForm — поля зависят от типа объекта (категории)
2. Описание	`short_description`, `description`
3. Адрес	адрес (каскад ГАРН/ФИАС), `city`, координаты (карта/пин/геокодинг)
4. Фото	ImageUploader (доступен после создания черновика)
5. Контакты	`phone`, `email`, `site`
6. Время работы	`working_hours`
7. Цены и удобства	`prices[]`, `amenity_ids`, транспорт/возраст/группы/культурное наследие/риски
8. Предпросмотр	сводка

3. Адрес (ГАРН/ФИАС)

Ввод: населённый пункт → улица → дом (каскадные подсказки).
После выбора адрес подтверждается по ФИАС (address_quality: good) — иначе none/unmatched.
Координаты: перетаскиваемый пин на карте, геолокация или ручной ввод.
Импорт с карты: вставьте ссылку на Яндекс/2ГИС (POST /objects/import-from-map).

4. Фото

Форматы: JPG/PNG/GIF/WEBP (по MIME).
Лимиты тарифа на фото объекта: free=1, budget=3, business=10, vip=∞, municipal=30, nko=20.
При превышении — ошибка photo_limit_reached → модалка «Повысить тариф».

5. Тарифные лимиты

Тариф	Объектов	Фото
free	1	1
budget	5	3
business	∞	10
vip	∞	∞
municipal	50	30
nko	20	20

При превышении — tariff_limit_reached → предложение повысить тариф.

6. Автосохранение

Черновик автоматически сохраняется в localStorage (stores/objectDraft) — при обрыве можно продолжить.

7. Частые ошибки

Ошибка	Причина	Решение
`tariff_limit_reached`	превышен лимит объектов	повысьте тариф
`photo_limit_reached`	превышен лимит фото	удалите лишние или повысьте тариф
Адрес не найден	нет в ФИАС	введите вручную, координаты через пин
Не сохранён шаг 0	`short_name` пустое	заполните название

8. API (для разработчиков)

Метод	Путь	Кто
POST	`/objects` (status=draft)	auth
PUT	`/objects/{id}`	владелец
POST	`/objects/import-from-map` `{url}`	auth
GET	`/object-types`, `/tourism-types`, `/amenities`, `/transport-types`, `/age-groups`, `/group-types`, `/cultural-heritage-types`, `/risk-factors`	публично
GET	`/addresses/localities`, `/streets`, `/houses`, `/geocode`, `/reverse`	публично
POST	`/upload` (multipart file+object_id)	владелец
POST	`/upload/price`	владелец (фото позиции прайса, ≤1 МБ)

9. Где код

Фронт: easySite/app/components/objects/ObjectWizard.vue, LocationPicker.vue, AddressCascade.vue, ExtensionForm.vue, easySite/app/pages/objects/create.vue
API: api_easysite/internal/domain/object/, address/, upload/

EasySite102: регистрация и верификация

Инструкция: регистрация и верификация на EasySite (B2B)

1. Как это устроено

EasySite — B2B-платформа для владельцев туристических объектов. Регистрация → подтверждение email → заполнение профиля → верификация модератором (проверка личности/бизнеса) → публикация объектов.

Страница	URL
Регистрация	`/auth/register`
Вход	`/auth/login`
Восстановление пароля	`/auth/forgot-password`, `/auth/reset-password`
Подтверждение email	`/auth/verify-email`, `/auth/verify-email-pending`
Профиль + подача на верификацию	`/profile/edit`

2. Регистрация

1. /auth/register — заполните:

- Email (валидный),

- Имя и Фамилия (мин. 2 символа),

- Пароль (мин. 8 символов) + подтверждение,

- Согласие (152-ФЗ) — обязательно,

- Маркетинговое согласие — опционально,

- Тип предприятия: ИП / ООО / АО / МУП / ГУП / АУ / НКО / (физлицо),

- Самозанятый (НПД) — чекбокс.

2. Подтвердите email по ссылке из письма.

Верификация email обязательна для публикации отзывов/заявок; согласия обязательны для CRUD объектов.

3. Заполнение профиля

/profile/edit — поля: full_name, inn (до 12), phone, city, email, enterprise_type, org_full_name, org_short_name, org_inn, address, planned_objects_count; аватар — загрузка/удаление. Сохранение — кнопка «Сохранить».

4. Верификация модератором

1. Заполните профиль полностью.
2. Нажмите «Отправить на проверку» (POST /account/me/submit-verification) — статус станет pending.
3. Модератор проверяет по чеклисту из 5 пунктов: phone_verified (телефон подтверждён), inn_checked (ИНН проверен), address_confirmed (адрес подтверждён), objects_discussed (объекты обсуждены), responsibility_informed (об ответственности уведомлён).
4. Решение: approved / rejected (с комментарием). Статусы: not_submitted | pending | approved | rejected.
5. Статус виден на баннере /profile.

После верификации становятся доступны: публикация объектов, аналитика, экспорт и др. Для администраторов/модераторов — раздел /admin/verification.

5. Частые ошибки

Ошибка	Причина	Решение
Пароль < 8	валидация	пароль от 8 символов
«Email не подтверждён»	нет подтверждения	ссылка из письма / «Отправить повторно»
Заявка на проверку не уходит	профиль не заполнен	заполните все обязательные поля
Верификация отклонена	чеклист не выполнен	исправьте по комментарию модератора

6. API (для разработчиков)

Метод	Путь	Кто
POST	`/auth/register`, `/auth/login`, `/auth/refresh`, `/auth/logout`	публично
POST	`/auth/reset-password`, `/auth/reset-password/confirm`	публично
GET	`/auth/verify-email?token=`	публично
POST	`/auth/resend-verification`	auth
PUT	`/account/me`	auth
POST	`/account/me/avatar`, `DELETE /account/me/avatar`	auth
POST	`/account/me/submit-verification`	auth
GET	`/account/admin/accounts/pending-verification`	admin
PUT	`/account/admin/accounts/moderator-verify`	admin

7. Где код

Фронт: easySite/app/pages/auth/, easySite/app/pages/profile/edit.vue, easySite/app/pages/admin/verification/
API: api_easysite/internal/domain/auth/, api_easysite/internal/domain/account/

EasySite102: тарифы и оплата

Инструкция: тарифы и оплата на EasySite (B2B)

1. Как это устроено

Страница	URL
Тарифы	`/pricing`
Оплата	`/pay`
Моя подписка	`/profile` → вкладка «Подписка»

Оплата — ручной перевод (карта Т-Банка или СБП по QR). После перевода укажите назначение платежа, админ подтверждает → создаётся подписка.

2. Тарифы

slug	Название	Цена	Объектов	Фото/объект	Аналитика	Экспорт	API	Платежи	CRM	Виджет
`free`	Бесплатный	0 ₽	1	1	–	–	–	–	–	–
`budget`	Бюджетная 500	500 ₽/мес	5	3	✓	–	–	–	–	–
`business`	Бизнес 1000	1000 ₽/мес	∞	10	✓	✓	–	–	–	–
`vip`	VIP 2500	2500 ₽/мес	∞	∞	✓	✓	✓	✓	✓	✓
`municipal`	Муниципальный	по договорённости	50	30	✓	✓	✓	–	–	–
`nko`	Социальный	0 ₽	20	20	✓	✓	–	–	–	–

Особенности:

municipal — только для МУП/ГУП/АУ; nko — для НКО.
business и nko имеют триал (14 и 30 дней соответственно).
Флаги тарифов: has_analytics, has_priority_boost, has_export, has_api, has_payments, has_crm, has_widget, moderation_hours, max_sales, max_notices, max_events, support_level.

3. Оплата (шаги)

1. /pricing → выберите тариф → «Оформить» → /pay.
2. Укажите период: 1 / 3 / 6 / 12 месяцев.
3. Email плательщика (на него придут данные).
4. Способ оплаты:

- карта Т-Банка 2200 7005 6131 9004, или

- СБП по QR.

5. В назначении платежа укажите строго:

   {tariff_slug} {N}мес {email}

Пример: business 1мес ivan@mail.ru.

6. Отправьте форму (POST /manual-payments). Статус платежа — pending.
7. После подтверждения админом создаётся подписка → тариф активируется.

Если назначение платежа заполнено неверно — админ не сможет сопоставить платёж, обработка затянется. Пишите точно по шаблону.

4. Подписка

Текущая подписка и её тариф — /profile → «Подписка».
Отмена — кнопка «Отменить подписку» (PUT /subscriptions/cancel).
История платежей — /profile → «Платежи» (GET /me/payments, GET /me/manual-payments).
Перед окончанием подписки приходит уведомление (subscription_expiring).

5. Авто-подписка

POST /subscriptions — создание подписки автоматически (например, после подтверждённого ручного платежа). Обычно пользователю не требуется вызывать вручную.

6. Частые ошибки

Ошибка	Причина	Решение
Платёж «завис» в pending	назначение платежа не совпало	напишите в поддержку с номером перевода и email
Тариф не активировался	подтверждение ещё не прошло	подождите (обычно в течение рабочего дня)
Недоступен раздел (CRM/виджет/экспорт)	тариф без флага	повысьте тариф

7. API (для разработчиков)

Метод	Путь	Кто
GET	`/tariffs`, `/tariffs/{slug}`	публично
GET	`/me/subscription`	auth
POST	`/subscriptions`	auth
PUT	`/subscriptions/cancel`	auth
GET	`/me/manual-payments`, `/me/payments`	auth
POST	`/manual-payments`	auth
GET	`/admin/manual-payments`	admin
PUT	`/admin/manual-payments/{id}/confirm` / `/reject`	admin

8. Где код

Фронт: easySite/app/pages/pay/index.vue, pricing.vue, admin/payments.vue, admin/subscriptions/
API: api_easysite/internal/domain/tariff/, subscription/, manualpayment/

Страница	URL
Настройка	`/profile/widget`
Вставка	код на ваш сайт

Параметр	Описание
Объект	конкретный объект или «все объекты» (null)
Цвет	`primary_color` (hex)
Позиция	правый/левый нижний угол
Заголовок	`title` (≤100)
Текст кнопки	`button_text` (≤50)
Иконка кнопки	чат / телефон / календарь
Поля формы	чекбоксы: имя, телефон, email, комментарий, даты
Сообщение после отправки	`success_message`
Разрешённые домены	`allowed_domains` — где виджет можно встраивать (защита от чужого размещения)

Ошибка	Причина	Решение
«Виджет недоступен»	тариф без `has_widget`	повысьте тариф (Business+)
Заявки не приходят	виджет на другом домене	добавьте домен в `allowed_domains`
Кнопка не видна	код вставлен неверно	проверьте `data-widget-id`, вставьте перед `</body>`

Метод	Путь	Кто
GET/POST	`/widget/configs`	auth + verified + `has_widget`
PUT/DELETE	`/widget/configs/{id}`	владелец
GET	`/widget/config/{widget_id}`	публично
POST	`/widget/inquiry`	публично (rate limit 5/час/IP, honeypot)
GET	`/widget/embed.js`	публично (go:embed `widget.min.js`)

Пользовательские руководства

ЯлАрба: AI-чат с Арбой

Инструкция: AI-чат «Арба» и семантический поиск (B2C)

1. Как это устроено

2. Использование чата

3. Семантический поиск

4. Возможные вопросы Арбе

5. Ограничения

6. API (для разработчиков)

7. Где код

ЯлАрба: избранное и отзывы

Инструкция: избранное и отзывы на ЯлАрба (B2C)

1. Как это устроено

2. Избранное

3. Написание отзыва

4. Управление отзывами

5. Частые ошибки

6. API (для разработчиков)

7. Где код

ЯлАрба: профиль и уведомления

Инструкция: профиль, уведомления, согласия и обратная связь (B2C)

1. Как это устроено

2. Профиль и настройки

3. Уведомления

4. Согласия (152-ФЗ)

5. Обращения в поддержку

6. Реферальная программа

7. Маркетинг (рассылки)

8. Частые ошибки

9. Где код

ЯлАрба: регистрация и вход

Инструкция: регистрация и вход на ЯлАрба (B2C)

1. Как это устроено

2. Регистрация

3. Вход

4. Восстановление пароля

5. OAuth

6. Частые ошибки

7. API (для разработчиков)

8. Где код

ЯлАрба: маршруты

Инструкция: маршруты на ЯлАрба (B2C)

1. Как это устроено

2. Создание маршрута вручную

3. AI-маршрут

4. Просмотр и шаринг

5. Частые ошибки

6. API (для разработчиков)

7. Где код

ЯлАрба: поиск и фильтры

Инструкция: поиск, фильтры и карта на ЯлАрба (B2C)

1. Как это устроено

2. Поиск

Фильтры (сайдбар)

Сортировка

Пагинация

3. Карта

4. Сохранение поиска

5. Частые ошибки

6. API (для разработчиков)

7. Где код

EasySite102: аналитика и экспорт

Инструкция: аналитика и экспорт на EasySite (B2B)

1. Как это устроено

2. Дашборд (по всем объектам)

3. Аналитика по объекту

4. Экспорт

5. Частые ошибки

6. API (для разработчиков)

7. Где код

EasySite102: CRM-интеграции

Инструкция: CRM-интеграции на EasySite (B2B)

1. Как это устроено

2. Подключение AmoCRM (OAuth v4)

3. Подключение Bitrix24

4. Как работают лиды

5. Управление

6. Частые ошибки

7. API (для разработчиков)

8. Где код