WellNuo/PRD-WEB.md

PRD — WellNuo Web

❓ Вопросы для уточнения

✅ Вопрос 1: BLE Service UUIDs

Нужно извлечь точные Service UUID и Characteristic UUIDs из services/ble/BLEManager.ts. Без них Web Bluetooth API не сможет найти WP сенсоры. Ответ:

• SERVICE_UUID: 4fafc201-1fb5-459e-8fcc-c5c9c331914b
• CHAR_UUID: beb5483e-36e1-4688-b7f5-ea07361b26a8 (Источник: services/ble/types.ts:41-42)

✅ Вопрос 2: Домен и Deployment

Где будет хоститься веб-версия? Это влияет на настройку CORS и SSL сертификатов для Web Bluetooth. Ответ: wellnuo.smartlaunchhub.com — тот же домен что и API (упрощает CORS)

✅ Вопрос 3: Стратегия Offline

Нужна ли работа offline для веба или всегда требуется интернет? В мобилке есть useOfflineAwareData.ts. Ответ: Не нужно — всегда требуется интернет для работы

💡 Рекомендации

❌ Рекомендация 1: Progressive Web App (PWA)

Что: Добавить PWA манифест и Service Worker для установки на рабочий стол Почему: Пользователи смогут "установить" веб-версию как нативное приложение, работа будет более stable Приоритет: Средний Решение: Нет, пропустить

✅ Рекомендация 2: Shared UI Components Library

Что: Создать общую библиотеку компонентов между мобильной и веб версией Почему: Consistency в дизайне, переиспользование логики валидации, меньше дублирования Приоритет: Высокий Решение: Да, добавить в задачи

✅ Рекомендация 3: Browser/BLE Fallback Strategy

Что: Graceful degradation — если браузер не поддерживается или BLE не работает:

1. Показать сообщение "Ваш браузер не поддерживает Web Bluetooth"
2. Предложить: "Попробуйте Chrome/Edge" или "Проверьте что Bluetooth включен"
3. Показать ссылку/QR на скачивание мобильного приложения (не навязчиво) Почему: Пользователь должен понимать что делать если что-то не работает Приоритет: Средний Решение: Да, добавить в задачи

❌ Рекомендация 4: Real-time Status Updates

Что: WebSocket соединение для live обновлений статуса сенсоров Почему: Пользователи увидят изменения статуса без перезагрузки страницы Приоритет: Низкий Решение: Нет, пропустить

❌ Рекомендация 5: Analytics & Error Tracking

Что: Интегрировать Sentry для error tracking и Analytics для user behavior Почему: Отслеживать проблемы с BLE на разных браузерах/ОС, понимать usage patterns Приоритет: Высокий Решение: Нет, пропустить (не для MVP)

---

Overview

Полноценная веб-версия WellNuo для настройки и мониторинга BLE-сенсоров с ноутбука/десктопа. Переиспользует существующий backend и API endpoints.

Ключевое преимущество: Удобная настройка сенсоров с большого экрана, полная клавиатура для ввода WiFi паролей.

Browser Compatibility & Error Handling

Поддерживаемые браузеры

• Chrome 70+ (Windows 10+, macOS)
• Edge 79+ (Windows 10+)
• Opera 57+ (Windows, macOS)

Неподдерживаемые

• Safari (Apple не реализовали Web Bluetooth)
• Firefox (Mozilla отказались по privacy concerns)
• Любой браузер на iOS (системные ограничения)

Tech Stack

Компонент	Технология	Обоснование
Framework	Next.js 14 (App Router)	SSR, API routes, похож на Expo Router
Styling	Tailwind CSS	Быстрая разработка, переиспользование из мобилки
State	Zustand	Легковесный, консистентность с мобильным app
BLE	Web Bluetooth API	Нативный браузерный API
Auth	JWT (существующий)	Один backend для мобилки и веба

Implementation Tasks

Phase 1: Foundation & Browser Compatibility @worker1

• @worker1 Создать Next.js проект с Tailwind CSS

  • Файл: next.config.js, tailwind.config.js, package.json
  • Настроить: TypeScript, ESLint, Prettier
  • Готово когда: npm run dev запускается без ошибок

• @worker1 Реализовать Browser Compatibility Check

  • Файл: lib/browserCheck.ts
  • Что сделать: Проверка navigator.bluetooth availability
  • Функции: isBrowserSupported(), getBrowserInfo(), getRecommendedBrowsers()
  • Готово когда: возвращает корректные boolean/объекты для разных браузеров

• @worker1 Создать Unsupported Browser Page (из рекомендации 3)

  • Файл: app/unsupported/page.tsx
  • Компоненты:
    1. Сообщение "Ваш браузер не поддерживает Web Bluetooth"
    2. Карточки рекомендуемых браузеров (Chrome, Edge, Opera)
    3. Секция "Проверьте что Bluetooth включен на устройстве"
    4. Ссылка + QR-код на скачивание мобильного приложения (не навязчиво)
  • Готово когда: отображается понятный fallback с альтернативами

