# Prototyp Rahmenvertrag (Epic PH-1063)

Klickbarer HTML-Prototyp, statisch, ohne Build. Stand: 05.10.2026, ~20:41 (Europe/Berlin). Phase-1-Schnitt + Angebots-Wizard / Schnell-Angebot nach Kevin-Call. Deploy: Cloudflare Pages `rahmenvertrag-prototypes`.

## Entscheidungen Kevin 05.10.2026 (eingearbeitet 11:50 Berlin)
1. **Der Rahmenvertrag hängt am Kunden allein**, nicht an einem Kunden-Partner-Paar. Bindungsschlüssel = Kunde (`frame_contract.customer_id`).
2. **Vertragsparteien sind Kunde und grenke.** Der Partner/Händler ist **Vermittler**, keine Vertragspartei. Steht als Annahme-Banner auf 07 und 11. Track B (01–06, 08–09) ist nicht umgebaut.
3. **Der Menüpunkt heißt „Rahmenverträge“**, nicht „Oberrahmen“: Sidebar für Partner, grenke-Login und Approval. Dateinamen bleiben (`07-oberrahmen-…`). „Oberrahmen/Teilrahmen“ bleibt intern als Begriff für das Datenmodell.
4. **Partner-Sicht 11 (PH-1342):** Einstieg = Kundenliste mit Rest offen je Kunde, Detail je Rahmenvertrag. **„Neues Angebot erstellen“ ist aktiv** (Modal nur Artikel, Kunde/Rahmen vorausgewählt).
5. **Angebots-Wizard (Screen 12, Call ~20:41):** Normaler Wizard ist Hauptweg. Bei passendem Rahmen: Ja/Nein „Dieses Objekt kann aus deinem Rahmenvertrag finanziert werden“. Rechts unter Preiskalkulation grüne RV-Karte (Name + Restbudget), nur bei Ja. Finanzierungsdauer/-art aus dem Rahmen sind locked. Kein separater RV-Angebotsflow.
6. **Rechte:** Partner = lesen + Angebot/Simulation; grenke/Approval = ansehen/bearbeiten/anlegen (klar markiert auf 07/11).
**Alle Daten sind fiktiv.** Spec/Jira unverändert; nur Prototyp + Deploy.

## Phase 1 vs. Phase 2
- **Phase 1 (dieser Sprint):** Datenmodell Oberrahmen → Teilrahmen (je Teilrahmen eine Objektkategorie, Volumen, approvalStatus), manuelle Pflege durch grenke-Login/Approval (Screen 07).
- Dazu die **Partner-Sicht** „Rahmenverträge“ (Screen 11, seit 05.10. 11:45 umgebaut nach Kevin Voice / PH-1342): Einstieg = Kunden mit Rahmen und „Rest offen“ je Kunde; Klick auf einen Kunden zeigt je Rahmenvertrag den Rest offen, Teilrahmen/Objektkategorie nur als zweite Ebene; dazu Anfragen und ihre Zuordnung. ~~Restbudget je Objekttyp als Einstieg~~ (ersetzt).
- **Anfragen laufen automatisch hinein:** Beim Einreichen einer Finanzierungsanfrage wird über Kunde + Objektkategorie (Partner nur als Sichtbarkeitsfilter, F25) der passende freigegebene Teilrahmen gefunden und belastet (reserviert → abgerufen, Rückbuchung bei Ablehnung). Der bestehende Antragsweg und der grenke-Prüfweg bleiben unverändert.
- **Kein Einlesen in Phase 1:** Rahmen werden von Hand gepflegt, keine Upload-/OCR-/Import-Strecke.
- **Wizard im Prototyp (Screen 12):** Ja/Nein-Rahmenfinanzierung, RV-Karte, locked Felder — kein separater Flow.
- **Track B / Spec später:** Abruf ohne neue Prüfung (Spec offen) / F24-Übermittlung, Einlesen & Prüfung (01–06, 08–09), produktiver Import grenke/ITAM.
- Annahmen sind im Prototyp gelb markiert (`Annahme F24`, `F3`, `F21`, `F25`, `N2`) und in `drafts/rahmenvertrag/phase1-annahmen-check-2026-10-05.md` erklärt.

