MCVIngenieros/mmorales.photo
3
1
Fork 0
Code Issues 15 Pull Requests 1 Actions 2 Projects 3 Releases Wiki Activity

docu

Browse Source
This commit is contained in:
MANUEL JUAN MORALES AMAT
2025-08-28 23:41:06 +02:00
parent 585eca0420
commit cbcf1f245b
9 changed files with 505 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
docs/analisis-tecnico.md Normal file
View File

@@ -0,0 +1,142 @@
# Galerías Fotográficas - Análisis técnico
## Arquitectura del sistema
Queremos hacer un sistema modular, con componentes independientes que se puedan desarrollar, probar e implementar de forma aislada.
Esto permitirá una mayor flexibilidad y escalabilidad en el desarrollo del sistema.
Queremos abstraer todo lo posible las dependencias entre capas. De tal forma que el frontal y backend puedan intercambiarse con diferentes implementaciones sin afectar al resto del sistema.
Para ello, vamos a hacer el backend database-agnostic, puediendo conectar con diferentes servidores de bases de datos. La responsabilidad de escoger motor de base de datos recaerá sobre el cliente.
Nosotros usaremos Sqlite para desarrollo local y PostgreSQL para producción.
Para poder desarrollarlo rápidamente y tener una base sobre la que iterar, empezaremos con un monolito modular.
Este monolito quedará estructurado en módulos que puedan migrarse a microservicios en el futuro.
Comandaremos el desarrollo mediante DDD (Domain-Driven Design) y CQRS (Command Query Responsibility Segregation).
Algunos procesos como el procesado de imágenes se harán de forma desacoplada y asíncrona.
Para el frontal, Angular nos ofrece componentes que usaremos para componer vistas siguiendo una arquitectura MVVM (Model-View-ViewModel).
Para que el frontend y el backend no dependan entre ellos, vamos a establecer una serie de estándares de comunicación.
Siempre usaremos el estandar HTTP mediante TLS. (HTTPS)
En toda comunicación se preferirá enviar y recibir los datos mediante el body de la petición.
Toda la información sensible, como contraseñas, se enviará cifrada mediante RSA 256.
Para ello, el cliente generará un thumprint único que incluirá el user-agent y un dato único del navegador mas un UUIDv4; hará una petición HEAD al endpoint `/security/rsa` enviando el thumbprint en el header `XXX-Thumbprint`.
El cliente recibirá una respuesta vacía (204 No Content) con un header `XXX-encryption-key` que se utilizará para cifrar los valores de los campos concretos.
En la siguiente petición, donde se enviarán los datos sensibles, el cliente incluirá `XXX-Thumbprint` en el header.
Al recibir la petición, tendrá que rotar el thumbprint.
Cada thumbprint será válido durante 5 minutos en caso de conexiones lentas. Sin embargo, no se permitirá su reutilización.
En caso de que hubiese un MIM (Man-In-The-Middle) o cualquier otro tipo de atacante tratando de interceptar la comunicación, debe ser capaz de detectar y leer el doble cifrado de HTTPS + thumbprint-rsa.
De esta forma, todas las peticiones deben cumplir con el siguiente contrato:
0. Como requisito indispensable, toda la comunicación debe realizarse mediante HTTPS.
1. Todas las peticiones deben incluir un header `XXX-Thumbprint` con el thumbprint actual.
2. Todas las peticiones incluirán un body que sigue el patron `Request<T>`.
3. Las peticiones con datos sensibles, tendrán sus datos cifrados mediante RSA 256.
El patrón `Request<T>` incluirá un campo con los datos de la petición, otro con el thumprint duplicado y un último campo que indica si tiene datos sensibles o no.
Con una implementación como la que sigue:
```c# Request<T>.cs
public class Request<T> where T : IDTOSerializable
{
public T Data { get; set; }
public string Thumbprint { get; set; }
public bool HasSensitiveData { get; set; }
}
```
En el caso de errores, seguiremos el estandar Problem Details extendido.
En el caso de respuestas exitosas, las apis responderan mediante el patron `Response<T>`.
Una `Response<T>` estará compuesta por diferentes campos que indicarán el estado de la transacción, el resultado de la transacción, y los posibles errores lógicos pertenecientes a los datos enviados.
De esta forma, garantizamos un contrato como el siguiente:
```c# Response<T>.cs
public class Response<T> where T : IDTOSerializable
{
public bool IsSuccess { get; set; } = false;
public T Result { get; set; }
public List<DataError>? Errors { get; set; } = null;
public static Response<T> Success(T result)
{
return new Response<T>
{
IsSuccess = true,
Result = result
};
}
public static Response<T> Failure(T result, List<DataError> errors)
{
return new Response<T>
{
IsSuccess = false,
Result = result,
Errors = errors
};
}
}
```
En caso de que los datos enviados al backend provoquen un error lógico, por ejemplo: una imagen que se ha subido no se puede guardar por que ha llegado corrupta; devolveremos una `Response<T>` que contenga un `DataError` como este:
``````c#
public class DataError
{
public string Message { get; set; }
public string? Details { get; set; }
}
``````
De esta forma, el cliente podrá interpretar los errores y mostrarlos al usuario de forma adecuada.
La autenticación y autorización se manejarán mediante JWT (JSON Web Tokens) y OAuth 2.0.
Para ello el front atacará al backend para obtener el token de acceso y luego lo incluirá en las cabeceras de las peticiones con este formato `Authorization: Bearer <token>`.
También incluirá el token de refresco en las peticiones que requieran autenticación, con este formato `XXX-Refresh-Token: <token>`.
## El stack
### Backend
Vamos a usar ASP.NET Core como framework principal, junto con Entity Framework Core para la gestión de la base de datos.
Redis se utilizará como caché distribuido para mejorar el rendimiento.
PostgreSQL se utilizará como sistema de gestión de bases de datos relacional. En desarrollo se utilizará SQLite.
### Frontend
Vamos a usar Angular como framework principal, junto con TailwindCSS para el diseño y NgRx para la gestión del estado.
Vite como empaquetador y Node.js como entorno de ejecución.
Usaremos RxJS para la programación reactiva.
## Base de datos: Esquema y relaciones
## Infraestructura
Inicialmente se utilizará un enfoque monolítico, pero se diseñará con la posibilidad de escalar a microservicios en el futuro.
El producto final debe poder desplegarse en docker y kubernetes. Para ello usarmos Podman como herramienta para gestionar los contenedores.
Usaremos una caché para resultados intermedios, como el portfolio.
## Seguridad
Para mantener seguro el sistema obligaremos el uso de HTTPS en todas las comunicaciones.
Los usuarios deberán autenticarse mediante OAuth 2.0 y OpenID Connect usando JWT (JSON Web Tokens) para la gestión de sesiones. Firmaremos los tokens JWT con una clave secreta almacenada de forma segura. Validaremos la firma siempre. El certificado usado variará cada 24 horas y en cada reinicio.
Los JWT tendrán asociados un Refresh Token que permitirá obtener nuevos tokens de acceso sin necesidad de volver a autenticarse.
Para protegernos contra ataques CSRF (Cross-Site Request Forgery), implementaremos tokens CSRF en todas las solicitudes que modifiquen datos.
Habilitaremos CORS (Cross-Origin Resource Sharing) para permitir que solo dominios específicos puedan acceder a nuestra API.
Implementaremos políticas de contraseñas seguras, incluyendo longitud mínima, complejidad y expiración periódica.
Además, se instará a los usuarios a habilitar la autenticación de dos factores (2FA) para añadir una capa adicional de seguridad.
Todos los usuarios que inicien sesión mediante usuario y contraseña recibirán un correo electrónico de acceso único, con un token de acceso que caducará en 5 minutos.
Para proteger los datos sensibles, como contraseñas y tokens, se utilizará hashing y cifrado.
Implementaremos un sistema de roles y permisos para controlar el acceso a diferentes partes del sistema.
Para evitar ataques de fuerza bruta y ataques de tiempo, implementaremos 4 políticas:
- Limitar el número de intentos de inicio de sesión fallidos y bloquear el acceso temporalmente.
- Implementar un sistema de CAPTCHA que aparecerá aleatoriamente en cada intento de inicio de sesión y después de 3 intentos fallidos.
- Monitorear y registrar los intentos de inicio de sesión para detectar patrones sospechosos.
- Retrasar aleatoriamente las respuestas del servidor una cantidad de tiempo variable inferior a los 3 segundos. (Sacrificamos un poco de la experiencia por algo más de seguridad)
Guardaremos el mínimo número de cookies posibles y evitaremos usar cookies de sesión.
Todas las cookies que usemos serán seguras, HttpOnly y SameSite=Strict.

