# Tecnologías del backend

Este documento explica qué tecnologías usa el backend (servidor y motor) y por qué
se han elegido frente a otras alternativas.

## 1. Lenguaje

El backend se desarrolla en **Python 3.12**. CadQuery solo admite de 3.12 a 3.13,
como fija el `pyproject.toml`.

La razón principal es que Python tiene bibliotecas maduras y gratuitas para leer
archivos CAD y generar sólidos 3D. En Java o C#, lo equivalente es mucho más
limitado o necesita licencias comerciales. Además, permite crear APIs rápidamente.

## 2. Bibliotecas

### 2.1. Motor: geometría y modelado

| Tecnología | Para qué se usa | Por qué esta y no otra |
| --- | --- | --- |
| **ezdxf** | Leer las entidades, capas, tipos de línea, textos y cabecera de los DXF. | Es la biblioteca de referencia en Python para DXF: admite todas las versiones, está bien documentada y no necesita AutoCAD. |
| **shapely** | Geometría 2D de las vistas: unir segmentos, formar contornos, calcular áreas y saber si un contorno está dentro de otro. | Resuelve en una línea operaciones que a mano serían largas y darían problemas de tolerancia. |
| **numpy** | Cálculos con coordenadas y tolerancias. | Estándar en Python, y ya lo usa CadQuery. |
| **CadQuery** (OpenCASCADE) | Construir los sólidos (celdas, extrusiones, booleanas), proyectar aristas y exportar a STEP y STL. | Usa OpenCASCADE, el mismo núcleo que FreeCAD, con una API en Python más sencilla. pythonOCC ofrece lo mismo con un código más complejo, y FreeCAD es pesado para usarlo dentro de un servidor. |
| **OR-Tools (CP-SAT)** | Elegir qué celdas forman la pieza para que sus proyecciones coincidan con el plano. | El prototipo prueba todas las combinaciones, y eso no funciona a partir de unas 18 celdas. CP-SAT resuelve el mismo problema como restricciones. |

### 2.2. Servidor: API, seguridad y base de datos

| Tecnología | Para qué se usa | Por qué esta y no otra |
| --- | --- | --- |
| **FastAPI** | Crear la API REST con la que se comunica el frontend. | Más moderna y rápida que Flask, valida los datos sola y genera la documentación Swagger sin trabajo extra. Django sería excesivo para una API. |
| **Uvicorn** | Servidor que ejecuta FastAPI. | Es el recomendado por FastAPI. |
| **Pydantic** | Definir y validar los datos que entran y salen de la API. | Viene integrado con FastAPI. |
| **SQLAlchemy** | Acceder a MySQL mediante un ORM. | Es el ORM más usado en Python y evita escribir SQL a mano en cada consulta. |
| **PyMySQL** | Conectar SQLAlchemy con MySQL. | Está escrito en Python puro y se instala sin problemas en Docker. |
| **Alembic** | Gestionar las migraciones de la base de datos. | Es la herramienta oficial de migraciones de SQLAlchemy. |
| **passlib (bcrypt)** | Calcular el hash de las contraseñas. | bcrypt es lento por diseño, lo que dificulta los ataques de fuerza bruta. |
| **PyJWT** | Generar y verificar los tokens de sesión. | Permite una autenticación sin estado, adecuada para una API REST. |

### 2.3. Pruebas

| Tecnología | Para qué se usa | Por qué esta y no otra |
| --- | --- | --- |
| **pytest** | Pruebas del motor (catálogo de piezas) y de la API. | Es el estándar en Python, con una sintaxis más sencilla que *unittest*. |
| **httpx** (`TestClient` de FastAPI) | Llamar a los endpoints desde las pruebas sin levantar el servidor. | Es lo que usa FastAPI para probar. |

## 3. Base de datos

Se usa **MySQL 8** para guardar los usuarios (con la contraseña cifrada), los
proyectos, el historial de conversiones con sus avisos y las rutas de los archivos
generados.

Los archivos en sí (DXF, STEP, STL) no se guardan en la base de datos, sino en un
volumen de Docker, porque pueden ser grandes.

Se ha elegido MySQL porque el equipo ya lo conoce del ciclo y cubre de sobra las
necesidades del proyecto. PostgreSQL sería una alternativa igual de válida.

## 4. Herramientas de desarrollo

| Herramienta | Uso en el proyecto |
| --- | --- |
| **uv** | Gestionar las dependencias con `pyproject.toml` y `uv.lock`, tanto en local como dentro de la imagen Docker, para tener las mismas versiones en todas partes. |
| **Docker** | Ejecutar el backend con todas sus dependencias. CadQuery es especialmente delicado de instalar, y el contenedor evita problemas entre equipos. |
| **Docker Compose** | Levantar juntos el backend y MySQL, y lanzar las pruebas contra una base de datos de pruebas, con un solo comando. |
| **Git y Gitea del instituto** | Control de versiones, ramas por tarea, *pull requests* revisados, *issues* y tablero, según `CONTRIBUTING.md`. |
| **Visual Studio Code** | Editor y depurador, con integración de Python, Git y Docker. |
| **Swagger UI** | Probar los endpoints desde el navegador. Lo genera FastAPI en `/docs`. |
| **FreeCAD / Fusion 360** | Abrir los STEP generados y comprobar que la pieza es correcta. |

## 5. Ampliación futura

| Tecnología | Para qué se usará |
| --- | --- |
| **PyMuPDF** | Extraer los trazos vectoriales de los planos en PDF. |
| **OpenCV** y **Tesseract OCR** | Detectar líneas y leer cotas en planos escaneados. |

*Riesgo identificado: reconocer cotas con OCR en planos reales es poco fiable
(símbolos especiales, textos girados, solapamientos). Por eso queda como
ampliación y no como parte del producto mínimo.*