docs: add project README with architecture, setup and API reference
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
luklpz
parent
7eb17a8da2
commit
1193c2d888
|
|
@ -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=<MYSQLPASSWORD del plugin MySQL>
|
||||||
|
SPRING_JPA_DATABASE_PLATFORM=org.hibernate.dialect.MySQLDialect
|
||||||
|
SPRING_JPA_HIBERNATE_DDL_AUTO=validate
|
||||||
|
SYNC_SCHEDULING_ENABLED=true
|
||||||
|
DOLIBARR_API_KEY=<clave API Dolibarr>
|
||||||
|
PRESTASHOP_API_KEY=<clave WS PrestaShop>
|
||||||
|
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`.
|
||||||
Loading…
Reference in New Issue