sim-autostore/USER_MANUAL.md

RS-SIM-AS User Manual

Überblick

RS-SIM-AS ist eine REST-API zur Simulation der AutoStore-Schnittstelle für die Lagerung und den Abruf von Behältern (BINs). Die API simuliert das Verhalten eines AutoStore-Systems und ermöglicht es Warehouse Management Systemen (WMS), Aufgaben zur Behälterhandhabung zu erstellen und deren Ausführung zu verfolgen.

Hauptfunktionen

1. Behälter-Management (BINs)

• Erstellen: Neue Behälter in das System einführen
• Abfragen: Informationen über bestehende Behälter abrufen
• Löschen: Behälter aus dem System entfernen
• Massenerstellung: Mehrere Behälter mit einem einzigen Befehl erstellen

2. Port-Management

• Erstellen: Neue Ein-/Ausgangspunkte (Ports) definieren
• Statusverfolgung: Port-Status (FREE/OCCUPIED) überwachen
• Behälter-Ankunft/Abfahrt: Behälterbewegungen an Ports simulieren

3. Aufgaben-Management (Tasks)

• Aufgabengruppen erstellen: Zusammengehörige Aufgaben definieren
• Aufgabenstatus verfolgen: Fortschritt einzelner Aufgaben überwachen
• XML-basierte Kommunikation: Spezifikationskonform über HTTP POST

4. Hintergrund-Simulationslogik (NEU)

Die API verfügt über eine integrierte Hintergrund-Simulationslogik, die automatisch die Ausführung von Aufgaben simuliert:

• Automatische Verarbeitung: Aufgaben mit Status "queued" werden automatisch verarbeitet
• Statusaktualisierung: Tasks werden von "queued" auf "completed" gesetzt
• Gruppenabschluss: TaskGroups werden als "completed" markiert, wenn alle zugehörigen Tasks abgeschlossen sind
• Kontinuierlicher Betrieb: Die Simulation läuft alle 5 Sekunden im Hintergrund
• Fehlerbehandlung: Robuste Behandlung von Fehlern während der Simulation

Funktionsweise der Simulationslogik:

1. Alle 5 Sekunden überprüft das System die Datenbank nach Aufgaben mit Status "queued"
2. Gefundene Aufgaben werden sofort als "completed" markiert (in der Realität würde hier eine Zeitverzögerung die tatsächliche Roboterarbeit simulieren)
3. Nach Abschluss aller Aufgaben einer Gruppe wird auch die Gruppenstatus auf "completed" gesetzt
4. Die Simulation läuft automatisch beim Start der Anwendung und stoppt beim Herunterfahren

API-Endpunkte

REST-Endpunkte (JSON)

• GET / - Health Check
• POST /bins/ - Behälter erstellen
• GET /bins/ - Alle Behälter auflisten
• GET /bins/{bin_id} - Einzelnen Behälter abrufen
• DELETE /bins/{bin_id} - Behälter löschen
• POST /bins/generate - Mehrere Behälter erstellen
• POST /ports/ - Port erstellen
• GET /ports/ - Alle Ports auflisten
• GET /ports/{port_id} - Einzelnen Port abrufen
• POST /ports/{port_id}/arrive - Behälter-Ankunft am Port
• POST /ports/{port_id}/depart - Behälter-Abfahrt vom Port

XML-Endpunkt (Spezifikationskonform)

• POST /api - XML-basierte Befehle
  • CreateTaskgroup - Neue Aufgabengruppe erstellen
  • GetTaskInfo - Aufgaben- oder Gruppeninformationen abrufen
  • GetBinInfo - Detaillierte Informationen über einen Behälter abrufen (NEU)

GetBinInfo-Befehl (NEU)

Der GetBinInfo-Befehl ermöglicht das Abrufen detaillierter Informationen über einen bestimmten Behälter.

Anfrage-Format:

<AutoStore>
    <GetBinInfo>
        <Bin>BIN-12345</Bin>
    </GetBinInfo>
</AutoStore>

Antwort-Format (Erfolg):

<AutoStore>
    <GetBinInfo>
        <Bin>BIN-12345</Bin>
        <ContentCode>5</ContentCode>
    </GetBinInfo>
</AutoStore>

Antwort-Format (Fehler):

<AutoStore>
    <Error>
        <Description>Bin not found: BIN-99999</Description>
    </Error>
</AutoStore>

Validierungen:

• Bin-ID ist erforderlich
• Behälter muss in der Datenbank existieren
• Gibt HTTP 400 bei fehlender Bin-ID zurück
• Gibt HTTP 404 bei nicht gefundenem Behälter zurück

Installation und Start

1. Abhängigkeiten installieren:

   pip install -r requirements.txt
   

2. Anwendung starten:

   uvicorn src.main:app --reload
   

3. Zugriff: Die API ist unter http://localhost:8000 verfügbar

Testumgebung

Das Projekt enthält umfassende Tests:

• Unit-Tests: Testen einzelner Funktionen und API-Endpunkte
• Integrationstests: Testen des Zusammenspiels verschiedener Komponenten
• Simulationstests: Spezielle Tests für die Hintergrund-Simulationslogik

# Alle Tests ausführen
pytest

# Nur Simulationstests ausführen
pytest tests/test_simulation.py

Entwicklung

Projekt-Struktur

src/
├── main.py          # FastAPI-Anwendung und Endpunkte
├── models.py        # SQLAlchemy-Datenmodelle
├── schemas.py       # Pydantic-Schemas für Datenvalidierung
├── crud.py          # Datenbankoperationen
├── database.py      # Datenbankverbindung
└── simulation.py    # Hintergrund-Simulationslogik (NEU)

tests/
├── conftest.py      # Test-Konfiguration und Fixtures
├── test_main.py     # API-Endpunkt-Tests
└── test_simulation.py # Simulationslogik-Tests (NEU)

Datenbank

Die Anwendung verwendet SQLite für Entwicklung und Tests. Für Produktion kann PostgreSQL konfiguriert werden.

Changelog

Version 0.3.0 (Aktuell)

• ✅ GetBinInfo XML-Befehl implementiert
  • Detaillierte Behälterinformationen über XML-API abrufbar
  • Vollständige Fehlerbehandlung für nicht existierende Behälter
  • Validierung für fehlende Bin-IDs
  • Umfassende Tests für alle Szenarien
• ✅ Verbesserte XML-Fehlerbehandlung
• ✅ Erweiterte API-Dokumentation

Version 0.2.0

• ✅ Hintergrund-Simulationslogik implementiert
  • Automatische Verarbeitung von Aufgaben im Hintergrund
  • Statusaktualisierung von Tasks und TaskGroups
  • Kontinuierlicher 5-Sekunden-Zyklus
  • Umfassende Tests für die Simulationslogik
• ✅ Einheitliche Status-Verwaltung ("queued" → "completed")
• ✅ Verbesserte Fehlerbehandlung
• ✅ Erweiterte Testabdeckung

Version 0.1.0

• ✅ Grundlegende API-Struktur
• ✅ Behälter- und Port-Management
• ✅ XML-basierte Aufgabenerstellung
• ✅ Datenbankintegration mit SQLAlchemy