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

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

• Цель бизнеса (12–24 мес): Получать 20 квалифицированных B2B-лидов в месяц и сократить нагрузку на менеджеров на 30% за счёт самообслуживания в кабинете за 18 мес.
• Кто платит vs кто пользуется: Платит B2B-компания (интегратор/аутсорс); пользуются её клиенты — руководители и сотрудники компаний.
• Ценность для пользователя (одной фразой): Клиент видит статус каждой заявки онлайн, не дергая менеджера.
• KPI успеха v1 (3–7 измеримых):
  • ≥ 20 лидов/мес с сайта
  • ≥ 60% клиентов активны в кабинете ежемесячно
  • Снижение входящих звонков «какой статус?» на 30%
  • Время первой реакции на заявку ≤ 2 ч
  • NPS клиентов ≥ 50
• Монетизация / экономика: Абонентское обслуживание от 90 тыс. ₽/мес и проекты внедрения; кабинет — инструмент удержания.
• Go-to-market: LinkedIn-аналог/VC.ru-статьи, отраслевые конференции, партнёрства, кейсы.
• SEO / контент / маркетинг в v1: Страницы услуг и отраслей, кейсы, блог экспертов.
• Конкуренты / аналоги (1–3) и отличие: Сайты интеграторов (Первый Бит, КОРУС), Service Desk-системы (Okdesk, Usedesk). Отличие: маркетинг и клиентский портал в одном продукте.
• Анти-цели v1: Не строим полноценный Service Desk, биллинг и мобильное приложение в v1.

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

• Название проекта: FlowDesk — корпоративный сайт B2B-интегратора с личным кабинетом клиента
• Одной фразой: Маркетинговый сайт + личный кабинет клиента со статусами заявок.
• Для кого: Руководители и ИТ-ответственные малого и среднего бизнеса.
• Проблема: Клиенты не видят прогресс работ, менеджеры тратят время на ответы «что со статусом?».
• Связь с §0: каждый сценарий v1 ведёт к KPI конверсии и измеряется целями в аналитике.

2. Границы

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

• Маркетинговые страницы: главная, услуги, кейсы, о компании, контакты
• Форма запроса КП
• Вход клиента (email + пароль)
• Кабинет: список заявок, статусы, детали, комментарии
• Создание новой заявки из кабинета с файлом
• Уведомления о смене статуса по email
• Админка менеджера: заявки клиентов, смена статуса

OUT OF SCOPE:

• Биллинг и акты
• SLA-калькулятор
• Чат в реальном времени
• SSO

Позже (v2+):

• Документы и акты в кабинете
• Интеграция с Jira/1С
• Telegram-уведомления
• Чат на WebSocket

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: Redis для кэша каталога/сессий; логи pino, uptime-мониторинг
• Хостинг / облако: VPS в РФ (Timeweb Cloud / Selectel), Nginx, Docker Compose
• Монолит / модульный монолит / сервисы: модульный монолит

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

1. Директор компании оставляет запрос КП и получает звонок менеджера.
2. Клиент логинится, создаёт заявку «Настроить обмен 1С» с вложением, видит статус «В работе».
3. Менеджер меняет статус на «На согласовании», клиент получает email и комментирует.

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

Сущность	Поля (примерно)	Связи	Заметки
Company	name, inn, plan, manager_id	1:N User, 1:N Ticket	Клиент
User	email, password_hash, name, role(client/manager/admin), company_id	N:1 Company	Роли
Ticket	number, company_id, title, description, status, priority, created_at, updated_at, due_at	1:N Comment, 1:N Attachment	Статусы: new/in_progress/review/done/closed
Comment	ticket_id, author_id, body, created_at	N:1 Ticket	—
Attachment	ticket_id, file_url, size, mime	N:1 Ticket	Лимит 20 МБ
Lead	name, company, phone, email, message, utm	—	Запрос КП

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

• SMTP — уведомления
• S3-совместимое хранилище (Yandex Object Storage) — файлы
• Яндекс Метрика
• v2: Jira/1С API

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

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

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

• JWT (access+refresh) в httpOnly cookie, bcrypt, роли client/manager/admin, изоляция данных по company_id, проверка mime файлов, rate-limit входа, аудит-лог изменений статуса.
• HTTPS (Let's Encrypt), helmet, CSP, валидация входных данных на сервере, секреты в .env вне репозитория.

9. UX / клиенты

• Web desktop-first для кабинета, mobile-friendly; админка 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

• Клиент видит только заявки своей компании
• Смена статуса пишется в аудит и отправляет email
• Фильтр заявок по статусу работает
• Файл до 20 МБ загружается, запрещённые типы отклоняются
• Маркетинговые страницы проходят Lighthouse ≥ 90

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