diff --git a/README.md b/README.md new file mode 100644 index 0000000..7a26dd0 --- /dev/null +++ b/README.md @@ -0,0 +1,211 @@ +# TFG — Integración Dolibarr · PrestaShop + +Sistema de sincronización bidireccional entre el ERP **Dolibarr** y la tienda **PrestaShop**, desarrollado como Trabajo de Fin de Grado del ciclo DAM. + +--- + +## Arquitectura + +``` +┌─────────────────────────────────────────────┐ +│ APPS CLIENTE │ +│ JavaFX (escritorio) · Android (móvil) │ +└──────────────────┬──────────────────────────┘ + │ REST + Basic Auth +┌──────────────────▼──────────────────────────┐ +│ SYNC-SERVICE │ +│ Spring Boot 3 · Java 21 · Railway │ +│ API REST propia · @Scheduled sync jobs │ +│ H2 (dev) · MySQL (prod) │ +└────────────┬──────────────────┬─────────────┘ + │ │ + ┌────────▼──────┐ ┌────────▼──────────┐ + │ DOLIBARR │ │ PRESTASHOP │ + │ ERP · REST │ │ E-commerce · WS │ + └───────────────┘ └───────────────────┘ +``` + +**Flujos de sincronización:** +- `PRODUCT_PUSH` — Productos Dolibarr → PrestaShop (incremental por fecha) +- `STOCK_PUSH` — Stock Dolibarr → PrestaShop +- `ORDER_PULL` — Pedidos PrestaShop → Dolibarr (como comandas y facturas) + +--- + +## Módulos + +| Directorio | Descripción | +|---|---| +| `sync-service/` | Backend Spring Boot. API REST + jobs de sincronización | +| `javafx-client/` | Cliente escritorio JavaFX 21 | +| `android-app/` | Cliente Android (Kotlin) | + +--- + +## Requisitos previos + +- **JDK 21** — [Adoptium Temurin 21](https://adoptium.net/) +- **Maven 3.8+** — [maven.apache.org](https://maven.apache.org/download.cgi) +- **Android Studio** (solo para la app Android) + +--- + +## sync-service — Arrancar en local (perfil dev) + +### 1. Crear `application-dev.yml` + +```bash +cp sync-service/src/main/resources/application-dev.yml.example \ + sync-service/src/main/resources/application-dev.yml +``` + +Edita el fichero y rellena las claves reales: + +```yaml +integration: + dolibarr: + api-key: TU_DOLIBARR_API_KEY + prestashop: + api-key: TU_PRESTASHOP_API_KEY +``` + +> `application-dev.yml` está en `.gitignore` — nunca se sube al repositorio. + +### 2. Arrancar + +```bash +cd sync-service +./mvnw spring-boot:run -Dspring-boot.run.profiles=dev +``` + +El servidor arranca en `http://localhost:8080`. +Consola H2 disponible en `http://localhost:8080/h2-console`. + +### 3. Autenticación + +Todas las peticiones requieren **Basic Auth**: +- Usuario: `admin` +- Contraseña: `admin123` (configurable en `api.security.password`) + +--- + +## sync-service — API REST + +### Sincronización manual + +| Método | Endpoint | Descripción | +|---|---|---| +| `POST` | `/api/sync/products` | Empuja productos Dolibarr → PrestaShop | +| `POST` | `/api/sync/stock` | Empuja stock Dolibarr → PrestaShop | +| `POST` | `/api/sync/orders` | Importa pedidos PrestaShop → Dolibarr | +| `GET` | `/api/sync/diagnostics/dolibarr` | Verifica conectividad con Dolibarr | + +### Mappings + +| Método | Endpoint | Descripción | +|---|---|---| +| `GET` | `/api/mappings/products` | Lista mapeos de productos | +| `GET` | `/api/mappings/products?status=SYNCED` | Filtra por estado (`SYNCED`/`PENDING`/`ERROR`) | +| `GET` | `/api/mappings/orders` | Lista mapeos de pedidos | + +### Logs + +| Método | Endpoint | Descripción | +|---|---|---| +| `GET` | `/api/logs` | Lista todos los logs de sincronización | +| `GET` | `/api/logs?type=PRODUCT_PUSH` | Filtra por tipo | +| `GET` | `/api/logs/{id}` | Detalle de un log concreto | + +### Health + +| Método | Endpoint | +|---|---| +| `GET` | `/actuator/health` | + +### Swagger UI + +``` +http://localhost:8080/swagger-ui.html +``` + +--- + +## sync-service — Despliegue en Railway + +URL pública: `https://proyectointermodular-production-a9c3.up.railway.app` + +Swagger UI: `https://proyectointermodular-production-a9c3.up.railway.app/swagger-ui.html` + +**Variables de entorno requeridas en el servicio Railway:** + +``` +SPRING_PROFILES_ACTIVE=prod +SPRING_DATASOURCE_URL=jdbc:mysql://mysql.railway.internal:3306/railway?useSSL=false&serverTimezone=UTC&characterEncoding=UTF-8&allowPublicKeyRetrieval=true +SPRING_DATASOURCE_USERNAME=root +SPRING_DATASOURCE_PASSWORD= +SPRING_JPA_DATABASE_PLATFORM=org.hibernate.dialect.MySQLDialect +SPRING_JPA_HIBERNATE_DDL_AUTO=validate +SYNC_SCHEDULING_ENABLED=true +DOLIBARR_API_KEY= +PRESTASHOP_API_KEY= +API_SECURITY_PASSWORD={noop}admin123 +``` + +Flyway ejecuta `V1__init.sql` en el primer arranque y crea las tablas automáticamente. + +--- + +## javafx-client — Arrancar + +### Requisitos + +- JDK 21 +- Maven 3.8+ (JavaFX se descarga automáticamente de Maven Central) + +### Ejecutar + +```bash +cd javafx-client +mvn javafx:run +``` + +La primera ejecución descarga dependencias (~1-2 min). Las siguientes arrancan directamente. + +### Configuración + +La URL del servidor, usuario y contraseña se guardan automáticamente al hacer login y se pueden cambiar desde la pestaña **Ajustes** de la aplicación. Por defecto apunta al servidor Railway. + +--- + +## android-app — Arrancar + +Abrir el directorio `android-app/` con Android Studio y ejecutar en emulador o dispositivo físico. + +--- + +## Stack tecnológico + +| Componente | Tecnología | +|---|---| +| Backend | Java 21 · Spring Boot 3 · Maven | +| Persistencia | Spring Data JPA · H2 (dev) · MySQL (prod) | +| Migraciones | Flyway | +| Cliente HTTP | `RestClient` (Spring 6) | +| Serialización | Jackson | +| Seguridad | Spring Security · Basic Auth · `DelegatingPasswordEncoder` | +| Scheduling | `@Scheduled` · `ThreadPoolTaskScheduler(poolSize=1)` | +| Docs API | SpringDoc OpenAPI (Swagger UI) | +| Cliente escritorio | JavaFX 21 | +| Cliente móvil | Kotlin · Android | +| Despliegue | Railway · GitHub Actions (push automático) | + +--- + +## Sistemas externos + +| Sistema | URL base | +|---|---| +| Dolibarr API | `https://prestashop.loading.net/dolibarr/api/index.php` | +| PrestaShop WS | `https://prestashop.loading.net/tienda/api` | + +> **Nota PrestaShop 8.2.5:** el endpoint raíz `/api/` devuelve 500. Usar siempre recursos específicos (`/api/products`, `/api/orders`, etc.). La clave WS se pasa como query param `ws_key` — el hosting elimina el header `Authorization`.