Sergei
20aacb4044
- PRD.md updates - E2E test updates (auth, complete-auth, full-flow) - Ralphy progress tracking files - Admin tsconfig files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
196 lines
12 KiB
Markdown
196 lines
12 KiB
Markdown
# 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
|
||
|
||
- [x] **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
|
||
|
||
- [x] BLE scan finds WP sensors with signal strength indication
|
||
- [x] WiFi configuration works reliably with credential validation
|
||
- [x] 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.
|