WellNuo/PRD.md

PRD — WellNuo Sensor Integration (BLE + API)

Overview

Full integration of WP sensors with WellNuo app:

• BLE scanning and connection
• WiFi configuration
• API attachment to beneficiary's deployment
• Real-time sensor management

---

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

❓ Вопрос 1: BLE Permission Handling

Как обрабатывать отказ пользователя в BLE разрешениях? Это критично для основного флоу — без BLE сканирование невозможно. Ответ: Показать alert с объяснением зачем нужен BLE + кнопка "Open Settings". Уже есть BLEContext.tsx с permission handling — нужно улучшить UX сообщений.

❓ Вопрос 2: Concurrent Sensor Setup

Что если пользователь пытается настроить несколько сенсоров одновременно? BLE connection обычно exclusive. Ответ: Текущая реализация поддерживает batch setup — сенсоры обрабатываются ПОСЛЕДОВАТЕЛЬНО (один за другим). setup-wifi.tsx уже имеет processSensorsSequentially(). Одновременные BLE connections не нужны.

❓ Вопрос 3: WiFi Credentials Validation

Нужно ли валидировать WiFi пароль перед отправкой в сенсор? Некорректный пароль = сенсор недоступен до физической перезагрузки. Ответ: Базовая валидация (длина ≥8 символов для WPA2). Сложная валидация невозможна — мы не знаем тип WiFi сети. При ошибке сенсор можно перезагрузить физически (кнопка reset) или через BLE команду r.

❓ Вопрос 4: Deployment ID Mapping

Как получить deployment_id для beneficiary? Есть ли это поле в WellNuo API или нужно создавать mapping? Ответ: ✅ УЖЕ РЕШЕНО! deploymentId хранится в WellNuo API как поле beneficiary. Получается через GET /me/beneficiaries/:id → beneficiary.deploymentId. Код в services/api.ts:1893-1910 уже работает.

---

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

💡 Рекомендация 1: BLE Connection State Management

Что: Добавить централизованный state machine для BLE соединений с retry логикой Почему: BLE нестабильно — нужен robust retry mechanism и clear error states для пользователя Приоритет: Высокий Принять? [x] Да, добавить в задачи — уже частично есть в BLEManager.ts, нужно улучшить

💡 Рекомендация 2: WiFi Credentials Cache

Что: Сохранять WiFi credentials в SecureStore для повторного использования Почему: Пользователь не захочет каждый раз вводить домашний WiFi пароль для каждого сенсора Приоритет: Средний Принять? [x] Да, добавить в задачи — файл services/wifiPasswordStore.ts уже существует, нужно интегрировать

💡 Рекомендация 3: Sensor Setup Analytics

Что: Добавить аналитику для tracking setup success rate и failure points Почему: Поможет выявить где пользователи застревают в setup flow и оптимизировать UX Приоритет: Низкий Принять? [ ] Нет, пропустить — не для MVP, добавим после релиза

💡 Рекомендация 4: Background Sync for Sensor Status

Что: Background task для периодического обновления статуса сенсоров Почему: Realtime статус критичен для healthcare приложения — пользователь должен знать что сенсор offline Приоритет: Высокий Принять? [ ] Нет, пропустить — достаточно pull-to-refresh + useFocusEffect. Background sync добавляет complexity и battery drain

💡 Рекомендация 5: QR Code для быстрого добавления

Что: QR код на сенсоре с well_id и MAC для автозаполнения Почему: Устранит human error в вводе MAC адреса и ускорит onboarding Приоритет: Средний Принять? [ ] Нет, пропустить — на сенсорах нет QR кодов. MAC парсится из BLE названия WP_523_81a14c автоматически

---

⚠️ CRITICAL: API Rules for Workers

ВНИМАНИЕ! Воркеры ОБЯЗАНЫ следовать этим правилам! Без этого сенсоры НЕ БУДУТ работать с Legacy API.

Два разных ID — НЕ ПУТАТЬ!

ID	Что это	Когда использовать	Пример
well_id	ID сенсора (из названия WP_523_...)	Создание нового устройства	523
device_id	ID записи в базе данных	Обновление/удаление существующего	456

Правило 1: Создание нового устройства (attach)

device_form с параметрами:
- well_id: 523          ← ID из названия сенсора WP_523_xxxxx
- device_mac: 81A14C    ← MAC адрес (UPPERCASE!)
- deployment_id: 24     ← ID деплоймента beneficiary