• @worker1 Настроить Root Layout с redirect logic

  • Файл: app/layout.tsx, app/page.tsx
  • Переиспользует: Логику из services/NavigationController.ts
  • Готово когда: автоматически редиректит на /login или /dashboard в зависимости от auth статуса

Phase 2: Authentication System @worker2

• @worker2 Адаптировать API client для веба

  • Файл: services/api.ts (новый, на базе мобильного)
  • Переиспользует: Все endpoints из мобильного services/api.ts
  • Изменения: Заменить AsyncStorage на localStorage, убрать React Native dependencies
  • Готово когда: все API методы работают в браузере

• @worker2 Создать Auth Store (Zustand)

  • Файл: stores/authStore.ts
  • Переиспользует: Логику из contexts/BeneficiaryContext.tsx
  • State: user, accessToken, beneficiaries, isLoading, error
  • Actions: login(), verifyOtp(), logout(), updateProfile()
  • Готово когда: состояние персистится в localStorage

• @worker2 Реализовать Login Page

  • Файл: app/(auth)/login/page.tsx
  • Переиспользует: Валидацию email из мобилки
  • Компоненты: Input для email, кнопка "Получить код", error handling
  • Готово когда: отправляет OTP и редиректит на verify-otp

• @worker2 Реализовать OTP Verification Page

  • Файл: app/(auth)/verify-otp/page.tsx
  • Переиспользует: OTP логику из мобильного приложения
  • Компоненты: 6 полей для цифр, таймер "отправить повторно", auto-submit
  • Готово когда: успешная верификация редиректит через NavigationController

• @worker2 Создать Protected Route Middleware

  • Файл: middleware.ts
  • Что сделать: Проверка JWT токена, redirect на /login если unauthorized
  • Исключения: /login, /verify-otp, /unsupported - доступны без авторизации
  • Готово когда: защищенные роуты требуют авторизации

Phase 3: Core UI Components @worker3

• @worker3 Создать Shared UI Library (из рекомендации 2)

  • Папка: packages/ui/ — монорепо структура
  • Компоненты: Button, Input, Card, Avatar, Badge, Modal
  • Что сделать: Общие типы и стили между mobile (React Native) и web (React)
  • Готово когда: компоненты импортируются в обе версии приложения

• @worker3 Создать базовые UI компоненты

  • Файлы: components/ui/Button.tsx, components/ui/Input.tsx, components/ui/Card.tsx
  • Переиспользует: Дизайн из мобильных компонентов UI
  • Что сделать: Адаптировать для веба с Tailwind CSS
  • Готово когда: компоненты готовы к использованию в формах

• @worker3 Реализовать Layout компоненты

  • Файлы: components/Layout/Header.tsx, components/Layout/Sidebar.tsx
  • Компоненты: Навигация, профильное меню, breadcrumbs
  • Готово когда: layout отображается корректно на всех экранах

• @worker3 Создать Loading & Error компоненты

  • Файлы: components/ui/LoadingSpinner.tsx, components/ui/ErrorMessage.tsx
  • Переиспользует: Логику из мобильных компонентов
  • Что сделать: Skeleton loader, error boundary, retry buttons
  • Готово когда: компоненты показывают appropriate feedback

Phase 4: Dashboard & Beneficiary Management @worker2

• @worker2 Создать Dashboard Page

  • Файл: app/(main)/dashboard/page.tsx
  • Переиспользует: API calls из api.getAllBeneficiaries()
  • Компоненты: Список beneficiaries, добавление нового, summary cards
  • Готово когда: отображает всех beneficiaries с корректными данными

• @worker2 Реализовать Beneficiary Detail Page

  • Файл: app/(main)/beneficiaries/[id]/page.tsx
  • Переиспользует: api.getWellNuoBeneficiary(id), логику из мобильного detail экрана
  • Компоненты: Табы (Обзор, Сенсоры, История), статус сенсоров, actions
  • Готово когда: показывает все данные beneficiary и список подключенных сенсоров

• @worker2 Создать Add Beneficiary Flow

  • Файл: app/(auth)/add-loved-one/page.tsx
  • Переиспользует: Валидацию из мобильного приложения
  • Готово когда: создает beneficiary и правильно редиректит через NavigationController

Phase 5: Web Bluetooth Integration @worker1

• @worker1 Реализовать Web Bluetooth Service

  • Файл: services/webBluetooth.ts
  • Переиспользует: UUIDs и логику из services/ble/BLEManager.ts
  • Функции: scanForDevices(), connectToDevice(), writeCharacteristic(), readCharacteristic()
  • Готово когда: успешно находит и подключается к WP сенсорам

