# Falukant: Überfälle auf Transporte und Transportwachen

Dieses Dokument beschreibt das Zielmodell für einen neuen Untergrundtyp **Überfälle auf Transporte** sowie das ergänzende Schutzsystem **Transportwachen**.

Ziel:

- Untergrundspieler können bewaffnete Banden anheuern
- Banden lauern in geeigneten Regionen und überfallen dort zufällige Transporte
- Beute wird nicht vollständig, sondern nur teilweise erlangt
- Beute landet im nächstgelegenen Lager des Auftraggebers
- Opfer und Auftraggeber spüren wirtschaftliche und soziale Folgen
- Transporte können mit Wachen geschützt werden
- Überfallserfolg hängt später im Daemon an Bandengröße, Wachzahl, Region und Zufall

## 1. Bestandsaufnahme

Bereits vorhanden:

- Untergrundaktivitäten im Backend und UI
- Transportsystem mit Fahrzeugen, Routen, Start- und Zielniederlassung
- Lager-/Bestandssystem in Niederlassungen
- Fahrzeug- und Transportverwaltung in [BranchView.vue](/mnt/share/torsten/Programs/YourPart3/frontend/src/views/falukant/BranchView.vue)
- Untergrundformular in [UndergroundView.vue](/mnt/share/torsten/Programs/YourPart3/frontend/src/views/falukant/UndergroundView.vue)

Noch nicht vorhanden:

- Untergrundtyp `raid_transport`
- Bandengröße / Bandenkosten
- Wachen auf Transporten
- Kampfauflösung zwischen Überfall und Eskorte
- Beutetransfer in Lager
- Overworld-/Socket-Kommunikation für Überfälle

## 2. Kernidee

Ein Untergrundspieler kann eine Bande für einen Transportüberfall anheuern.

Die Bande:

- wird einer Region zugewiesen
- darf nur in Regionen vom Typ `4` oder `5` operieren
- darf nicht in `town` operieren
- lauert dort auf zufällige Transporte

Bei einem Überfall:

- wird nicht der gesamte Transport geraubt
- nur ein Teil der transportierten Ware wird erbeutet
- nur ein Teil kann tatsächlich abtransportiert werden
- die Beute wird in das nächstgelegene Lager des Auftraggebers eingebucht

Der Überfall wirkt:

- auf das Opfer wirtschaftlich und reputativ
- auf den Auftraggeber als Gewinnchance, aber auch als Risiko

## 3. Neuer Untergrundtyp

Neuer Typ:

- `raid_transport`

Geplanter UI-Name:

- `Überfälle auf Transporte`

Grundparameter:

- `type`: `raid_transport`
- `regionId`: Region, in der gelauert wird
- `bandSize`: Stärke der angeheuerten Bande
- optional später:
  - `focus`: eher Waren, eher Fahrzeuge, eher schwache Transporte

## 4. Regionsregeln

Die Aktivität darf nur in Regionen starten, die:

- Regionstyp `4` oder `5` haben
- nicht `town` sind

Begründung:

- Überfälle sollen auf Wegen, Randregionen oder schlecht gesicherten Zonen stattfinden
- nicht direkt im Stadtkern

UI-Regel:

- im Untergrundformular nur zulässige Regionen anbieten

Backend-Regel:

- Region validieren
- unzulässige Region serverseitig ablehnen

## 5. Bandensystem

### 5.1 Bandengröße

Der Spieler wählt eine Bandengröße, z. B.:

- `small`
- `medium`
- `large`

Alternativ numerisch:

- `3`
- `6`
- `10`

Empfehlung für Version 1:

- numerischer Wert `bandSize`
- UI zeigt zusätzlich Stufenbezeichnung

### 5.2 Kosten

Die Kosten steigen überproportional, damit große Überfälle nicht trivial werden.

Beispielmodell:

- Grundkosten: `20`
- pro Bandit: `+12`
- Risikozuschlag: `bandSize * 2`

Beispiel:

- `3` Banditen: `62`
- `6` Banditen: `104`
- `10` Banditen: `160`

Die finalen Werte sind Balancing und können später angepasst werden.

## 6. Transportwachen

### 6.1 Grundidee

Für Transporte sollen Wachen mitgeschickt werden können.

Wirkung:

- geringere Überfallchance
- höhere Abwehrchance
- geringere Beute bei erfolgreichem Überfall

### 6.2 UI-Verhalten

Beim Erstellen eines Transports:

- zusätzliches Feld `wachen`
- nur positive ganze Zahl
- sichtbare Zusatzkosten

In der Transportübersicht:

- Wachenanzahl anzeigen

### 6.3 Kosten

Wachen verursachen direkte Transportmehrkosten.

Beispiel:

- `guardCount * 4`

Optional später:

- bessere Wachenstufe
- bewaffnete Eskorte

## 7. Überfallauflösung im Daemon

Der externe Daemon bleibt die führende Quelle für die eigentliche Auflösung.

Der Worker prüft periodisch:

1. aktive `raid_transport`-Aktivitäten
2. Transporte, die gerade durch passende Regionen laufen
3. ob eine Kollision zwischen Aktivität und Transport zustande kommt

### 7.1 Kandidatenprüfung

Ein Transport ist überfallbar, wenn:

- er aktiv ist
- seine Route durch die Zielregion der Bande führt oder dort endet
- er dem Auftraggeber nicht selbst gehört

### 7.2 Begegnungschance

Die Basiswahrscheinlichkeit hängt u. a. ab von:

- Bandengröße
- Regionstyp
- Transportfrequenz / Zufall
- ggf. Diskretions- oder Untergrundfaktoren

### 7.3 Kampfwert

