feat: implementar 12 mejoras, tests, docs y optimizaciones

- Fase A: license templates, search history, cost estimator - Fase B: import URL, bulk ZIP, batch download - Fase C: comparison mode, mesh validation, measurement tool - Fase D: cross-section clipping, overhang heatmap, layer animation - Refactor Pydantic/SQLAlchemy warnings - 24 tests pytest - README actualizado - WebP thumbnails, lazy loading, cache headers
2026-04-27 09:14:58 +00:00
commit 14b307110d
31 changed files with 5386 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,139 @@
+# STL Repository
+
+Aplicacion web completa para gestionar, organizar, visualizar y compartir modelos 3D en formato STL y 3MF.
+
+## Caracteristicas principales
+
+### Gestion de modelos
+- **Subida multi-archivo**: STL, 3MF e imagenes de referencia (JPG/PNG)
+- **Importacion desde URL**: Descarga directa de archivos .stl/.3mf desde cualquier URL
+- **Subida masiva ZIP**: Procesa automaticamente todos los STL/3MF dentro de un ZIP
+- **Deteccion de duplicados**: Por hash SHA256
+- **Metadatos enriquecidos**: Titulo, autor, descripcion, categoria, tags (autocompletado)
+- **Templates de licencia**: CC0, CC-BY, CC-BY-SA, CC-BY-NC, GPL-3.0, MIT
+
+### Galeria y busqueda
+- **Galeria responsive** con grid animado y glassmorphism
+- **Busqueda avanzada**: Por texto, categoria, tag, rango de caras, dimensiones
+- **Ordenamiento**: Mas nuevos, mas descargados, mas grandes, mejor valorados
+- **Historial de busqueda**: Persistido en localStorage
+- **Nube de tags** con conteo
+- **Paginacion** con "cargar mas"
+
+### Visualizacion 3D (Three.js)
+- **Viewer interactivo** multi-parte con controles orbitales
+- **Modos de vista**: Solido, wireframe, ejes, bounding box
+- **Vistas rapidas**: Frontal, superior, lateral, isometrica
+- **Herramienta de medicion**: Click en dos puntos para distancia en mm
+- **Corte transversal**: Plano de clipping con slider interactivo
+- **Mapa de voladizos**: Heatmap de angulos de impresion (verde/amarillo/rojo)
+- **Animacion de capas**: Simulacion de construccion capa por capa
+- **Modo comparacion**: Abrir dos modelos lado a lado
+
+### Social y organizacion
+- **Valoraciones**: 1-5 estrellas con promedio calculado
+- **Comentarios**: Con nombre de autor y fecha
+- **Colecciones**: Crear listas y agregar/quitar modelos
+- **QR Code**: Compartir modelo escaneando codigo
+- **Descarga batch**: Seleccionar multiples modelos y descargar ZIP
+
+### Analisis y validacion
+- **Validacion de malla** (trimesh): Watertight, volumen, area, Euler, agujeros
+- **Estimador de impresion**: Volumen, peso en gramos, costo y tiempo estimado
+- **Thumbnails automaticos** generados server-side
+
+### Infraestructura
+- **Backup completo**: Endpoint que exporta DB + archivos + metadatos JSON como ZIP
+- **Docker**: Dockerfile + docker-compose.yml listos
+- **Tests automatizados**: 24 tests pytest (API + parsers)
+
+## Stack tecnologico
+
+- **Backend**: Python 3.12 + FastAPI + SQLAlchemy + SQLite + trimesh
+- **Frontend**: HTML5 + Vanilla JS + Tailwind CSS (CDN) + Three.js r128
+- **Procesamiento**: numpy + Pillow
+- **Empaquetado**: uv (gestor de dependencias)
+
+## Instalacion y uso
+
+### Requisitos
+- Python 3.12+
+- `uv` instalado (`pip install uv` o ver https://docs.astral.sh/uv/)
+
+### Iniciar servidor
+```bash
+cd /root/stl-repo
+export PATH="$HOME/.local/bin:$PATH"
+uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Abrir en navegador: `http://localhost:8000`
+
+### Docker
+```bash
+docker-compose up --build
+```
+
+### Tests
+```bash
+uv run pytest tests/ -v
+```
+
+## Estructura del proyecto
+
+```
+app/
+  main.py           # Punto de entrada FastAPI
+  models.py         # Modelos SQLAlchemy (ORM)
+  schemas.py        # Esquemas Pydantic
+  database.py       # Conexion SQLite
+  parsers.py        # Parser STL/3MF + generacion de thumbnails
+  routers/
+    models.py       # Endpoints principales (CRUD, busqueda, descargas, etc.)
+  migrate.py        # Migraciones de DB
+static/
+  index.html        # Galeria
+  upload.html       # Formulario de subida (archivos/URL/ZIP)
+  detail.html       # Vista detalle con viewer 3D
+  css/style.css
+  js/
+    app.js          # Logica de galeria
+    upload.js       # Logica de subida
+    detail.js       # Viewer 3D + herramientas avanzadas
+    api.js          # Cliente HTTP
+    theme.js        # Tema oscuro/claro
+uploads/            # Archivos 3D subidos
+thumbnails/         # Thumbnails PNG generados
+images/             # Imagenes de referencia subidas
+tests/
+  test_api.py       # Tests de API (24 tests)
+  test_parsers.py   # Tests de parsing y thumbnails
+```
+
+## API Endpoints principales
+
+| Metodo | Endpoint | Descripcion |
+|--------|----------|-------------|
+| GET | `/api/models/` | Listar modelos (con filtros y paginacion) |
+| POST | `/api/models/` | Subir modelo nuevo |
+| POST | `/api/models/import-url` | Importar desde URL |
+| POST | `/api/models/bulk-zip` | Subir ZIP con multiples modelos |
+| POST | `/api/models/batch-download` | Descargar seleccionados como ZIP |
+| GET | `/api/models/{id}` | Detalle completo de modelo |
+| PUT | `/api/models/{id}` | Actualizar metadatos |
+| DELETE | `/api/models/{id}` | Eliminar modelo |
+| GET | `/api/models/{id}/validate` | Validar malla (trimesh) |
+| GET | `/api/models/{id}/estimate` | Estimar costo/tiempo de impresion |
+| GET | `/api/models/{id}/download` | Descargar archivo principal |
+| GET | `/api/models/{id}/download-all` | Descargar todas las partes en ZIP |
+| GET | `/api/models/{id}/thumbnail` | Thumbnail PNG |
+| GET | `/api/models/{id}/qr` | Codigo QR para compartir |
+| POST | `/api/models/{id}/ratings` | Valorar modelo |
+| POST | `/api/models/{id}/comments` | Comentar |
+| GET | `/api/models/tags` | Listar tags con conteo |
+| GET/POST | `/api/models/collections/...` | CRUD de colecciones |
+| GET | `/api/models/system/backup` | Backup completo ZIP |
+
+## Version
+
+v2.2.0 — Abril 2026