# 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

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

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

```typescript
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)

- [x] **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 визуально

- [x] **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 и прогресс

- [x] **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 визуально

- [x] **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

- [x] **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.