feat: add MQTT topic parsing and pipeline config

backend/app/core/config.py

@@ -56,6 +56,17 @@ class Settings(BaseSettings):
     POSTGRES_PASSWORD: str = ""
     POSTGRES_DB: str = ""
 
+    MQTT_HOST: str = "101.35.119.226"
+    MQTT_PORT: int = 1883
+    MQTT_USERNAME: str = ""
+    MQTT_PASSWORD: str = ""
+    MQTT_TOPIC_PATTERN: str = "terminal/+/raw"
+    MQTT_CLIENT_ID: str = "spatialhub-mqtt-ingestor"
+    RAW_HOT_RETENTION_DAYS: int = 90
+    RAW_ARCHIVE_BASE_DIR: str = "/data/archive/gnss"
+    PARSER_BATCH_SIZE: int = 200
+    PARSER_POLL_INTERVAL_MS: int = 300
+
     @computed_field  # type: ignore[prop-decorator]
     @property
     def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn:

backend/app/mqtt/__init__.py

@@ -0,0 +1 @@
+"""MQTT ingestion pipeline package."""

backend/app/mqtt/topic.py

@@ -0,0 +1,10 @@
+import re
+
+TOPIC_PATTERN = re.compile(r"^terminal/(?P<device_id>[^/]+)/raw$")
+
+
+def extract_device_id(topic: str) -> str:
+    match = TOPIC_PATTERN.match(topic)
+    if match is None:
+        raise ValueError("topic must match terminal/{device_id}/raw")
+    return match.group("device_id")

backend/pyproject.toml

@@ -19,6 +19,7 @@ dependencies = [
     "sentry-sdk[fastapi]>=2.0.0,<3.0.0",
     "pyjwt<3.0.0,>=2.8.0",
     "pwdlib[argon2,bcrypt]>=0.3.0",
+    "paho-mqtt<3.0.0,>=2.1.0",
 ]
 
 [dependency-groups]

backend/tests/mqtt/test_topic.py

@@ -0,0 +1,12 @@
+import pytest
+
+from app.mqtt.topic import extract_device_id
+
+
+def test_extract_device_id_success() -> None:
+    assert extract_device_id("terminal/device-001/raw") == "device-001"
+
+
+def test_extract_device_id_rejects_invalid_topic() -> None:
+    with pytest.raises(ValueError, match="terminal/\\{device_id\\}/raw"):
+        extract_device_id("terminal/device-001/nmea")