## Demo-Pfad (Kevin Call 05.10. ~20:41)
1. `11` Partner, Menü „Rahmenverträge“: Rechte-Pill lesen+Angebot; Kundenliste → `?kunde=K-104877`.
2. `11` „Neues Angebot erstellen“ → Modal nur Artikel (Kunde/Rahmen vorausgewählt) → weiter in Wizard 12.
3. `12` Angebots-Wizard Schritt Finanzierung: Banner „Dieses Objekt kann aus deinem Rahmenvertrag finanziert werden“ → Ja/Nein.
4. Bei Ja: grüne RV-Karte rechts unter Preiskalkulation (Name + Restbudget); Finanzierungsdauer/-art locked.
5. `07` Approval/grenke: Rechte-Pill pflegen/anlegen; Liste aller sichtbaren Rahmen.
Live: https://rahmenvertrag-prototypes.pages.dev/

**In diesem Sprint (schnittfertig):** PH-1064 mit PH-1334–1337 (Entities inkl. approvalStatus und Kategorie, Kunde/Partner, Service mit Guards, Voter, Pflege-Maske 07), neuer Subtask „Anfrage → Teilrahmen zuordnen“ (Abruf-Entity, Reservierung/Abruf/Rückbuchung), PH-1097-Anteil Partner-Sicht (Screen 11 + Karte in 10). Details: `drafts/rahmenvertrag/phase1-sprint-schnitt-2026-10-05.md`.

**Bewusst weggelassen / später:** Track B Einlesen & Prüfung, produktiver Import, Spec „ohne neue Prüfung“/F24, Flag/Kairos, Go-Partner, Benachrichtigungen. Wizard-Rahmenfinanzierung ist im Prototyp (12) klickbar.

## Starten
```bash
cd /workspace/prometheus-agents/prototypes/rahmenvertrag
python3 -m http.server 8765   # dann http://localhost:8765/index.html
```
`file://` geht ebenfalls (index.html direkt öffnen).

- Phase 1: `screens/11-partner-meine-rahmen.html` (Partner), `screens/07-oberrahmen-teilbudget-pflege.html?rolle=approval&or=OR-RNP-2026`. Simulierte Anfragen liegen in localStorage `rv-proto-abrufe`; „Simulation zurücksetzen“ (11) oder „Demo zurücksetzen“ (index) löscht sie. `?demo=anfrage` zeigt auf 11 einen festen Zustand nach einer Anfrage (für Screenshots).
- Track B: `?schritt=0..10` setzt den Szenario-Schritt (wird in localStorage `rv-proto-schritt` gemerkt). „Demo zurücksetzen“ steht auf der Index-Seite.
- `?rolle=grenke|approval` setzt die interne Rolle. Die Partner-Screens (08–10) laufen immer als Partner.
- `?demo=fehler` zeigt die Validierungsfehler auf 04, 06 und 07.
- Screenshots: `python3 screenshots.py` (Playwright, 1280 px) → `screenshots/`

