votianlt/MQTT_README.md

VOTIANLT MQTT Messaging API

This document describes how mobile/Flutter apps should communicate with the backend using MQTT. It replaces the previous STOMP/WebSocket communication.

⚠️ WICHTIG: Neue Konfiguration (Stand: 2025-10-22)

Broker: mqtt-2.assecutor.de:42099 (MQTT v5) Port: 42099 (geändert von 1883!) QoS: 2 (exactly once) Retain: Enabled for critical topics (see below), otherwise not retained Payloads: JSON (UTF‑8)

Connection Parameters

• MQTT clientId: choose a stable, unique per-device id (e.g., app-)
• Clean session: false (recommended for guaranteed delivery). The broker will queue QoS>0 messages while the app is offline.
• Authentication: REQUIRED (neu!)
  • Username: app
  • Password: apppwd
• Keep-Alive: 60 seconds
• Connection Timeout: 60 seconds

Migration Notice

📖 Für die Migration auf das neue System siehe:

• MQTT_MIGRATION_GUIDE.md - Detaillierte Migrationsanleitung
• MQTT_QUICK_REFERENCE.md - Schnellreferenz mit Code-Beispielen
• CHANGELOG_MQTT.md - Vollständige Liste aller Änderungen

Topic Naming (v1/*)

• v1/app//auth/login (App -> Server)
• v1/users//notifications (Server -> App)
• v1/broadcasts (Server -> App)
• v1/app//jobs/assigned (App -> Server request)
• v1/app//job/status (App -> Server)
• v1/app//device/location (App -> Server)
• v1/tasks/ (Server -> App events for a single task)
• v1/task-updates (Server -> App general task events) [optional]

General pattern

• Requests from apps go under v1/app//...
• Server responses and events are published to either a user‑ or task‑scoped topic as listed above.

1. Authentication (App -> Server) Topic: v1/app//auth/login Payload request: { "email": "user@example.com", "password": "secret" }

Response (Server -> App) Topic: v1/users//notifications Payload: { "type": "auth", "success": true, "message": "Anmeldung erfolgreich", "appUserId": "" }

2. Job status update (App -> Server) Topic: v1/app//job/status Payload request (example): { "jobId": "", "status": "ON_ROUTE", "note": "...", "timestamp": "2025-09-13T22:00:00" }

Server may publish derived updates to:

• v1/broadcasts (if global) or
• v1/users//notifications (if per user)

3. Device location (App -> Server) Topic: v1/app//device/location Payload: { "lat": 48.12345, "lon": 11.54321, "accuracy": 5.4, "timestamp": "2025-09-13T22:00:00" }

4. Assigned jobs request (App -> Server) Topic: v1/app//jobs/assigned Payload request: { "appUserId": "" }

Response (Server -> App) Topic: v1/users//notifications Payload: { "type": "jobs", "jobs": [ { /* JobWithRelatedDataDTO */ } ] }

5. Task completion events (Server -> App)

• When a task is completed (CONFIRMATION, SIGNATURE, BARCODE, TODOLIST, PHOTO), the server publishes an event to the task‑scoped topic. Topic: v1/tasks/ Payload: { "event": "taskCompleted", "taskId": "", "jobId": "", "taskType": "PHOTO|CONFIRMATION|...", "completed": true, "completedAt": "2025-09-13T22:05:00", "completedBy": "driver01", "note": "optional" }

6. Photo uploads (MQTT)

• Apps send photos as base64 strings within the MQTT payload when reporting PHOTO task completion.

Topic (App -> Server): v1/app//task/photo/completed Payload: { "taskId": "", "completedBy": "driver01", "note": "optional", "extraData": { "photos": ["", ""], "count": 2 } }

Server behavior:

• Saves the photos in the photos collection, marks the task as completed, and publishes an event: Topic (Server -> App): v1/tasks/ Payload: { "event": "taskCompleted", "taskId": "", "jobId": "", "taskType": "PHOTO", "completed": true, "completedAt": "...", "completedBy": "driver01", "note": "optional" }

7. Broadcasts and notifications (Server -> App)

• Broadcasts: v1/broadcasts
• User notifications: v1/users//notifications Payload example: { "type": "broadcast|notification", "message": "...", "timestamp": "2025-09-13T22:10:00" }

Chat Messaging (App ↔ Server)

Mobile apps exchange chat messages with the backend through dedicated topics. JSON samples can be found under src/main/resources/mqtt/chat.

App → Server

• Topic: /server/{clientId}/message
• Payload example: src/main/resources/mqtt/chat/incoming-chat-message.json
• Required fields: sender, receiver, content
• Optional fields: jobId (Mongo ObjectId), jobNumber
• Payloads missing required fields or containing invalid jobId values are rejected with a warning log.

Server → App

• Topic: /client/{receiver}/message
• Payload example: src/main/resources/mqtt/chat/outgoing-chat-message.json
• Notes: direction (INCOMING/OUTGOING) and messageType (GENERAL/JOB_RELATED) mirror the persisted message entity. read remains false until the receiver acknowledges the message via the REST API.

Quality of Service

• Chat topics inherit the global default QoS 2 (app.mqtt.default-qos).
• Messages are not retained; offline clients rely on QoS queueing on the broker.

Quality of Service & Retain

• QoS 2 (exactly once) is used by default server side for both inbound subscriptions and outbound publications.
• Retained messages are disabled by default to avoid stale updates.

Error Handling

• Server logs errors; apps should implement local retries for transient failures.
• For request/response patterns over MQTT, include correlationId in payloads if you need strict pairing.

Security

• If authentication is required at broker level, configure username/password.
• Consider using TLS if the broker supports it.

Migration notes

• Previous STOMP destinations like /topic/tasks/{taskId} are now MQTT topics v1/tasks/.
• Photos for PHOTO tasks must be embedded in the MQTT message (extraData.photos) published to v1/app//task/photo/completed. The old HTTP endpoints have been removed.