docs: шаблоны ссылок для Директа и Instagram, инструкция по деплою

docs/deploy.md

@@ -0,0 +1,40 @@
+# Деплой и эксплуатация
+
+```
+Интернет → nginx на VPS (kvarta.unuchak.com, certbot)
+             /      → 127.0.0.1:13120  kvarta-landing (Next.js standalone)
+             /api/  → 127.0.0.1:13121  kvarta-api (Hono + SQLite в volume kvarta-data)
+kvarta-api → Tailscale → домашний сервер :8788 kvarta-tg-relay (nginx) → api.telegram.org
+```
+
+С VPS `api.telegram.org` недоступен, поэтому Bot API идёт через ретранслятор на домашнем сервере (`deploy/tg-relay`). Он пропускает только запросы нашего бота и только из tailnet; токена на домашнем сервере нет.
+
+## Первый запуск
+
+1. `CERTBOT_EMAIL=… deploy/setup-nginx.sh` — конфиг nginx, `nginx -t`, reload, сертификат. Повторный запуск безопасен.
+2. `deploy/deploy.sh` — сборка образов `linux/amd64` локально (JS собирается нативно, нативные модули — под целевую платформу), `docker save | ssh docker load`, `docker-compose up -d`, проверка `/api/health`. Требует чистого дерева git.
+3. На VPS заполнить `/root/kvarta_site/api.env` (chmod 600, скрипты его не трогают): `TELEGRAM_BOT_TOKEN`, `TELEGRAM_ADMIN_ID`, `TELEGRAM_API_BASE=http://<tailscale-ip-домашнего>:8788`.
+4. `TELEGRAM_BOT_ID=<цифры токена до двоеточия> deploy/tg-relay/deploy.sh` — ретранслятор на домашнем сервере (оба узла должны быть в Tailscale; на VPS — `tailscale up --accept-dns=false`, чтобы не задеть DNS соседних сайтов).
+5. Telegram: администратор пишет боту `/start`; в группе включить «Темы», сделать бота админом с правом «Управление темами»; написать в группе `/setup`. Бот создаст «Kvarta Cafe: Заявки» и «Kvarta Cafe: Система» и пришлёт в личку `TELEGRAM_CHAT_ID`, `TELEGRAM_LEADS_THREAD_ID`, `TELEGRAM_SYSTEM_THREAD_ID` — вписать в `api.env` и перезапустить api:
+
+```
+cd /root/kvarta_site && KVARTA_TAG=$(sed -n 's/^current=//p' .deployed) \
+  docker-compose -f docker-compose_vps.yml -p kvarta up -d --force-recreate api
+```
+
+Пока Telegram не настроен, заявки копятся в базе со статусом `pending` и уходят после настройки.
+
+## Обновление и откат
+
+- `deploy/deploy.sh` — новая версия; на сервере остаются текущий и предыдущий образы `kvarta-*`, чужие образы не трогаются.
+- `deploy/deploy.sh --rollback` — вернуть предыдущую версию.
+
+## Бэкапы
+
+- Каждый день в 03:00 по Минску и при старте, если за сегодня копии нет: `db.backup()` → gzip → `/data/backups/` в volume, 14 копий. Каждая копия уходит администратору в личку, итог — в «Систему».
+- Бот в личке администратора: `/backups` — список с кнопками восстановления, `/backup` — копия сейчас, присланный `.sqlite.gz` — восстановление из файла. Перед восстановлением бот показывает, какие заявки пропадут, и сохраняет текущую базу как `pre-restore-…`.
+
+## Где смотреть, если что-то не так
+
+- `docker-compose -f docker-compose_vps.yml -p kvarta logs api` — в том числе сбои связи с Telegram (раз в 10 минут).
+- Тема «Kvarta Cafe: Система» — 500, неотправленные после 10 попыток заявки, ошибки Telegram, старт и бэкапы.

docs/links.md

@@ -0,0 +1,40 @@
+# Ссылки для рекламы
+
+Лендинг сохраняет `utm_*`, `yclid`, `fbclid`, referrer, страницу входа и страницу отправки. Первое касание живёт 30 дней в localStorage, последнее — в sessionStorage; в заявку и в Telegram попадают оба (см. `GLOSSARY.md`).
+
+## Яндекс Директ
+
+В поле «Ссылка» объявления (макросы Директ подставит сам, `yclid` добавляется автоматически при включённой разметке ссылок для Метрики):
+
+```
+https://kvarta.unuchak.com/?utm_source=yandex&utm_medium=cpc&utm_campaign={campaign_id}&utm_content={ad_id}&utm_term={keyword}
+```
+
+Для РСЯ вместо `cpc` удобно различать площадку: `utm_medium={source_type}` (`search` / `context`).
+
+## Instagram
+
+Реклама через Ads Manager — поле «Параметры URL» (макросы Meta, `fbclid` Meta добавит сама):
+
+```
+utm_source=instagram&utm_medium=paid_social&utm_campaign={{campaign.name}}&utm_content={{ad.name}}
+```
+
+Ссылка в профиле:
+
+```
+https://kvarta.unuchak.com/?utm_source=instagram&utm_medium=social&utm_campaign=bio
+```
+
+Сторис со стикером-ссылкой:
+
+```
+https://kvarta.unuchak.com/?utm_source=instagram&utm_medium=social&utm_campaign=stories
+```
+
+## Как это выглядит у менеджера
+
+```
+Источник: yandex / cpc / 12345678 (первый визит: instagram, 9 дн. назад)
+Страница: /?utm_source=yandex&… → /#catalog
+```