## Datenmodell Phase 1 (im Prototyp: `data/beispieldaten.js`, Logik `app.js` → `Proto.rahmenStand()`, `Proto.zuordnen()`)
- **Oberrahmen** (`frame_contract`, im UI „Rahmenvertrag“): Kennung*, Kunde* (Vertragspartei mit grenke, Bindungsschlüssel), Partner-Kontext (optional, nur Vermittler/Sichtbarkeit, keine Vertragspartei), Gesamtvolumen*, Laufzeit von/bis (optional), approvalStatus `draft|approved|rejected` (Default approved), Herkunft.
- **Teilrahmen** (`frame_contract_part`): Bezeichnung*, Teilvolumen*, Objektkategorie (0..1, eindeutig im Oberrahmen), Partner (optional, nur Sichtbarkeitsfilter, leer = keine Einschränkung; F25 offen).
- **Abruf** (neu, Arbeitstitel `frame_contract_drawdown`): Anfrage/Vorgang, Teilrahmen, Betrag (Finanzierungsvolumen netto), Status `reserviert|abgerufen|zurueckgebucht`; Anfragen ohne Treffer bekommen keinen Abruf (im Prototyp als `ohne_rahmen` nur zur Anzeige).
- **Abgeleitet, nicht gepflegt:** abgerufen, in Anfrage, Restvolumen = Teilvolumen − abgerufen − reserviert.
- **Zuordnungsregel:** approved + gleicher Kunde (Rahmen hängt am Kunden) + Teilrahmen für den Partner sichtbar + gleiche Kategorie + heute in der Laufzeit + Betrag ≤ Rest. Sonst normaler Prüfweg, kein Splitten. Dem Partner wird der Grund nur neutral angezeigt (keine Entwürfe, keine fremden Teilrahmen).
- Beispielbestand Partner Bürotechnik Rhein-Main: OR-HESS-2026 (Laufzeit ab 01.11.), OR-RNP-2026 und OR-MBO-2026 (aktiv, mit Anfragen), OR-ASE-2026 (draft, unsichtbar).

## Phase 2 / Track B: Szenario (Statusmodell nach Neuschnitt-Draft `drafts/rahmenvertrag/neu/PH-1066.md`)
| Schritt | Status | Wo |
|---|---|---|
| 0–1 | Entwurf (Partner lädt hoch, korrigiert die Auslese) | 08, 09 |
| 2 | Eingegangen | 01, 02 |
| 3 | In Auslesung | 02 |
| 4 | Fachliche Prüfung offen (Runde 1) | 04 |
| 5 | Nacharbeit erforderlich (Seitenzweig) | 09 (Partner), 03 |
| 6 | Fachliche Prüfung offen (Runde 2, Dokumente v2) | 04 |
| 7 | KYC/Bonität offen | 05 |
| 8 | Freigabe vorbereitet | 06 |
| 9 | Freigegeben → Teilrahmen im Oberrahmen | 07, 10 |
| 10 | Abgelehnt | 06, 10 |

## Phase 2 / Track B: Klickpfad
08 Upload → 09 Auslese korrigieren & einreichen → 01 Liste (grenke-Login) → 02 Dokumente/Auslesung → 04 Formal-Check (Mängel → Rückgabe) → 09 Nacharbeit (Partner) → 04 Runde 2 → 05 KYC → 06 Entscheidung → 07 Oberrahmen / 10 Partner-Status mit Restvolumen.

## Screens (Dateinamen und Zuordnung nach `drafts/rahmenvertrag/screen-mapping.md`)
**Phase 1 / Demo:** 07, 11, **12 (Angebots-Wizard)** und Restvolumen-Karte in 10. **Track B:** 01–06, 08–09. Nichts wurde gelöscht.

