Add Legacy API documentation for device & deployment management
Documents available API endpoints and their limitations: - set_deployment: Creates deployment (WORKS, returns deployment_id) - device_form: Attaches device to deployment (WORKS) - request_devices: Gets devices list (BROKEN - KeyError in Legacy API) Includes room location codes, SQL queries for WellNuo DB access, and complete flow examples for beneficiary setup. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
dd5bc7f95a
commit
ff35690e46
383
docs/LEGACY_API_DEVICES.md
Normal file
383
docs/LEGACY_API_DEVICES.md
Normal file
@ -0,0 +1,383 @@
|
|||||||
|
# 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 для существующих устройств
|
||||||
Loading…
x
Reference in New Issue
Block a user