# Storage Module

## Descripcion

Sistema de almacenamiento de archivos con soporte multi-proveedor (S3, GCS, Azure, local). Gestiona buckets, carpetas jerarquicas, archivos con versionado, thumbnails, y tokens de acceso temporal. Incluye cuotas por tenant y busqueda de archivos.

## Entidades

| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `StorageBucket` | storage.buckets | Contenedores de almacenamiento con configuracion de proveedor y limites |
| `StorageFolder` | storage.folders | Carpetas jerarquicas dentro de buckets |
| `StorageFile` | storage.files | Archivos con metadata, checksums, thumbnails y versionado |
| `StorageUpload` | storage.uploads | Uploads en progreso (multipart) |
| `FileAccessToken` | storage.file_access_tokens | Tokens temporales para acceso a archivos |
| `FileShare` | storage.file_shares | Archivos compartidos con enlaces publicos |
| `TenantUsage` | storage.tenant_usage | Estadisticas de uso de almacenamiento por tenant |

## Servicios

| Servicio | Responsabilidades |
|----------|-------------------|
| `StorageService` | CRUD de buckets, folders y files; busqueda; estadisticas de uso; versionado |

## Endpoints

| Method | Path | Descripcion |
|--------|------|-------------|
| GET | `/buckets` | Lista buckets disponibles |
| GET | `/buckets/:id` | Obtiene bucket por ID |
| POST | `/buckets` | Crea nuevo bucket |
| PATCH | `/buckets/:id` | Actualiza bucket |
| DELETE | `/buckets/:id` | Elimina bucket (debe estar vacio) |
| GET | `/buckets/:bucketId/folders` | Lista carpetas en bucket |
| GET | `/folders/:id` | Obtiene carpeta por ID |
| POST | `/folders` | Crea carpeta |
| PATCH | `/folders/:id` | Actualiza carpeta |
| DELETE | `/folders/:id` | Elimina carpeta (opcional recursivo) |
| GET | `/buckets/:bucketId/files` | Lista archivos en bucket/carpeta |
| GET | `/files/:id` | Obtiene archivo por ID |
| GET | `/files/key/:storageKey` | Obtiene archivo por storage key |
| POST | `/files` | Registra archivo subido |
| PATCH | `/files/:id` | Actualiza metadata de archivo |
| DELETE | `/files/:id` | Elimina archivo |
| POST | `/files/:id/download` | Registra descarga (incrementa contador) |
| GET | `/search` | Busca archivos por nombre/descripcion |
| GET | `/usage` | Obtiene uso de almacenamiento del tenant |
| GET | `/recent` | Lista archivos recientes |

## Dependencias

- `common` - Utilidades compartidas
- `auth` - Contexto de tenant
- Proveedor de storage (S3/GCS/Azure/local)

## Configuracion

La configuracion del proveedor se almacena en cada bucket (`storageConfig`).

| Proveedor | Configuracion Requerida |
|-----------|------------------------|
| `local` | basePath |
| `s3` | region, bucket, accessKeyId, secretAccessKey |
| `gcs` | projectId, bucket, keyFile |
| `azure` | accountName, accountKey, containerName |

## Tipos de Bucket

| Tipo | Descripcion |
|------|-------------|
| `public` | Archivos accesibles sin autenticacion |
| `private` | Requiere autenticacion para acceso |
| `protected` | Acceso via tokens temporales |

## Categorias de Archivo

- `image` - Imagenes (jpg, png, gif, etc.)
- `document` - Documentos (pdf, doc, xls, etc.)
- `video` - Videos
- `audio` - Archivos de audio
- `archive` - Archivos comprimidos
- `other` - Otros tipos

## Versionado

Cuando esta habilitado en el bucket:
- Cada actualizacion crea una nueva version
- Se mantiene referencia al `parentVersionId`
- Solo la ultima version tiene `isLatest = true`
- Limite configurable de versiones por archivo