• @worker1 Создать BLE Scanner Component

  • Файл: components/BLEScanner.tsx
  • Переиспользует: Логику из мобильного BLE scanner
  • Компоненты: Список найденных устройств, signal strength, connect buttons
  • Готово когда: отображает найденные WP устройства с возможностью подключения

• @worker1 Реализовать WiFi Setup Flow

  • Файл: components/WiFiSetup.tsx
  • Переиспользует: Логику из services/espProvisioning.ts
  • Компоненты: Список WiFi сетей, поля для SSID/пароль, progress indicator
  • Готово когда: успешно настраивает WiFi на сенсоре через BLE

• @worker1 Создать Sensor Management Pages

  • Файл: app/(main)/beneficiaries/[id]/add-sensor/page.tsx
  • Интеграция: BLE scanner + WiFi setup + API attachment
  • Готово когда: полный flow от поиска до прикрепления сенсора к beneficiary

Phase 6: Error Handling & Edge Cases @worker3

• @worker3 Реализовать BLE Error Handling (из рекомендации 3)

  • Файл: hooks/useBLE.ts, components/BLEErrorFallback.tsx
  • Сценарии: Bluetooth disabled, permission denied, device not found, connection lost
  • Компоненты:
    1. "Bluetooth выключен" → инструкция как включить
    2. "Разрешение отклонено" → как дать разрешение в настройках браузера
    3. "Устройство не найдено" → проверьте что сенсор включен и рядом
    4. Общий fallback: "Не получается? Попробуйте другой браузер или скачайте приложение"
  • Готово когда: все BLE ошибки обрабатываются с понятными сообщениями и recovery actions

• @worker3 Добавить Network Error Handling

  • Файл: hooks/useApiWithRetry.ts
  • Переиспользует: Error handling patterns из мобилки
  • Готово когда: API ошибки показывают appropriate messages и retry options

• @worker3 Создать Online Status Check

  • Файл: hooks/useOnlineStatus.ts
  • Что сделать: Простая проверка navigator.onLine, показать баннер если нет сети
  • Готово когда: при потере сети показывается сообщение "Нет подключения к интернету"

Phase 7: Responsive Design & Polish @worker3

• @worker3 Адаптировать для всех экранов

  • Файлы: Все page components
  • Breakpoints: Mobile (768px), Tablet (1024px), Desktop (1280px+)
  • Готово когда: корректно отображается на всех размерах экранов

• @worker3 Добавить Dark Mode Support

  • Файлы: tailwind.config.js, theme context
  • Переиспользует: Color scheme из мобилки
  • Готово когда: переключение темы работает для всех компонентов

• @worker3 Реализовать Loading States

  • Компоненты: Skeleton loaders для всех асинхронных операций
  • Готово когда: пользователь видет feedback во время загрузки данных

Phase 8: Testing & Quality Assurance @worker1

• @worker1 Создать E2E тесты для критичных flows

  • Файлы: tests/e2e/auth.spec.ts, tests/e2e/ble-setup.spec.ts
  • Сценарии: Полный auth flow, BLE scan и setup, beneficiary management
  • Готово когда: тесты проходят на Chrome и Edge

• @worker1 Добавить Unit тесты для BLE сервиса

  • Файл: services/__tests__/webBluetooth.test.ts
  • Mock: Web Bluetooth API для тестирования
  • Готово когда: покрытие >80% для BLE логики

Success Criteria

• ✅ Browser Support: Работает в Chrome/Edge/Opera, показывает понятную ошибку в Safari/Firefox
• ✅ Authentication: Auth flow идентичен мобилке, JWT токен корректно управляется
• ✅ BLE Integration: Сканирование находит WP сенсоры, WiFi setup работает полностью
• ✅ Data Sync: Все изменения синхронизируются с тем же backend что и мобильное приложение
• ✅ Error Handling: Все ошибки (BLE, Network, Validation) обрабатываются с user-friendly messages
• ✅ Responsive Design: Корректно отображается от 768px до 4K мониторов
• ✅ Performance: Первичная загрузка <3 секунд, BLE операции <10 секунд

✅ Статус

PRD ГОТОВ К ИСПОЛНЕНИЮ

Все вопросы отвечены:

• ✅ BLE UUIDs извлечены из кодовой базы
• ✅ Домен: wellnuo.smartlaunchhub.com
• ✅ Offline: не требуется

Принятые рекомендации (добавлены в задачи):

• ✅ Shared UI Components Library — общие компоненты mobile/web
• ✅ Browser/BLE Fallback Strategy — graceful degradation при проблемах

Отклонённые рекомендации:

• ❌ PWA — не для MVP
• ❌ WebSocket real-time updates — не для MVP
• ❌ Analytics/Sentry — не для MVP

Задачи распределены между воркерами: @worker1 (Backend/BLE), @worker2 (Auth/API), @worker3 (UI/UX).

Следующий шаг:

cd ~/Documents/Projects/WellNuo && ralphy-sonnet --prd PRD-WEB.md