Prerrequisitos

Antes de comenzar, asegúrate de tener instaladas las siguientes herramientas:

PostgreSQL

Versión 15 o superior

Java JDK

Versión 21 o superior

Android Studio

Koala (2024.1.1) o más reciente

Nota: El backend requiere Java 21, mientras que la app Android se compila contra SDK 36 con un SDK mínimo de 26 (Android 8.0).

Configuración Paso a Paso

Paso 1: Clonar el Repositorio

Clona el repositorio de iMirly en tu máquina local:

bash
git clone https://github.com/Anyeel/imirly.git 
cd imirly

La estructura del proyecto incluye dos directorios principales:

yaml
imirly/
├── backend/          # Spring Boot API
├── frontend/         # Aplicación Android
└── docker-compose.yml # Configuración de contenedor PostgreSQL

Paso 2: Configurar la Base de Datos PostgreSQL

Tienes dos opciones para ejecutar PostgreSQL:

El proyecto incluye un archivo docker-compose.yml para una configuración sencilla:

yaml
version: '3.8'
services:
  db:
    image: postgres:15
    container_name: imirly_db_container
    restart: always
    environment:
      POSTGRES_USER: user_imirly
      POSTGRES_PASSWORD: password_imirly
      POSTGRES_DB: imirly_db
    ports:
      - "5432:5432"
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

Inicia el contenedor de la base de datos:

bash
docker-compose up -d

Si prefieres una instalación local, crea la base de datos manualmente:

sql
CREATE DATABASE imirly_db;
CREATE USER user_imirly WITH PASSWORD 'password_imirly';
GRANT ALL PRIVILEGES ON DATABASE imirly_db TO user_imirly;

Paso 3: Configurar Propiedades del Backend

Navega al archivo de configuración del backend y verifica los ajustes de conexión a la base de datos:

bash
cd backend/src/main/resources

El archivo application.properties debe contener:

properties
spring.application.name=iMirly
spring.datasource.url=jdbc:postgresql://localhost:5432/imirly_db
spring.datasource.username=user_imirly
spring.datasource.password=password_imirly
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

⚠️ Importante: Si usaste credenciales diferentes al configurar PostgreSQL, actualiza los campos username y password según corresponda.

Paso 4: Iniciar el Backend Spring Boot

Desde el directorio backend/, inicia el servidor usando Maven:

bash
cd backend
./mvnw spring-boot:run
bash
cd backend
mvn spring-boot:run

La aplicación se iniciará en http://localhost:8080.

✅ Seeder Automático: En el primer inicio, el componente DatabaseSeeder pobla automáticamente la base de datos con categorías y subcategorías de servicios. Verás la confirmación en la consola:

bash
=========================================================
🚀 EJECUTANDO SEEDER: Poblando BD vacía... 🚀
=========================================================
✅ BASE DE DATOS INICIALIZADA EXITOSAMENTE! ✅

¿Qué se inicializa?

El seeder crea automáticamente:

  • 7 categorías principales: Hogar, Belleza y Estética, Educación, Cuidado, Deportes y Salud, Mascotas, Eventos y Otros
  • 50+ subcategorías en todos los tipos de servicios
  • Mapeo de iconos para la UI de la app Android
java
// Ejemplo de DatabaseSeeder.java
CategoriaEntity hogar = crearCategoria("Hogar", "hogar");
crearSubcategoria("Electricista", "hogar_electricista", hogar);
crearSubcategoria("Fontanería", "hogar_fontaneria", hogar);
crearSubcategoria("Limpieza", "hogar_limpieza", hogar);
// ... más subcategorías

Paso 5: Verificar que el Backend está funcionando

Prueba los endpoints de la API para confirmar que el backend está operativo:

bash
# Health check (requiere Spring Actuator)
curl http://localhost:8080/actuator/health

# Probar conexión a base de datos - obtener categorías
curl http://localhost:8080/api/v1/catalog/categorias

Respuesta esperada para categorías:

json
[
  {
    "id": "...",
    "nombre": "Hogar",
    "icono": "hogar"
  },
  {
    "id": "...",
    "nombre": "Estética y Belleza",
    "icono": "belleza"
  }
  // ... más categorías
]

Paso 6: Configurar la Aplicación Android

Abre Android Studio e importa el directorio frontend/ como un proyecto.

Actualizar URL Base de la API (si es necesario)

La app Android viene preconfigurada para conectarse al backend local. Verifica el archivo RetrofitClient.kt:

kotlin
// frontend/app/src/main/java/com/imirly/app/network/RetrofitClient.kt
object RetrofitClient {
    private const val BASE_URL = "http://10.0.2.2:8080"
    
    // 10.0.2.2 es la IP especial para que el emulador Android llegue a la máquina host
    // Para dispositivos físicos, reemplaza con la IP local de tu computadora (ej: "http://192.168.1.100:8080")
}

⚠️ Importante: La IP 10.0.2.2 solo funciona para emuladores Android. Si pruebas en un dispositivo físico, reemplázala con la dirección IP de tu red local.

Sincronizar Dependencias Gradle

1

Abrir Proyecto

Android Studio detectará los archivos build.gradle.kts y te pedirá sincronizar

