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

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

• Цель бизнеса (12–24 мес): Выйти на 400 заказов в месяц и выручку 2 млн ₽/мес через собственный сайт за 18 мес, снизить зависимость от маркетплейсов.
• Кто платит vs кто пользуется: Платит владелец бренда; пользуются покупатели 25–40 лет.
• Ценность для пользователя (одной фразой): Купить базовую одежду в скандинавском стиле напрямую у бренда без наценки маркетплейса.
• KPI успеха v1 (3–7 измеримых):
  • Конверсия в заказ ≥ 1,8%
  • Добавление в корзину ≥ 8% сессий
  • Брошенные корзины ≤ 70%
  • Средний чек ≥ 6 500 ₽
  • Повторные покупки ≥ 20% за 6 мес
• Монетизация / экономика: Маржа 55–65% на собственном производстве; бесплатная доставка от 7 000 ₽.
• Go-to-market: Instagram-подобные соцсети и VK, Telegram-канал бренда, коллаборации с блогерами, ретаргет брошенных корзин.
• SEO / контент / маркетинг в v1: Страницы категорий и товаров с уникальными описаниями, микроразметка Product/Offer, лукбук-статьи.
• Конкуренты / аналоги (1–3) и отличие: Wildberries/Ozon, 12 Storeez, Lime. Отличие: камерный бренд, честный состав, быстрый чекаут.
• Анти-цели v1: Не делаем маркетплейс, программу лояльности и мультивалютность в v1.

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

• Название проекта: NordWear — мини интернет-магазин одежды и аксессуаров
• Одной фразой: Каталог из 8–12 товаров, карточка, корзина и оформление заказа.
• Для кого: Горожане 25–40 лет, ценящие минимализм и натуральные ткани.
• Проблема: На маркетплейсе бренд теряет маржу и связь с покупателем.
• Связь с §0: каждый сценарий v1 ведёт к KPI конверсии и измеряется целями в аналитике.

2. Границы

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

• Главная с лукбуком
• Каталог 8–12 товаров с фильтром по категории
• Карточка товара: фото, размер, состав, цена
• Корзина (localStorage в макете, сервер в проде)
• Оформление заказа: контакты, доставка, комментарий
• Подтверждение заказа на email
• Админка товаров и заказов

OUT OF SCOPE:

• Отзывы с фото
• Личный кабинет
• Программа лояльности
• Мультиязычность

Позже (v2+):

• Онлайн-оплата ЮKassa
• СДЭК API с расчётом доставки
• Личный кабинет и история заказов
• Промокоды

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. Покупатель фильтрует «Верхняя одежда», открывает парку, выбирает размер M и добавляет в корзину.
2. Покупатель меняет количество в корзине и оформляет заказ с доставкой СДЭК.
3. Менеджер видит заказ в админке и меняет статус на «Отправлен».

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

Сущность	Поля (примерно)	Связи	Заметки
Product	title, slug, category, price, old_price, composition, images[], is_active	1:N Variant	8–12 SKU
Variant	product_id, size, stock	N:1 Product	Остатки
Cart	session_id, items[{variant_id, qty}]	—	В макете — localStorage
Order	number, name, phone, email, address, delivery_method, total, status, created_at	1:N OrderItem	Статусы: new/paid/shipped/done/cancelled
OrderItem	order_id, variant_id, qty, price	N:1 Order	Цена снимком

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

• ЮKassa (v2) — оплата
• СДЭК API (v2) — доставка
• SMTP — письмо о заказе
• Яндекс Метрика e-commerce

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

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

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

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

9. UX / клиенты

• Web, mobile-first; админка 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

• Корзина сохраняется после перезагрузки страницы
• Итог пересчитывается при изменении количества
• Нельзя оформить заказ с пустой корзиной или без телефона
• После заказа корзина очищается и показывается номер заказа
• Карточка товара открывается и закрывается на mobile без багов

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