1. Jahresprojekt: Thema und Team

Jahresprojekt: Thema und Team

Als erstes in diesem Gegenstand wird nicht programmiert, sondern entschieden. Am Ende der Woche steht ein Thema, eine Teamgröße, ein Satz aufgeschriebener Anforderungen, eine Architekturentscheidung und ein Repository, in dem ab der nächsten Woche etwas wächst.

Das sieht nach Vorgeplänkel aus und hat die längste Wirkung von allem, was dieses Jahr passiert: Die dreißig folgenden Wochen arbeiten an genau diesem Thema weiter. Solange nichts gebaut ist, kostet ein Themenwechsel eine Unterrichtsstunde. Im März kostet er das halbe Projekt.

Der Reflex, diese Woche schnell hinter sich zu bringen, ist verständlich und schlägt zuverlässig im zweiten Semester zurück. Wer im Februar bemerkt, dass sein Thema nie eine zweite Rolle gebraucht hat, hat kein Kapitel über Autorisierung, sondern ein Problem.

Warum ein Jahresprojekt

Ein Übungsbeispiel hat keine Vergangenheit. Man legt es an, löst es, gibt es ab, und beim nächsten beginnt man wieder mit einem leeren Verzeichnis. Deshalb zeigt sich am Übungsbeispiel eine ganze Klasse von Problemen nie.

Ein System, das im September angelegt wurde und im Juni noch läuft, hat eine Vergangenheit, und die meldet sich. In der Datenbank stehen Daten, die beim nächsten Modellwechsel nicht verloren gehen dürfen, also wird migriert statt neu angelegt. Eine Funktion, die im November richtig war, passt im März nicht mehr, aber jemand benutzt sie bereits. Eine Änderung bricht eine Stelle, die zwei Monate lang unauffällig funktioniert hat. Der Server läuft auch über die Weihnachtsferien, mitsamt den Anmeldeversuchen, die dort jede Nacht auflaufen.

Das ist der Unterschied zwischen „Beispiel gelöst” und „System betrieben”. Migrationen, Regressionen, Altlasten und Betriebsverantwortung entstehen über Zeit und lassen sich in einer Doppelstunde nicht nachstellen.

Zur Abgrenzung: In Softwareentwicklung entsteht am Jahresende vielleicht ein Client-Server-Projekt in etwa vier Wochen. Das ist eine andere Übung mit einem anderen Zweck, dort geht es um Entwurf und Umsetzung unter Zeitdruck. Hier wächst ein System über 31 Wochen, ist dabei die ganze Zeit öffentlich erreichbar und gehört Ihnen.

Ein Thema, das trägt

Ein taugliches Thema erkennt man an vier Eigenschaften.

Es hat Nutzer, die man benennen kann. Nicht „alle Sportvereine in Kärnten”, sondern der Zeugwart Ihres Vereins, die Trainerin der U14 und die Eltern, die nachschauen wollen, wann das nächste Spiel ist. Drei Personen, die man tatsächlich fragen könnte, genügen. Ohne Nutzer wird das Projekt zur Fingerübung, und im Kapitel über Benutzerergonomie fehlt Ihnen das Material.

Es hat Struktur. Drei bis fünf Entitäten mit Beziehungen dazwischen sind die Untergrenze. Eine einzelne Tabelle ergibt kein Datenmodell, an dem sich Transaktionen, Indizes oder das N+1-Problem zeigen lassen.

Es hat Inhalte und Daten. Daten sind das, was Benutzer erzeugen: Buchungen, Anmeldungen, Angebote. Inhalte sind das, was eine Redaktion pflegt: Hausordnung, Anleitungen, Neuigkeiten, Impressum. Beides zusammen ergibt den Anlass für einen Webservice und für ein CMS.

Es verlangt Anmeldung und Rollen. Wenn jede Person alles darf, gibt es nichts zu autorisieren. Die Frage lautet: Welche Handlung soll einer bestimmten Gruppe vorbehalten sein, und was passiert, wenn es jemand anderer versucht?

Daraus ergibt sich, was ein Thema abdecken muss:

