Skip to content
BranchesTags

Repository files navigation

TaskPro Backend

API REST para la gestión de proyectos, tareas y equipos de trabajo. Desarrollada con Node.js, Express, Prisma ORM y PostgreSQL, incluye autenticación JWT, control de roles, tablero Kanban, métricas de rendimiento y trazabilidad completa de actividad.

Características

Módulo Descripción
Autenticación Login con JWT y protección de rutas mediante middleware
Usuarios CRUD completo con roles (ADMIN, GERENTE, COLABORADOR) y activación/desactivación
Proyectos Gestión de proyectos con miembros, estados y eliminación lógica
Tareas CRUD, asignación múltiple, prioridad, peso, fechas límite y adjuntos
Kanban Vista por columnas (PENDING, IN_PROGRESS, DONE) y cambio de estado vía drag & drop
Comentarios Comentarios por tarea con soporte de archivos adjuntos
Métricas Dashboard global, métricas por proyecto y rendimiento por usuario
Trazabilidad Historial de estados, registro de actividad y auditoría de acciones
Documentación Swagger UI interactivo con especificación OpenAPI 3.0

Stack tecnológico

  • Runtime: Node.js
  • Framework: Express 4
  • ORM: Prisma 6
  • Base de datos: PostgreSQL (compatible con Neon)
  • Seguridad: Helmet, bcrypt, JWT
  • Validación: express-validator
  • Documentación: swagger-jsdoc + swagger-ui-express
  • Archivos: Multer

Requisitos previos

  • Node.js 18 o superior
  • PostgreSQL 14+ (local o instancia en la nube)
  • npm

Instalación

# 1. Clonar e instalar dependencias
git clone <url-del-repositorio>
cd TaskPro-Backend
npm install

# 2. Configurar variables de entorno (crear .env — ver sección siguiente)

# 3. Generar cliente Prisma y aplicar migraciones
npx prisma generate
npx prisma migrate dev

# 4. Poblar datos iniciales en la BD original (.env)
npm run seed

# 5. Iniciar servidor en modo desarrollo
npm run dev

El servidor quedará disponible en http://localhost:3000.

Verificar estado:

curl http://localhost:3000/health
# → { "success": true, "message": "OK" }

Variables de entorno

Crear un archivo .env en la raíz del proyecto:

DATABASE_URL="postgresql://usuario:password@host:5432/taskpro?sslmode=require"
JWT_SECRET="clave-secreta-segura-y-larga"
PORT=3000
Variable Descripción Requerida
DATABASE_URL Cadena de conexión PostgreSQL Sí
JWT_SECRET Clave para firmar tokens JWT Sí
PORT Puerto del servidor (default: 3000) No

Nota: No subir .env ni .env.test al repositorio. Ambos están en .gitignore.

Bases de datos: desarrollo y tests

El proyecto usa dos archivos de entorno con instancias de PostgreSQL separadas:

Archivo Uso Comandos que lo utilizan
.env Aplicación en desarrollo/producción (BD original) npm run dev, npm start, npm run seed, migraciones
.env.test Tests automatizados únicamente npm test, npm run test:coverage 
# Desarrollo — crear .env con tu instancia principal (Neon, local, etc.)
DATABASE_URL="postgresql://usuario:password@host:5432/neondb?sslmode=require"
JWT_SECRET="clave-secreta-segura-y-larga"
PORT=3000

# Tests — copiar plantilla y apuntar a una BD distinta
cp .env.test.example .env.test

Importante: npm run seed siempre usa la BD de .env (original), no la de .env.test. Los tests de integración limpian y repueblan solo la BD configurada en .env.test.

Scripts disponibles

Comando Descripción
npm run dev Servidor con recarga automática (nodemon)
npm start Servidor en modo producción
npm run seed Inserta roles y usuario admin en la BD de .env (original)
npm run prisma:generate Regenera el cliente Prisma
npm run prisma:migrate Ejecuta migraciones en desarrollo
npm run prisma:deploy Aplica migraciones en producción
npm test Ejecuta la suite de tests
npm run test:watch Tests en modo watch
npm run test:coverage Tests con reporte de cobertura

