# 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" }`