2

Sincronizar Gradle

Haz clic en "Sync Now" en la barra de notificaciones, o ve a File → Sync Project with Gradle Files

3

Esperar Dependencias

Gradle descargará todas las dependencias necesarias incluyendo Retrofit, Jetpack Compose y Navigation

Dependencias clave en app/build.gradle.kts:

kotlin
dependencies {
    // Jetpack Compose para UI
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.compose.material3)
    
    // Retrofit para comunicación con API
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
    
    // Navigation
    implementation("androidx.navigation:navigation-compose:2.8.0")
    
    // ViewModel para gestión de estado
    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.8.4")
}

Paso 7: Ejecutar la Aplicación Android

1

Seleccionar Dispositivo/Emulador

Crea un Android Virtual Device (AVD) o conecta un dispositivo físico con depuración USB habilitada

2

Compilar y Ejecutar

Haz clic en el botón verde "Run" (▶️) o presiona Shift + F10

3

Esperar la Compilación

Gradle compilará el código Kotlin e instalará el APK en tu dispositivo/emulador

4

La App se Lanza

La aplicación se abrirá en la pantalla de onboarding

Paso 8: Crear tu Primera Cuenta

Una vez que la app esté ejecutándose, prueba el flujo completo:

1

Navegar a Registro

Desde la pantalla de onboarding, toca "Crear Cuenta"

2

Completar Formulario de Registro

Ingresa los datos: Nombre, Email, Contraseña, Tipo de Usuario (Cliente o Profesional), Documento de Identidad

3

Enviar Registro

La app envía una petición POST a /api/v1/auth/register

4

Recibir Token JWT

Tras el registro exitoso, recibirás un token JWT que se almacena automáticamente

Flujo de registro desde AuthController.java:

java
@PostMapping("/register")
public ResponseEntity<?> registerUser(@RequestBody RegisterUserRequest request) {
    try {
        RegisterUserCommand command = new RegisterUserCommand(
            request.getNombre(),
            request.getEmail(),
            request.getRawPassword(),
            UserType.valueOf(request.getTipoUsuario().toUpperCase()),
            request.getDocumentoIdentidad()
        );
        
        User newUser = registerUserUseCase.registerUser(command);
        return ResponseEntity.status(HttpStatus.CREATED)
            .body("Usuario registrado con ID: " + newUser.getId());
    } catch (IllegalArgumentException e) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(e.getMessage());
    }
}

Paso 9: Explorar Funcionalidades Principales

Con la autenticación completa, explora la plataforma:

Para Proveedores de Servicios (Profesional)

  • Crear un Anuncio de Servicio: Navega a la pantalla "Publicar", selecciona categoría y subcategoría, ingresa detalles del servicio, precio y ubicación, envía para crear un anuncio activo
  • Gestionar tus Anuncios: Ver todos tus servicios publicados, pausar/reactivar anuncios, editar precios y descripciones

Para Clientes

  • Explorar Servicios: Explora categorías en la pantalla de inicio, ver subcategorías y anuncios activos, ver valoraciones y detalles del proveedor
  • Solicitar un Servicio: Selecciona un anuncio, envía una solicitud de servicio con detalles, recibe propuestas de presupuesto vía chat
  • Aceptar Propuestas: Revisar precios propuestos, aceptar para retener fondos en garantía, seguir la finalización del servicio

Solución de Problemas

El Backend no Inicia

Problema: Error de conexión a PostgreSQL

bash
Caused by: org.postgresql.util.PSQLException: Connection refused

Solución: Verifica que PostgreSQL esté ejecutándose:

bash
# Para Docker
docker ps | grep imirly_db

# Para instalación local
sudo systemctl status postgresql

La App Android no Conecta al Backend

Problema: Error de red o respuestas 404

Soluciones:

  • Verifica que el backend esté ejecutándose en el puerto 8080
  • Revisa el BASE_URL en RetrofitClient.kt
  • Para dispositivos físicos, asegúrate de estar en la misma red WiFi
  • Desactiva cualquier VPN que pueda bloquear conexiones locales

Base de Datos Ya Inicializada

Si ves:

bash
✅ La base de datos ya tiene categorías. Saltando Seed.

Esto es normal - el seeder solo se ejecuta una vez. Para volver a ejecutarlo:

sql
-- Conecta a la base de datos y trunca las tablas
TRUNCATE TABLE usuarios, categoria CASCADE;

Luego reinicia el backend.

Referencia Rápida

Puertos Predeterminados

  • Backend API: http://localhost:8080
  • PostgreSQL: localhost:5432

Credenciales de Base de Datos

  • Database: imirly_db
  • Username: user_imirly
  • Password: password_imirly

Endpoints Clave de la API

  • Auth: /api/v1/auth/register, /api/v1/auth/login
  • Catálogo: /api/v1/catalog/categorias, /api/v1/catalog/subcategorias
  • Anuncios: /api/v1/anuncios
  • Contratos: /api/v1/solicitudes
  • Mensajes: /api/v1/mensajes

Siguientes Pasos

Ahora que iMirly está ejecutándose localmente, profundiza en la arquitectura: