En este módulo vamos a construir una apicación completa en un entorno web, separando el BackEnd y el FrontEnd. Aprenderemos hacerca de estas trecnologías:

• FastAPI (Python)
• SQLAlchemy + SQLite
• Vue.js 3 (Composition API) + Pinia (estado) + Vue Router
• Vuetify 3 (Material Design)
• pytest (unitarias/integración backend) + Vitest + Vue Test Utils (unitarias frontend) + Playwright (E2E)
• Docker + Docker Compose + Nginx (local, sin cloud) + GitHub Actions simulado (CI)

Para ello, iremos estudiando los conceptos teóricos necesarios y los aplicaremos a un proyecto global que se desarrollará durante el módulo. El detalle del proyecto es el siguiente:

TaskFlow — Documento técnico de alcance del proyecto

Módulo asociado: CLM1042 — Programación de aplicaciones utilizando frameworks (DAW, 2º curso, 80h) Tipo de documento: especificación de alcance funcional y técnico (a modo de documento de arquitectura/requisitos de un proyecto real de empresa) Versión: 1.0

1. Introducción

1.1. Propósito del documento

Este documento define el alcance funcional y técnico de TaskFlow, la aplicación web que el alumnado construye de forma incremental a lo largo del módulo CLM1042. Sirve como referencia única de qué debe hacer la aplicación, qué no debe hacer (para no desviar el foco pedagógico), y qué decisiones de arquitectura se han tomado y por qué.

Este documento cumple, dentro del aula, el mismo papel que un documento de requisitos o una especificación técnica cumple en un proyecto de empresa: es el contrato de referencia entre lo que se pide y lo que se construye.

1.2. Descripción general del producto

TaskFlow es una aplicación web de gestión de tareas y proyectos para un único equipo de trabajo. Permite a un usuario autenticado crear proyectos, agrupar tareas dentro de esos proyectos, marcarlas como completadas, categorizarlas y gestionar todo el ciclo de vida de una tarea desde una interfaz web moderna, responsiva y con feedback visual inmediato.

Es intencionalmente un dominio de negocio simple y conocido (cualquier alumno entiende qué es "una tarea" y "un proyecto" sin necesidad de formación previa en un sector concreto), lo que permite dedicar el 100% del esfuerzo cognitivo a la tecnología y no al dominio del problema.

1.3. Alcance pedagógico

TaskFlow no es un producto real destinado a usuarios finales ni a producción con tráfico real. Es un vehículo didáctico: su complejidad funcional está deliberadamente acotada para que sea abarcable en 80 horas lectivas, mientras que su complejidad técnica (arquitectura en capas, autenticación, testing en 3 niveles, contenerización) sí refleja fielmente las prácticas de un proyecto profesional real.

1.4. Fuera de alcance (explícitamente)

Para mantener el proyecto abarcable en el tiempo disponible, quedan fuera del alcance del proyecto base (aunque varios se ofrecen como retos de ampliación opcionales):

• Gestión de múltiples equipos/organizaciones (multi-tenancy).
• Roles y permisos granulares más allá de autenticación simple (ver Reto 1.5 de ampliación para RBAC básico).
• Notificaciones push o por email reales.
• Comentarios o adjuntos en tareas.
• Aplicación móvil nativa (solo web responsiva).
• Internacionalización (i18n) — ofrecida como reto de ampliación opcional.
• Colaboración en tiempo real (edición simultánea) — parcialmente cubierta como reto de ampliación con WebSockets.
• Facturación, pagos o cualquier lógica comercial.
• Cumplimiento normativo de protección de datos a nivel de producción real (RGPD aplicado a un entorno real) — se trabajan buenas prácticas de seguridad, pero no se persigue un cumplimiento normativo certificable.

2. Objetivos del proyecto

2.1. Objetivos funcionales

1. Permitir a un usuario registrarse e iniciar sesión de forma segura.
2. Permitir crear, consultar, editar y eliminar proyectos.
3. Permitir crear, consultar, editar y eliminar tareas, asociadas opcionalmente a un proyecto y a una categoría.
4. Permitir marcar una tarea como completada/pendiente.
5. Ofrecer una interfaz visual coherente, responsiva y con feedback claro ante acciones y errores.

2.2. Objetivos técnicos (trazados a los RA del módulo)

3. Actores y roles

4. Requisitos funcionales

Numerados con prefijo RF-XX, agrupados por entidad de negocio.

4.1. Autenticación y sesión

