mindnet/docs/03_Technical_References/PROD_DEPLOYMENT_CHECKLIST.md

# Deployment-Checkliste: Prod vs. Dev Retrieval-Problem

**Datum**: 2026-01-12  
**Version**: v4.5.10  
**Status**: 🔴 Kritisch

## Problem

Prod-System findet keine Suchergebnisse, während Dev-System korrekt funktioniert. Identischer Code, identische Daten.

## Identifizierte Ursachen

### 1. 🔴 **KRITISCH: Alte EdgeDTO-Version in Prod**

**Symptom**:
```
ERROR: 1 validation error for EdgeDTO
provenance
  Input should be 'explicit', 'rule', 'smart' or 'structure' 
  [type=literal_error, input_value='explicit:callout', input_type=str]
```

**Ursache**: 
- Prod verwendet eine **alte Version** des `EdgeDTO`-Modells aus `app/models/dto.py`
- Die alte Version unterstützt nur: `"explicit", "rule", "smart", "structure"`
- Die neue Version (v4.5.3+) unterstützt: `"explicit:callout", "explicit:wikilink", "explicit:note_zone", ...`

**Lösung**: 
- ✅ Code in `dto.py` ist bereits korrekt (Zeile 51-56)
- ⚠️ **Prod muss neu gestartet werden**, um die neue Version zu laden
- ⚠️ **Python-Modul-Cache leeren** falls nötig: `find . -type d -name __pycache__ -exec rm -r {} +`

### 2. ✅ Collection-Präfix korrekt

- Prod: `COLLECTION_PREFIX=mindnet` → `mindnet_chunks` ✅
- Dev: `COLLECTION_PREFIX=mindnet_dev` → `mindnet_dev_chunks` ✅
- **Kein Problem hier**

## Sofortmaßnahmen

### Schritt 1: Code-Verifikation in Prod

```bash
# In Prod-System
cd /path/to/mindnet
grep -A 10 "provenance.*Literal" app/models/dto.py
```

**Erwartete Ausgabe**:
```python
provenance: Optional[Literal[
    "explicit", "rule", "smart", "structure",
    "explicit:callout", "explicit:wikilink", "explicit:note_zone", ...
]] = "explicit"
```

**Falls nicht vorhanden**: Code ist nicht aktualisiert → Deployment erforderlich

### Schritt 2: Python-Cache leeren

```bash
# In Prod-System
find . -type d -name __pycache__ -exec rm -r {} +
find . -name "*.pyc" -delete
```

### Schritt 3: Service neu starten

```bash
# FastAPI/uvicorn neu starten
# Oder Docker-Container neu starten
```

### Schritt 4: Verifikation

1. **Test-Query ausführen**:
   ```bash
   curl -X POST http://localhost:8001/api/chat \
     -H "Content-Type: application/json" \
     -d '{"message": "Was für einen Status hat das Projekt mindnet?"}'
   ```

2. **Log prüfen**:
   - ✅ Keine `validation error for EdgeDTO` mehr
   - ✅ `✨ [SUCCESS] Stream 'facts_stream' lieferte X Treffer.`
   - ✅ Ergebnisse werden zurückgegeben

## Code-Vergleich

### Aktuelle Version (sollte in Prod sein):

```python
# app/models/dto.py (Zeile 51-56)
provenance: Optional[Literal[
    "explicit", "rule", "smart", "structure",
    "explicit:callout", "explicit:wikilink", "explicit:note_zone", "explicit:note_scope",
    "inline:rel", "callout:edge", "semantic_ai", "structure:belongs_to", "structure:order",
    "derived:backlink", "edge_defaults", "global_pool"
]] = "explicit"
```

### Alte Version (verursacht Fehler):

```python
# Alte Version (nur 4 Werte)
provenance: Optional[Literal[
    "explicit", "rule", "smart", "structure"
]] = "explicit"
```

## Weitere mögliche Ursachen (wenn Fix nicht hilft)

### 1. Unterschiedliche Python-Versionen
- Prüfen: `python --version` in Dev vs. Prod
- Pydantic-Verhalten kann zwischen Versionen variieren

### 2. Unterschiedliche Pydantic-Versionen
- Prüfen: `pip list | grep pydantic` in Dev vs. Prod
- `requirements.txt` sollte identisch sein

### 3. Unterschiedliche Embedding-Modelle
- Prüfen: `MINDNET_EMBEDDING_MODEL` in beiden Systemen
- **Beide verwenden**: `nomic-embed-text` ✅

### 4. Unterschiedliche Vektor-Dimensionen
- Prüfen: `VECTOR_DIM` in beiden Systemen
- **Beide verwenden**: `768` ✅

## Erwartetes Ergebnis nach Fix

- ✅ Keine Pydantic-Validierungsfehler mehr
- ✅ Alle Streams liefern Ergebnisse
- ✅ Retrieval funktioniert identisch in Dev und Prod
- ✅ `explicit:callout` Provenance wird korrekt akzeptiert