| Screen | Rolle | Ticket | Subtasks | Zweck / Inhalt | Zustände & Fehler |
|---|---|---|---|---|---|
| **Phase 1** `11-partner-meine-rahmen.html` (+ `?kunde=<id>`) | Partner | **PH-1342**, PH-1097-Anteil, neuer Subtask Zuordnung | – | **Seit 05.10. (PH-1342):** Annahme-Banner Vertragsparteien; Kundenliste mit Rest offen / in Anfrage / später verfügbar / Auslastung; Kunden-Detail je Rahmenvertrag mit Vertragsparteien und Teilrahmen-Zeilen (Objektkategorie zweite Ebene), Phase-2-Button ausgegraut (Hinweis „ohne neue Prüfung vorgesehen, Spec offen“). ~~Restbudget je Objekttyp (sofort nutzbar / später verfügbar), Rahmen & Teilrahmen mit Auslastung,~~ Anfragen & Zuordnung, „Anfrage simulieren“, Genehmigung/Ablehnung simulieren, ausgegrauter Phase-2-Hinweis | Treffer → reserviert; kein Treffer → normaler Prüfweg (Grund neutral); Betrag ≤ 0 → Fehler am Feld; Objekttyp „fast ausgeschöpft“ < 10 % Rest |
| `01-pruefakte-uebersicht.html` | grenke-Login, Approval | PH-1066 | PH-1321 (Liste, Filter, Detailkopf mit Tabs), PH-1319 (Status/Voter) | Liste der Prüfakten, 5 Status-Kacheln, Filter (Status, Partner, Suche) | 7 Beispielfälle, aktueller Fall abhängig vom Schritt |
| `02-dokumente-versionen-korrektur.html` | grenke-Login | PH-1065, PH-1167 | PH-1322 (Upload/Versionierung), PH-1323 (Kerndaten manuell + Änderungsnachweis + Kundenzuordnung), PH-1324 (KI-Vorbefüllung, blockiert durch PH-1167) | Kundenzuordnung, Dokumente mit Versionen, Auslese-Tabelle (17 Felder, Konfidenz, Partner-Korrekturen), Modal „Korrigieren“ mit Pflicht-Begründung | „Auslesung übernehmen“ 2→3, „Kerndaten bestätigen → Formal-Check“ 3→4; v2-Dokumente ab Schritt 6 |
| `03-statusleiste-historie.html` | intern | PH-1066 | PH-1320 (Historie insert-only, Statusleiste), PH-1321 (Detailkopf) | Übersicht der Prüfakte: nächster Schritt, Kerndaten, Teilbudgets, Historie (Timeline) | Statusleiste je Schritt 0–10 |
| `04-formal-check-maengel.html` | grenke-Login | PH-1067 | PH-1328 (Regelwerk formal-v1 R1–R10, Prüflauf), PH-1329 (Mängel-UI je Feld, Übersteuern mit Begründung, Nacharbeit, Guard to_kyc) | Je Feld OK / Hinweis / Mangel; Mangeltext Pflicht; Rückgabe-Modal an den Partner | Runde 1: 3 Mängel + 1 Hinweis → Schritt 5; Runde 2 (ab 6) ohne Mängel → „Abschließen“ → 7. Fehler `?demo=fehler`: Mangel ohne Text. „Regel übersteuern“ ist bisher nur angedeutet (Toast) |
| `05-kyc-vorlage.html` | Approval-Team | PH-1068 | PH-1330 (Quelle, Kennzahlen, Vertretung/wB, „KYC abschließen“ + Guard), PH-1331 (Befunde, Rückfragen, GwG, Eskalation, Bestands-Ampel lesend) | Banner „keine automatischen Schwellen“, Kennzahlen, Vertretung, wirtschaftlich Berechtigte, Tabelle Befunde & Rückfragen, GwG-Bestätigung manuell | „KYC abschließen“ erst nach GwG-Bestätigung → 8 |
| `06-entscheidungsvorlage-freigabe.html` | Approval / grenke-Login | PH-1069 | PH-1332 (Bündelung, Empfehlung mit Begründung), PH-1333 (Freigeben/Ablehnen, transaktionale Übernahme in den Oberrahmen) | Gebündelte Vorlage (Kerndaten, Formal-Check, KYC, Teilbudgets), Empfehlung, Entscheidung: Freigeben / mit Auflage / Nacharbeit anfordern / Ablehnen | Begründung Pflicht außer bei reiner Freigabe (`?demo=fehler`); → 9, 10 oder 5 |
| **Phase 1** `07-oberrahmen-teilbudget-pflege.html` (Menü „Rahmenverträge“) | grenke-Login, Approval | PH-1064 | PH-1334–1337 (PH-1333 Übernahme aus Track B später) | Annahme-Banner Vertragsparteien (seit 05.10. 11:50); Liste (4 Rahmen) + Formular: Kennung, Kunde*, Partner-Kontext (optional, Vermittler), Vertragsparteien (Anzeige), Volumen, Laufzeit, approvalStatus; Teilrahmen mit Kategorie (max. 1), Partner (optional), Volumen, abgerufen/in Anfrage/Rest (berechnet); zugeordnete Anfragen lesend; `?or=<Kennung>` wählt den Rahmen | Summen-Guard (`?demo=fehler`), Volumen nicht unter Summe senkbar, Teilvolumen nicht unter abgerufen + in Anfrage, Kategorie doppelt, Kennung doppelt je Kunde, Pflichtfelder; Kategorie/Partner/Entfernen gesperrt, sobald Anfragen zugeordnet sind |
| `08-partner-eingang-upload.html` | Partner | PH-1090, PH-1065 | PH-1325 (Entwurf anlegen, Upload, Kundenzuordnung), PH-1322 | Kundenzuordnung, Dropzone, Dateiliste, Checkliste der Pflichtdokumente | Fehler: HEIC-Format nicht unterstützt; „Auslesen starten“ → 09 (Schritt 1) |
| `09-partner-korrektur-einreichen.html` | Partner | PH-1090, PH-1065, PH-1167 | PH-1326 (Kerndaten korrigieren, Prüfvorschau, Einreichen), PH-1327 (Nacharbeit: Mängel je Feld, erneut einreichen), PH-1324 | PDF-Vorschau mit Markierungen + Felder; Summen-Check; Bestätigung; bei Schritt 5 Mängel-Banner und 3 Nachreich-Slots | Fehler: ungültige IBAN, Summe Teilbudgets ≠ Volumen; Einreichen → 2; Nacharbeit → 6 |
| `10-partner-status-restvolumen.html` | Partner | PH-1090, PH-1066, PH-1097 | PH-1327 (Partner-Statusliste) | **Zusätzlich, nicht im Mapping:** Partner-Sicht auf Status eines eingereichten RV (Track B), CTA je Schritt, Dokumente, Verlauf. Ab Schritt 9 Karte „Ihre Teilrahmen & Restvolumen“ (Phase 1, berechnet wie 11) mit Link zu 11 | vereinfachte Partner-Statusleiste; Hinweis, wenn die Laufzeit noch nicht begonnen hat |

