WellNuo/docs/LEGACY_API_DEVICES.md

# Legacy API — Device & Deployment Management

## Overview

WellNuo использует **Legacy API** (`eluxnetworks.net`) для управления IoT устройствами и деплойментами.

**Архитектура баз данных:**
- **Legacy DB** (eluxnetworks.net, внутренняя) — хранит deployments, users, devices созданные через API
- **WellNuo DB** (`wellnuo_app` на eluxnetworks.net:5432) — хранит связи WellNuo beneficiaries с Legacy deployments

---

## Authentication

### Login (Get Token)

```bash
curl -s -X POST https://eluxnetworks.net/function/well-api/api \
  -d "function=credentials" \
  -d "user_name=robster" \
  -d "ps=rob2" \
  -d "clientId=001" \
  -d "nonce=$(date +%s)"
```

**Response:**
```json
{
  "ok": 1,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user_name": "robster",
  "expiry": 1766257742
}
```

**Token validity:** 7 days

---

## Deployments

### Create Deployment (set_deployment) ✅ РАБОТАЕТ

Создаёт deployment и пользователя-бенефициара в Legacy системе.

```bash
TOKEN="your-jwt-token"
TIMESTAMP=$(date +%s)

curl -s -X POST https://eluxnetworks.net/function/well-api/api \
  -d "function=set_deployment" \
  -d "user_name=robster" \
  -d "token=$TOKEN" \
  -d "deployment=NEW" \
  -d "beneficiary_name=Test User" \
  -d "beneficiary_email=test${TIMESTAMP}@example.com" \
  -d "beneficiary_user_name=testuser${TIMESTAMP}" \
  -d "beneficiary_password=securepass123" \
  -d "beneficiary_address=123 Main St" \
  -d "beneficiary_photo=/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAn/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCwAB//2Q==" \
  -d "firstName=Test" \
  -d "lastName=User" \
  -d "first_name=Test" \
  -d "last_name=User" \
  -d "new_user_name=testuser${TIMESTAMP}" \
  -d "phone_number=+10000000000" \
  -d "key=securepass123" \
  -d "signature=Test" \
  -d "gps_age=0" \
  -d "wifis=[]" \
  -d "devices=[]"
```

**Response:**
```json
{
  "ok": 1,
  "deployment_id": 120,
  "beneficiary_user_id": 273,
  "status": "200 OK"
}
```

**Важные параметры:**
| Параметр | Обязательный | Описание |
|----------|--------------|----------|
| `beneficiary_photo` | ✅ Да | Base64 JPEG (даже минимальный 1x1 pixel) |
| `beneficiary_user_name` | ✅ Да | Уникальный username |
| `beneficiary_email` | ✅ Да | Уникальный email |
| `key` | ✅ Да | Пароль бенефициара |
| `signature` | ✅ Да | Подпись (любое значение) |

---

## Devices

### Room Location Codes

| Room | Code |
|------|------|
| Bedroom | 102 |
| Living Room | 103 |
| Kitchen | 104 |
| Bathroom | 105 |
| Hallway | 106 |
| Office | 107 |
| Garage | 108 |
| Dining Room | 109 |
| Basement | 110 |
| Other | 200 |

### Attach Device to Deployment (device_form)

```bash
TOKEN="your-jwt-token"

curl -s -X POST https://eluxnetworks.net/function/well-api/api \
  -d "function=device_form" \
  -d "user_name=robster" \
  -d "token=$TOKEN" \
  -d "well_id=523" \
  -d "mac=142B2F81AAD4" \
  -d "location=102" \
  -d "description=Bedroom" \
  -d "group_id=120"
```

**Response:**
```json
{"ok": 1}
```

### Set Device Well ID (device_set_well_id)

Привязка устройства к деплойменту:

```bash
TOKEN="your-jwt-token"

curl -s -X POST https://eluxnetworks.net/function/well-api/api \
  -d "function=device_set_well_id" \
  -d "user_name=robster" \
  -d "token=$TOKEN" \
  -d "well_id=523" \
  -d "new_group_id=120"
```

### Get Deployment Devices (request_devices)

```bash
TOKEN="your-jwt-token"

curl -s -X POST https://eluxnetworks.net/function/well-api/api \
  -d "function=request_devices" \
  -d "user_name=robster" \
  -d "token=$TOKEN" \
  -d "deployment_id=120"
```

> **Примечание:** Может требовать внутреннюю инициализацию. Если не работает — используйте SQL.

---

## WellNuo Database Access

Для работы с WellNuo данными (связи beneficiary ↔ deployment) используйте PostgreSQL напрямую.

### Connection

```bash
PGCONNECT_TIMEOUT=15 PGPASSWORD='W31153Rg31' psql \
  -h eluxnetworks.net -p 5432 -U sergei -d wellnuo_app
```

### Link Beneficiary to Legacy Deployment

```sql
-- Привязать WellNuo beneficiary к Legacy deployment
INSERT INTO beneficiary_deployments (beneficiary_id, legacy_deployment_id)
VALUES (71, 120)
ON CONFLICT (beneficiary_id)
DO UPDATE SET legacy_deployment_id = 120;
```

### Get Devices for Deployment

```sql
SELECT
  id AS well_id,
  mac,
  description AS room_name,
  location AS room_code,
  group_id AS deployment_id,
  online,
  last_data_at
FROM devices
WHERE group_id = 120
ORDER BY id;
```

### Check Device Online Status

```sql
SELECT
  id AS well_id,
  description AS room,
  online,
  last_data_at,
  CASE
    WHEN online = true AND last_data_at > NOW() - INTERVAL '5 minutes' THEN 'Online'
    WHEN last_data_at > NOW() - INTERVAL '1 hour' THEN 'Recent'
    ELSE 'Offline'
  END AS status
FROM devices
WHERE group_id = 120;
```

### Change Room Assignment

```sql
UPDATE devices
SET
  location = 103,           -- Living Room
  description = 'Living Room'
WHERE id = 523;
```

---

## Complete Flow: Create Beneficiary with Device

### 1. Get Legacy Token

```bash
TOKEN=$(curl -s -X POST https://eluxnetworks.net/function/well-api/api \
  -d "function=credentials&user_name=robster&ps=rob2&clientId=001&nonce=$(date +%s)" \
  | jq -r '.token')
```

### 2. Create Legacy Deployment

```bash
TIMESTAMP=$(date +%s)
RESPONSE=$(curl -s -X POST https://eluxnetworks.net/function/well-api/api \
  -d "function=set_deployment" \
  -d "user_name=robster" \
  -d "token=$TOKEN" \
  -d "deployment=NEW" \
  -d "beneficiary_name=John Doe" \
  -d "beneficiary_email=john${TIMESTAMP}@example.com" \
  -d "beneficiary_user_name=johndoe${TIMESTAMP}" \
  -d "beneficiary_password=pass123" \
  -d "beneficiary_address=123 Main St" \
  -d "beneficiary_photo=/9j/4AAQSkZJRgABAQEASABIAAD..." \
  -d "firstName=John" \
  -d "lastName=Doe" \
  -d "first_name=John" \
  -d "last_name=Doe" \
  -d "new_user_name=johndoe${TIMESTAMP}" \
  -d "phone_number=+15551234567" \
  -d "key=pass123" \
  -d "signature=wellnuo" \
  -d "gps_age=0" \
  -d "wifis=[]" \
  -d "devices=[]")

DEPLOYMENT_ID=$(echo $RESPONSE | jq -r '.deployment_id')
echo "Created deployment: $DEPLOYMENT_ID"
```

### 3. Attach Device to Deployment

```bash
curl -s -X POST https://eluxnetworks.net/function/well-api/api \
  -d "function=device_form" \
  -d "user_name=robster" \
  -d "token=$TOKEN" \
  -d "well_id=523" \
  -d "mac=142B2F81AAD4" \
  -d "location=102" \
  -d "description=Bedroom" \
  -d "group_id=$DEPLOYMENT_ID"
```

### 4. Link to WellNuo Beneficiary

```bash
PGPASSWORD='W31153Rg31' psql -h eluxnetworks.net -p 5432 -U sergei -d wellnuo_app -c "
  INSERT INTO beneficiary_deployments (beneficiary_id, legacy_deployment_id)
  VALUES (71, $DEPLOYMENT_ID)
  ON CONFLICT (beneficiary_id) DO UPDATE SET legacy_deployment_id = $DEPLOYMENT_ID;
"
```

---

## WellNuo Backend Integration

Код в `/var/www/wellnuo-api/src/legacyAPI.js`:

```javascript
// Room location mapping
const ROOM_LOCATIONS = {
  'Bedroom': 102,
  'Living Room': 103,
  'Kitchen': 104,
  'Bathroom': 105,
  'Hallway': 106,
  'Office': 107,
  'Garage': 108,
  'Dining Room': 109,
  'Basement': 110,
  'Other': 200
};

// Create deployment via Legacy API
async function createLegacyDeployment(params) {
  const formData = new URLSearchParams({
    function: 'set_deployment',
    user_name: params.username,
    token: params.token,
    deployment: 'NEW',
    beneficiary_name: params.beneficiaryName,
    beneficiary_email: params.beneficiaryEmail,
    beneficiary_user_name: params.beneficiaryUsername,
    beneficiary_password: params.beneficiaryPassword,
    beneficiary_photo: params.beneficiaryPhoto || MINIMAL_JPEG,
    // ... other params
  });

  const response = await fetch(LEGACY_API_URL, {
    method: 'POST',
    body: formData
  });

  const data = await response.json();
  return data.deployment_id; // Returns actual deployment ID (e.g., 120)
}
```

---

## Quick Reference

| Task | Method | Endpoint/Query |
|------|--------|----------------|
| Login | API | `function=credentials` |
| Create deployment | API | `function=set_deployment` |
| Attach device | API | `function=device_form` |
| Change device group | API | `function=device_set_well_id` |
| Get devices | SQL | `SELECT * FROM devices WHERE group_id = ?` |
| Change room | SQL | `UPDATE devices SET location = ?` |
| Check online status | SQL | `SELECT online, last_data_at FROM devices` |
| Link WellNuo beneficiary | SQL | `INSERT INTO beneficiary_deployments...` |

---

## Database Tables

### devices (Legacy DB, accessible via SQL)
```
id (well_id), mac, description (room), location (room_code),
group_id (deployment_id), online, last_data_at, firmware
```

### beneficiary_deployments (WellNuo DB)
```
beneficiary_id, legacy_deployment_id
```

---

## Troubleshooting

### `deployment_id: 0` в ответе
- Убедитесь что передаёте `beneficiary_photo` с валидным base64 JPEG
- Все обязательные поля должны быть заполнены

### `request_devices` возвращает ошибку
- Используйте SQL запрос к таблице `devices` как альтернативу

### Device не обновляется через API
- Используйте SQL UPDATE для существующих устройств