• RF-01. El sistema debe permitir registrar un nuevo usuario con nombre de usuario y contraseña.
• RF-02. El sistema debe rechazar el registro con un nombre de usuario ya existente, informando el motivo.
• RF-03. El sistema debe permitir iniciar sesión con usuario y contraseña, devolviendo un token de sesión válido.
• RF-04. El sistema debe rechazar credenciales incorrectas con un mensaje claro, sin especificar si el fallo es el usuario o la contraseña (buena práctica de seguridad).
• RF-05. El sistema debe expirar automáticamente la sesión tras un periodo de inactividad configurado (30 minutos en el alcance base).
• RF-06. El sistema debe permitir cerrar sesión de forma explícita, invalidando el acceso a rutas protegidas del cliente.
• RF-07. Ninguna funcionalidad de creación, edición o eliminación de proyectos/tareas/categorías debe ser accesible sin sesión iniciada.

4.2. Gestión de proyectos

• RF-08. El sistema debe permitir crear un proyecto con nombre (obligatorio) y descripción (opcional).
• RF-09. El sistema debe permitir listar todos los proyectos del usuario.
• RF-10. El sistema debe permitir consultar el detalle de un proyecto, incluyendo sus tareas asociadas.
• RF-11. El sistema debe permitir editar el nombre y la descripción de un proyecto existente.
• RF-12. El sistema debe permitir eliminar un proyecto. Al eliminar un proyecto, el sistema debe decidir explícitamente qué ocurre con sus tareas asociadas (eliminación en cascada o desasociación), y esta decisión debe estar documentada y ser consistente en todo el sistema.

4.3. Gestión de tareas

• RF-13. El sistema debe permitir crear una tarea con título (obligatorio, máximo 100 caracteres), descripción (opcional), proyecto asociado (opcional) y categoría asociada (opcional).
• RF-14. El sistema debe permitir listar tareas, con filtro opcional por proyecto y por estado (completada/pendiente).
• RF-15. El sistema debe permitir listar tareas de forma paginada.
• RF-16. El sistema debe permitir editar cualquier campo de una tarea existente.
• RF-17. El sistema debe permitir alternar el estado de una tarea entre pendiente y completada con una única acción (no un formulario completo).
• RF-18. El sistema debe permitir eliminar una tarea de forma permanente.
• RF-19. El sistema debe rechazar la creación/edición de una tarea con título vacío, mostrando un mensaje de validación claro tanto en el servidor como en el cliente.

4.4. Gestión de categorías

• RF-20. El sistema debe permitir crear una categoría con nombre y color asociado.
• RF-21. El sistema debe permitir listar, editar y eliminar categorías.
• RF-22. Una tarea puede tener como máximo una categoría asociada (relación opcional 1-N desde Category hacia Task).

4.5. Interfaz de usuario

• RF-23. La interfaz debe mostrar de forma visual y distinguible el estado de cada tarea (pendiente/completada), incluyendo color y/o icono.
• RF-24. La interfaz debe funcionar correctamente en tres rangos de ancho de pantalla: móvil (≥375px), tablet (≥768px) y escritorio (≥1280px).
• RF-25. La interfaz debe informar visualmente al usuario durante estados de carga (peticiones en curso) y de error (fallo de red o del servidor), nunca dejando la pantalla en un estado ambiguo o silenciosamente roto.
• RF-26. La interfaz debe ofrecer, como mínimo, un tema visual claro y uno oscuro, seleccionable por el usuario.

5. Requisitos no funcionales

Numerados con prefijo RNF-XX.

6. Modelo de dominio

6.1. Entidades principales

User
 ├─ id: int (PK)
 ├─ username: string (único)
 └─ hashed_password: string

Project
 ├─ id: int (PK)
 ├─ name: string
 ├─ description: string (opcional)
 └─ owner_id: int (FK → User)   [según decisión de alcance, ver 6.3]

Category
 ├─ id: int (PK)
 ├─ name: string
 └─ color: string (código hex o nombre de color)

Task
 ├─ id: int (PK)
 ├─ title: string (máx. 100 caracteres)
 ├─ description: string (opcional)
 ├─ completed: boolean (por defecto false)
 ├─ created_at: datetime
 ├─ project_id: int (FK → Project, opcional)
 └─ category_id: int (FK → Category, opcional)

6.2. Relaciones

• User 1 — N Project (un usuario tiene varios proyectos; en el alcance mínimo puede simplificarse a un espacio de trabajo compartido por todos los usuarios autenticados, según decisión docente — ver 6.3).
• Project 1 — N Task (relación opcional: una tarea puede no pertenecer a ningún proyecto).
• Category 1 — N Task (relación opcional: una tarea puede no tener categoría).

6.3. Decisión de alcance abierta (a resolver por el docente/alumnado antes de UD1)

El modelo permite dos variantes igualmente válidas pedagógicamente:

1. Variante simple (recomendada para el ritmo de 80h): todos los usuarios autenticados comparten el mismo espacio de proyectos/tareas (no hay owner_id, cualquier usuario ve y edita todo). Reduce la complejidad de autorización a "autenticado sí/no".
2. Variante con propiedad (recomendada solo si el grupo tiene nivel alto, ver evaluación inicial): cada proyecto/tarea pertenece a un usuario (owner_id), y un usuario solo puede ver/editar sus propios recursos. Añade una dimensión más de autorización (no solo "¿estás autenticado?" sino "¿es tuyo este recurso?").

Recomendación: partir de la variante simple en el proyecto base de clase, y ofrecer la variante con propiedad como extensión del Reto 1.5 (RBAC) para quien quiera profundizar.

7. Arquitectura técnica

7.1. Diagrama de componentes (alto nivel)

┌─────────────────────┐        HTTPS/JSON        ┌──────────────────────┐
│   Cliente (SPA)      │ ────────────────────────▶ │   Servidor Nginx      │
│   Vue 3 + Vuetify    │ ◀──────────────────────── │  (reverse proxy +     │
│   + Pinia (estado)   │                            │   estáticos)          │
└─────────────────────┘                            └──────────┬───────────┘
                                                                 │ /api/*
                                                                 ▼
                                                     ┌──────────────────────┐
                                                     │   API FastAPI          │
                                                     │   (Uvicorn)            │
                                                     │   + SQLAlchemy ORM     │
                                                     │   + Auth JWT           │
                                                     └──────────┬───────────┘
                                                                 │
                                                                 ▼
                                                     ┌──────────────────────┐
                                                     │   Base de datos        │
                                                     │   SQLite (volumen      │
                                                     │   persistente Docker)  │
                                                     └──────────────────────┘

7.2. Justificación de las decisiones de arquitectura

7.3. Stack tecnológico completo

8. Interfaces de la API (contrato REST resumido)

Formato de error estándar (aplicado de forma consistente en todos los endpoints):

{
  "detail": "Descripción del error legible para el desarrollador consumidor de la API"
}

9. Casos de uso principales (narrativa)

CU-01 — Registro e inicio de sesión

Un visitante accede a la aplicación, no tiene cuenta, se registra con usuario y contraseña, y a continuación inicia sesión. El sistema le redirige automáticamente a la vista de tareas. En visitas posteriores, si la sesión sigue vigente, no se le vuelve a pedir el login.

CU-02 — Crear y organizar un proyecto con tareas

Un usuario autenticado crea un proyecto nuevo ("Rediseño web"). A continuación crea varias tareas dentro de ese proyecto, algunas con categoría asignada ("Diseño", "Desarrollo"). Ve la lista de tareas del proyecto, filtrable por estado.

CU-03 — Gestión diaria de tareas

Un usuario abre la aplicación, ve sus tareas pendientes destacadas visualmente, marca varias como completadas con un solo clic, y crea una tarea nueva rápidamente desde un formulario simple con validación en tiempo real.

CU-04 — Uso en dispositivo móvil

Un usuario accede desde su teléfono. La interfaz se adapta automáticamente: la navegación pasa a un menú desplegable, las tarjetas de tareas se apilan en una sola columna, y todos los botones son accesibles sin necesidad de hacer zoom.

CU-05 — Fallo de red gestionado con elegancia

Durante el uso normal, la conexión al backend falla temporalmente (simulado en pruebas con page.route). La interfaz no se congela ni muestra una pantalla en blanco: informa al usuario del problema y le permite reintentar la acción cuando la conexión se restablece.

10. Criterios de aceptación del proyecto completo

El proyecto TaskFlow se considera funcionalmente completo cuando:

1. Todos los requisitos funcionales (RF-01 a RF-26) están implementados y verificables mediante demo en vivo.
2. Todos los requisitos no funcionales de seguridad (RNF-01 a RNF-03, RNF-12) están cumplidos y verificados en la auditoría cruzada de UD5.
3. La aplicación completa arranca con un único comando (docker compose up) desde un repositorio recién clonado, sin pasos manuales adicionales no documentados.
4. La suite de pruebas automatizada (unit + integración + E2E) se ejecuta en verde antes de cada entrega.
5. La aplicación es usable, sin defectos visuales bloqueantes, en los tres rangos de pantalla definidos en RF-24.
6. Existe documentación mínima (README) que permite a una persona ajena al proyecto levantarlo y entender su arquitectura en menos de 10 minutos de lectura.

11. Trazabilidad con la programación didáctica del módulo

12. Glosario