`PH-1319` (Entity, Workflow `frame_contract_case`, Voter) hat keine eigene UI. Sichtbar wird es über die Statusleiste/Übergänge (01, 03) und die Rollenumschaltung im Header.

## Struktur
- `index.html`: Einstieg mit Rollen, Klickpfad und Screen-Tabelle
- `shared.css`: Design-Tokens + Komponenten · `app.js`: Shell (Header, Sidebar je Rolle), Zustand, Helfer
- `components/statusleiste.js`, `components/pruefakte-kopf.js` · `data/beispieldaten.js`
- `screens/01–12` · `screenshots/` · `screenshots.py` · `assets/logo.svg`
- Backup vor dem Phase-1-Umbau: `drafts/rahmenvertrag/backups/prototyp-rahmenvertrag-vor-phase1-2026-10-05/`

## Tokens & Templates (Quellen in `/workspace/prometheus`)
- Tokens: `assets/styles/app.css`, `config/design-tokens.yaml`, `docs/patterns/design-tokens.md`. Primary #143cdc, Pink #bd2ebd, gray-900 / #6b7280, gray-50 als Hintergrund
- Shell: `templates/layouts/pages/layout_app.html.twig` (md:ml-64, lg:pt-24 lg:px-8, page-actions-Leiste unten), `partials/_globals/app-header/*` (h-[3.75rem]), `partials/_globals/app-sidebar/*` (w-64, aktiv blue-600/gray-100), Labels aus `translations/messages.de.yml`
- Komponenten: `_components/badge`, `_components/card`, `_components/commission-status-bar` (Muster für die Statusleiste), `_atoms/links/button.html.twig`, Detailseite nach `pages/partner/commissions/show.html.twig`
- Im Code gibt es noch keine Rahmenvertrag-Entities. Angelehnt wird an `RequestedDocument`/`RequestItemCategory` (PH-1126) und die Workflows in `config/packages/workflows/*.yaml`

