Beispielarbeiten · Texte & Doku

Technische Dokumentation: Installation und API aus dem Code

Installationsanleitung und API-Referenz, erzeugt aus Code und Schnittstellenbeschreibung. Jedes Beispiel in der Doku wurde ausgeführt, und eine Lücke im Code wurde gemeldet statt überspielt.

Musterarbeit (Demo), kein Kundenauftrag. Gebaut als Probeaufgabe mit erfundenen Beispieldaten; die Prüfzahlen unten stammen aus dem automatischen Prüflauf und sind nicht geschönt.

Was gebaut wurde

Jede öffentliche Funktion und jede Route beschrieben
Codebeispiele, die als Test laufen
Fehlende Beschreibungen im Code werden genannt, nicht erfunden

technische-doku-projekt.zip herunterladen

Wie geprüft wurde

Automatischer Prüflauf vom 18.10.2026, aus dem Protokoll (Testdaten erfunden, Zahlen gemessen):

Aus Code/Docstrings/OpenAPI erzeugt: INSTALLATION.md + API.md
5/5 oeffentliche Funktionen und 5/5 Routen dokumentiert, Luecke korrekt gemeldet (lagerverwaltung.kern.protokoll_als_text)
4 pycon-Beispiele per doctest (0 Fehler), 5/5 Python-HTTP-Beispiele laufen

Grenzen

Was diese Probe nicht abdeckt, steht hier, damit niemand mehr erwartet:

