Eine Web-App mit dem AI Unified Process bauen

Die Vision prüfen #

Die Vision ist das einzige Artefakt, das Sie selbst schreiben. Alles Weitere wird daraus generiert.

Für dieses Tutorial liegt die Vision bereits unter docs/vision.md bereit; öffnen Sie sie und lesen Sie sie, bevor Sie weitermachen. Sie ist die Quelle der Wahrheit für jeden folgenden Schritt. Halten Sie sie kurz; eine Seite reicht: das Problem, die Lösung, die Zielnutzer, die Ziele und die Nicht-Ziele.

Anforderungskatalog generieren #

Dieser Skill liest docs/vision.md, stellt bis zu fünf Rückfragen, wo die Vision eine Entscheidung offenlässt, und produziert einen strukturierten Anforderungskatalog in docs/requirements.md sowie die Fachbegriffe in docs/glossary.md. Der Katalog enthält:

• Funktionale Anforderungen als User Stories (Als Mitglied möchte ich den Katalog durchsuchen, damit ich ein Buch finde, ohne die Bibliothekarin zu fragen).
• Nicht-funktionale Anforderungen (Performance, Usability, Wartbarkeit).
• Rahmenbedingungen (der Tech-Stack aus der README, die Nicht-Ziele aus der Vision, ...).

Prüfen Sie den Katalog, bevor Sie weitermachen; das ist Ihre letzte Gelegenheit, kostengünstig nachzusteuern. Jeder spätere Schritt baut auf dieser Liste auf.

Entitätsmodell aufbauen #

Aus den Anforderungen identifiziert der Skill die Domänenentitäten und schreibt docs/entity_model.md: ein Mermaid-ER-Diagramm der Entitäten, ihrer Beziehungen und Kardinalitäten sowie eine Attributtabelle pro Entität mit Datentypen, Länge oder Genauigkeit und Validierungsregeln (Pflichtfelder, Längen, Eindeutigkeit).

Für die Book Library erwartet Sie etwa Folgendes:

• Book (id, title, author, isbn, copies)
• Member (id, user_id, name, email) – ein Mitglied der Bibliothek, 1:1 mit einer bestehenden app_user-Zeile verknüpft.
• Loan (id, book_id, member_id, borrowed_at, returned_at)

Die Entität AppUser (id, username, password_hash, role, created_at) gehört zum Starterprojekt und muss nicht im Entitätsmodell auftauchen; behandeln Sie sie als externe Grenze.

Architektur festhalten #

Vor der ersten Zeile Code hält der Skill fest, welcher Layer-Skill jede technische Schicht baut und testet. Er erkennt Flyway, jOOQ, Spring Boot und Vaadin an der pom.xml und am Quellbaum des Starterprojekts und schreibt die Stack-Datei nach docs/architecture/stack.md. Die Stack-Datei enthält:

• Die Schichtentabelle Migration mit /flyway-schema, Persistenz mit /jooq-persistence, Service mit /spring-service, UI mit /vaadin-flow-ui, den Test-Skill jeder Schicht, die einen hat, und die E2E-Schicht mit /vaadin-e2e-test
• Die Tabelle der Integrationsschicht wo ein Use Case getestet wird, je Einstiegsschicht: einer, den die UI anbietet, in der UI, deren Browserless-Tests im Prozess gegen die echte Datenbank laufen, und einer, den nur der Service anbietet, etwa ein zeitgesteuerter Job, im Service
• Der E2E-Umfang Use cases and test cases: Jeder über die UI angebotene Use Case erhält auch einen Browsertest; mit Test cases only entstehen Browsertests nur für die Journeys
• Modulaufbau und Befehle wo der Code jeder Schicht liegt und wie man ihn baut und testet

Das Starterprojekt bringt bereits ein docs/architecture.md mit seinen Package-Konventionen mit; der Skill liest es als Eingabe und lässt es, wo es ist; die Stack-Datei liegt neben dem Architekturdokument des Teams. Diesen Schritt führen Sie einmal pro Projekt aus und danach nur, wenn sich eine Schicht ändert. Prüfen Sie die Datei wie jedes andere Artefakt: Die Schritte zum Implementieren und Testen lesen sie.

Use-Case-Diagramm zeichnen #

Der Skill erzeugt aus den Anforderungen ein PlantUML-Use-Case-Diagramm unter docs/use_cases.puml. Es zeigt die beiden Akteure (Member, Librarian) und die Use Cases, an denen sie beteiligt sind:

Nutzen Sie das Diagramm zur Abdeckungsprüfung: Jede Anforderung sollte mindestens einem Use Case zugeordnet sein, und jeder Use Case sollte auf eine Anforderung zurückführbar sein.

Erste Use-Case-Spezifikation schreiben #

Wählen Sie den Use Case, der die anderen freischaltet, zuerst. Für die Book Library ist das UC-001 Katalog durchsuchen; er hat keine Vorbedingungen, gibt dem Mitglied sofort etwas zu tun und liefert die Datenstrukturen, die UC-002 braucht.

Der Skill schreibt docs/use_cases/UC-001-search-catalog.md mit primärem und sekundären Akteuren, Auslöser, den verknüpften Anforderungen, Vorbedingungen, dem Hauptablauf als nummerierte Schritte, Alternativabläufen, Nachbedingungen für Erfolg und Misserfolg und Geschäftsregeln (BR-001, …). Sie beginnt mit Status: Draft.

Use Case implementieren #