Testing

El proyecto incluye tests unitarios e de integración con Jest y Supertest.

Ejecutar tests

npm test
npm run test:watch
npm run test:coverage

Configuración de base de datos para tests

Los tests de integración limpian y repueblan la base de datos en cada suite. Deben usar una instancia distinta a la de .env (ver Bases de datos: desarrollo y tests).

cp .env.test.example .env.test

Ejemplo de .env.test:

DATABASE_URL="postgresql://usuario:password@localhost:5432/taskpro_test"
JWT_SECRET="test-jwt-secret-key"
PORT=3001

Si no existe .env.test, se utiliza el archivo .env principal.

Estructura de tests

tests/
├── setup.js                  # Variables de entorno y NODE_ENV=test
├── helpers/
│   ├── db.js                 # Limpieza y seed de datos de prueba
│   └── auth.js               # Helpers de login y tokens
├── unit/
│   └── utils.test.js         # Utilidades (ApiError, respuestas)
└── integration/
    ├── health.test.js        # Health check y rutas 404
    ├── auth.test.js          # Login y autenticación
    ├── users.test.js         # CRUD y permisos de usuarios
    ├── projects.test.js      # Proyectos, métricas y dashboard
    ├── tasks.test.js         # Kanban, tareas y adjuntos
    └── comments.test.js      # Comentarios con y sin archivos

Cobertura actual

Área Escenarios probados
Health Endpoint /health, rutas inexistentes
Auth Login válido/inválido, validaciones, token requerido
Usuarios Listado, creación (ADMIN), permisos, activar/desactivar
Proyectos CRUD, métricas por proyecto y por usuario, rendimiento del equipo
Tareas Kanban, cambio de estado, creación, vencidas, adjuntos, actividad
Comentarios Creación JSON, con archivo adjunto, listado por tarea
Dashboard Métricas globales del sistema

Autenticación y roles

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "admin@taskpro.com",
  "password": "Admin123*"
}

Respuesta exitosa:

{
  "success": true,
  "message": "Login exitoso",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 1,
      "name": "Administrador PRO",
      "email": "admin@taskpro.com",
      "role": "ADMIN"
    }
  }
}

Uso del token

Incluir en todas las rutas protegidas:

Authorization: Bearer <token>

Roles y permisos

Rol Permisos principales
ADMIN Acceso total: gestión de usuarios, proyectos y tareas
GERENTE Crear/editar proyectos y tareas, ver métricas
COLABORADOR Consultar y actualizar tareas asignadas

Estructura del proyecto

TaskPro-Backend/
├── prisma/
│   ├── schema.prisma       # Modelo de datos
│   ├── migrations/         # Migraciones SQL
│   └── seed.js             # Datos iniciales
├── src/
│   ├── config/             # Entorno, logger, multer
│   ├── controllers/        # Controladores HTTP
│   ├── docs/               # Configuración Swagger
│   ├── middlewares/        # Auth, roles, validación, errores
│   ├── routes/             # Definición de rutas
│   ├── services/           # Lógica de negocio
│   ├── utils/              # Helpers y respuestas
│   └── app.js              # Punto de entrada
├── uploads/                # Archivos subidos (adjuntos)
├── PAYLOADS_FRONTEND.md    # Guía detallada de payloads
└── README.md

Endpoints principales

Prefijo base: /api

Auth

Método Ruta Descripción
POST /auth/login Iniciar sesión

Usuarios

Método Ruta Rol Descripción
POST /users ADMIN Crear usuario
GET /users Auth Listar usuarios
PUT /users/:id Auth Actualizar usuario
PATCH /users/:id/status Auth Activar/desactivar usuario
GET /usuarios Auth Listado simplificado

Proyectos

Método Ruta Rol Descripción
POST /projects ADMIN, GERENTE Crear proyecto
GET /projects Auth Listar proyectos
GET /projects/:id Auth Obtener proyecto
PUT /projects/:id ADMIN, GERENTE Actualizar proyecto
PATCH /projects/:id/members ADMIN, GERENTE Gestionar miembros
PATCH /projects/:id/status ADMIN, GERENTE Cambiar estado
DELETE /projects/:id ADMIN, GERENTE Eliminación lógica
GET /projects/:id/metrics Auth Métricas del proyecto
GET /projects/:id/metrics/users Auth Rendimiento de todos los usuarios
GET /projects/:id/metrics/users/:userId Auth Métricas de un usuario

