plano3d/docs/propuesta-lizette/01-requisitos-backend.md

Requisitos del backend

Este documento recoge los requisitos del backend de Plano3D: el servidor (API REST, cuentas, historial y base de datos) y el motor que convierte el plano técnico 2D en una pieza 3D. La interfaz y el visor 3D son del frontend y no se incluyen aquí.

Cada requisito tiene un identificador para poder citarlo desde el resto de la documentación, los issues y las pruebas. La prioridad indica su importancia para la primera versión: Alta (imprescindible), Media (deseable) o Baja (opcional).

1. Requisitos funcionales

Cuentas y proyectos

ID	Nombre	Descripción	Prioridad
RF-01	Registro de usuario	El usuario crea una cuenta con correo electrónico y contraseña.	Alta
RF-02	Inicio de sesión	El usuario se autentica y recibe un token que envía en el resto de peticiones.	Alta
RF-03	Gestión de proyectos	El usuario crea, lista, consulta y elimina sus proyectos. Solo ve los suyos.	Alta
RF-04	Subida del plano	La API recibe un plano (DXF; DWG y PDF vectorial en la ampliación) asociado a un proyecto.	Alta
RF-05	Validación del archivo	Antes de procesar se comprueban la extensión, el tamaño máximo y que el archivo se puede abrir. Si no, se rechaza explicando el motivo.	Alta

Conversión (motor)

ID	Nombre	Descripción	Prioridad
RF-06	Lectura del plano	Se extraen las entidades geométricas (LINE, ARC, CIRCLE, LWPOLYLINE con bulge, POLYLINE), se separan las líneas visibles de las ocultas y se ignoran el marco, el cajetín, los textos y las cotas.	Alta
RF-07	Unidades y escala	Se pasa todo a mm según $INSUNITS y se aplica la escala del cajetín, o la que indique el usuario. Si falta, se avisa.	Alta
RF-08	Vistas	Se agrupan las líneas en vistas y se identifican alzado, planta y perfil.	Alta
RF-09	Sistema de proyección	Se detecta si el plano sigue el sistema europeo (ISO-E) o el americano (ISO-A), y se avisa si los mezcla.	Alta
RF-10	Reconstrucción	Se genera el sólido cuyas tres proyecciones reproducen el plano: caras planas, chaflanes, agujeros pasantes y roscas (como agujero y nota).	Alta
RF-11	Geometría ampliada	Agujeros ciegos, avellanados y cajeados, y piezas de revolución.	Media
RF-12	Plan B: pieza plana	Si el plano tiene una sola vista, se extruye el contorno exterior con el espesor indicado y se restan los agujeros.	Alta
RF-13	Verificación del plano	Se proyectan las aristas del sólido y se comparan con el plano, y se comprueban las cotas. Cada diferencia genera un aviso.	Alta
RF-14	Avisos	Cada problema se devuelve con un código estable, un mensaje comprensible, una gravedad (info, aviso o bloqueante) y la vista afectada.	Alta
RF-15	Alternativas	Si varias piezas reproducen el plano, se indica cuántas hay y el usuario puede elegir una.	Media
RF-16	Exportación	La pieza se exporta a STEP (para CAD) y STL (para la vista previa del frontend).	Alta

Historial y archivos

ID	Nombre	Descripción	Prioridad
RF-17	Conversión en segundo plano	La API responde enseguida con el identificador de la conversión, y el trabajo se hace en segundo plano.	Alta
RF-18	Estado de la conversión	Cada conversión tiene un estado (pendiente, procesando, completada o error) que el frontend puede consultar.	Alta
RF-19	Historial	Se guardan en MySQL todas las conversiones de cada proyecto, con sus parámetros, el resultado, los avisos y los archivos generados.	Alta
RF-20	Repetir una conversión	El usuario puede volver a convertir un plano con otros parámetros (escala, alternativa, espesor) sin subirlo de nuevo.	Media
RF-21	Descarga de archivos	El usuario descarga el plano original y los STEP/STL de sus proyectos.	Alta

2. Requisitos no funcionales

ID	Categoría	Descripción
RNF-01	Seguridad	Las contraseñas se guardan con bcrypt, nunca en texto plano.
RNF-02	Seguridad	Todos los endpoints, salvo el registro y el inicio de sesión, piden un token JWT válido y con caducidad.
RNF-03	Seguridad	Un usuario no puede ver ni descargar proyectos ni archivos de otro usuario.
RNF-04	Seguridad	Las credenciales (base de datos, clave JWT) van en variables de entorno (archivo .env) y no se suben al repositorio.
RNF-05	Fiabilidad	Nunca se entrega una pieza que no reproduce el plano sin avisarlo. Lo que no se soporta se detecta y se avisa.
RNF-06	Robustez	Un plano erróneo no tumba el servidor ni afecta a otras peticiones: la conversión queda en estado de error, con el motivo.
RNF-07	Robustez	El tamaño máximo de archivo admitido es de 20 MB.
RNF-08	Rendimiento	Una pieza del catálogo de pruebas se convierte en menos de 10 segundos.
RNF-09	Mantenibilidad	El servidor se organiza en capas (rutas, servicios, repositorios y modelos) y el motor en etapas. Todo sigue PEP 8.
RNF-10	Calidad	Hay pruebas automáticas (pytest) del motor, con el catálogo de piezas, y de la API. Pasan antes de cada pull request.
RNF-11	Portabilidad	El backend y la base de datos se levantan con un solo comando (docker compose up), y las pruebas se ejecutan en el mismo entorno Docker en cualquier equipo.
RNF-12	Documentación	La API se documenta automáticamente con OpenAPI/Swagger, y es el contrato con el frontend.
RNF-13	Trazabilidad	Las operaciones y los errores se registran en un log.

Los valores numéricos (20 MB, 10 segundos) son objetivos iniciales y se ajustarán con las pruebas.

3. Restricciones y supuestos

• Piezas mecánicas. No se admiten planos de arquitectura.
• La reconstrucción completa necesita tres vistas ortogonales alineadas. Con una sola vista se aplica el plan B (RF-12).
• No se reconstruyen superficies libres ni splines: se detectan y se avisa.
• La lectura de DWG depende de un conversor externo instalado en la imagen Docker.

4. Ampliación futura

ID	Nombre	Descripción	Prioridad
RF-22	PDF vectorial	Se extraen las líneas de un PDF vectorial y se procesan como un DXF.	Media
RF-23	DWG	Los DWG se convierten a DXF con un conversor externo.	Media
RF-24	PDF escaneado y OCR	Se detectan líneas y cotas en planos escaneados.	Baja