WellNuo/specs/wellnuo/FEATURE-SENSORS-SYSTEM.md

FEATURE: Sensors Management System

ID: FEATURE-SENSORS Status: 🟡 In Progress Priority: High Created: 2026-01-19

---

Overview

Система управления BLE-сенсорами WP для мониторинга пожилых людей (beneficiaries). Сенсоры измеряют активность в помещении и передают данные через WiFi на Legacy API.

Схема архитектуры: https://diagrams.love/canvas?schema=cmkm6nt6x0063ll5lqaq49lbt

---

Сущности

Beneficiary (Подопечный)

• Пожилой человек, за которым ухаживают
• Хранится в: WellNuo API (PostgreSQL)
• Поля: firstName, lastName, avatar, dateOfBirth

Deployment (Домовладение)

• Место проживания beneficiary в Legacy API
• Хранится в: Legacy API (eluxnetworks.net)
• Поля: address, timezone, devices[], beneficiary_id
• Связь: 1 Beneficiary = 1 Deployment

Device (WP Sensor)

• Физический BLE/WiFi сенсор
• Хранится в: Legacy API
• Поля:
  • well_id — уникальный ID устройства
  • mac — MAC адрес
  • location — где установлен (текстовое поле, редактируемое)
  • description — описание (текстовое поле, редактируемое)
  • deployment_id — привязка к домовладению
  • status — online/warning/offline (вычисляется по lastSeen)

---

API

WellNuo API (Primary)

Base URL: https://wellnuo.smartlaunchhub.com/api Auth: Bearer JWT token

Используется для:

• Авторизация пользователей
• CRUD beneficiaries
• Подписки и платежи
• Профиль пользователя

Legacy API (External)

Base URL: https://eluxnetworks.net/function/well-api/api Auth: Form-encoded (user_name, token)

⚠️ Внешний сервис — нет доступа к коду, только API

Ключевые endpoints для устройств:

Endpoint	Описание	Параметры
device_list_by_deployment	Список устройств deployment	deployment_id
device_form	Создать/обновить устройство	well_id, device_mac, location, description, deployment_id
device_set_group	Установить группу	device_id, group_id
request_devices	Получить online устройства	deployment_id, fresh=true

Формат device_form:

POST /function/well-api/api
Content-Type: application/x-www-form-urlencoded

function=device_form
user_name={{user_name}}
token={{token}}
well_id=497
device_mac=142B2F81A14C
location=Спальня, у кровати
description=Основной сенсор
deployment_id=22

---

Bluetooth Flow

BLE Manager

Файл: services/ble/BLEManager.ts Библиотека: react-native-ble-plx

UUID и протокол:

SERVICE_UUID: '4fafc201-1fb5-459e-8fcc-c5c9c331914b'
CHAR_UUID: 'beb5483e-36e1-4688-b7f5-ea07361b26a8'

BLE команды:

Команда	Формат	Описание
PIN Unlock	pin|7856	Разблокировка устройства
Get WiFi List	w	Получить доступные WiFi
Set WiFi	W|SSID,PASSWORD	Установить WiFi
Get WiFi Status	a	Текущее подключение
Reboot	s	Перезагрузка
Disconnect	D	Отключение BLE

Таймауты:

• Сканирование: 10 сек
• Команда: 5 сек

Формат ответа WiFi List:

SSID1,-55;SSID2,-70;SSID3,-80

---

Экраны

1. Equipment Screen

Путь: /(tabs)/beneficiaries/:id/equipment Файл: app/(tabs)/beneficiaries/[id]/equipment.tsx

Функции:

• Summary card (total/online/warning/offline)
• Список подключённых сенсоров (из API)
• BLE сканирование поблизости
• Detach сенсор

Текущие ограничения:

• ❌ НЕТ редактирования location/description

2. Add Sensor Screen

Путь: /(tabs)/beneficiaries/:id/add-sensor Файл: app/(tabs)/beneficiaries/[id]/add-sensor.tsx

Функции:

• Инструкции по добавлению (4 шага)
• BLE сканирование
• Список найденных устройств с RSSI

3. Setup WiFi Screen

Путь: /(tabs)/beneficiaries/:id/setup-wifi Файл: app/(tabs)/beneficiaries/[id]/setup-wifi.tsx

Функции:

• Получить WiFi список от сенсора (BLE)
• Выбор сети и ввод пароля
• Подключение и привязка к beneficiary

