breakpilot-core/.claude/rules/night-scheduler.md

# Night Scheduler - Entwicklerdokumentation

**Status:** Produktiv
**Letzte Aktualisierung:** 2026-02-09
**URL:** https://macmini:3002/infrastructure/night-mode
**API:** http://macmini:8096

---

## Uebersicht

Der Night Scheduler ermoeglicht die automatische Nachtabschaltung der Docker-Services:
- Zeitgesteuerte Abschaltung (Standard: 22:00)
- Zeitgesteuerter Start (Standard: 06:00)
- Manuelle Sofortaktionen (Start/Stop)
- Dashboard-UI zur Konfiguration

---

## Architektur

```
┌─────────────────────────────────────────────────────────────┐
│  Admin Dashboard (Port 3002)                                │
│  /infrastructure/night-mode                                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  API Proxy: /api/admin/night-mode                           │
│  - GET: Status abrufen                                      │
│  - POST: Konfiguration speichern                            │
│  - POST /execute: Sofortaktion (start/stop)                 │
│  - GET /services: Service-Liste                             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  night-scheduler (Port 8096)                                │
│  - Python/FastAPI Container                                 │
│  - Prueft jede Minute ob Aktion faellig                     │
│  - Fuehrt docker compose start/stop aus                     │
│  - Speichert Config in /config/night-mode.json              │
└─────────────────────────────────────────────────────────────┘
```

---

## Dateien

| Pfad | Beschreibung |
|------|--------------|
| `night-scheduler/scheduler.py` | Python Scheduler mit FastAPI |
| `night-scheduler/Dockerfile` | Container mit Docker CLI |
| `night-scheduler/requirements.txt` | Dependencies |
| `night-scheduler/config/night-mode.json` | Konfigurationsdatei |
| `night-scheduler/tests/test_scheduler.py` | Unit Tests |
| `admin-v2/app/api/admin/night-mode/route.ts` | API Proxy |
| `admin-v2/app/api/admin/night-mode/execute/route.ts` | Execute Endpoint |
| `admin-v2/app/api/admin/night-mode/services/route.ts` | Services Endpoint |
| `admin-v2/app/(admin)/infrastructure/night-mode/page.tsx` | UI Seite |

---

## API Endpoints

### GET /api/night-mode
Status und Konfiguration abrufen.

**Response:**
```json
{
  "config": {
    "enabled": true,
    "shutdown_time": "22:00",
    "startup_time": "06:00",
    "last_action": "startup",
    "last_action_time": "2026-02-09T06:00:00",
    "excluded_services": ["night-scheduler", "nginx"]
  },
  "current_time": "14:30:00",
  "next_action": "shutdown",
  "next_action_time": "22:00",
  "time_until_next_action": "7h 30min",
  "services_status": {
    "backend": "running",
    "postgres": "running"
  }
}
```

### POST /api/night-mode
Konfiguration aktualisieren.

**Request:**
```json
{
  "enabled": true,
  "shutdown_time": "23:00",
  "startup_time": "07:00",
  "excluded_services": ["night-scheduler", "nginx", "vault"]
}
```

### POST /api/night-mode/execute
Sofortige Aktion ausfuehren.

**Request:**
```json
{
  "action": "stop"  // oder "start"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Aktion 'stop' erfolgreich ausgefuehrt fuer 25 Services"
}
```

### GET /api/night-mode/services
Liste aller Services abrufen.

**Response:**
```json
{
  "all_services": ["backend", "postgres", "valkey", ...],
  "excluded_services": ["night-scheduler", "nginx"],
  "status": {
    "backend": "running",
    "postgres": "running"
  }
}
```

---

## Konfiguration

### Config-Format (night-mode.json)

```json
{
  "enabled": true,
  "shutdown_time": "22:00",
  "startup_time": "06:00",
  "last_action": "startup",
  "last_action_time": "2026-02-09T06:00:00",
  "excluded_services": ["night-scheduler", "nginx"]
}
```

### Umgebungsvariablen

| Variable | Default | Beschreibung |
|----------|---------|--------------|
| `COMPOSE_PROJECT_NAME` | `breakpilot-pwa` | Docker Compose Projektname |

---

## Ausgeschlossene Services

Diese Services werden NICHT gestoppt:

1. **night-scheduler** - Muss laufen, um Services zu starten
2. **nginx** - Optional, fuer HTTPS-Zugriff

Weitere Services koennen ueber die Konfiguration ausgeschlossen werden.

---

## Docker Compose Integration

```yaml
night-scheduler:
  build: ./night-scheduler
  container_name: breakpilot-pwa-night-scheduler
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - ./night-scheduler/config:/config
    - ./docker-compose.yml:/app/docker-compose.yml:ro
  environment:
    - COMPOSE_PROJECT_NAME=breakpilot-pwa
  ports:
    - "8096:8096"
  networks:
    - breakpilot-pwa-network
  restart: unless-stopped
```

---

## Tests ausfuehren

```bash
# Im Container
docker exec -it breakpilot-pwa-night-scheduler pytest -v

# Lokal (mit Dependencies)
cd night-scheduler
pip install -r requirements.txt
pytest -v tests/
```

---

## Deployment

```bash
# 1. Dateien synchronisieren
rsync -avz night-scheduler/ macmini:.../night-scheduler/

# 2. Container bauen
ssh macmini "docker compose -f .../docker-compose.yml build --no-cache night-scheduler"

# 3. Container starten
ssh macmini "docker compose -f .../docker-compose.yml up -d night-scheduler"

# 4. Testen
curl http://macmini:8096/health
curl http://macmini:8096/api/night-mode
```

---

## Troubleshooting

### Problem: Services werden nicht gestoppt/gestartet

1. Pruefen ob Docker Socket gemountet ist:
   ```bash
   docker exec breakpilot-pwa-night-scheduler ls -la /var/run/docker.sock
   ```

2. Pruefen ob docker compose CLI verfuegbar ist:
   ```bash
   docker exec breakpilot-pwa-night-scheduler docker compose version
   ```

3. Logs pruefen:
   ```bash
   docker logs breakpilot-pwa-night-scheduler
   ```

### Problem: Konfiguration wird nicht gespeichert

1. Pruefen ob /config beschreibbar ist:
   ```bash
   docker exec breakpilot-pwa-night-scheduler touch /config/test
   ```

2. Volume-Mount pruefen in docker-compose.yml

### Problem: API nicht erreichbar

1. Container-Status pruefen:
   ```bash
   docker ps | grep night-scheduler
   ```

2. Health-Check pruefen:
   ```bash
   curl http://localhost:8096/health
   ```

---

## Sicherheitshinweise

- Der Container benoetigt Zugriff auf den Docker Socket
- Nur interne Services koennen gestoppt/gestartet werden
- Keine Authentifizierung (internes Netzwerk)
- Keine sensitiven Daten in der Konfiguration

---

## Dependencies (SBOM)

| Package | Version | Lizenz |
|---------|---------|--------|
| FastAPI | 0.109.0 | MIT |
| Uvicorn | 0.27.0 | BSD-3-Clause |
| Pydantic | 2.5.3 | MIT |
| pytest | 8.0.0 | MIT |
| pytest-asyncio | 0.23.0 | Apache-2.0 |
| httpx | 0.26.0 | BSD-3-Clause |

---

## Aenderungshistorie

| Datum | Aenderung |
|-------|-----------|
| 2026-02-09 | Initiale Implementierung |