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

4 воркера без конфликтов по файлам:

• @worker1 — BLE Services (services/ble/*)
• @worker2 — API Services (services/api.ts, services/*.ts)
• @worker3 — Equipment Screen (equipment.tsx)
• @worker4 — Setup Screens (setup-wifi.tsx, add-sensor.tsx, device-settings/)

---

@worker1 — BLE Services (services/ble/*)

• Add BLE permissions handling with graceful fallback

  • Файл: services/ble/BLEManager.ts
  • Что сделать: Добавить requestPermissions() метод с iOS/Android specific handling
  • Готово когда: При отказе в разрешениях показывается понятная ошибка с инструкциями

• Implement BLE connection state machine

  • Файл: services/ble/BLEManager.ts, services/ble/types.ts
  • Что сделать: State enum (idle/scanning/connecting/connected/error), retry логика, timeout handling
  • Готово когда: BLE соединение восстанавливается автоматически при обрыве

• Add concurrent connection protection

  • Файл: services/ble/BLEManager.ts
  • Что сделать: Mutex для предотвращения одновременных BLE операций
  • Готово когда: Попытка подключиться к второму устройству показывает ошибку "Disconnect current device first"

• Create BLE integration tests

  • Файл: services/ble/__tests__/BLEManager.integration.test.ts
  • Переиспользует: MockBLEManager.ts patterns
  • Что сделать: Test complete setup flow with mock BLE device
  • Готово когда: Setup flow тестируется end-to-end без real hardware

---

@worker2 — API & Backend Services (services/*.ts)

• Implement WiFi credentials cache in SecureStore

  • Файл: services/wifiPasswordStore.ts
  • Переиспользует: services/storage.ts patterns
  • Что сделать: Save/retrieve WiFi networks, auto-suggest previously used networks
  • Готово когда: При повторной настройке предлагается сохраненный пароль

• Create deployment_id lookup mechanism

  • Файл: services/api.ts
  • Что сделать: Add getDeploymentForBeneficiary() method to resolve beneficiary → deployment_id mapping
  • Готово когда: attachDeviceToBeneficiary() автоматически получает deployment_id

• Add API error handling for sensor attachment

  • Файл: services/api.ts:1878-1945
  • Переиспользует: Existing error handling patterns
  • Что сделать: Specific error messages for duplicate MAC, invalid well_id, network errors
  • Готово когда: Пользователь получает понятные ошибки вместо generic "API Error"

• Add sensor health monitoring

  • Файл: services/api.ts, новый services/sensorHealth.ts
  • Что сделать: Track offline duration, battery status, connection quality metrics
  • Готово когда: Equipment screen показывает health warnings

• Add sensor setup analytics

  • Файл: новый services/analytics.ts
  • Что сделать: Track setup funnel, failure points, time-to-complete
  • Готово когда: Analytics показывают setup conversion rate

---

@worker3 — Equipment Screen (equipment.tsx)

• Add pull-to-refresh with loading states

  • Файл: app/(tabs)/beneficiaries/[id]/equipment.tsx
  • Переиспользует: components/ui/LoadingSpinner.tsx
  • Что сделать: RefreshControl + loading overlay, haptic feedback
  • Готово когда: Pull-to-refresh работает с visual feedback

• Enhanced sensor cards with status indicators

  • Файл: app/(tabs)/beneficiaries/[id]/equipment.tsx:400-468
  • Переиспользует: components/ui/icon-symbol.tsx для status dots
  • Что сделать: Location icon + name, last seen relative time, online/warning/offline status dot
  • Готово когда: Каждый сенсор показывает location, status и last seen

• Add empty state with prominent Add Sensor button

  • Файл: app/(tabs)/beneficiaries/[id]/equipment.tsx
  • Переиспользует: components/ui/Button.tsx
  • Что сделать: Illustration + "No sensors added yet" + large "Add Sensor" button
  • Готово когда: Empty state направляет к add-sensor screen

• Add bulk sensor operations

  • Файл: app/(tabs)/beneficiaries/[id]/equipment.tsx
  • Что сделать: Select multiple sensors → bulk detach, bulk location update
  • Готово когда: Long press активирует selection mode с bulk actions

• Add offline mode graceful degradation

  • Файл: app/(tabs)/beneficiaries/[id]/equipment.tsx
  • Переиспользует: Network state detection patterns
  • Что сделать: Show cached sensor data when offline, queue operations for retry
  • Готово когда: App показывает sensor data даже без internet

---

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

• Add WiFi credentials validation

  • Файл: app/(tabs)/beneficiaries/[id]/setup-wifi.tsx
  • Переиспользует: utils/serialValidation.ts pattern
  • Что сделать: Validate SSID length, password complexity, show warnings for weak passwords
  • Готово когда: Невалидные credentials блокируют отправку с объяснением

• 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.