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