Bereich	Was im Thema stecken muss	Kapitel
Datenbank	drei bis fünf Entitäten mit Beziehungen, Abfragen über mehr als eine Tabelle	6
Webservice	lesende und schreibende Endpunkte mit Regeln, nicht nur Durchreichen	4, 7
Frontend	Listen, Detailansichten, Formulare mit Validierung	10, 11
Inhaltsbereich	Seiten, die redaktionell gepflegt werden, ohne Code zu ändern	14
Betrieb	öffentlich erreichbar unter eigener Adresse, abgesichert	2, 3
Rollen	mindestens zwei Rollen mit unterschiedlichen Rechten	8, 9

Woran Themen scheitern

Themen sollen eine Abdeckung der sechs Bereiche haben. Wer nur drei davon abdeckt, hat kein Jahresprojekt, sondern eine Übung. Die häufigsten Gründe für ein Scheitern:

Eine reine Tabellenverwaltung: anlegen, ändern, löschen über eine Entität, ohne fachliche Regeln. Es gibt nichts zu validieren, nichts zu berechtigen, nichts zu modellieren.

Das Thema ohne Inhaltsanteil: Wenn nirgendwo Text steht, den jemand ohne Programmierkenntnisse pflegen soll, fehlt der Anlass für das CMS und damit ein guter Teil des zweiten Semesters.

Das Thema, das von fremden Daten lebt: Eine Anwendung, die im Kern eine fremde Schnittstelle anzeigt, hat kein eigenes Datenmodell und keine eigenen Schreibvorgänge. Fremde Schnittstellen sind als Zutat willkommen, nicht als Hauptgang.

Themenkatalog

Die folgenden Themen erfüllen die Abdeckung und sollen als Anregung dienen. Ein eigenes Thema aus dem eigenen Umfeld ist meistens das bessere, weil es echte Nutzer mitbringt.

Thema	Entitäten (Auszug)	Inhaltsbereich	Rollen
Vereinsverwaltung	Mitglied, Mannschaft, Termin, Beitrag	Vereinsnachrichten, Chronik, Statuten	Vorstand, Mitglied, Gast
Werkstattbuchung	Maschine, Zeitfenster, Buchung, Einschulung	Sicherheitshinweise, Bedienanleitungen	Werkstattleitung, Mitglied
Schulprojektbörse	Projekt, Betreuer, Bewerbung, Firma	Ausschreibungstexte, Leitfäden	Lehrperson, Schüler, Firma
Sportevent	Bewerb, Teilnehmer, Startliste, Ergebnis	Ausschreibung, Anfahrt, Neuigkeiten	Veranstalter, Teilnehmer
Fachbibliothek einer Abteilung	Medium, Exemplar, Entlehnung, Vormerkung	Empfehlungen, Benutzungsordnung	Bibliothekar, Entlehner
Nachhilfebörse	Angebot, Fach, Termin, Rückmeldung	Lerntipps, Regeln der Vermittlung	Anbieter, Suchender, Redaktion
Repair-Café	Gerät, Termin, Reparaturprotokoll, Ersatzteil	Anleitungen, Termine, Über uns	Reparateur, Besucher
Probenraumverwaltung	Band, Raum, Slot, Ausrüstung	Hausordnung, Preise, Anfahrt	Betreiber, Band
Fahrgemeinschaften	Fahrt, Sitzplatz, Anfrage, Bewertung	Regeln, Sicherheitshinweise	Fahrer, Mitfahrer
Rezeptarchiv mit Redaktion	Rezept, Zutat, Sammlung, Kommentar	redaktionelle Themenwochen	Redaktion, Autor, Leser
Kulturverein	Veranstaltung, Künstler, Reservierung, Saal	Programmheft, Archiv, Presse	Veranstalter, Besucher
Lehrmittelverleih	Gerät, Ausleihe, Wartung, Standort	Handbücher, Ausleihbedingungen	Verwaltung, Lehrperson

Themenprüfung in fünf Minuten

Gehen Sie die Abdeckungstabelle Zeile für Zeile durch und schreiben Sie zu jeder Zeile ein konkretes Beispiel aus Ihrem Thema auf: welche Entitäten, welcher schreibende Endpunkt, welche Seite in der Redaktion, welche zweite Rolle. Bleibt eine Zeile leer, ist das Thema noch nicht fertig gedacht. Meist genügt eine Erweiterung, gelegentlich ist es das falsche Thema.