Estados de proyecto: ACTIVE · PAUSED · FINISHED

Tareas

Método Ruta Rol Descripción
POST /tasks Auth Crear tarea
POST /tasks/project/:id Auth Crear tarea en proyecto
GET /tasks Auth Listar todas las tareas
GET /tasks/:id Auth Obtener tarea
GET /tasks/project/:id Auth Tareas por proyecto
GET /tasks/kanban/:projectId Auth Vista Kanban
PATCH /tasks/:id/status Auth Cambiar estado (Kanban)
PUT /tasks/:id Auth Actualizar tarea
DELETE /tasks/:id ADMIN, GERENTE Eliminar tarea
GET /tasks/:id/activity Auth Historial de actividad
POST /tasks/:id/attachments Auth Subir adjunto
GET /tasks/overdue/list Auth Tareas vencidas

Estados de tarea: PENDING · IN_PROGRESS · DONE

Ejemplo — Vista Kanban:

GET /api/tasks/kanban/1
Authorization: Bearer <token>
{
  "success": true,
  "message": "Kanban obtenido",
  "data": {
    "PENDING": [{ "id": 1, "title": "Diseñar base de datos", "..." : "..." }],
    "IN_PROGRESS": [],
    "DONE": []
  }
}

Ejemplo — Mover tarea entre columnas:

PATCH /api/tasks/1/status
Content-Type: application/json

{ "status": "IN_PROGRESS" }

Comentarios

Método Ruta Descripción
POST /comments Crear comentario (JSON o multipart/form-data con archivo)
GET /comments/task/:id Listar comentarios de una tarea

Dashboard

Método Ruta Descripción
GET /dashboard/metrics Métricas globales del sistema

Incluye: proyectos activos, tareas por estado, tareas vencidas, progreso por peso, tareas completadas/creadas en la semana y desglose por prioridad.

Formato de respuesta

Todas las respuestas siguen un contrato uniforme:

Éxito:

{
  "success": true,
  "message": "Descripción de la operación",
  "data": { }
}

Error:

{
  "success": false,
  "message": "Descripción del error",
  "details": null
}

Documentación Swagger

Con el servidor en ejecución:

Recurso URL
Interfaz interactiva http://localhost:3000/api/docs
Especificación OpenAPI http://localhost:3000/api/docs.json

Desde Swagger UI puedes autenticarte con el botón Authorize usando el token JWT obtenido en el login.

Integración con frontend

Para payloads detallados de cada endpoint (body, params, ejemplos de respuesta y enums), consultar:

PAYLOADS_FRONTEND.md

Recomendaciones clave:

  • Persistir el token tras el login y enviarlo en el header Authorization.
  • Redirigir a login ante respuestas 401.
  • Usar GET /api/tasks/kanban/:projectId para cargar columnas iniciales del tablero.
  • Usar PATCH /api/tasks/:id/status para drag & drop en Kanban.
  • Enviar adjuntos con FormData (multipart/form-data), no JSON.

Datos de prueba (seed)

El comando npm run seed crea los roles del sistema y el usuario administrador en la base de datos original (.env):

npm run seed
Campo Valor
Nombre Administrador PRO
Email admin@taskpro.com
Contraseña Admin123*
Rol ADMIN

Si el usuario ya existe, el seed actualiza el nombre a Administrador PRO sin cambiar el email ni la contraseña (salvo que se modifique el script).

No confundir con tests: npm test usa .env.test y repuebla datos de prueba propios (admin@test.com, etc.). Esa BD es independiente de la de la aplicación.

Modelo de datos

Entidades principales: User, Role, Project, ProjectMember, Task, TaskAssignment, Comment, Attachment, TaskHistory, TaskActivity, AuditLog.

El esquema completo está definido en prisma/schema.prisma. Diagrama ER en PlantUML: docs/er-diagram.puml.

Licencia

ISC

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages