feat: Initial commit for OnEver Drive centralized backup system with Windows PyQt6 agent and Proxmox LXC deployment

2026-08-13 19:33:44 -03:00
commit 1bfb808c79
77 changed files with 10675 additions and 0 deletions
@@ -0,0 +1,143 @@
+# OnEver Drive — Referencia de API REST & WebSockets
+
+Base URL: `/api`
+
+---
+
+## 1. Autenticación
+
+### `POST /api/auth/login`
+Inicia sesión de usuario administrativo.
+- **Body**:
+  ```json
+  {
+    "email": "admin@oneverdrive.local",
+    "password": "Admin1234!"
+  }
+  ```
+- **Response**:
+  ```json
+  {
+    "access_token": "eyJhbGciOi...",
+    "token_type": "bearer",
+    "user": { "id": 1, "email": "admin@oneverdrive.local", "role": "ADMIN" }
+  }
+  ```
+
+---
+
+## 2. Clientes Windows
+
+### `POST /api/clients/registration-code`
+Genera un código temporal de un solo uso para registrar un nuevo agente Windows.
+- **Auth**: Bearer Token (ADMIN)
+- **Body**: `{ "client_name_hint": "SQL Server Prod", "expires_in_hours": 48 }`
+- **Response**: `{ "code": "OED-4A2F-9B1C", "expires_at": "2026-08-15T12:00:00Z" }`
+
+### `POST /api/clients/register`
+Invocado por el agente Windows con el código de registro para obtener credenciales únicas.
+- **Body**:
+  ```json
+  {
+    "registration_code": "OED-4A2F-9B1C",
+    "name": "SQL Server Prod",
+    "hostname": "WIN-SRV-2022",
+    "os_info": "Windows Server 2022 Datacenter",
+    "agent_version": "1.0.0"
+  }
+  ```
+- **Response**:
+  ```json
+  {
+    "client_code": "CLIENT-0001",
+    "device_id": "8f3b4d7c-3b1a-4d2e-9c1a-8f3b4d7c3b1a",
+    "device_token": "oed_sec_a8b9c0d1...",
+    "name": "SQL Server Prod",
+    "server_time": "2026-08-13T16:00:00Z"
+  }
+  ```
+
+### `GET /api/clients`
+Lista todos los clientes registrados.
+
+### `POST /api/clients/{id}/revoke`
+Revoca inmediatamente las credenciales de un cliente Windows.
+
+---
+
+## 3. Motor de Transferencia por Chunks
+
+### `POST /api/upload/session`
+Inicia una nueva sesión de subida o reanuda una sesión existente incompleta.
+- **Headers**:
+  `X-Device-Id: <DEVICE_ID>`
+  `X-Device-Token: <DEVICE_TOKEN>`
+- **Body**:
+  ```json
+  {
+    "filename": "database_production.bak",
+    "file_size": 12582912,
+    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "chunk_size": 4194304,
+    "job_id": 1
+  }
+  ```
+- **Response**:
+  ```json
+  {
+    "session_code": "6f2e8b1a-...",
+    "filename": "database_production.bak",
+    "file_size": 12582912,
+    "chunk_size": 4194304,
+    "total_chunks": 3,
+    "received_chunks": [0],
+    "status": "UPLOADING"
+  }
+  ```
+
+### `POST /api/upload/{session_code}/chunk`
+Envía los bytes de un bloque específico.
+- **Headers**:
+  `X-Device-Id: <DEVICE_ID>`
+  `X-Device-Token: <DEVICE_TOKEN>`
+  `X-Chunk-Index: 1`
+  `X-Chunk-SHA256: <CHUNK_HASH>`
+- **Body**: Raw binary bytes
+- **Response**:
+  ```json
+  {
+    "chunk_index": 1,
+    "is_received": true,
+    "total_received": 2,
+    "total_chunks": 3,
+    "progress_percent": 66.67
+  }
+  ```
+
+### `GET /api/upload/{session_code}/status`
+Devuelve el estado de la sesión y la lista de chunks pendientes de subida.
+
+### `POST /api/upload/{session_code}/complete`
+Solicita el ensamblado secuencial del archivo y la verificación de integridad SHA-256 total.
+- **Response**:
+  ```json
+  {
+    "session_code": "6f2e8b1a-...",
+    "filename": "database_production.bak",
+    "relative_path": "clients/CLIENT-0001/JOB-001/20260813_160000_database_production.bak",
+    "file_size": 12582912,
+    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "status": "SUCCESS"
+  }
+  ```
+
+---
+
+## 4. WebSockets Telemetría en Tiempo Real
+
+### Endpoint: `/ws/telemetry`
+Eventos transmitidos:
+- `UPLOAD_PROGRESS`: `{ "session_code", "filename", "client_id", "chunk_index", "received_chunks", "total_chunks", "progress_percent" }`
+- `UPLOAD_COMPLETED`: `{ "session_code", "filename", "client_id", "file_size", "sha256", "status" }`
+- `CLIENT_REGISTERED`: `{ "id", "client_code", "name", "hostname", "status" }`
+- `EVENT_LOG`: `{ "id", "timestamp", "event_type", "severity", "message" }`