Beschreibungen stammen aus Docstrings/OpenAPI des Codes - was dort fehlt, wird als Luecke markiert, nicht erfunden; fachliche Erklaerungen (Architektur, Betrieb, Warum) muss jemand ergaenzen
Python-Projekte (AST, Google-Docstrings) und FastAPI/OpenAPI; andere Sprachen nur ueber eine OpenAPI-Datei
Installationsanleitung lokal unter Windows ausgefuehrt (Server-Start + Schnelltest); Linux/macOS-Befehle nicht auf einem echten System geprueft; pip install selbst nicht neu ausgefuehrt (Pakete …
Ausgabe Markdown; Sphinx/MkDocs-Webseite waere ein weiterer Schritt

INSTALLATION.md

# lagerverwaltung 0.3.1 - Installation

Kleine Lagerverwaltung mit Python-API und REST-Schnittstelle

## Voraussetzungen

- Python >=3.10
- Abhaengigkeiten (werden bei der Installation mitinstalliert):
- `fastapi>=0.110`
- `uvicorn>=0.29`

## Installation

Windows (PowerShell):

```powershell
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .
```

Linux/macOS:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

Fuer die Tests zusaetzlich: `pip install -e ".[test]"` (pytest>=8 httpx>=0.27).

## Schnelltest

```bash
python -c "import lagerverwaltung; print(lagerverwaltung.__version__)"
```

Erwartete Ausgabe: `0.3.1`

## Server starten

```bash
uvicorn lagerverwaltung.api:app --host 127.0.0.1 --port 8000
```

Danach: interaktive Doku unter http://127.0.0.1:8000/docs, Maschinenbeschreibung unter
http://127.0.0.1:8000/openapi.json. Beschreibung aller Funktionen und Routen: [API.md](API.md).

API.md

# lagerverwaltung 0.3.1 - API-Referenz

## Python-API

### `artikel_anlegen(nummer: str, name: str, preis: float, meldebestand: int = 0) -> Artikel`

Modul: `lagerverwaltung.kern`

Legt einen Artikel mit Bestand 0 an. 

| Parameter | Beschreibung |
|---|---|
| `nummer` | Artikelnummer, nicht leer. |
| `name` | Bezeichnung. |
| `preis` | Einkaufspreis netto in EUR, nicht negativ. |
| `meldebestand` | Ab diesem Bestand oder darunter wird nachbestellt. |

**Rueckgabe:** Der neue Artikel.

**Fehler:** ValueError: bei leerer Nummer oder negativem Preis.

```pycon
>>> from lagerverwaltung.kern import *
>>> a = artikel_anlegen("A-1", "Schraube M4", 0.12, meldebestand=100)
>>> a.bestand, a.meldebestand
(0, 100)
```

### `bestand_buchen(artikel: Artikel, menge: int, grund: str = '') -> int`

Modul: `lagerverwaltung.kern`

Bucht einen Zugang (positive Menge) oder Abgang (negative Menge). 

| Parameter | Beschreibung |
|---|---|
| `artikel` | Der Artikel. |
| `menge` | Zugang positiv, Abgang negativ, nicht 0. |
| `grund` | Freitext fuer das Buchungsprotokoll. |

**Rueckgabe:** Der neue Bestand.

**Fehler:** ValueError: wenn der Bestand negativ wuerde oder die Menge 0 ist.

```pycon
>>> from lagerverwaltung.kern import *
>>> a = artikel_anlegen("A-1", "Schraube M4", 0.12)
>>> bestand_buchen(a, 500, "Lieferung")
500
>>> bestand_buchen(a, -120, "Auftrag 17")
380
```

### `nachbestellen(artikel_liste: list[Artikel]) -> list[str]`

Modul: `lagerverwaltung.kern`

Artikelnummern, deren Bestand den Meldebestand erreicht oder unterschritten hat. 

| Parameter | Beschreibung |
|---|---|
| `artikel_liste` | Alle Artikel. |

**Rueckgabe:** Sortierte Artikelnummern.

```pycon
>>> from lagerverwaltung.kern import *
>>> a = artikel_anlegen("A-1", "Schraube", 0.1, meldebestand=10)
>>> b = artikel_anlegen("B-2", "Mutter", 0.05, meldebestand=0)
>>> nachbestellen([b, a])
['A-1', 'B-2']
```

### `lagerwert(artikel_liste: list[Artikel]) -> float`

Modul: `lagerverwaltung.kern`

Summe Bestand x Preis, auf Cent gerundet. 

| Parameter | Beschreibung |
|---|---|
| `artikel_liste` | Alle Artikel. |

**Rueckgabe:** Lagerwert in EUR.

```pycon
>>> from lagerverwaltung.kern import *
>>> a = artikel_anlegen("A-1", "Schraube", 0.12)
>>> _ = bestand_buchen(a, 250)
>>> lagerwert([a])
30.0
```

### `protokoll_als_text(artikel: Artikel) -> str`

Modul: `lagerverwaltung.kern`

> **Luecke:** Im Code ist keine Beschreibung vorhanden. Bitte ergaenzen.

## HTTP-API

Artikel anlegen, Bestand buchen, Nachbestellliste und Lagerwert abfragen.

Basisadresse: `http://127.0.0.1:8000`

### GET /artikel

**Alle Artikel** - Alle Artikel, nach Nummer sortiert.

Antworten: `200` Successful Response

```bash
curl -X GET http://127.0.0.1:8000/artikel
```

```python
from fastapi.testclient import TestClient
from lagerverwaltung.api import app

client = TestClient(app)
antwort = client.get('/artikel')
assert antwort.status_code == 200, antwort.text
print(antwort.json())
```

### POST /artikel

**Artikel anlegen** - Legt einen Artikel mit Bestand 0 an.

Anfrage (JSON):

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `nummer` | string | ja | Artikelnummer |
| `name` | string | ja | Bezeichnung |
| `preis` | number | ja | Einkaufspreis netto in EUR |
| `meldebestand` | integer | nein | Nachbestellgrenze |

Antworten: `201` Successful Response, `409` Artikelnummer gibt es schon, `422` Validation Error

```bash
curl -X POST http://127.0.0.1:8000/artikel -H "Content-Type: application/json" -d '{"nummer": "A-1", "name": "Schraube M4", "preis": 0.12, "meldebestand": 100}'
```

```python
from fastapi.testclient import TestClient
from lagerverwaltung.api import app

client = TestClient(app)
antwort = client.post('/artikel', json={'nummer': 'A-1', 'name': 'Schraube M4', 'preis': 0.12, 'meldebestand': 100})
assert antwort.status_code == 201, antwort.text
assert set(['nummer', 'name', 'preis', 'bestand', 'meldebestand']) <= set(antwort.json()), antwort.json()
print(antwort.json())
```

### GET /artikel/{nummer}

**Einen Artikel lesen** - Ein Artikel mit aktuellem Bestand.

| Parameter | Ort | Typ | Pflicht |
|---|---|---|---|
| `nummer` | path | string | ja |

Antworten: `200` Successful Response, `404` unbekannte Artikelnummer, `422` Validation Error

```bash
curl -X GET http://127.0.0.1:8000/artikel/A-1
```

```python
from fastapi.testclient import TestClient
from lagerverwaltung.api import app

client = TestClient(app)
client.post('/artikel', json={'nummer': 'A-1', 'name': 'Schraube M4', 'preis': 0.12, 'meldebestand': 100})  # Voraussetzung: Artikel existiert
antwort = client.get('/artikel/A-1')
assert antwort.status_code == 200, antwort.text
assert set(['nummer', 'name', 'preis', 'bestand', 'meldebestand']) <= set(antwort.json()), antwort.json()
print(antwort.json())
```

### POST /artikel/{nummer}/buchung

**Bestand buchen** - Bucht Zugang oder Abgang; der Bestand darf nicht negativ werden.

| Parameter | Ort | Typ | Pflicht |
|---|---|---|---|
| `nummer` | path | string | ja |

Anfrage (JSON):

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `menge` | integer | ja | Zugang positiv, Abgang negativ |
| `grund` | string | nein | Grund fuer das Protokoll |

Antworten: `200` Successful Response, `404` unbekannte Artikelnummer, `422` Bestand wuerde negativ

```bash
curl -X POST http://127.0.0.1:8000/artikel/A-1/buchung -H "Content-Type: application/json" -d '{"menge": 500, "grund": "Lieferung"}'
```

```python
from fastapi.testclient import TestClient
from lagerverwaltung.api import app

client = TestClient(app)
client.post('/artikel', json={'nummer': 'A-1', 'name': 'Schraube M4', 'preis': 0.12, 'meldebestand': 100})  # Voraussetzung: Artikel existiert
antwort = client.post('/artikel/A-1/buchung', json={'menge': 500, 'grund': 'Lieferung'})
assert antwort.status_code == 200, antwort.text
assert set(['nummer', 'name', 'preis', 'bestand', 'meldebestand']) <= set(antwort.json()), antwort.json()
print(antwort.json())
```

### GET /auswertung

**Lagerwert und Nachbestellliste** - Lagerwert in EUR und Artikelnummern zum Nachbestellen.

Antworten: `200` Successful Response

```bash
curl -X GET http://127.0.0.1:8000/auswertung
```

```python
from fastapi.testclient import TestClient
from lagerverwaltung.api import app

client = TestClient(app)
antwort = client.get('/auswertung')
assert antwort.status_code == 200, antwort.text
print(antwort.json())
```

## Luecken

- `lagerverwaltung.kern.protokoll_als_text`: keine Beschreibung im Code

So etwas für deinen Betrieb?

Beschreib kurz, was du brauchst. Du bekommst einen Festpreis, bevor ich anfange; ohne dein Ja passiert nichts.

Zur Werkstatt