Hier zahlt sich die Kette aus. Der Skill liest die Use-Case-Spezifikation, die verlinkten Anforderungen, das Entitätsmodell und die Stack-Datei, fragt Lücken in der Spezifikation in einer Runde ab und führt dann die Layer-Skills von unten nach oben aus. Jede Schicht übergibt die Typen und Methoden, die sie angelegt hat, an die nächste:

• /flyway-schema schreibt ein versioniertes Flyway-Skript unter src/main/resources/db/migration/. Da das Starterprojekt bereits V001__create_app_user.sql enthält, ergänzt es eine neue Version (z. B. V002__create_member_book_loan.sql) mit den Tabellen, Primär- und Fremdschlüsseln (inklusive member.user_id → app_user.id) sowie den NOT-NULL-, UNIQUE- und CHECK-Constraints aus dem Entitätsmodell.
• /jooq-persistence schreibt ein jOOQ-basiertes Repository (BookRepository) gegen die Klassen, die jOOQ aus der Migration generiert, und projiziert die Ergebnisse in Java-Records.
• /spring-service schreibt den Service mit den Transaktionsgrenzen und den Geschäftsregeln des Use Case.
• /vaadin-flow-ui schreibt die Vaadin-View (SearchCatalogView), an MainLayout angebunden und direkt mit dem Service verbunden.

Zwischendurch führt der Skill den Build aus, damit die jOOQ-Klassen aktuell sind, bevor das Repository entsteht. Tests schreibt er keine. Starten Sie die App über TestApplication aus Ihrer IDE oder mit ./mvnw spring-boot:test-run auf der Kommandozeile, melden Sie sich als alice / alice an und öffnen Sie den Katalog. Er ist noch leer: Kein Use Case legt bisher Bücher an, und die produktiven Migrationen enthalten keine Demodaten, deshalb sehen Sie die Leer-Meldung aus der Spezifikation. Die Bücher kommen mit den Testdaten des nächsten Schritts.

Tests für den Use Case schreiben #

Der Skill testet den Use Case einmal, in der Integrationsschicht. Bei Vaadin Flow ist das die UI, also schreibt /vaadin-flow-ui-test unter src/test/java die Klasse UC001SearchCatalogTest, die die AbstractBrowserlessTest des Starters erweitert, einen SpringBrowserlessTest mit der Testcontainers-Datenbank. Sie steuert die View ohne Browser, aber gegen den echten Service und die echte Datenbank: zur View navigieren, Suchfeld und Grid finden, eine Anfrage eintippen, prüfen, dass das Grid die erwarteten Zeilen zeigt, und jeden Alternativablauf und jede Geschäftsregel der Spezifikation abdecken. Jede Testmethode trägt @UseCase(id = "UC-001"), die Testdaten landen in einer wiederholbaren Migration, src/test/resources/db/migration/R__uc001_search_catalog.sql, die Flyway ohne Profil und ohne @TestPropertySource neben den Produktionsmigrationen findet. Sobald diese Testdaten den Katalog füllen, lässt sich der Ablauf mit leerem Katalog mit ihnen nicht mehr herstellen; seine Testmethode ist deshalb mit @Transactional annotiert, löscht die Bücher innerhalb der Testtransaktion und prüft die Meldung für den leeren Katalog; der Rollback stellt die Testdaten wieder her.

Mit dem E2E-Umfang Use cases and test cases endet derselbe Lauf mit der E2E-Schicht und schreibt auch gleich den End-to-End-Test des nächsten Schritts.

Weil diese Tests durch alle darunterliegenden Schichten laufen, bekommen Repository und Service keine eigenen Tests. Ausführen mit ./mvnw test. Die Tests sind schnell, unter einer Sekunde pro Test, und bilden die innere Feedback-Schleife beim Iterieren an der View.

Starten Sie TestApplication jetzt erneut (oder ./mvnw spring-boot:test-run): Sie läuft auf dem Test-Classpath und lädt deshalb dieselben Testdaten aus src/test/resources/db/migration, also können Sie eine Suchanfrage eingeben, die Filterung des Grids sehen und die Ergebnisse so sortiert vorfinden, wie es die Spezifikation verlangt.

End-to-End-Test ausführen #

Mit dem E2E-Umfang Use cases and test cases hat der /use-case-test-Lauf aus Schritt 8 den Browsertest bereits geschrieben: /vaadin-e2e-test hat einen Playwright + Drama Finder Test erzeugt, UC001SearchCatalogIT, der AbstractBasePlaywrightIT erweitert. Er bootet die komplette Spring-Boot-App auf einem zufälligen Port und steuert einen echten Browser durch den Use Case: App mit frischer Datenbank starten, über die Login-View anmelden, Katalogseite öffnen, Suchanfrage eintippen und prüfen, dass die sichtbaren Zeilen der Spezifikation entsprechen. Der Ablauf mit leerem Katalog bekommt keinen Browsertest: Die laufende App hat einen einzigen Datensatz, und der Browserless-Test deckt ihn bereits ab.

./mvnw verify führt die Browserless-Tests und danach die Integrationstests aus. Das ist Ihre äussere Feedback-Schleife: langsamer als die Browserless-Tests, beweist aber, dass JavaScript, CSS, Routing und Datenbank zusammenspielen. Um nur den Browsertest zu schreiben oder abzugleichen, etwa nach einer Änderung an der View, führen Sie /use-case-test UC-001 e2e aus; mit dem E2E-Umfang Test cases only verlangen Sie so überhaupt erst einen Browsertest für einen Use Case.