Allein oder im Team

Erlaubt sind eine, zwei oder drei Personen. Was sich mit der Teamgröße ändert, ist die Menge an Funktionen, nicht der Umfang der Kette: Server, Webservice, Frontend und Inhaltsbereich gehören in jedem Fall dazu. Eine Einzelperson liefert weniger Bewerbe, weniger Filter, weniger Auswertungen und wird auch nicht an der Funktionsmenge eines Dreierteams gemessen (siehe Beurteilung, Grundsatz 5).

Im Team kommt eine Bedingung dazu: Die Aufgaben rotieren. Am Jahresende muss jede Person jeden Bereich erklären können, weil die Beurteilung den individuellen Beitrag über Git-Historie und Reviews nachvollzieht (Grundsatz 6). Wer neun Monate lang nur Formulare baut, kann Betrieb, Datenbank und Absicherung nicht nachweisen, egal wie gut das Team insgesamt dasteht.

Einiges gehört am ersten Tag schriftlich ins Repository, weil es später Streit erspart: wer welchen Bereich in welchem Zeitraum übernimmt, wer den Server bezahlt und auf wessen Namen er läuft, wo das Repository liegt und wer Zugriff hat, und wie ein Merge Request geprüft wird, bevor er auf main landet.

Die häufigste Teamfalle

Die Aufteilung „du machst Frontend, ich mache Backend” wirkt am Anfang effizient. Sie führt dazu, dass im Juni niemand die andere Hälfte des eigenen Projekts erklären kann, und sie erzeugt genau an der Schnittstelle die längsten Diskussionen, weil beide Seiten aufeinander warten. Teilen Sie stattdessen nach Funktion: Eine Person baut ein Feature von der Datenbank bis zum Formular durch, die nächste das nächste Feature.

Anforderungen aufschreiben

Ein Projekt, dessen Anforderungen nur im Kopf existieren, ändert sie unbemerkt. Am Ende dieser Woche steht deshalb eine kurze Liste, an der sich später prüfen lässt, ob etwas fertig ist.

Nutzergeschichten

Das Format ist bekannt und hier bewusst schlicht gehalten:

Als <Rolle> möchte ich <Ziel>, damit <Nutzen>.

Der Nutzenteil ist der interessante. Wer ihn nicht ausformulieren kann, hat meist ein Feature aufgeschrieben und keine Anforderung. Ein Beispiel aus der Werkstattbuchung, mit Akzeptanzkriterien:

Als Mitglied möchte ich die freien Zeitfenster einer Maschine sehen,
damit ich meine Arbeit planen kann.

Akzeptanzkriterien:
- Der Kalender zeigt die nächsten 14 Tage.
- Belegte Zeitfenster sind als belegt erkennbar, ohne fremde Namen zu zeigen.
- Maschinen ohne meine Einschulung sind sichtbar, aber nicht buchbar.
- Ohne Anmeldung ist der Kalender lesbar, eine Buchung nicht möglich.

Ein Akzeptanzkriterium ist eine Prüfbedingung. Die Probe: Kann eine zweite Person allein anhand des Kriteriums entscheiden, ob es erfüllt ist? „Der Kalender ist übersichtlich” besteht diese Probe nicht, „Der Kalender zeigt die nächsten 14 Tage” schon. Diese Kriterien sind später die Vorlage für Ihre Tests, deshalb lohnt sich die Genauigkeit jetzt.

Muss, Soll, Kann

Zwölf bis zwanzig Geschichten reichen für ein Schuljahr aus. Jede bekommt eine Priorität:

• Muss ist der Teil, ohne den das Projekt kein Projekt ist. Er muss bis zum Sicherheits-Review in Kapitel 16 stehen, weil dieses Kapitel das fertige System prüft und nicht die Absicht.
• Soll ist das, was in ein gutes Projekt gehört, aber verschiebbar ist.
• Kann ist die Ideenablage. Dorthin kommt alles, was im Lauf des Jahres einfällt, und dort bleibt es meistens auch.

