CleanPro — техническое описание

0. Бизнес-цели и успех (обязательно)

• Цель бизнеса (12–24 мес): Выйти на 150 заказов уборки в месяц из сайта в одном городе-миллионнике; снизить стоимость заявки ниже 600 ₽ за 12 мес.
• Кто платит vs кто пользуется: Платит владелец клининговой компании; пользуются частные клиенты и офис-менеджеры.
• Ценность для пользователя (одной фразой): Узнать точную цену уборки за 30 секунд и оставить заявку без звонка.
• KPI успеха v1 (3–7 измеримых):
  • Конверсия посетитель → заявка ≥ 6%
  • ≥ 70% заявок приходят с заполненным расчётом
  • Доля заявок с UTM-метками ≥ 95%
  • Время загрузки LCP < 2,0 с на 4G
  • ≥ 40% посетителей взаимодействуют с калькулятором
• Монетизация / экономика: Доход клиента — оплата уборок (средний чек 6–12 тыс. ₽); сайт окупается при 10–15 заказах.
• Go-to-market: Яндекс Директ и VK Реклама на квизовую посадку, карточки на Яндекс Картах и Авито, сарафан через промокоды.
• SEO / контент / маркетинг в v1: Страницы под запросы «уборка квартиры [город]», «генеральная уборка цена», «уборка после ремонта»; 3 статьи-гайда; микроразметка LocalBusiness и FAQ.
• Конкуренты / аналоги (1–3) и отличие: Qlean, Getclean, местные клинингы на Tilda. Отличие: прозрачный калькулятор с фиксированной ценой и сквозная аналитика UTM до заявки.
• Анти-цели v1: Не делаем личный кабинет клиента, онлайн-оплату и мобильное приложение; не ведём рекламу.

1. Название и суть

• Название проекта: CleanPro — лендинг клининговой компании с калькулятором
• Одной фразой: Одностраничник, который считает цену уборки и собирает заявку с источником трафика.
• Для кого: Жители и офисы города, которым нужна разовая или регулярная уборка.
• Проблема: Клиенты не оставляют заявку, потому что не понимают итоговую цену; владелец не знает, какая реклама даёт заказы.
• Связь с §0: каждый сценарий v1 ведёт к KPI конверсии и измеряется целями в аналитике.

2. Границы

IN SCOPE (обязательно в v1):

• Hero с оффером и CTA
• Калькулятор: площадь (м²), тип помещения (квартира/дом/офис/после ремонта), тип уборки, срочность, доп. услуги
• Форма заявки с телефоном, адресом, датой и автоподстановкой расчёта
• Скрытые UTM-поля (utm_source, utm_medium, utm_campaign, utm_content, utm_term) и yclid/gclid
• Секции: услуги, как мы работаем, гарантии, отзывы, FAQ, контакты
• Отправка заявки в Telegram и на email, сохранение в БД
• Админ-страница со списком заявок и ценами

OUT OF SCOPE:

• Онлайн-оплата
• Личный кабинет клиента
• Расписание клинеров
• Мобильное приложение

Позже (v2+):

• Онлайн-оплата и предоплата
• Подписка на регулярную уборку
• Интеграция с amoCRM/Bitrix24
• A/B-тесты офферов

3. Стек

• Frontend: React 19 + Vite (продакшен); макет — чистый HTML/CSS/JS без сборки
• Стили UI: CSS Modules / собственная дизайн-система по INPUT/DESIGN.html
• Backend: Node.js 20 LTS + Express
• БД OLTP: PostgreSQL 16
• Аналитика / OLAP: Яндекс Метрика; OLAP не требуется в v1
• Кэш / очереди / observability: не требуется в v1; логи pino, uptime-мониторинг
• Хостинг / облако: VPS в РФ (Timeweb Cloud / Selectel), Nginx, Docker Compose
• Монолит / модульный монолит / сервисы: модульный монолит

4. Ключевые сценарии

1. Посетитель с рекламы вводит 54 м², выбирает «квартира», «генеральная», «срочно» — видит 9 180 ₽ и оставляет заявку с этим расчётом.
2. Офис-менеджер выбирает «офис 200 м²», добавляет мойку окон, отправляет заявку; менеджер получает её в Telegram с UTM.
3. Владелец открывает админку, фильтрует заявки по utm_campaign и видит, какая кампания приносит заказы.

5. Сущности и данные

Сущность	Поля (примерно)	Связи	Заметки
Lead	id, name, phone, address, date, comment, created_at, status	1:1 Calculation, 1:1 UtmData	Статусы: new/called/booked/lost
Calculation	area_m2, room_type, clean_type, urgency, extras[], price_total	принадлежит Lead	Цена хранится снимком на момент заявки
UtmData	utm_source, utm_medium, utm_campaign, utm_content, utm_term, yclid, gclid, referrer, landing_url	принадлежит Lead	Сохраняется из URL в sessionStorage
PriceRule	room_type, clean_type, rate_per_m2, min_price, urgency_coef	используется калькулятором	Редактируется в админке
Review	author, text, rating, photo	—	Статичный контент v1

6. Интеграции

• Telegram Bot API — уведомление о заявке
• SMTP (Nodemailer) — копия заявки на email
• Яндекс Метрика — цели «calc_used», «lead_sent»
• Яндекс Карты — блок «Зона выезда»

7. Нефункциональные требования

• Ожидаемая нагрузка: До 5 000 посетителей и 300 заявок в месяц
• Latency / доступность: TTFB < 300 мс, LCP < 2,5 с на mobile, доступность 99,5%
• Retention EventLog / evidence / audit: логи 30 дней, заявки/заказы 3 года, бэкап БД ежедневно с хранением 14 дней
• Compliance: 152-ФЗ: согласие на обработку ПД у формы, политика конфиденциальности, хранение ПД на серверах в РФ

8. Безопасность

• Без регистрации для посетителей; админка — один пользователь, вход по JWT; капча (Yandex SmartCaptcha) и rate-limit на форму; телефон и адрес — ПД.
• HTTPS (Let's Encrypt), helmet, CSP, валидация входных данных на сервере, секреты в .env вне репозитория.

9. UX / клиенты

• Web, mobile-first (70% трафика с телефона); админка — desktop.
• Доступность: контраст AA, фокус-состояния, подписи полей форм.

9b. Дизайн

• HTML-референс: INPUT/DESIGN.html (картинки в INPUT/assets/, описания в INPUT/assets/DESCRIPTIONS.md)

9c. CI/CD и окружения

• Окружения: local / ci / staging / production
• CI: GitHub Actions — lint, тесты, сборка Docker-образа; деплой на staging по merge в main, на production по тегу
• Хостинг: VPS в РФ, Docker Compose, Nginx reverse proxy

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

• Язык кода: TypeScript (strict) на фронте и бэке; автотесты Vitest + Playwright для ключевых сценариев
• Запрещённые практики: хранение секретов в репозитории, ПД в логах, inline-SQL без параметров

11. Готовые модули

• logging-pino
• rate-limiting
• caching-redis
• auth-jwt
• websocket-socketio
• admin-panel
• file-upload
• crud-table
• payments-stripe
• search
• email-nodemailer

12. Критерии приёмки v1

• Калькулятор пересчитывает цену без перезагрузки при каждом изменении поля
• Заявка сохраняется в БД и приходит в Telegram за < 10 с
• UTM из URL сохраняются и уходят вместе с заявкой
• Lighthouse Performance ≥ 90 на mobile
• Страница корректна на ширине 360–1920 px
• Форма не отправляется без согласия на обработку ПД

13. Свободные заметки