Für Version 1 reicht ein abstrahierter Vergleich:

- `raidPower = bandSize + random(0..bandSize)`
- `guardPower = guardCount + random(0..guardCount)`

Modifikatoren:

- bessere Fahrzeuge können leicht entkommen
- große Transporte sind leichter sichtbar

Ergebnis:

- `repelled`
- `partial_success`
- `major_success`

## 8. Beute

Es darf niemals der komplette Transport verloren gehen.

### 8.1 Grundregel

Bei erfolgreichem Überfall:

- nur ein Teil der transportierten Menge wird geraubt
- nur ein Teil dieser Menge erreicht als Beute den Auftraggeber

Empfohlene Formel:

- `baseLootShare = 0.15 bis 0.45`
- bei `major_success` bis `0.60`
- Wachen senken den Wert

Zusätzlich:

- Abrunden auf ganze Mengeneinheiten
- mindestens `1`, wenn überhaupt Erfolg

### 8.2 Einlagerung

Die Beute wird in das nächstgelegene Lager des Auftraggebers eingebucht.

Priorität:

1. nächstgelegene Niederlassung des Auftraggebers
2. nur wenn dort Lager für den Produkttyp vorhanden oder anlegbar
3. falls kein geeignetes Lager existiert:
  - Beute teilweise verfallen lassen
  - Rest als `lost_due_to_storage`

Wichtig:

- nie stillschweigend alles gutschreiben
- Lagerkapazität berücksichtigen

## 9. Folgen

### 9.1 Für das Opfer

- Warenverlust
- optional kleiner Reputationsschaden
- Hinweis in Geld-/Transporthistorie
- evtl. Routenanpassung oder Absicherungsdruck

### 9.2 Für den Auftraggeber

- Kosten der Bande
- möglicher Beutegewinn
- optional leichter Reputations- oder Verdachtsanstieg
- Risiko von Gegenmaßnahmen in späteren Ausbaustufen

## 10. Datenmodell

Für eine erste technische Umsetzung werden voraussichtlich neue Felder benötigt.

### 10.1 Underground-Aktivität

In `underground.result` bzw. Payload:

- `bandSize`
- `attempts`
- `successes`
- `lastTargetTransportId`
- `lastLoot`
- `lastOutcome`

### 10.2 Transport

Neu empfohlen:

- `guardCount`
- optional später `guardQuality`

### 10.3 Transport-/Überfall-Log

Optional, aber sinnvoll:

- eigener Logeintrag oder JSON-Protokoll mit:
  - Opfer
  - Auftraggeber
  - Region
  - Bandengröße
  - Wachen
  - geraubte Mengen
  - eingelagerte Mengen

## 11. Socket-Events

Empfohlene Events für die UI:

### 11.1 Überfall auf Opferseite

```json
{
  "event": "falukantTransportRaid",
  "user_id": 123,
  "reason": "transport_raided"
}
```

### 11.2 Überfall auf Auftraggeberseite

```json
{
  "event": "falukantUndergroundUpdate",
  "user_id": 456,
  "reason": "raid_success"
}
```

Mögliche `reason`:

- `transport_raided`
- `raid_repelled`
- `raid_success`
- `raid_partial_success`
- `raid_loot_stored`

Begleitende Events:

- `falukantUpdateStatus`
- `falukantBranchUpdate`
- optional `falukantUpdateDebt` nicht nötig

## 12. UI-Anforderungen

### 12.1 Underground

In [UndergroundView.vue](/mnt/share/torsten/Programs/YourPart3/frontend/src/views/falukant/UndergroundView.vue):

- neuer Typ `raid_transport`
- Regionsauswahl mit erlaubten Regionstypen
- Wahl der Bandengröße
- Kostenanzeige
- spätere Ergebnisanzeige:
  - Erfolg / Misserfolg
  - Beute
  - Zielregion

### 12.2 Transport

In [BranchView.vue](/mnt/share/torsten/Programs/YourPart3/frontend/src/views/falukant/BranchView.vue):

- Wachenfeld beim Transportstart
- Wachenanzahl in Transportliste
- Hinweis, dass Wachen Überfälle erschweren, aber Kosten erhöhen

## 13. Technische Reihenfolge

### TRA1. Konzept und Typerweiterung

- `raid_transport` als Underground-Typ anlegen
- Produktions-SQL für Bestandsdatenbank

### TRA2. Lokale Projektbasis

- API akzeptiert `bandSize`
- UI unterstützt Bandengröße und erlaubte Regionen
- Transporte erhalten `guardCount`

### TRA3. Daemon-Auflösung

- Worker prüft Kollisionen zwischen Aktivität und aktiven Transporten
- Überfallausgang berechnen
- Beute teilweise einlagern
- Events senden

### TRA4. UI-Feinschliff

- Ergebnisflächen
- Logs
- klarere Rückmeldungen für Opfer und Auftraggeber

## 14. Hinweis für den Daemon

Der Daemon soll später explizit berücksichtigen:

- DB-Änderungen für `guardCount` und den neuen Underground-Typ werden projektseitig vorbereitet
- Überfälle dürfen nie Totalverlust erzeugen
- Lagerkapazität begrenzt reale Beute
- Wachen reduzieren Erfolgsquote und Beutemenge

## 15. Definition of Done

Die erste vollständige Version gilt als fertig, wenn:

1. `raid_transport` im Untergrund auswählbar ist
2. Transporte mit Wachen gestartet werden können
3. der Daemon aktive Überfälle gegen echte Transporte auflösen kann
4. das Opfer nie die komplette Fracht verliert
5. Beute im nächstgelegenen Lager des Auftraggebers landet
6. Opfer- und Auftraggeber-UI per Socket aktualisiert werden