Ein Muss-Set aus dreißig Geschichten ist kein Muss-Set, sondern eine Wunschliste mit falscher Beschriftung. Fünf bis acht sind realistisch.

Abstimmung mit Softwareentwicklung

Nutzergeschichten, Backlog, Priorisierung und Retrospektive gehören methodisch in den Unterricht über agiles Arbeiten in SEW. Hier werden sie als Werkzeug benutzt, damit das Projekt eine prüfbare Grundlage hat. Wenn Sie dort mit einer bestimmten Form arbeiten, verwenden Sie diese auch hier, statt zwei Systeme parallel zu führen.

Das Domänenmodell als Skizze

Neben die Geschichten gehört eine Skizze der Entitäten und ihrer Beziehungen. Sie soll auf eine Seite passen und beantwortet zwei Fragen: Welche Dinge gibt es, und wie hängen sie zusammen?

erDiagram
  MITGLIED ||--o{ BUCHUNG : "bucht"
  MASCHINE ||--o{ BUCHUNG : "wird belegt in"
  MITGLIED ||--o{ EINSCHULUNG : "besitzt"
  MASCHINE ||--o{ EINSCHULUNG : "verlangt"
  BUCHUNG {
    int id
    datetime beginn
    datetime ende
  }

Der Entwurf selbst, also Normalisierung, Schlüssel und Datentypen, gehört in Informationssysteme. Hier geht es nur so tief, dass die Beziehungen stimmen: Die Skizze oben sagt bereits, dass eine Buchung ohne Mitglied und ohne Maschine nicht existieren kann und dass die Einschulung eine eigene Verbindung zwischen beiden ist. Beides taucht in Kapitel 6 wieder auf, dann als Fremdschlüssel und Migration.

Den Schnitt festlegen

Die zentrale Entscheidung dieses Jahres betrifft den Zuschnitt der Anwendung. Zwei Wege stehen offen, und beide sind zulässig.

Beim Next.js-Fullstack liegen Oberfläche und Serverlogik in einer Anwendung. Der Datenzugriff passiert in Server Components und Route Handlers, ausgeliefert wird ein Container.

Bei getrennten Anwendungen ist der Webservice ein eigenes Programm mit eigener Adresse und eigenem Container, das Frontend spricht über HTTP mit ihm. Dieser Aufbau ist der Normalfall in größeren Systemen und Gegenstand von Kapitel 5.

Kriterium	Next.js-Fullstack	Getrennte Anwendungen
Auslieferung	ein Container	zwei Container, zwei Namen im Reverse Proxy
Aufruf der Serverlogik	im selben Prozess	über HTTP, mit CORS und Anmeldung über Systemgrenzen
Schnittstelle	intern, jederzeit änderbar	expliziter Vertrag, dokumentiert und versioniert
Arbeitsteilung	eine Codebasis, viele Berührungspunkte	zwei Verantwortungsbereiche mit klarer Grenze
Betriebsaufwand	gering	spürbar höher
Fehlersuche	ein Log	zwei Logs und die Frage, welche Seite schuld ist

Für eine Einzelperson ist der Fullstack meist die vernünftigere Wahl: weniger Betrieb, mehr Zeit für Funktionen. Ein Dreierteam profitiert vom getrennten Aufbau, weil die Schnittstelle zur Absprache zwingt und beide Seiten unabhängig weiterarbeiten können. Ausschlaggebend ist nicht, welche Variante moderner klingt, sondern welche Sie begründen können.

flowchart LR
  B[Browser] --> P[Reverse Proxy und TLS]
  P --> F[Frontend]
  P --> W[Webservice]
  P --> C[CMS]
  F --> W
  W --> D[(Datenbank)]
  C --> DC[(CMS-Datenbank)]

Zeichnen Sie diese Landschaft für Ihr eigenes Projekt, mit Ihren Namen und Ihrer Aufteilung. Im Fullstack-Fall fallen Frontend und Webservice zu einem Kasten zusammen; alles andere bleibt. Die Skizze wird im Lauf des Jahres fortgeschrieben, jedes Mal, wenn ein Kasten dazukommt.

Was jetzt schon feststehen muss, ist überschaubar: der Wunschname der Domain, die Sprachen der Oberfläche (eine oder zwei, siehe Kapitel 12) und die grobe Größenordnung der Daten, also Dutzende, Tausende oder Millionen Datensätze. Offen bleiben dürfen die konkreten Bibliotheken, die Auswahl des CMS und die Rendering-Strategien. Diese Fragen beantworten die jeweiligen Kapitel, und eine Antwort im September wäre geraten.

Umentscheiden hat ein Ablaufdatum

Der Schnitt lässt sich später ändern, aber nicht beliebig lange. Sobald in Kapitel 6 die Datenbank und in Kapitel 8 die Anmeldung stehen, betrifft ein Wechsel den gesamten Datenzugriff und das gesamte Sitzungsmodell. Wer wechseln will, tut es bis Kapitel 6. Danach wird die einmal getroffene Entscheidung durchgezogen und im Entscheidungsprotokoll begründet.

Repository und Dokumentation

Das Repository wird diese Woche angelegt, mit Struktur, nicht nur mit einer leeren README.md.

projekt/
├── README.md              Was ist das, wie startet man es lokal
├── .env.example           alle benötigten Variablen, ohne Werte
├── docs/
│   ├── architektur.md     Systemskizze, Schnitt, Datenmodell
│   ├── betrieb.md         jeder Eingriff am Server: Datum, Befehl, Grund, Ergebnis
│   ├── entscheidungen.md  das Entscheidungsprotokoll
│   └── haertung.md        Härtungsmaßnahmen mit Nachweis
└── src/

Die README.md beantwortet eine einzige Frage: Wie bringt eine fremde Person dieses Projekt auf ihrem Rechner zum Laufen? Wenn die Antwort länger als eine Bildschirmseite ist, ist das ein Befund über das Projekt und nicht über die Datei.

Das Entscheidungsprotokoll

In docs/entscheidungen.md steht jede Entscheidung, die Sie nicht in einer Minute wieder umdrehen können. Die Form ist bewusst leichtgewichtig, vier Abschnitte genügen:

## 2 - Getrenntes Frontend und Backend

Datum: 2026-09-21
Status: entschieden

### Entscheidung
Frontend (Next.js) und Webservice (Node.js) werden als getrennte Anwendungen
entwickelt, gebaut und ausgeliefert.

### Alternativen
Ein Next.js-Fullstack mit Route Handlers. Weniger Betriebsaufwand, aber im
Dreierteam schwerer aufzuteilen, weil alle in derselben Codebasis arbeiten.

### Begründung
Wir sind zu dritt und wollen die Schnittstelle als Vertrag zwischen zwei Teilen
behandeln. Den Mehraufwand im Betrieb (zwei Container, CORS, zwei Logs) nehmen
wir dafür in Kauf.

### Folgen
- Die Schnittstelle wird ab Kapitel 4 mit OpenAPI beschrieben.
- Die Anmeldung muss über Systemgrenzen funktionieren (Kapitel 8).
- Das Deployment umfasst zwei Container hinter demselben Reverse Proxy.

Das Protokoll wird das ganze Jahr fortgeschrieben und zahlt sich spätestens im Juni aus. Im Abschlussgespräch lautet die Frage regelmäßig „Warum haben Sie das so gemacht?”, und darauf antwortet ein Eintrag von damals besser als eine Erinnerung von heute.

Zusammenarbeit und Geheimnisse

Für die Zusammenarbeit genügt ein kurzer Satz an Regeln.

main bleibt lauffähig. Was dort liegt, muss startbar sein, gearbeitet wird in Branches.

Jede Zusammenführung läuft über einen Merge Request und wird gelesen. Im Team von der jeweils anderen Person; wer allein arbeitet, liest den eigenen Diff am nächsten Tag noch einmal durch und notiert in zwei Sätzen, was geändert wurde und warum.

Commit-Betreffzeilen sind kurz und im Imperativ, mit Bezug zum Issue. Der Unterschied zwischen Fix und Buchung überschneidet sich nicht mehr mit Wartungsfenster (#14) zeigt sich, wenn Sie im Mai eine Änderung suchen.

Geheimnisse bleiben draußen. .env gehört in .gitignore, .env.example mit allen Variablennamen und ohne Werte gehört ins Repository.

Ein committetes Passwort ist verbrannt

Ein Zugangsdatum, das einmal committet wurde, verschwindet nicht dadurch, dass Sie es im nächsten Commit löschen: Es steht in der Historie, und die liegt bei jedem, der das Repository geklont hat. Der einzige wirksame Schritt ist, das Geheimnis zu wechseln, also Passwort ändern, Schlüssel neu erzeugen, Token widerrufen. Diese Regel gilt ab dem ersten Commit dieser Woche, weil sie später niemand nachholt.

Zuletzt die Projekttafel: Die Muss-Geschichten wandern als Issues auf ein Board (GitLab, GitHub oder ein anderes), mit den Akzeptanzkriterien im Text. Damit beantworten Sie die Frage, die im Unterricht wöchentlich kommt: Woran arbeiten Sie gerade, und was ist der nächste Schritt?

Häufige Stolperfallen

1. Thema zu groß gewählt. Im Februar liegt ein halbes System vor, das an drei Stellen unfertig ist. Ein kleines Thema, sauber durchgezogen, ist die bessere Arbeit und die bessere Note.
2. Thema zu klein gewählt. Bei der Datenbankschnittstelle gibt es dann nichts zu modellieren und beim Sicherheits-Review nichts abzusichern.
3. Anforderungen als Featureliste. „Kalenderfunktion” sagt niemandem, wann sie fertig ist. Eine Geschichte mit Akzeptanzkriterien sagt es.
4. Die Architekturentscheidung offenlassen und im Dezember immer noch beide Varianten halb umgesetzt haben.
5. Aufteilung nach Technologie im Team. Am Jahresende kann niemand die andere Hälfte erklären, und genau danach wird gefragt.
6. Dokumentation als Abschlussarbeit gedacht. Wer die Betriebsdokumentation im Juni schreibt, erfindet sie. Wer sie im September beginnt, liest sie im Juni nach.

Lernergebnisse

• Erschaffen: eine Projektidee entwickeln, die Datenbank, Webservice, Frontend, Inhaltsbereich, Betrieb und Rollen abdeckt.
• Beurteilen: ein Thema anhand der Abdeckungskriterien prüfen und begründet annehmen, erweitern oder verwerfen.
• Anwenden: Anforderungen als Nutzergeschichten mit prüfbaren Akzeptanzkriterien formulieren und nach Muss, Soll und Kann priorisieren.
• Anwenden: Entitäten und Beziehungen des eigenen Themas als Skizze darstellen.
• Beurteilen: den Schnitt zwischen Frontend, Webservice und Inhaltsbereich für das eigene Projekt begründen und die Alternative benennen, die verworfen wurde.
• Anwenden: ein Repository mit Dokumentations- und Entscheidungsstruktur aufsetzen und den Umgang mit Geheimnissen von Anfang an richtig einrichten.
• Erklären: begründen, warum ein über das Jahr laufendes System andere Fragen aufwirft als ein einzelnes Übungsbeispiel.

Arbeit am Jahresprojekt

Abgabe am Ende des Kapitels:

• Projektskizze auf einer Seite: Thema, Nutzer, Zweck, Abgrenzung.
• Nutzergeschichten mit Akzeptanzkriterien, davon fünf bis acht als Muss-Set gekennzeichnet.
• Domänenskizze mit Entitäten und Beziehungen.
• Architekturskizze mit Begründung des Schnitts, als erster Eintrag im Entscheidungsprotokoll.
• Angelegtes Repository mit README.md, docs/-Gerüst, .gitignore und .env.example.
• Im Team: die schriftlichen Absprachen zu Aufgaben, Server, Zugriff und Review.

Passende Übungen

• Aufgabe 01 - Team bilden und Projektidee festlegen
• Aufgabe 02 - Nutzergeschichten und Akzeptanzkriterien
• Aufgabe 03 - Repository, Dokumentationsgerüst und erstes Entscheidungsprotokoll