14 KiB
Stufe 1 - Detaillierung AP1 – Spezifikation, Architekturschnitt und technischer Durchstich
Vertraulichkeit: intern
Kein Kundendokument. Enthält Einschätzungen zur eigenen Kompetenzlage und zum Vorgehen bei fehlender Architekturerfahrung. Eine daraus abgeleitete Leistungsbeschreibung für die Beauftragung von AP1 (O8) wäre gesondert zu erstellen.
Bezug: AP-02 Grobplanung Stufe 1 „Souveräne Suche" V0.3, dort Kapitel 2.2 (AP1), 2.3 (Kalibrierungspaket), 3 (Schätzung), 7 (Gate G1); Internes Konzeptdokument v0.5, Abschnitte 5.1, 5.4, 6.2, 6.3, Kritikpunkt K6; Entscheidungsvorlage O1 – Intern v0.3
| erstellt durch: | d-opt GmbH Oberneumarker Str. 59 08496 Neumark (Sachsen) |
| erstellt von: | Florian Förster |
| Erstellungsdatum: | 10.08.2026 |
| geändert von: | Florian Förster |
| Änderungsdatum: | 12.08.2026 |
| Dokumentversion: | V0.1 |
1. Zweck und Einordnung
Dieses Dokument detailliert das Arbeitspaket AP1 aus der Grobplanung auf Teilaufgabenebene. Anlass: AP1 ist das erste beauftragbare Paket, dient als Pilotierung und liefert mit Gate G1 den empirischen Anker für die Revision der Gesamtschätzung. Seine Zusammensetzung muss deshalb nachvollziehbar sein, bevor über die Beauftragung entschieden wird.
Verbindlichkeit: Die Aufwandswerte übernehmen die Schätzklasse der Grobplanung (±40–50 %). Die Teilaufgaben-Werte summieren sich auf die dort ausgewiesenen 25 / 32 / 45 PT; sie sind eine Zerlegung, keine Neuschätzung.
Geltungsbereich: AP1 endet mit Gate G1. Was danach folgt (AP2 ff.), ist nicht Gegenstand dieses Dokuments.
2. Rolle von AP1 im Gesamtvorhaben
AP1 erfüllt vier Funktionen gleichzeitig – das ist der Grund für den Zuschnitt als Spezifikation plus Durchstich und nicht als reines Konzeptpaket:
- Festlegung der nicht umkehrbaren Entscheidungen (Kapitel 4), bevor darauf aufgebaut wird;
- Messung der realen Umsetzungsgeschwindigkeit unter Parallelbelastung – Grundlage der Schätzrevision an G1;
- Prüfung der kritischsten Fremdannahme: Umfang und Reife des Moodle-Web-Service-Zugriffs (Annahme A3 der O1-Vorlage, Risiko R-G2 der Grobplanung);
- Vorzeigbares Zwischenergebnis für mastersolution nach wenigen Monaten statt am Ende der Teilstufe.
3. Teilaufgaben und Aufwand
| Nr. | Teilaufgabe | O | W | P | Ergebnisartefakt |
|---|---|---|---|---|---|
| AP1.1 | Anforderungsdetaillierung und Abnahmekriterien Stufe 1a | 3 | 4 | 6 | Spezifikation Stufe 1a mit messbaren Abnahmekriterien |
| AP1.2 | Schnittstellenschnitt (Vertrag des Dienstes) | 3 | 4 | 6 | Schnittstellenvertrag V1 (Operationen, Fehlerfälle, Versionierung) |
| AP1.3 | Datenmodell der Index-Einheit | 2 | 3 | 5 | Datenmodell V1 inkl. Berechtigungs-, Klassifikations- und Timestamp-Attributen |
| AP1.4 | Entscheidung Berechtigungsprüfung (mit Messung) | 3 | 4 | 7 | Entscheidungsnotiz D3 mit Messwerten |
| AP1.5 | Technischer Durchstich (Implementierung) | 11 | 13 | 16 | Lauffähiger Durchstich gegen Moodle-Testinstanz |
| AP1.6 | Dokumentation, Messprotokoll, Schätzrevision | 3 | 4 | 5 | Entscheidungsnotizen, Messprotokoll, revidierte Schätzung für G1 |
| Summe AP1 | 25 | 32 | 45 |
Verteilung: Rund 40 % des Aufwands (AP1.5) ist Implementierung. Auf das, was klassisch „Architekturarbeit" heißt (AP1.2–AP1.4), entfallen etwa 11 Tage. AP1 ist damit kein Konzeptpaket mit angehängtem Prototyp, sondern ein Bau-Paket mit vorgeschalteten Festlegungen.
4. Die drei nicht umkehrbaren Entscheidungen
Architekturentscheidungen unterscheiden sich in ihrer Rücknehmbarkeit. Zweibahnig heißt: später mit überschaubarem Aufwand korrigierbar – Wahl der Embedding-Bibliothek, Aufbau der Suchmaske, Wahl des Web-Frameworks. Einbahnig heißt: eine Korrektur kostet ein Vielfaches, weil alles Nachfolgende darauf aufgesetzt hat. Nur die einbahnigen Entscheidungen rechtfertigen den Aufwand in AP1; alle übrigen werden bewusst offen gelassen und im Bauverlauf entschieden.
D1 – Datenmodell der Index-Einheit (AP1.3)
Zu entscheiden: Welche Attribute trägt eine Index-Einheit? Insbesondere: Berechtigungsattribute, Klassifikationsattribute (Kurskontext-Sperre, E9), Herkunftsangaben für den Absprung, Zeitstempel-Vorsorge für Paket V.
Warum einbahnig: Fehlt ein Attribut, ist nicht das Hinzufügen des Feldes teuer, sondern der Neuaufbau des gesamten Indexbestands und die Nachziehung jeder Abfrage, die daran vorbeigebaut wurde. Dieselbe Logik hat das Register bereits bei E9 angewandt.
Bewusste Ausnahme: Die Timestamp-Vorsorge bleibt auch dann im Datenmodell, wenn Paket V nicht beauftragt wird (Grobplanung 2.2).
D2 – Schnittstellenschnitt (AP1.2)
Zu entscheiden: Welche Operationen bietet der Dienst nach außen, wie werden Fehlerfälle und Nulltreffer signalisiert, wie wird versioniert?
Warum einbahnig: Der Schnitt muss die Stufen 2 bis 4 tragen. Trennt er Retrieval und Antwortgenerierung nicht sauber, wird er beim Hinzutreten des LLM in Stufe 2 umgebaut – samt allem, was mastersolution bis dahin daran angeschlossen hat. Der Aufwand liegt nicht im Aufschreiben, sondern im Durchspielen der drei künftigen Stufen gegen den heutigen Entwurf.
Prüffragen, die der Entwurf beantworten muss:
- Lässt sich in Stufe 2 eine generierte Antwort ergänzen, ohne die bestehenden Operationen zu ändern?
- Bleibt der Nachschlage-Pfad unabhängig von den Stufe-3/4-Komponenten (Konzept 5.4)?
- Ist der Schnitt oberflächenneutral im Sinne der O1-Option D, also gegenüber einer späteren Einbettung in eine andere Oberfläche unverändert verwendbar?
D3 – Verfahren der Berechtigungsprüfung (AP1.4)
Zu entscheiden: Wird je Suchanfrage live gegen Moodle geprüft, oder wird auf gespiegelten Berechtigungen gearbeitet – und mit welcher Aktualisierungsfrequenz?
Warum einbahnig: Die Entscheidung bestimmt den Zuschnitt von AP4, dem teuersten und riskantesten Paket, und wirkt auf AP2 und AP5 zurück.
Warum nicht am Schreibtisch entscheidbar: Beide Wege haben je einen Nachteil, dessen Größe nur messbar ist – die Live-Abfrage kostet Latenz, die Spiegelung erzeugt ein Aktualitätsfenster, in dem ein Nutzer etwas sehen kann, das er nicht mehr sehen darf. Beide Größen sind zu messen, nicht zu schätzen.
Messplan:
- Antwortzeit einer Berechtigungsabfrage gegen die Moodle-Testinstanz, Median und oberes Perzentil, bei mindestens zwei Lastniveaus;
- Anzahl der je Suchanfrage nötigen Abfragen bei realistischer Trefferzahl;
- daraus Hochrechnung des Latenzanteils der Prüfung am Gesamtbudget;
- für die Spiegelvariante: Aufwand und Dauer eines Abgleichs sowie das resultierende Aktualitätsfenster.
Abzuleitendes Kriterium: Das Latenzbudget für Stufe 1 ist in AP1.1 festzulegen und in AP1.4 gegen die Messwerte zu prüfen. Das Konzept operationalisiert die Anforderung „Geschwindigkeit" bislang nicht (Kritikpunkt K6); AP1 schließt diese Lücke für Stufe 1.
5. Technischer Durchstich (AP1.5)
Ziel: ein schmaler, aber vollständiger End-zu-End-Pfad – nicht ein Funktionsumfang, sondern eine Durchgängigkeit.
Im Umfang:
- Anbindung an eine Moodle-Testinstanz über Web Services; Bezug von Material eines Materialtyps;
- Indizierung nach dem Datenmodell aus D1;
- Suche mit wirksamem Berechtigungsfilter nach dem Verfahren aus D3;
- minimale Ergebnisdarstellung mit Quellenangabe und Absprung in das Material;
- Messpunkte für Latenz und Web-Service-Verhalten.
Nicht im Umfang: mehrere Materialtypen, Cross-Encoder-Reranking, unterbrechungsfreie Reindizierung, Goldstandard und Metrikpfad, Mandantenfähigkeit, Barrierefreiheit, produktionsreife Fehlerbehandlung, Testabdeckung im Zielumfang. Diese gehören zu AP2–AP9 und werden im Durchstich bewusst weggelassen.
Abnahmekriterien:
- Eine Suchanfrage eines Testnutzers liefert ausschließlich Treffer aus Material, auf das dieser Nutzer in Moodle Zugriff hat;
- ein Testnutzer ohne Zugriff erhält für dieselbe Anfrage keine Treffer aus dem geschützten Material;
- der Absprung führt in das korrekte Material an der erwarteten Stelle;
- die Messpunkte aus D3 liefern verwertbare Werte.
Kriterium 2 ist das eigentliche Abnahmekriterium des Durchstichs: Es prüft die Kernzusage des Produkts, nicht die Suchfunktion.
6. Vorgehen bei fehlender Architekturerfahrung
Die drei Entscheidungen aus Kapitel 4 setzen keine langjährige Architekturerfahrung voraus, aber sie verlangen eine andere Methode als das Entscheiden aus Erfahrung.
Entscheiden aus Messung statt aus Erfahrung. Genau deshalb ist der Durchstich Teil von AP1 und nicht ein Folgepaket. Wo eine Entscheidung an einer unbekannten Größe hängt, wird die Größe gemessen, bevor entschieden wird. Das ist auch für erfahrene Architekten der methodisch sauberere Weg; hier ist er zusätzlich notwendig.
Entscheidungsnotizen. Je Entscheidung eine kurze Notiz mit Kontext, betrachteten Alternativen, getroffener Wahl und Begründung – Umfang etwa eine halbe Seite. Zweck: Sie ist in achtzehn Monaten die einzige Erklärung, warum etwas so gebaut wurde, und sie adressiert unmittelbar das Übergaberisiko R-G1 der Grobplanung. Der Aufwand ist in AP1.6 enthalten.
Gezielte Zweitmeinung. Für D3 ist das Profil der Kollegin passgenau: Die Frage ist im Kern ein Konsistenz- und Aktualitätsproblem, keine Softwareentwicklungsfrage. Für D1 ist eine Zweitmeinung nützlich, für D2 weniger geeignet (Grobplanung 6.3). Der Zeitbedarf ist gering und in AP1.4 abgedeckt; die Verfügbarkeit ist nicht gesichert (P-5) und wird nicht eingeplant.
Bewusst offen lassen. Alles Zweibahnige wird in AP1 nicht entschieden. Die häufigste Fehlerquelle bei erstmaliger Architekturarbeit ist nicht die zu späte, sondern die zu frühe und zu umfangreiche Festlegung.
7. Ergebnisartefakte und Abschluss (Gate G1)
| Artefakt | Aus | Verwendung danach |
|---|---|---|
| Spezifikation Stufe 1a mit Abnahmekriterien | AP1.1 | Abnahmegrundlage G3 |
| Schnittstellenvertrag V1 | AP1.2 | Grundlage AP5, AP6; Abstimmung mit mastersolution |
| Datenmodell V1 | AP1.3 | Grundlage AP2, AP4; Vorsorge für 1b und Paket V |
| Entscheidungsnotizen D1–D3 | AP1.2–1.4, 1.6 | Nachvollziehbarkeit, Übergabefähigkeit |
| Lauffähiger Durchstich | AP1.5 | Vorführung; technische Basis für AP2 ff. |
| Messprotokoll (Latenz, Web-Service-Verhalten, Geschwindigkeit) | AP1.4–1.6 | Eingang in die Schätzrevision |
| Revidierte Schätzung Stufe 1a | AP1.6 | Festpreisfähigkeit AP2–AP6 (Grobplanung Kap. 9) |
Messung der eigenen Geschwindigkeit – Vorgehen: Je Teilaufgabe werden die tatsächlich aufgewendeten Personentage sowie die Anzahl und Dauer der Unterbrechungen durch Parallelprojekte erfasst. Daraus ergeben sich zwei Kennzahlen für G1: die effektiv verfügbaren PT je Woche (Abgleich mit dem Kapazitätsszenario S2 der Grobplanung) und der Schätzfaktor als Verhältnis von tatsächlichem zu geschätztem Aufwand je Teilaufgabe. Beide gehen in die Revision der Pakete AP2–AP9 ein.
8. Vorbedingungen für den Start von AP1
Aus Gate G0 der Grobplanung, hier auf AP1 bezogen:
| Nr. | Vorbedingung | Verantwortlich |
|---|---|---|
| V-1 | Moodle-Testinstanz mit repräsentativem Materialbestand verfügbar | mastersolution |
| V-2 | Web-Service-Zugriff eingerichtet, Testnutzer mit unterschiedlichen Rollen und Kurszugehörigkeiten angelegt | mastersolution |
| V-3 | Priorisierungsentscheidung gemäß Szenario S2 getroffen | Geschäftsführung d-opt |
| V-4 | O1 entschieden oder Planungsannahme P-1 kundenbestätigt | mastersolution / d-opt |
V-1 und V-2 sind hart: Ohne sie ist AP1.4 nicht messbar und AP1.5 nicht durchführbar; AP1 fiele auf ein reines Konzeptpaket zurück und verlöre seine Kalibrierungsfunktion.
9. Risiken innerhalb von AP1
| Nr. | Risiko | Wirkung | Behandlung |
|---|---|---|---|
| R-AP1-1 | Web-Service-Zugriff reicht nicht für Materialbezug oder Berechtigungsabfrage (R-G2) | D3 nicht entscheidbar, Rückfall auf Export-Wege, Rückwirkung auf AP2/AP5 | Früh im Durchstich prüfen – vor der Indizierungsarbeit; Zwischenstand an mastersolution |
| R-AP1-2 | Der Durchstich wächst zum Prototyp aus (Umfangsdrift) | AP1 sprengt die Spanne, Kalibrierungswert sinkt | Negativliste in Kapitel 5 als verbindliche Abgrenzung; Abnahme nur gegen die vier Kriterien |
| R-AP1-3 | Zu frühe Festlegung zweibahniger Entscheidungen | Aufwand ohne Nutzen, spätere Bindung ohne Notwendigkeit | Beschränkung der Entscheidungsnotizen auf D1–D3 |
| R-AP1-4 | Testmaterial nicht repräsentativ (zu wenige Rollen, zu homogene Inhalte) | Berechtigungsprüfung wird scheinbar bestanden | Anforderung an V-1/V-2 präzisieren: mindestens zwei Rollen, mindestens ein geschützter und ein offener Kursbereich |
10. Kürzungsoptionen
Falls der Umfang von AP1 reduziert werden muss:
Kürzbar (zusammen 3–4 PT): Abnahmekriterien knapper fassen (AP1.1) und die Dokumentation auf D1–D3 beschränken (AP1.6).
Nicht kürzbar: AP1.4 und AP1.5. Sie sind der Grund, warum AP1 als Kalibrierungspaket taugt – ohne Messung fehlt der empirische Anker für G1, ohne Durchstich die Prüfung der Fremdannahme. Eine Kürzung hier spart wenige Tage und entwertet das gesamte Paket.
11. Offene Punkte
| Nr. | Punkt | Klärung durch |
|---|---|---|
| OP-1 | Festlegung des Latenzbudgets für Stufe 1 (Konzept K6) | AP1.1, intern |
| OP-2 | Auswahl des Materialtyps für den Durchstich | AP1.1, gemeinsam mit mastersolution |
| OP-3 | Verfügbarkeit der Kollegin für die Zweitmeinung zu D3 | intern, vor Beginn AP1.4 |
| OP-4 | Ob AP1 separat beauftragt oder als Teil eines Gesamtauftrags geführt wird | O8 |