275
docs/casos-uso.md Normal file
View File

@@ -0,0 +1,275 @@
# Galerías Fotográficas - Casos de Uso
## Caso de uso 1: Administrador da de alta un nuevo profesional
1. El administrador accede al sistema.
2. El administrador navega a la sección de gestión de profesionales.
3. El administrador selecciona la opción "Agregar nuevo profesional".
4. El administrador completa el formulario con los datos del nuevo profesional.
5. El administrador envía el formulario.
6. El sistema confirma la creación del nuevo profesional.
## Caso de uso 2: Administrador crea un portfolio
1. El administrador accede al sistema.
2. El administrador navega a la sección de gestión de portfolios.
3. El administrador selecciona la opción "Crear nuevo portfolio".
4. El administrador completa el formulario con los datos del nuevo portfolio.
5. El administrador envía el formulario.
6. El sistema confirma la creación del nuevo portfolio.
## Caso de uso 3: Profesional crea una imagen
1. El profesional accede al sistema.
2. El profesional navega a la sección de gestión de imágenes.
3. El profesional selecciona la opción "Crear nueva imagen".
4. El profesional completa el formulario con los datos de la nueva imagen.
5. El profesional envía el formulario.
6. El sistema confirma la creación de la nueva imagen.
## Caso de uso 4: Profesional crea un conjunto de imágenes
1. El profesional accede al sistema.
2. El profesional navega a la sección de gestión de conjuntos de imágenes.
3. El profesional selecciona la opción "Crear nuevo conjunto de imágenes".
4. El profesional completa el formulario con los datos del nuevo conjunto de imágenes.
5. El profesional envía el formulario.
6. El sistema confirma la creación del nuevo conjunto de imágenes.
## Caso de uso 5: Profesional crea una colección
1. El profesional accede al sistema.
2. El profesional navega a la sección de gestión de colecciones.
3. El profesional selecciona la opción "Crear nueva colección".
4. El profesional completa el formulario con los datos de la nueva colección.
5. El profesional envía el formulario.
6. El sistema confirma la creación de la nueva colección.
## Caso de uso 6: Profesional añade una imagen al portfolio
1. El profesional accede al sistema.
2. El profesional navega a la sección de gestión de portfolios.
3. El profesional selecciona el portfolio al que desea añadir la imagen.
4. El profesional selecciona la opción "Añadir imagen".
5. El profesional completa el formulario con los datos de la imagen.
6. El profesional envía el formulario.
7. El sistema confirma la adición de la imagen al portfolio.
## Caso de uso 7: Profesional añade varias imágenes al portfolio
1. El profesional accede al sistema.
2. El profesional navega a la sección de gestión de portfolios.
3. El profesional selecciona el portfolio al que desea añadir las imágenes.
4. El profesional selecciona la opción "Añadir varias imágenes".
5. El profesional completa el formulario con los datos de las imágenes.
6. El profesional envía el formulario.
7. El sistema confirma la adición de las imágenes al portfolio.
## Caso de uso 8: Profesional añade una colección al portfolio
1. El profesional accede al sistema.
2. El profesional navega a la sección de gestión de portfolios.
3. El profesional selecciona el portfolio al que desea añadir la colección.
4. El profesional selecciona la opción "Añadir colección".
5. El profesional completa el formulario con los datos de la colección.
6. El profesional envía el formulario.
7. El sistema confirma la adición de la colección al portfolio.
## Caso de uso 9: Profesional añade varias colecciones al portfolio
1. El profesional accede al sistema.
2. El profesional navega a la sección de gestión de portfolios.
3. El profesional selecciona el portfolio al que desea añadir las colecciones.
4. El profesional selecciona la opción "Añadir varias colecciones".
5. El profesional completa el formulario con los datos de las colecciones.
6. El profesional envía el formulario.
7. El sistema confirma la adición de las colecciones al portfolio.
## Caso de uso 10: Cliente compra una imagen individual
1. El cliente accede al sistema.
2. El cliente navega a la sección de imágenes.
3. El cliente selecciona la imagen que desea comprar.
4. El cliente añade la imagen al carrito de compras.
5. El cliente procede al pago.
6. El sistema confirma la compra de la imagen.
## Caso de uso 11: Cliente compra un conjunto de imágenes individuales
1. El cliente accede al sistema.
2. El cliente navega a la sección de conjuntos de imágenes.
3. El cliente selecciona el conjunto de imágenes que desea comprar.
4. El cliente añade el conjunto de imágenes al carrito de compras.
5. El cliente procede al pago.
6. El sistema confirma la compra del conjunto de imágenes.
## Caso de uso 12: Cliente compra una colección
1. El cliente accede al sistema.
2. El cliente navega a la sección de colecciones.
3. El cliente selecciona la colección que desea comprar.
4. El cliente añade la colección al carrito de compras.
5. El cliente procede al pago.
6. El sistema confirma la compra de la colección.
## Caso de uso 13: Cliente ve en el historial de compras una imagen individual
1. El cliente accede al sistema.
2. El cliente navega a la sección de historial de compras.
3. El cliente selecciona la imagen individual que desea ver.
4. El sistema muestra los detalles de la imagen individual.
## Caso de uso 14: Cliente ve en el historial de compras un conjunto de imágenes individuales
1. El cliente accede al sistema.
2. El cliente navega a la sección de historial de compras.
3. El cliente selecciona el conjunto de imágenes individuales que desea ver.
4. El sistema muestra los detalles del conjunto de imágenes individuales.
## Caso de uso 15: Cliente ve en el historial de compras una colección
1. El cliente accede al sistema.
2. El cliente navega a la sección de historial de compras.
3. El cliente selecciona la colección que desea ver.
4. El sistema muestra los detalles de la colección.
## Caso de uso 16: Cliente contrata una sesión
1. El cliente accede al sistema.
2. El cliente navega a la sección de sesiones.
3. El cliente selecciona la sesión que desea contratar.
4. El cliente completa el formulario de contratación.
5. El cliente envía el formulario.
6. El sistema confirma la contratación de la sesión.
## Caso de uso 17: Profesional acepta una sesión
1. El profesional accede al sistema.
2. El profesional navega a la sección de sesiones.
3. El profesional selecciona la sesión que desea aceptar.
4. El profesional confirma la aceptación de la sesión.
5. El sistema notifica al cliente sobre la aceptación de la sesión.
## Caso de uso 18: Profesional rechaza una sesión
1. El profesional accede al sistema.
2. El profesional navega a la sección de sesiones.
3. El profesional selecciona la sesión que desea rechazar.
4. El profesional confirma el rechazo de la sesión.
5. El sistema notifica al cliente sobre el rechazo de la sesión.
## Caso de uso 19: Profesional añade una imagen a una sesión
1. El profesional accede al sistema.
2. El profesional navega a la sección de sesiones.
3. El profesional selecciona la sesión a la que desea añadir la imagen.
4. El profesional sube la imagen.
5. El sistema confirma la adición de la imagen a la sesión.
## Caso de uso 20: Cliente da feedback de una imagen
1. El cliente accede al sistema.
2. El cliente navega a la sección de imágenes.
3. El cliente selecciona la imagen a la que desea dar feedback.
4. El cliente proporciona su feedback.
5. El sistema confirma la recepción del feedback.
## Caso de uso 21: Profesional crea una versión de una imagen
1. El profesional accede al sistema.
2. El profesional navega a la sección de imágenes.
3. El profesional selecciona la imagen de la que desea crear una versión.
4. El profesional realiza las modificaciones necesarias en la imagen.
5. El profesional guarda la nueva versión de la imagen.
6. El sistema confirma la creación de la nueva versión de la imagen.
## Caso de uso 22: Cliente da feedback de una version de una imagen
1. El cliente accede al sistema.
2. El cliente navega a la sección de imágenes.
3. El cliente selecciona la versión de la imagen a la que desea dar feedback.
4. El cliente proporciona su feedback.
5. El sistema confirma la recepción del feedback.
## Caso de uso 23: Cliente selecciona imagen para finalizar sesión
1. El cliente accede al sistema.
2. El cliente navega a la sección de imágenes.
3. El cliente selecciona la imagen que desea utilizar para finalizar la sesión.
4. El sistema muestra la imagen seleccionada.
## Caso de uso 24: Profesional finaliza una sesión
1. El profesional accede al sistema.
2. El profesional navega a la sección de sesiones.
3. El profesional selecciona la sesión que desea finalizar.
4. El profesional confirma la finalización de la sesión.
5. El sistema notifica al cliente sobre la finalización de la sesión.
## Caso de uso 25: Profesional crea un evento-colección
1. El profesional accede al sistema.
2. El profesional navega a la sección de eventos.
3. El profesional selecciona la opción de crear un nuevo evento-colección.
4. El profesional completa el formulario de creación del evento-colección.
5. El profesional envía el formulario.
6. El sistema confirma la creación del evento-colección.
## Caso de uso 26: Profesional añade una imagen a un evento
1. El profesional accede al sistema.
2. El profesional navega a la sección de eventos.
3. El profesional selecciona el evento al que desea añadir la imagen.
4. El profesional sube la imagen.
5. El sistema confirma la adición de la imagen al evento.
## Caso de uso 27: Profesional añade un tag a un evento
1. El profesional accede al sistema.
2. El profesional navega a la sección de eventos.
3. El profesional selecciona el evento al que desea añadir el tag.
4. El profesional introduce el tag.
5. El sistema confirma la adición del tag al evento.
## Caso de uso 28: Profesional añade un tag a una imagen
1. El profesional accede al sistema.
2. El profesional navega a la sección de imágenes.
3. El profesional selecciona la imagen a la que desea añadir el tag.
4. El profesional introduce el tag.
5. El sistema confirma la adición del tag a la imagen.
## Caso de uso 29: Anónimo busca imagen por tags
1. El anónimo accede al sistema.
2. El anónimo navega a la sección de imágenes.
3. El anónimo introduce el tag por el que desea buscar.
4. El sistema muestra las imágenes que coinciden con el tag.
## Caso de uso 30: Anónimo busca evento por tags
1. El anónimo accede al sistema.
2. El anónimo navega a la sección de eventos.
3. El anónimo introduce el tag por el que desea buscar.
4. El sistema muestra los eventos que coinciden con el tag.
## Caso de uso 31: Anónimo busca colección por tags
1. El anónimo accede al sistema.
2. El anónimo navega a la sección de colecciones.
3. El anónimo introduce el tag por el que desea buscar.
4. El sistema muestra las colecciones que coinciden con el tag.
## Caso de uso 32: Anónimo filtra imagen por fecha
1. El anónimo accede al sistema.
2. El anónimo navega a la sección de imágenes.
3. El anónimo selecciona el rango de fechas para filtrar las imágenes.
4. El sistema muestra las imágenes que coinciden con el rango de fechas.
## Caso de uso 33: Anónimo filtra eventos por fecha
1. El anónimo accede al sistema.
2. El anónimo navega a la sección de eventos.
3. El anónimo selecciona el rango de fechas para filtrar los eventos.
4. El sistema muestra los eventos que coinciden con el rango de fechas.

