ChapuApp es una plataforma integral de gestión de servicios de campo (Field Service Management) que conecta a clientes que requieren reparaciones u obras en el hogar con profesionales cualificados de su zona geográfica.
La solución combina un comparador de presupuestos, gestión de agenda interactiva sin solapamientos, expediente e historial técnico digital por propiedad (Libro Técnico de la Vivienda) y un motor de asistencia con Inteligencia Artificial que automatiza el triaje de incidencias, la recomendación de técnicos por cercanía y reputación, y la asistencia en la redacción de propuestas comerciales.
- Descripción General
- Módulos del Sistema
- Arquitectura del Software
- Pila Tecnológica
- Modelo de Datos
- Reglas de Negocio Principales
- Estructura del Código Fuente
- Requisitos e Instalación Local
- Pruebas y Calidad
El proyecto resuelve dos problemáticas fundamentales del sector de reformas y reparaciones del hogar:
- Para los clientes: Dificultad para encontrar mano de obra verificada, falta de transparencia en presupuestos y la pérdida de historial de mantenimiento de sus viviendas.
- Para los profesionales: Ineficiencia en la captación de clientes locales, pérdidas de tiempo en la elaboración de propuestas y conflictos de agenda o solapamientos de citas.
Además, el sistema integra un motor de reglas administrativas que mitiga la mala praxis mediante validación de licencias oficiales, retención temporal de pagos (escrow) y sanciones disciplinarias automáticas por bajas calificaciones o cancelaciones injustificadas.
- Gestión de Propiedades: Registro y administración de inmuebles vinculados al cliente.
- Publicación de Averías: Registro de incidencias con descripción, grado de urgencia (NORMAL, URGENTE_24H, EMERGENCIA) y adjuntos multimedia.
- Comparador de Presupuestos: Interfaz visual en tarjetas para evaluar propuestas desglosadas por horas, precio/hora, repuestos y reputación del técnico.
- Reserva de Citas y Pagos: Selección de franja horaria disponible y registro de transacciones con retención de fondos (escrow).
- Libro Técnico de la Vivienda: Expediente cronológico de intervenciones, profesionales intervinientes y piezas sustituidas por inmueble.
- Valoraciones y Reseñas: Evaluación de 1 a 5 estrellas restringida a intervenciones finalizadas.
- Perfil Operativo y Cobertura: Configuración de tarifa base/hora, radio de acción en kilómetros, código postal de origen y especialidades.
- Marketplace de Trabajos: Tablero interactivo con filtros por categoría, urgencia y proximidad.
- Generador de Presupuestos: Herramienta de cálculo automatizado de costes y desglose formal de mano de obra y materiales.
- Agenda e Itinerario: Calendario de intervenciones con bloqueo automático anti-solapamientos.
- Ciclo de Vida de la Obra: Máquina de estados completa (
ACEPTADO->EN_CAMINO->EN_PROCESO->PENDIENTE_REPUESTO->FINALIZADO->PAGADO).
- Triaje y Categorización: Análisis del texto descriptivo para inferir categoría técnica, urgencia y repuestos preliminares.
- Algoritmo de Matching: Recomendación de los 3 profesionales más aptos considerando cercanía, puntuación media y disponibilidad.
- Asistente de Presupuestos: Conversión de notas borrador esquemáticas del técnico en propuestas comerciales profesionales.
- ServiBot: Chatbot de consulta técnica para normativas, diagramas de montaje y diagnósticos.
- Verificación de Credenciales: Validación manual de certificaciones y licencias aportadas por técnicos por categoría.
- Gestión de Categorías y Comisiones: Configuración de oficios y porcentajes de comisión de la plataforma.
- Penalizaciones Automáticas: Motor disciplinario para la congelación preventiva de cuentas por bajo rendimiento o cancelaciones.
- Dashboard Analítico e Inspección IA: Métricas de negocio y registro de auditoría anonimizado de interacciones con IA.
El sistema sigue una Arquitectura en Capas Desacopladas (MVC + DAO), garantizando la separación estricta de responsabilidades:
+-------------------------------------------------------------+
| Capa de Presentación / UI |
| (Java Swing + FlatLaf Look&Feel) |
+-------------------------------------------------------------+
|
v
+-------------------------------------------------------------+
| Capa de Controladores |
| (SolicitudController, AgendaController, etc.) |
+-------------------------------------------------------------+
|
v
+-------------------------------------------------------------+
| Capa de Servicios / Negocio |
| (PresupuestoService, AgendaService, PenalizacionService) |
+-------------------------------------------------------------+
| |
v v
+-------------------------------+ +---------------------------+
| Capa de Acceso a Datos | | Cliente API REST IA |
| (JDBC Nativo / DAO) | | (HttpClient + Gson) |
+-------------------------------+ +---------------------------+
|
v
+-------------------------------+
| Base de Datos Relacional |
| (MySQL 8.0 InnoDB) |
+-------------------------------+
- Presentación (
views): Formularios, tableros y comparadores creados en Java Swing. No contienen lógica de negocio. - Controladores (
controllers): Capturan eventos de usuario, invocan servicios de dominio y gestionan el flujo de las vistas. - Servicios (
services): Encapsulan todas las Reglas de Negocio (RN-01 a RN-04), orquestan transacciones y aplican políticas de seguridad. - Acceso a Datos (
repository/dao): Clases DAO que ejecutan consultas SQL relacionales conPreparedStatementy manejan bloqueos explícitos (SELECT ... FOR UPDATE). - Modelo (
models): Entidades POJO que transportan la información entre todas las capas.
| Componente | Tecnología | Justificación |
|---|---|---|
| Lenguaje de Programación | Java 17 LTS | Estabilidad, rendimiento en JVM, soporta Records, Bloques de Texto y Tipado Inferido. |
| Interfaz Gráfica (GUI) | Java Swing + FlatLaf | Aplicación de escritorio nativa con diseño moderno y soporte de temas (Dark Slate). |
| Base de Datos | MySQL 8.0 (InnoDB) | Soporte estricto de transacciones ACID, integridad referencial y bloqueos a nivel de fila. |
| Conexión a BD | JDBC Nativo (java.sql) |
Consultas preparadas directas contra inyección SQL sin sobrecarga de ORMs pesados. |
| Cliente REST / JSON | Java HttpClient + Gson |
Comunicación HTTP/2 asíncrona/síncrona con servicios externos de IA y formateo JSON. |
| Pruebas Unitarias | JUnit 5 | Cobertura de pruebas en la capa de servicios y verificación de reglas de negocio. |
| Control de Versiones | Git + GitHub | Gestión de ramas, trazabilidad de código y colaboración. |
| Entorno Local | Docker + Portainer | Despliegue en contenedor aislado de la base de datos MySQL 8.0. |
El esquema relacional está compuesto por 12 tablas interconectadas en MySQL sobre el motor InnoDB:
usuarios: Entidad base para autenticación y RBAC (id_usuario,email,password_hash,rol,activo).clientes: Extensión de datos de cliente (id_cliente,telefono,direccion_principal).profesionales: Extensión técnica (id_profesional,tarifa_hora_base,radio_cobertura_km,puntuacion_media,estado_cuenta).viviendas: Propiedades vinculadas a los clientes (id_vivienda,id_cliente,alias,direccion,codigo_postal).categorias_servicio: Oficios técnicos (id_categoria,nombre_categoria,porcentaje_comision,requiere_licencia).acreditaciones_profesional: Certificaciones del técnico (id_acreditacion,id_profesional,id_categoria,estado_validacion).solicitudes_averia: Registro de incidencias (id_solicitud,id_cliente,id_vivienda,urgencia,estado_solicitud).presupuestos: Propuestas económicas (id_presupuesto,id_solicitud,horas_estimadas,importe_total,comision_plataforma).citas: Reservas de agenda (id_cita,id_presupuesto,fecha_intervencion,hora_inicio,hora_fin).valoraciones: Reseñas de clientes (id_valoracion,id_solicitud,puntuacion,comentario).pagos: Control de fondos y retenciones (id_pago,id_presupuesto,importe_bruto,comision_retenida,estado_pago).auditoria_ia: Trazabilidad de interacción con IA (id_auditoria,tipo_operacion,prompt_anonimizado,respuesta_ia).
-
RN-01 (Acreditación Obligatoria): Un profesional solo puede emitir presupuestos en categorías donde su documentación haya sido revisada y aprobada (
VALIDADO) por un administrador. -
RN-02 (Prevención de Solapamientos): El sistema bloquea reservas de citas en franjas coincidentes para un mismo técnico mediante transacciones ACID (
SELECT ... FOR UPDATE). -
RN-03 (Cálculo Financiero):
$$\text{Importe Total} = (\text{Horas Estimadas} \times \text{Tarifa Hora}) + \text{Coste Materiales}$$ $$\text{Comisión Plataforma} = \text{Importe Total} \times % \text{Comisión Categoría}$$ -
RN-04 (Penalización Automática): Si un técnico acumula 3 valoraciones consecutivas inferiores a 2.0 estrellas o 2 cancelaciones injustificadas en 7 días, su cuenta pasa automáticamente a
CONGELADO_REVISION. -
RN-05 (Caducidad de Presupuestos): Los presupuestos emitidos tienen una validez de 72 horas antes de pasar a estado
CADUCADO. - RNF-02 (Privacidad RGPD en IA): Exclusión o anonimización de cualquier dato personal identificativo (PII) antes de enviar peticiones a APIs externas de IA.
- RNF-14 (Degradación Elegante): Si la API de IA no responde en menos de 5 segundos, el sistema permite continuar el flujo de trabajo en modo manual sin interrumpir al usuario.
src/main/java/com/localrepair/
├── config/ # Configuración de conexiones y variables globales
├── controllers/ # Controladores de interfaz y mediadores de eventos
│ ├── AdminController.java
│ ├── AgendaController.java
│ ├── PresupuestoController.java
│ └── SolicitudController.java
├── exceptions/ # Excepciones de dominio personalizadas
│ ├── AccessDeniedException.java
│ ├── AccountFrozenException.java
│ ├── AgendaConflictException.java
│ └── UnaccreditedProfessionalException.java
├── models/ # Entidades del modelo de dominio (POJOs)
│ ├── Cita.java
│ ├── Cliente.java
│ ├── Presupuesto.java
│ ├── Profesional.java
│ ├── SolicitudAveria.java
│ └── Usuario.java
├── repository/ # Patrón DAO e interfaces de persistencia
│ ├── CitaDAO.java
│ ├── CitaDAOJdbc.java
│ ├── PresupuestoDAO.java
│ └── PresupuestoDAOJdbc.java
├── services/ # Lógica de negocio y reglas de dominio
│ ├── AIServiceClient.java
│ ├── AgendaService.java
│ ├── PenalizacionService.java
│ └── PresupuestoService.java
└── views/ # Componentes de interfaz Java Swing + FlatLaf
├── VistaAgendaPanel.java
└── VistaPresupuestoForm.java
- Java Development Kit (JDK): Versión 17 LTS o superior.
- Base de Datos: MySQL Server 8.0 o MariaDB 10.5+.
- Gestor de Dependencias/Entorno: VS Code con Extension Pack for Java o IDE equivalente.
- Docker y Docker Compose (Opcional): Para despliegue automatizado de la base de datos.
-
Clonar el repositorio:
git clone https://github.com/usuario/chapuapp.git cd chapuapp -
Desplegar la Base de Datos con Docker:
docker run -d \ --name chapuapp-db \ -e MYSQL_ROOT_PASSWORD=root \ -e MYSQL_DATABASE=chapuapp_db \ -p 3306:3306 \ mysql:8.0
-
Cargar el Esquema SQL: Ejecutar las sentencias del script DDL ubicado en
docs/schema.sqlpara crear las 12 tablas con sus correspondientes restricciones de clave foránea e índices. -
Configurar la conexión: Asegurar las credenciales de base de datos en el archivo de propiedades o clase de configuración
DatabaseConfig.java:url:jdbc:mysql://localhost:3306/chapuapp_dbuser:rootpassword:root
-
Compilar y Ejecutar:
javac -d bin -sourcepath src/main/java src/main/java/com/localrepair/Main.java java -cp bin com.localrepair.Main
El proyecto exige una cobertura mínima del 80% de líneas e instrucciones ejecutables en la capa de servicios (services).
Para ejecutar la suite completa de pruebas unitarias con JUnit 5:
mvn test- Comprobación matemática de comisiones e importes totales (
RN-03). - Verificación transaccional de bloqueos en agenda ante concurrencia (
RN-02). - Validación de acreditaciones de profesionales previo al envío de propuestas (
RN-01). - Ejecución del motor de penalizaciones automáticas y congelación de cuentas (
RN-04). - Comprobación del mecanismo de degradación elegante (fallback) por timeout en la API de IA.