TaskMaster - Sistema de Gestión de Tareas

TaskMaster - Sistema Completo de Gestión de Tareas

TaskMaster es un ejemplo completo de backend que demuestra todas las capacidades de Veloce-TS. Este ejemplo muestra cómo construir un sistema de gestión de tareas listo para producción con autenticación, autorización, características en tiempo real y más.

:::note Ejemplo Básico Este es un ejemplo básico solo de backend diseñado para demostrar las capacidades de Veloce-TS. Se enfoca en el desarrollo de APIs y no incluye una interfaz frontend. :::

🚀 Características Demostradas

✅ Características Principales del Framework

• Routing basado en decoradores (@Controller, @Get, @Post, etc.)
• Inyección de Dependencias con scope singleton
• Validación de solicitudes usando esquemas Zod
• Documentación OpenAPI automática
• Middleware personalizado (logging, analytics, performance)
• Manejo de errores con excepciones personalizadas
• Sistema de plugins integrado

✅ Autenticación y Autorización

• Autenticación basada en JWT con tokens de acceso/refresh
• Control de Acceso Basado en Roles (RBAC) con 5 niveles de roles
• Sistema de permisos granular
• Rutas y endpoints protegidos

✅ Base de Datos y Persistencia

• Integración SQLite usando la base de datos nativa de Bun
• Operaciones CRUD para todas las entidades
• Validación de datos y seguridad de tipos
• Gestión de relaciones

✅ Características Avanzadas

• Soporte GraphQL con resolvers personalizados
• Handlers WebSocket para notificaciones en tiempo real
• Middleware de analytics para seguimiento de rendimiento
• Endpoints de panel administrativo para gestión del sistema

📁 Estructura del Proyecto

taskmaster/
├── src/
│   ├── controllers/          # Controladores REST API
│   │   ├── auth.controller.ts
│   │   ├── task.controller.ts
│   │   ├── user.controller.ts
│   │   ├── team.controller.ts
│   │   └── admin.controller.ts
│   ├── services/             # Servicios de lógica de negocio
│   │   ├── user.service.ts
│   │   ├── task.service.ts
│   │   ├── team.service.ts
│   │   └── notification.service.ts
│   ├── resolvers/            # Resolvers GraphQL
│   │   ├── task.resolver.ts
│   │   └── user.resolver.ts
│   ├── websockets/           # Handlers WebSocket
│   │   └── notification.websocket.ts
│   ├── middleware/           # Middleware personalizado
│   │   ├── logging.middleware.ts
│   │   └── analytics.middleware.ts
│   ├── models/               # Tipos TypeScript
│   │   └── types.ts
│   ├── config/               # Archivos de configuración
│   │   ├── auth.config.ts
│   │   └── database.ts
│   └── index.ts              # Punto de entrada de la aplicación
├── package.json
└── README.md

🛠️ Configuración e Instalación

Prerrequisitos

• Bun >= 1.0.0
• Node.js >= 18.0.0

Inicio Rápido

1. Clonar el ejemplo:

git clone <repository-url>
cd examples/veloce-taskmaster

2. Instalar dependencias:

bun install

3. Ejecutar el servidor de desarrollo:

bun run dev

4. Acceder a la API:

• Documentación API: http://localhost:3001/docs
• Health Check: http://localhost:3001/health
• Info API: http://localhost:3001/api

📚 Ejemplos Clave de Implementación

🔐 Controlador de Autenticación

@Controller('/api/auth')
export class AuthController {
  @Post('/login')
  @ApiDoc({ summary: 'Login de usuario' })
  async login(
    @Body(LoginSchema) credentials: LoginCredentials,
    @Depends(UserService) userService: UserService,
    @Depends(AuthService) authService: AuthService
  ) {
    const user = await userService.validateCredentials(
      credentials.username,
      credentials.password
    );

    if (!user) {
      throw new AuthenticationException('Credenciales inválidas');
    }

    const tokens = await authService.generateTokens({
      sub: user.id,
      username: user.username,
      role: user.role,
      permissions: user.permissions
    });

    return { user, tokens };
  }
}

🎯 Controlador de Tareas con RBAC

@Controller('/api/tasks')
export class TaskController {
  @Get('/')
  @Auth()
  @MinimumRole('developer')
  async listTasks(
    @Query() filters: TaskFilters,
    @CurrentUser() user: JWTPayload,
    @Depends(TaskService) taskService: TaskService
  ) {
    // Filtrado basado en roles
    if (user.role !== 'admin' && user.role !== 'manager') {
      filters.assigneeId = user.sub;
    }

    return await taskService.findAll(filters);
  }

  @Post('/')
  @Auth()
  @MinimumRole('developer')
  @Permissions(['tasks:create'])
  async createTask(
    @Body(CreateTaskSchema) data: CreateTaskDTO,
    @CurrentUser() user: JWTPayload,
    @Depends(TaskService) taskService: TaskService
  ) {
    return await taskService.create(data, user.sub);
  }
}

🗄️ Capa de Servicio con SQLite

export class TaskService {
  private db: Database;

  constructor() {
    this.db = getDatabase();
  }

  async create(data: CreateTaskDTO, creatorId: string): Promise<Task> {
    const stmt = this.db.prepare(`
      INSERT INTO tasks (title, description, priority, creator_id, status)
      VALUES (?, ?, ?, ?, ?)
    `);

    const result = stmt.run(
      data.title,
      data.description,
      data.priority,
      creatorId,
      'todo'
    );

    return await this.findById(result.lastInsertRowid.toString());
  }
}

📊 Resolver GraphQL

@Resolver('Task')
export class TaskResolver {
  @GQLQuery('tasks')
  @Arg('filters', () => TaskFiltersInput)
  async getTasks(
    @Arg('filters') filters: TaskFilters,
    @Depends(TaskService) taskService: TaskService
  ) {
    return await taskService.findAll(filters);
  }

  @GQLMutation('createTask')
  @Arg('input', () => CreateTaskInput)
  async createTask(
    @Arg('input') input: CreateTaskDTO,
    @Depends(TaskService) taskService: TaskService,
    @CurrentUser() user: JWTPayload
  ) {
    return await taskService.create(input, user.sub);
  }
}

🔌 Handler WebSocket

@WebSocket('/ws/notifications')
export class NotificationWebSocket {
  @OnConnect()
  async onConnect(connection: WebSocketConnection) {
    console.log('Usuario conectado:', connection.id);
  }

  @OnMessage()
  async onMessage(
    connection: WebSocketConnection,
    message: any
  ) {
    // Transmitir notificación a todos los clientes conectados
    await this.broadcast(message);
  }
}

🛡️ Middleware Personalizado

export const loggingMiddleware = async (c: Context, next: Next) => {
  const start = Date.now();
  const requestId = crypto.randomUUID();

  c.set('requestId', requestId);
  c.set('startTime', start);

  console.log(`[${requestId}] → ${c.req.method} ${c.req.url}`);

  await next();

  const duration = Date.now() - start;
  console.log(`[${requestId}] ← ${c.req.method} ${c.req.url} ${c.res.status} (${duration}ms)`);
};

🎮 Usuarios Demo

El ejemplo incluye usuarios demo preconfigurados para pruebas:

Usuario	Contraseña	Rol	Permisos
admin	admin123	admin	Acceso completo
manager1	manager123	manager	Gestión de equipos
teamlead1	lead123	team_lead	Liderazgo de proyecto
dev1	dev123	developer	Gestión de tareas
dev2	dev123	developer	Gestión de tareas

📡 Endpoints de API

Autenticación

• POST /api/auth/register - Registro de usuario
• POST /api/auth/login - Login de usuario
• POST /api/auth/logout - Logout de usuario
• POST /api/auth/refresh - Renovar token
• GET /api/auth/me - Obtener usuario actual

Tareas

• GET /api/tasks - Listar tareas (con filtros)
• GET /api/tasks/:id - Obtener tarea por ID
• POST /api/tasks - Crear nueva tarea
• PUT /api/tasks/:id - Actualizar tarea
• DELETE /api/tasks/:id - Eliminar tarea
• POST /api/tasks/:id/status - Actualizar estado de tarea
• POST /api/tasks/:id/assign - Asignar tarea
• GET /api/tasks/stats/overview - Estadísticas de tareas

Usuarios y Equipos

• GET /api/users - Listar usuarios
• GET /api/teams - Listar equipos
• POST /api/teams - Crear equipo
• POST /api/teams/:id/members - Agregar miembro al equipo

Admin (Solo administradores)

• GET /api/admin/users - Todos los usuarios
• GET /api/admin/tasks - Todas las tareas
• PUT /api/admin/users/:id/role - Cambiar rol de usuario
• GET /api/admin/stats/system - Estadísticas del sistema

🔧 Configuración

Variables de Entorno

# Configuración del Servidor
PORT=3001
NODE_ENV=development

# Base de Datos
DATABASE_URL=./taskmaster.db

# Configuración JWT
JWT_SECRET=tu-clave-super-secreta
JWT_EXPIRES_IN=1h
JWT_REFRESH_EXPIRES_IN=7d

Esquema de Base de Datos

El ejemplo crea automáticamente las siguientes tablas:

• users - Cuentas y perfiles de usuario
• tasks - Gestión de tareas
• teams - Organización de equipos
• notifications - Notificaciones en tiempo real

🚀 Consideraciones para Producción

Aunque este es un ejemplo básico, aquí hay consideraciones para uso en producción:

🔒 Seguridad

• Usar variables de entorno para secretos
• Implementar hash de contraseñas adecuado (bcrypt)
• Agregar rate limiting
• Habilitar HTTPS
• Configurar CORS apropiadamente

🗄️ Base de Datos

• Usar PostgreSQL o MySQL para producción
• Implementar migraciones de base de datos
• Agregar connection pooling
• Configurar respaldos de base de datos

📊 Monitoreo

• Agregar logging comprehensivo
• Implementar health checks
• Configurar error tracking
• Monitorear métricas de rendimiento

🔄 Escalabilidad

• Usar Redis para almacenamiento de sesiones
• Implementar escalado horizontal
• Agregar load balancing
• Configurar CDN para assets estáticos

📖 Ruta de Aprendizaje

Este ejemplo demuestra:

1. Configuración Básica - Estructura del proyecto y configuración
2. Autenticación - Implementación de JWT y RBAC
3. Operaciones CRUD - Interacciones con base de datos
4. Middleware - Manejo personalizado de solicitudes/respuestas
5. GraphQL - Enfoque alternativo de API
6. WebSockets - Características en tiempo real
7. Validación - Validación de datos de solicitud
8. Documentación - Integración OpenAPI/Swagger

🔗 Recursos Relacionados

• Guía de Inicio
• Documentación de Decoradores
• Inyección de Dependencias
• Sistema de Plugins
• Referencia de API

---

:::tip Próximos Pasos ¿Listo para construir tu propia aplicación? ¡Consulta la Guía de Inicio para crear tu primer proyecto Veloce-TS! :::