40
docs/decisiones-arquitectura.md Normal file
View File

@@ -0,0 +1,40 @@
# Galerías Fotográficas - Decisiones de Arquitectura
## ¿Por qué Angular en lugar de React?
Como producto final, se pretende vender varias plantillas frontales.
Vamos a empezar por el diseño de la primera plantilla con Angular por su fácil escalabilidad y modularidad para el caso en que se incorporen nuevo programadores.
## ¿Por qué .NET en lugar de Node.js?
.NET ofrece un rendimiento superior y una mejor integración con herramientas empresariales, lo que lo hace más adecuado para aplicaciones de gran escala.
Además, permite un desarrollo más rápido y eficiente gracias a su robusto ecosistema de bibliotecas y herramientas.
## Decisiones sobre manejo de imágenes
Como objetivo final, se pretende tener una independencia total del proveedor de almacenamiento de imágenes. Para ello, se optará por una arquitectura que permita cambiar de proveedor sin afectar al resto del sistema.
Por facilidad y sencillez durante el desarrollo, se comenzará con un sqlite + el sistema de archivos local.
Para tratar los datos usaremos EntityFramework con una visión Data First, es decir, primero se definirá el modelo de datos y las relaciones en base de datos y posteriorimente se generarán las migraciones y se modificará el modelo del back.
Usaremos Serilog + OpenTelemetry para el monitoreo y trazabilidad de las aplicaciones de forma sencilla.
Usaremos Scalar + OpenApi para documentar la API de forma sencilla y visual.
Usaremos MailKit para enviar correos electrónicos de forma sencilla y eficiente.
Usaremos MediatR para la implementación de patrones CQRS (Command Query Responsibility Segregation) en el backend.
Usaremos Polly para la gestión de resiliencia y manejo de fallos en las aplicaciones.
Usaremos FluentValidation para la validación de datos de forma sencilla y eficiente.
Usaremos Hangfire para la gestión de trabajos en segundo plano.
Usaremos Redis como sistema de caché distribuido.
Usaremos PostgreSQL como sistema de gestión de bases de datos. Durante el desarrollo, y en entornos locales, usaremos sqlite.
Usaremos AutoMapper para la mapeo de objetos de forma sencilla y eficiente.
Para el front usaremos TailwindCSS para el diseño de interfaces de usuario de forma rápida.
Usaremos NgRx para la gestión del estado de la aplicación de forma predecible y eficiente.
## Elección de patrones arquitectónicos
En el backend se usará DDD ( Domain-Driven Design ) y CQRS ( Command Query Responsibility Segregation ).
Esto facilitará la escalabilidad y el mantenimiento del sistema a largo plazo.
Además, permite una rápida implementación de nuevas funcionalidades y una adaptación más simple para nuevo programadores.
En el frontend se utilizará una arquitectura MVVM (Model-View-ViewModel) repartida en componentes reutilizables.
Esto ayudará en la separación de responsabilidades de cada componente y facilitará la adición de nuevas pantallas.