Правило 2: MAC адрес всегда UPPERCASE

device_mac: mac.toUpperCase()  // "81A14C"

Правило 3: Парсинг well_id из BLE названия

const parts = deviceName.split('_');
const wellId = parseInt(parts[1], 10);  // 523
const mac = parts[2].toUpperCase();      // "81A14C"

---

Technical Architecture

Two API Systems

┌─────────────────────────────────────────────────────────────────────┐
│                        WellNuo App                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────────────┐           ┌─────────────────────────────┐  │
│  │    WellNuo API      │           │       Legacy API            │  │
│  │ (wellnuo.smartlaunchhub.com)    │  (eluxnetworks.net)        │  │
│  ├─────────────────────┤           ├─────────────────────────────┤  │
│  │ • Auth (JWT)        │           │ • Sensor data               │  │
│  │ • Beneficiaries     │           │ • Device management         │  │
│  │ • Subscriptions     │           │ • Deployment management     │  │
│  │ • deploymentId link │──────────▶│ • device_form               │  │
│  └─────────────────────┘           │ • device_list_by_deployment │  │
│                                    │ • request_devices           │  │
│                                    │ • get_devices_locations     │  │
│                                    └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

---

Tasks

Оставшиеся задачи — все в @worker4 (Setup Screens) Файлы: setup-wifi.tsx, add-sensor.tsx, device-settings/

---

@worker4 — Setup Screens (setup-wifi, add-sensor, device-settings)

• Add WiFi signal strength indicator in setup

  • Файл: app/(tabs)/beneficiaries/[id]/setup-wifi.tsx:89-156
  • Что сделать: Parse RSSI from BLE response, show signal bars UI
  • Готово когда: Список WiFi сетей показывает signal strength визуально

• Add setup progress indicator

  • Файл: app/(tabs)/beneficiaries/[id]/setup-wifi.tsx
  • Переиспользует: components/BatchSetupProgress.tsx pattern
  • Что сделать: 4-step progress: BLE Connect → WiFi Config → Reboot → API Attach
  • Готово когда: Пользователь видит текущий step и прогресс

• Improve BLE scan UI with signal strength

  • Файл: app/(tabs)/beneficiaries/[id]/add-sensor.tsx
  • Переиспользует: components/ui/LoadingSpinner.tsx
  • Что сделать: Show RSSI bars, device distance estimate, scan progress
  • Готово когда: Список сенсоров показывает signal quality визуально

• Enhanced device settings with reconnect flow

  • Файл: app/(tabs)/beneficiaries/[id]/device-settings/[deviceId].tsx:137-152
  • Переиспользует: existing setup-wifi screen
  • Что сделать: "Change WiFi" → guided BLE reconnect → WiFi update without full re-setup
  • Готово когда: WiFi изменение работает без re-pairing device

• Add comprehensive error states

  • Файл: app/(tabs)/beneficiaries/[id]/setup-wifi.tsx, add-sensor.tsx
  • Переиспользует: components/ui/ErrorMessage.tsx
  • Что сделать: BLE timeout, WiFi failure, API error → specific recovery actions
  • Готово когда: Каждая ошибка имеет clear recovery path

• Add E2E tests for sensor management

  • Файл: .maestro/sensor-setup.yaml
  • Что сделать: Full sensor setup flow from scan to API attachment
  • Готово когда: E2E test покрывает complete happy path

---

Success Criteria

• BLE scan finds WP sensors with signal strength indication
• WiFi configuration works reliably with credential validation
• API attachment succeeds with proper error handling
• Sensor status shows correctly (online/offline) with background updates
• Location/description can be changed through device settings
• Detach removes sensor from deployment cleanly
• All flows work on real device with proper permission handling
• Setup funnel analytics show >80% completion rate
• App handles offline mode gracefully

✅ Статус

PRD улучшен с focus на:

• Production readiness: Добавлены permission handling, error states, background sync
• User Experience: Credential cache, signal indicators, progress tracking, QR scanning
• Developer Experience: Четкое разделение worker'ов, переиспользование existing компонентов
• Quality: Integration tests, E2E coverage, analytics для optimization

Основные улучшения: state machine для BLE, WiFi credential cache, deployment mapping, background sensor sync, comprehensive error handling.