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