4. Device Settings Screen

Путь: /(tabs)/beneficiaries/:id/device-settings/:deviceId Файл: app/(tabs)/beneficiaries/[id]/device-settings/[deviceId].tsx

Функции:

• Просмотр Well ID, MAC, Deployment ID
• Текущий WiFi статус
• Изменение WiFi
• Перезагрузка

Текущие ограничения:

• ❌ НЕТ редактирования location/description

---

Что нужно доработать

TASK-1: Добавить редактирование location/description

Проблема: Сейчас location и description показываются в UI (equipment.tsx:454-456), но нет возможности их редактировать.

Решение:

1. Добавить в Device Settings Screen форму для редактирования
2. Создать метод updateDevice() в api.ts
3. Использовать Legacy API endpoint device_form

Файлы для изменения:

• services/api.ts — добавить updateDeviceMetadata(deviceId, location, description)
• app/(tabs)/beneficiaries/[id]/device-settings/[deviceId].tsx — добавить форму

API вызов:

async updateDeviceMetadata(
  deviceId: string,
  wellId: number,
  mac: string,
  location: string,
  description: string
) {
  const creds = await this.getLegacyCredentials();
  const formData = new URLSearchParams({
    function: 'device_form',
    user_name: creds.userName,
    token: creds.token,
    editing_device_id: deviceId,
    well_id: wellId.toString(),
    device_mac: mac,
    location: location,
    description: description,
  });
  // POST to Legacy API
}

TASK-2: Показывать placeholder для пустого location

Проблема: Если location пустой — ничего не показывается.

Решение: В equipment.tsx вместо:

{sensor.location && (
  <Text style={styles.deviceLocation}>{sensor.location}</Text>
)}

Сделать:

<TouchableOpacity onPress={() => openLocationEditor(sensor)}>
  <Text style={styles.deviceLocation}>
    {sensor.location || 'Tap to set location'}
  </Text>
</TouchableOpacity>

TASK-3: Quick edit location из Equipment Screen

Проблема: Сейчас для редактирования location нужно заходить в Device Settings.

Решение: Добавить inline редактирование или ActionSheet с опцией "Edit Location".

---

Ключевые файлы

Файл	Описание
services/ble/BLEManager.ts	BLE менеджер
services/ble/types.ts	Типы BLE
contexts/BLEContext.tsx	Global BLE state
services/api.ts	API методы
types/index.ts	WPSensor тип (строки 47-59)
app/(tabs)/beneficiaries/[id]/equipment.tsx	Equipment Screen
app/(tabs)/beneficiaries/[id]/add-sensor.tsx	Add Sensor
app/(tabs)/beneficiaries/[id]/setup-wifi.tsx	Setup WiFi
app/(tabs)/beneficiaries/[id]/device-settings/[deviceId].tsx	Device Settings
api/Wellnuo_API.postman_collection.json	Postman коллекция

---

Статусы сенсора

Вычисляются на клиенте по lastSeen:

Статус	Условие	Цвет
online	lastSeen < 5 мин	Зелёный
warning	5 мин < lastSeen < 60 мин	Жёлтый
offline	lastSeen > 60 мин	Красный

---

Mock режим

Когда приложение работает в iOS Simulator, используется MockBLEManager с тестовыми данными:

{
  id: 'mock-743',
  name: 'WP_497_81a14c',
  mac: '142B2F81A14C',
  rssi: -55,
  wellId: 497,
}

Это позволяет разрабатывать без физического устройства.

---

Implementation Steps

Phase 1: API метод для обновления устройства

• Создать updateDeviceMetadata() в api.ts
• Тестировать через curl/Postman

Phase 2: UI для редактирования в Device Settings

• Добавить TextInput для location
• Добавить TextInput для description
• Кнопка Save
• Loading state при сохранении

Phase 3: Quick edit из Equipment Screen

• Добавить ActionSheet с опцией "Edit Location"
• Или inline edit по тапу

Phase 4: Валидация и UX

• Показывать placeholder для пустого location
• Ограничить длину текста (если есть лимит API)
• Показывать success/error feedback

---

Verification Checklist

• Сенсоры загружаются из Legacy API
• BLE сканирование находит WP_* устройства
• WiFi настройка работает через BLE
• Location/description сохраняется в Legacy API
• Location отображается в Equipment Screen
• Mock режим работает в симуляторе