## Alt-Prototypen
`/workspace/rahmenvertrag-prototypes/` (Sept.) bleibt unangetastet und dient als inhaltliche Vorlage („ausbauen, nicht ersetzen“). Die neue `shared.css` ist frisch gebaut, weil die alte von den Tokens abweicht (Sidebar 240 statt 256 px, Borders #dfdfdf, color-mix-Badges).

## Offene Design-Fragen (Phase-1-relevante Fragen stehen im Annahmen-Check)
1. **F6** Status „Entwurf“ ja/nein: Die Partner-Korrektur der Auslese läuft im Prototyp im Entwurf.
2. KI-Auslese im Partner-Flow oder in v1 manuell (PH-1167 / PH-1324)? Davon hängt die Konfidenz-Anzeige auf 02/09 ab.
3. Partner-Statusleiste vereinfacht (Hochgeladen / Auslese prüfen / In Prüfung / Entschieden): Sieht der Partner Namen der grenke-Prüfer in der Historie?
4. **F7** Sichtbarkeit und Navigation für grenke-Login (Hub-User): Wo sitzt der Sidebar-Eintrag je Rolle? (Label ist seit 05.10. für alle Rollen „Rahmenverträge“.)
5. Formal-Check: Ist „Hinweis“ nur intern? Wie sieht der Übersteuern-Dialog aus (PH-1329), wer darf übersteuern? Regelversion je Feld anzeigen?
6. Entscheidung: Ist „Freigabe mit Auflage“ eine eigene Option? Vier-Augen-Prinzip? Ist die Entscheidung danach unveränderbar? Wer empfiehlt, wer entscheidet (PH-1332)?
7. Teilrahmen-Dimension Partner × Objektkategorie (PH-1097 vs. grenke-Protokoll 02.10.). Darf ein Teilvolumen unter den bereits abgerufenen Betrag fallen? Umgang mit nicht verteilter Restsumme?
8. **F8** Liste der Vertragsarten: Das Feld fehlt im Prototyp.
9. **F9** Benachrichtigungen in v1; Frist/Eskalation bei Nacharbeit.
10. ~~Eine Liste „Meine Rahmenverträge“ für den Partner fehlt bewusst~~ → seit 05.10. Screen 11 (Phase 1). Der zweite Eingang „digital erzeugen“ bleibt ausgegraut (Phase 2).
11. „Nacharbeit“ steht in Jira PH-1066 als Reihenstatus, im Neuschnitt-Draft als Seitenzweig. Der Prototyp folgt dem Draft.
12. **Flag vs. automatische Zuordnung** (PH-1097 AK7, PH-1100/F22 vs. Subtask Zuordnung): Folgt das Flag aus der Zuordnung, wird es manuell gesetzt, oder gilt beides? Der Prototyp zeigt nur die automatische Zuordnung. Spec-Folgeschritt.
13. **Abruf ohne neue Prüfung:** Kevin-Richtung 05.10. Ob das schon für Phase 1 (Zuordnungs-Subtask) oder erst mit PH-1096/F24 gilt, klärt die Spec. Im Prototyp steht es nur in den Phase-2-Hinweisen.
14. **F25** (Partner je Teilrahmen) bleibt offen, betrifft nur den Sichtbarkeitsfilter, nicht die Bindung.