plano3d/docs/propuesta-lizette/02-tecnologias-backend.md

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.