11
docs/documentacion-api.md Normal file
View File

@@ -0,0 +1,11 @@
Autenticación y autorización
Endpoints de usuarios
Endpoints de imágenes y colecciones
Endpoints de sesiones y feedback
Endpoints de pagos
Códigos de error y manejo de excepciones

9
docs/guia-estilo.md Normal file
View File

@@ -0,0 +1,9 @@
Paleta de colores y tipografías
Componentes reutilizables de Angular
Patrones de diseño UX/UI
Responsive design guidelines
Accesibilidad

7
docs/manual-usuario.md Normal file
View File

@@ -0,0 +1,7 @@
Guía para profesionales
Guía para clientes
FAQ y resolución de problemas
Videos tutoriales (cuando aplique)

11
docs/plan-desarrollo.md Normal file
View File

@@ -0,0 +1,11 @@
Fase 1: Configuración inicial y autenticación
Fase 2: Gestión básica de usuarios y almacenamiento
Fase 3: Sistema de portfolios y colecciones
Fase 4: Funcionalidades de colaboración y feedback
Fase 5: Sistema de pagos y comercialización
Fase 6: Optimizaciones y características avanzadas

9
docs/plan-testing.md Normal file
View File

@@ -0,0 +1,9 @@
Pruebas unitarias: Backend y frontend
Pruebas de integración: APIs y base de datos
Pruebas E2E: Flujos completos de usuario
Pruebas de rendimiento: Carga de imágenes
Criterios de aceptación

2
docs/requisitos-funcionales.md
View File

@@ -142,4 +142,4 @@ Todas las colecciones se pueden comprar y descargar.
Todos los clientes puede reservar una sesión.
Para los pagos se usará google pay o linkpay o stripe.
Se intentará ofrecer una experiencia de pago fluida y segura para los clientes.
Se intentará ofrecer una experiencia de pago fluida y segura para los clientes.