diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9521a2b --- /dev/null +++ b/.gitignore @@ -0,0 +1,30 @@ +node_modules/ +.pnpm-store/ +.next/ +out/ +dist/ +coverage/ +*.tsbuildinfo +next-env.d.ts + +# секреты и данные +.env +.env.* +!.env.example +*.env +!*.env.example +data/ +*.sqlite +*.sqlite-* +*.sqlite.gz + +# артефакты проверки дизайна и производительности +.screenshots/ +.lighthouse/ +test-results/ +playwright-report/ + +# worktree'ы агентов +.worktrees/ + +.DS_Store diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..8480d76 --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,49 @@ +# Кварта + +Лендинг минской обжарки «Кварта»: посетитель оставляет заявку, менеджер получает её в Telegram. + +## Language + +**Заявка**: +Обращение посетителя через форму: имя, телефон, интерес, комментарий. Имеет номер #N. +_Avoid_: лид, заказ, обращение + +**Уточнение**: +Повторная отправка с того же телефона в течение 10 минут после первой отправки заявки, которая что-то меняет. Дописывается к заявке, новой заявки не создаёт. +_Avoid_: дубль, обновление заявки + +**Окно уточнений**: +10 минут от создания заявки; уточнения его не продлевают. Отправка после окна — новая заявка. +_Avoid_: таймаут дублей + +**Интерес**: +Что хочет посетитель: подписка, разовый заказ или вопрос. +_Avoid_: тип заявки, категория + +## Люди + +**Посетитель**: +Человек на лендинге; после отправки формы — автор заявки. +_Avoid_: пользователь, клиент, лид + +**Менеджер**: +Сотрудник «Кварты», который читает заявки в Telegram-группе и перезванивает. +_Avoid_: оператор, админ + +**Администратор**: +Единственный человек, которому бот подчиняется в личке: бэкапы, восстановление, настройка тем. +_Avoid_: менеджер, владелец + +## Источник + +**Касание**: +Визит посетителя на лендинг с его метками (utm, yclid, fbclid), referrer и страницей входа. +_Avoid_: сессия, хит + +**Первое касание**: +Самый ранний визит посетителя за последние 30 дней, в том числе прямой без меток. +_Avoid_: first touch, первоисточник + +**Последнее касание**: +Визит, во время которого отправлена заявка; включает ещё и страницу отправки. +_Avoid_: last touch, текущий источник diff --git a/docs/adr/0001-landing-and-api-as-separate-services.md b/docs/adr/0001-landing-and-api-as-separate-services.md new file mode 100644 index 0000000..f93406c --- /dev/null +++ b/docs/adr/0001-landing-and-api-as-separate-services.md @@ -0,0 +1,13 @@ +# Лендинг и API — два отдельных приложения + +Лендинг (`apps/landing`, Next.js) и приём заявок (`apps/api`, Hono + better-sqlite3) живут в pnpm workspace как два приложения с общим пакетом `packages/shared` (телефон, контракт заявки, валидация) и деплоятся двумя контейнерами за одним nginx: `/` → 13120, `/api/` → 13121. Так бэкенд с базой, очередью Telegram и бэкапами перезапускается и развивается независимо от вёрстки, а граница между ними проверяется сборкой, а не договорённостью. + +## Considered Options + +- Одно Next.js-приложение с `route.ts` и границей модулей через ESLint — проще деплой (один образ), но API, планировщик бэкапов и long polling бота жили бы в процессе фронта. +- Статический экспорт лендинга, отдаваемый nginx с хоста — отказались: теряем `next/image` и меняем привычную на сервере схему «контейнер за nginx». + +## Consequences + +- Один домен, поэтому CORS не нужен; форма шлёт `fetch('/api/lead')`. +- `packages/shared` поставляется исходниками: Next — через `transpilePackages`, api — вшивается tsup. diff --git a/docs/adr/0002-telegram-bot-as-admin-channel.md b/docs/adr/0002-telegram-bot-as-admin-channel.md new file mode 100644 index 0000000..e3918f0 --- /dev/null +++ b/docs/adr/0002-telegram-bot-as-admin-channel.md @@ -0,0 +1,15 @@ +# Telegram-бот как канал администрирования + +Менеджер видит заявки только в Telegram, а на сервере соседствуют чужие боевые сайты, поэтому всё администрирование — настройка тем (`/setup`), ежедневные бэкапы с копией администратору в личку, восстановление базы — делает процесс api через бота, который читает обновления long polling'ом. Ни cron на хосте, ни входящего webhook'а, ни админки: на сервере меняется только наш каталог и один конфиг nginx. + +## Considered Options + +- Cron на хосте + ручное восстановление по ssh — трогает общий crontab сервера, и восстановление требует доступа по ssh. +- Webhook вместо polling — нужен публичный эндпоинт и секрет, а выигрыша при нашем трафике нет. +- Отдельный скрипт `tg:setup` через `getUpdates` — конфликтует с polling работающего api, заменён командой `/setup`. + +## Consequences + +- У бота один поток обновлений: никакой другой процесс не должен вызывать `getUpdates` с этим токеном. +- Если Telegram недоступен целиком, о сбоях узнаём только из `docker-compose logs api`. +- Восстановление из копии удаляет заявки, пришедшие после неё; бот перечисляет их в подтверждении и сохраняет текущую базу как `pre-restore`. diff --git a/docs/ai-log.md b/docs/ai-log.md new file mode 100644 index 0000000..9fafe44 --- /dev/null +++ b/docs/ai-log.md @@ -0,0 +1,8 @@ +# Ошибки ИИ + +Записи по ходу работы: что ИИ сделал не так, чем поймали, что исправили. Источник для раздела README «где ИИ ошибся». + +| # | Шаг | Ошибка ИИ | Чем поймали | Исправление | +|---|---|---|---|---| +| 1 | План, деплой | Предложил `docker compose run …`, не проверив сервер; там нет плагина compose, только `docker-compose` v2.23 | Осмотр сервера по ssh перед планом деплоя | Везде `docker-compose` | +| 2 | План, Telegram | Предложил скрипт `tg:setup` через `getUpdates`, а позже — long polling в api; два потребителя одного потока обновлений конфликтуют | Сам заметил при проектировании восстановления через бота | Скрипт заменён командой бота `/setup` (ADR-0002) | diff --git a/docs/plan.md b/docs/plan.md new file mode 100644 index 0000000..2a83473 --- /dev/null +++ b/docs/plan.md @@ -0,0 +1,166 @@ +# План реализации + +Согласованная спецификация (интервью 2026-10-17). Термины — по `GLOSSARY.md`, крупные решения — `docs/adr/`. Дедлайн сдачи: пн 2026-10-19 18:00 МСК. + +## Факты из ТЗ (ничего сверх них не выдумывать) + +- Обжарка «Кварта», Минск, с 2019 года, основатели Аня и Дмитрий (бывшие бариста). Партии по 5 кг, обжарка по четвергам, развоз по Минску по пятницам, зерно у клиента на 1–3 день после обжарки. +- Эфиопия Иргачеффе — цветочный, бергамот, светлая обжарка — 250 г, 32 BYN. +- Колумбия Уила — карамель, красное яблоко — 250 г, 29 BYN. +- Бразилия Серрадо — орех, шоколад, под эспрессо — 250 г, 26 BYN. +- Дрип-пакеты ассорти — 10 шт, 18 BYN. +- Подписка — 2 пачки по 250 г раз в месяц, доставка бесплатно — 54 BYN/мес. +- Самовывоз: Минск, ул. Короля, 9. Пн–пт 8:00–20:00, сб–вс 10:00–18:00. +- Доставка по Минску в пятницу, от 50 BYN бесплатно. Цена ниже 50 BYN в ТЗ не указана → «стоимость уточнит менеджер». +- Контактов в ТЗ нет; телефон вымышленный: +375 29 000-00-00. +- Аудитория 25–45, мобильный трафик из Instagram и Яндекса. Тон тёплый, простой, без пафоса. + +## Структура + +``` +apps/landing/ Next.js App Router, Tailwind, next/font (кириллица), next/og; output: 'standalone' + src/app/ layout.tsx, page.tsx, opengraph-image.tsx + src/components/ секции и LeadForm, StickyCta + src/content/site.ts все тексты и факты + src/lib/attribution.ts +apps/api/ Hono + @hono/node-server, better-sqlite3, сборка tsup → dist/index.js + src/app.ts createApp(deps) — без listen, для тестов через app.request() + src/index.ts запуск сервера, планировщики, polling бота + src/db/ открытие базы, миграции (PRAGMA user_version + SQL) + src/leads.ts создать заявку / уточнение / дубль — в одной транзакции + src/telegram/ клиент Bot API, очередь отправки, «Система», команды бота + src/backup.ts бэкапы и восстановление + src/rateLimit.ts +packages/shared/ @kvarta/shared, исходники TS без сборки + src/phone.ts normalizeBelarusPhone, isValidBelarusPhone, formatBelarusPhone, phoneError + src/lead.ts LeadRequest, LeadResponse, Touch, Interest, validateLead, тексты ошибок +deploy/ Dockerfile.landing, Dockerfile.api, docker-compose_vps.yml, deploy.sh, setup-nginx.sh, nginx/kvarta.unuchak.com.conf +``` + +Импорты: landing → shared, api → shared. Landing не импортирует api и наоборот. Тесты Vitest рядом с кодом (`*.test.ts`). + +## Телефон + +Оставить цифры и ведущий `+`. Принимаем: `375XXXXXXXXX` (12 цифр), `80XXXXXXXXX` (11), `0XXXXXXXXX` (10), `XXXXXXXXX` (9), где после префикса код `25|29|33|44|17` и 7 цифр. Результат `+375XXXXXXXXX`. Первая цифра абонентского номера не проверяется. Ошибки: +- пусто → «Укажите телефон — по нему перезвоним» +- другой код страны (`+7`, `+48`…) → «Нужен белорусский номер: +375…» +- неизвестный код → «Проверьте код оператора: 25, 29, 33, 44 или 17» +- не та длина → «После кода нужно 7 цифр» + +В форме: `inputmode="tel"`, `autocomplete="tel"`, без маски; на blur валидный номер переформатируется в `+375 29 123-45-67`; ошибка показывается после blur или submit. + +## Касания + +- Первое касание: localStorage `kvarta:first-touch`, `{ ...touch, at }`, живёт 30 дней, не перезаписывается до истечения, прямой визит тоже фиксируется. +- Последнее касание: sessionStorage `kvarta:last-touch`, записывается при входе в сессию; при отправке добавляется `submitPage`. +- `Touch = { utm_source?, utm_medium?, utm_campaign?, utm_content?, utm_term?, yclid?, fbclid?, referrer?, landingPage, submitPage?, at }`. Строки ≤ 500 символов. +- Хранилища в try/catch: недоступность не ломает отправку. + +## POST /api/lead + +Запрос JSON ≤ 16 КБ: `{ name (1–60 после trim), phone, interest: 'subscription'|'one_time'|'question', comment? (≤1000), company? (honeypot), firstTouch?: Touch|null, lastTouch: Touch }`. + +| Код | Тело | Когда | +|---|---|---| +| 201 | `{ok:true, duplicate:false}` | новая заявка; также при заполненном honeypot (ничего не сохраняем) | +| 200 | `{ok:true, duplicate:true, clarified:true}` | уточнение | +| 200 | `{ok:true, duplicate:true, clarified:false}` | повтор без изменений | +| 400 | `{ok:false, error:'validation', fieldErrors}` | ошибки полей | +| 413/415 | `{ok:false, error:'bad_request'}` | не JSON / слишком большое тело | +| 429 | `{ok:false, error:'rate_limited'}` + `Retry-After` | > 5 запросов / 10 мин с IP | +| 503 | `{ok:false, error:'unavailable'}` | идёт восстановление базы | +| 500 | `{ok:false, error:'server'}` | прочее | + +Номер заявки клиенту не отдаём. IP — из `X-Real-IP`, только если сокет от 127.0.0.1. IP в базе не храним. `GET /api/health` → `{ok:true, version}`. + +Клиент: кнопка «Отправляем…» и disabled на время запроса, таймаут 10 с; сеть/таймаут/5xx/429/413 → блок «Не получилось отправить. Попробуйте ещё раз или позвоните: +375 29 000-00-00». + +## Уточнения (окно 10 минут от created_at заявки) + +1. Тот же телефон, есть заявка моложе 10 мин, поля (name, interest, comment) равны последней версии (последнее уточнение, иначе заявка) → `clarified:false`, ничего не пишем, в Telegram ничего. +2. Поля отличаются → строка в `lead_clarifications`, в Telegram «Уточнение к заявке #N» с изменившимися полями. +3. Заявки моложе 10 мин нет → новая заявка. Уточнения окно не продлевают. + +Всё в одной транзакции better-sqlite3. + +## Схема + +```sql +CREATE TABLE leads ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + created_at TEXT NOT NULL, + phone TEXT NOT NULL, + name TEXT NOT NULL, + interest TEXT NOT NULL CHECK (interest IN ('subscription','one_time','question')), + comment TEXT, + first_touch TEXT, + last_touch TEXT NOT NULL, + user_agent TEXT, + tg_status TEXT NOT NULL DEFAULT 'pending' CHECK (tg_status IN ('pending','sent','failed')), + tg_attempts INTEGER NOT NULL DEFAULT 0, + tg_last_error TEXT, + tg_next_at TEXT +); +CREATE INDEX leads_phone_created ON leads(phone, created_at); + +CREATE TABLE lead_clarifications ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + lead_id INTEGER NOT NULL REFERENCES leads(id), + created_at TEXT NOT NULL, + name TEXT NOT NULL, + interest TEXT NOT NULL, + comment TEXT, + last_touch TEXT NOT NULL, + tg_status TEXT NOT NULL DEFAULT 'pending' CHECK (tg_status IN ('pending','sent','failed')), + tg_attempts INTEGER NOT NULL DEFAULT 0, + tg_last_error TEXT, + tg_next_at TEXT +); +``` + +Время — ISO 8601 UTC. Миграции через `PRAGMA user_version`. + +## Telegram + +- `.env` api: `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `TELEGRAM_LEADS_THREAD_ID`, `TELEGRAM_SYSTEM_THREAD_ID`, `TELEGRAM_ADMIN_ID`. Любая может отсутствовать — api работает, отправки копятся в `pending`. +- Порядок: транзакция → ответ клиенту → попытка отправки (таймаут 5 с). Фоновая очередь каждые 60 с: `pending`/`failed`, `tg_attempts < 10`, `tg_next_at <= now`, пауза 1, 2, 4… мин; уточнение не уходит раньше своей заявки. +- Сообщение — HTML, пользовательский ввод экранируется: + ``` + 🟥 Заявка #12 · подписка + Имя: … + Телефон: +375291234567 + Комментарий: … + Источник: yandex / cpc / osen (первый визит: instagram, 9 дн. назад) + Страница: … → … + ``` +- Тема «Kvarta Cafe: Система» (без персональных данных, только `#N`, код, короткий stack; одинаковые ошибки не чаще раза в 10 мин с «×N за период»): 500, заявка не ушла после 10 попыток, Telegram 400/403, сбой старта/миграции (best effort), «api запущен, версия », результат бэкапа и восстановления. Не шлём: 400, 429, honeypot. Без `TELEGRAM_SYSTEM_THREAD_ID` — только stdout. +- Бот: long polling `getUpdates` в процессе api — единственный потребитель обновлений. Команды принимаются только от `from.id == TELEGRAM_ADMIN_ID`, остальным молчим: + - `/setup` в группе: проверить, что темы включены и у бота есть право управлять темами (иначе объяснить по-русски), создать «Kvarta Cafe: Заявки» и «Kvarta Cafe: Система», прислать админу в личку строки `TELEGRAM_CHAT_ID=…`, `TELEGRAM_LEADS_THREAD_ID=…`, `TELEGRAM_SYSTEM_THREAD_ID=…`. Если id уже заданы — отказ, `/setup force` — создать заново. + - `/backups` в личке — последние копии с inline-кнопками (вкл. pre-restore). + - `/backup` — копия сейчас, прислать файлом. + - кнопка копии или присланный `.sqlite.gz` → подтверждение «Восстановить базу из …? Сейчас N заявок, M новее этой копии и пропадут (#…). Текущая база будет сохранена как pre-restore.» [Восстановить] [Отмена]. + +## Бэкапы + +- Ежедневно 03:00 Europe/Minsk и при старте, если за сегодня нет: `db.backup()` → gzip → `/data/backups/kvarta-YYYY-MM-DDTHHmm.sqlite.gz`. Храним 14 ежедневных; `pre-restore-*` — 30 дней. +- Каждую ежедневную копию — администратору в личку `sendDocument`; в «Систему» — «Бэкап 18.10 03:00: 12 заявок, 4 КБ ✅» или ошибку. +- Восстановление: gunzip → `PRAGMA integrity_check` → `user_version` не новее текущей → pre-restore копия → пауза приёма (503) → закрыть, подменить, открыть, миграции → отчёт админу и в «Систему». + +## Деплой + +- Сервер: root@185.5.249.52, x86_64, `docker-compose` v2.23 (плагина `docker compose` нет), диск занят на 89%. Рядом чужие боевые сайты — трогаем только своё. +- `/root/kvarta_site/`: `docker-compose_vps.yml` (landing `127.0.0.1:13120:3000`, api `127.0.0.1:13121:3000`, volume `kvarta-data:/data` только у api, `restart: unless-stopped`), `api.env` (chmod 600, заполняет автор, скрипты не трогают). +- `deploy/deploy.sh` (локально): чистое дерево → `SHA` → buildx `linux/amd64` → `kvarta-landing:$SHA`, `kvarta-api:$SHA` (+`latest`) → проверка ≥1 ГБ свободно → `docker save | gzip | ssh 'gunzip | docker load'` → scp compose → `up -d` → ждать `/api/health` 30 с → удалить `kvarta-*` кроме текущего и предыдущего. `--rollback` — на предыдущий тег. Никакого общего `docker image prune`. +- `deploy/setup-nginx.sh` (однократно): конфиг по образцу ai-testing (`/` → 13120, `/api/` → 13121, `X-Real-IP`), `nginx -t` → reload → `certbot --nginx -d kvarta.unuchak.com`. + +## Порядок коммитов (без Co-Authored-By) + +0. Подготовка: .gitignore, GLOSSARY, ADR, план, ai-log. +1. pnpm workspace. 2. shared: телефон + тесты. 3. api: health и lead с SQLite. 4. landing: заглушка с формой. 5. deploy → ★ прод. +6. Уточнения + тесты. 7. Касания + тесты. 8. Rate-limit, honeypot, ошибки. 9. Telegram → ★. 10. Бэкапы и восстановление → ★. +11. DESIGN.md. 12. Секции и тексты. 13. Анимации, липкая CTA, предзаполнение. 14. OG и метаданные. 15–17. Итерации критика. 18. impeccable audit + simplify. +19. README, Lighthouse, ссылки → ★ финал. + +## Если не хватает времени + +Контрольная точка вс 18.10 20:00: если этап 2 (шаги 6–10) не закрыт — режем по порядку: восстановление через бота → итерации критика до одной → тема «Система» → `/setup` → анимации (оставить штамп и кнопку) → повторы Telegram. Не режем: HTTPS-деплой, все блоки с ценами, форму с телефоном/дублями/UTM/ошибками, тесты, отправку в «Заявки», OG, README и Lighthouse.