Read-only PRD for a coding agent

Das Schreiben von Laborprotokollen zu einem Praktikumsskript kostet viel Zeit und ist…

18 of 18 sections ready

1. Problem, goal & success metric

Problem: Das Schreiben von Laborprotokollen zu einem Praktikumsskript kostet viel Zeit und ist mühsam (Struktur, Messwerte übertragen, Auswertung).

Ziel: Studierende erstellen Protokolle zu Praktikumsversuchen schneller und strukturierter, ausgehend von einem Versuchsskript.

Erfolgsmessung: Durchschnittliche Zeit pro Protokoll wird gegenüber dem bisherigen Aufwand halbiert.

2. Users & roles

Nutzer: Studierende in einem Hochschul-Praktikum, die nach jedem Versuch ein Protokoll schreiben.

Rollen: Nur Studierende (ein Rollentyp). Dozierende oder Admins sind nicht Teil des ersten Umfangs.

3. Core workflows

Ablauf (flexibel, Versuch zuerst):

Nutzer legt zuerst einen Versuch an, per PDF-Upload mit Prüfansicht oder manuell.
Danach kann er in beliebiger Reihenfolge das Protokoll schreiben, Messwerte erfassen, Diagramme erstellen und exportieren.
Ein Protokoll ohne angelegten Versuch ist nicht möglich.
Ein Protokoll kann als abgeschlossen markiert werden. Nach dem Export bleibt es bearbeitbar, nachdem der Nutzer die Änderung bestätigt hat.
Protokolle und Messdaten bleiben gespeichert, bis der Nutzer sie löscht.

4. Features & requirements

Zitierhilfe (Later): Quellen erfassen und im gewählten Zitierstil in das Protokoll einfügen. Feste Liste der Stile: APA 7, IEEE, Harvard, Chicago, DIN ISO 690, Vancouver. Der Nutzer kann eigene Stile hinzufügen.

5. Scope: must / later / never

Must:

Login per E-Mail und Passwort
Versuch aus PDF-Skript anlegen mit Prüfansicht
Versuch manuell anlegen
Protokoll-Editor mit allen Abschnitten
Messwerttabellen mit manueller Eingabe und CSV-Import
Diagramme aus Messwerttabellen
Export als PDF und Word (.docx)

Later:

Bildannotation (Pfeile, Markierungen, Textnotizen auf Fotos von Versuchsaufbauten und Messgeräten)
Versuchsvorlagen wiederverwenden
Protokoll-Vorlagen (feste Gliederungen für neue Protokolle)
Anhänge an Protokolle (Fotos, Dateien)
Rechtschreibprüfung im Protokoll-Editor (läuft ohne externen Dienst)
Zitierhilfe (Quellen erfassen und im Protokoll einfügen, feste Liste: APA 7, IEEE, Harvard, Chicago, DIN ISO 690, Vancouver; der Nutzer kann eigene Stile hinzufügen)
Weitere Sprachen bei Bedarf

Never:

Rollen für Dozierende oder Admins
Zusammenarbeit mehrerer Studierender an einem Protokoll

6. Screens & UI

Versuchsliste: alle Versuche eines Praktikums, mit Button "Skript hochladen" und "Versuch manuell anlegen".
Skript-Upload und Prüfansicht: PDF auswählen, erkannte Felder anzeigen und bestätigen oder korrigieren.
Versuchsformular: Titel, Ziel, Materialliste, Schritte manuell eingeben (wenn kein Skript vorliegt).
Protokoll-Editor: Abschnitte als Navigation.
Messwert-Ansicht: Tabelle mit manueller Eingabe, CSV-Import-Button und Diagrammansicht.
Exportdialog: PDF oder Word wählen.

7. Design system & visual style

Komponentenbibliothek: Material UI (MUI)
Theme: Dunkel oder hell, vom Nutzer wählbar; Standard dunkel
Primärfarbe: Mitteldunkles Blau, z. B. #1565C0 (vom Nutzer in den Einstellungen änderbar)
Schrift: Standard-Systemschrift von Material UI (Roboto)
Eckenradius: 4 px (MUI-Standard)
Abstände: 8-px-Raster
Sprache: Deutsch als Standard, Englisch umschaltbar
Tonalität: Sachlich und klar, Anrede per Du
Orientierung: Offizielle Material UI Dashboard-Vorlagen

8. Data model

Entität	Feld	Typ	Pflicht
Experiment	id	UUID	ja
Experiment	title	Text	ja
Experiment	goal	Text	ja
Experiment	materials	Text	nein
Experiment	steps	Text	nein
Report	id	UUID	ja
Report	experiment_id	UUID (FK)	ja
Report	cover_data	JSON	nein
Report	sections	JSON	nein
MeasurementTable	id	UUID	ja
MeasurementTable	report_id	UUID (FK)	ja
MeasurementTable	columns	JSON	ja
MeasurementTable	rows	JSON	nein

9. APIs & integrations

Skript-Upload: PDF-Dateien bis 50 MB; daraus werden Titel, Ziel, Materialliste und Durchführungsschritte automatisch ausgelesen und vor dem Speichern vom Nutzer korrigiert oder bestätigt.
CSV-Import: Messwerte aus CSV-Dateien übernehmen (Trenner Komma oder Semikolon, Kopfzeile erforderlich).
Export: Erzeugung von PDF und Word (.docx) ohne externe Dienste.

10. Auth, permissions & security

Login: E-Mail und Passwort, Registrierung mit Hochschul-E-Mail-Domain.
Berechtigungen: Jeder Studierende sieht und bearbeitet nur die eigenen Versuche, Protokolle und Messdaten.
Sicherheit: Passwörter gehasht gespeichert; alle Verbindungen über HTTPS.

11. Performance, privacy & accessibility

Nutzerlast: bis zu 100 gleichzeitige Studierende.
Dateien: Skripte nur als PDF, maximal 50 MB; Messwerte als CSV (beliebige Dateien mit Kopfzeile, Trennzeichen Komma oder Semikolon).
Datenschutz: Protokolle und Messdaten sind nur für den eigenen Account sichtbar.
Zugänglichkeit: Mindestens WCAG 2.1 AA (ausreichende Farbkontraste, vollständige Tastaturbedienung).

12. Edge cases & errors

Skript-PDF ohne erkennbaren Text (gescannt): Nutzer wird informiert und kann Felder manuell ausfüllen.
CSV mit unbekanntem Trennzeichen oder fehlender Kopfzeile: Import wird mit Fehlermeldung abgebrochen.
PDF über 50 MB: Upload wird abgelehnt mit Hinweis auf das Limit.
Messwerte mit fehlenden Zellen: werden als leer übernommen, markiert und im Diagramm als Lücke dargestellt.
Diagramme zeigen fehlende Messwerte als Lücken statt den Diagrammaufbau abzubrechen.

13. Stack & constraints

Frontend: React mit Material UI (MUI)
Backend: Node.js mit Express
Datenbank: PostgreSQL
Dateiablage: Hochgeladene PDF-Skripte (max. 50 MB) und CSV-Dateien werden serverseitig gespeichert.
Hosting: Zunächst lokal auf dem Entwicklungsrechner; serverbasiert mit Benutzerkonten und Login, Daten liegen auf dem Server, nicht nur im Browser.
Begründung: React und Material UI passen zusammen, Node.js/Express und PostgreSQL bilden Benutzerkonten und relationale Daten gut ab und reichen für bis zu 100 gleichzeitige Nutzer aus.

14. Existing code & do-not-change

Not needed: Das Projekt startet komplett neu, es gibt noch keinen bestehenden Code.

15. Build order

Login und Versuchsanlage: Registrierung und Login per E-Mail und Passwort; Versuch manuell oder per PDF-Upload anlegen, Prüfansicht für ausgelesene Felder.
Protokoll-Editor: Abschnitte Deckblatt, Versuchsziel, Materialliste, Durchführung, Auswertung, Diskussion; vorbefüllt aus dem Versuch.
Messwerte und Diagramme: Manuelle Eingabe und CSV-Import, Tabelle mit Spalten und Zeilen, Diagramme mit Achsen und Einheiten.
Export und Abschluss: Protokoll als abgeschlossen markieren, Export als PDF und Word (.docx), Warnung vor Änderungen nach dem Export.

16. Acceptance criteria & tests

Ein Versuch lässt sich nur mit Versuchsanlage (Upload oder manuell) erstellen.
Ein 50-MB-PDF wird akzeptiert, ein 51-MB-PDF abgelehnt.
Ein CSV-Import akzeptiert beliebige CSV-Dateien mit Kopfzeile (Trennzeichen Komma oder Semikolon) und übernimmt Spalten- und Zeilenanzahl automatisch.
Ein Diagramm aus einer Messwerttabelle zeigt Achsen, Einheiten und Beschriftung.
Ein Diagramm mit fehlenden Messwerten zeigt die Lücken, ohne abzubrechen.
Ein exportiertes PDF und Word-Dokument enthalten alle sieben Protokollabschnitte.
Nach dem Export fragt die App vor jeder Änderung nach einer Bestätigung.
Protokolle sind nach Login nur für den eigenen Account sichtbar.
Ein Protokoll lässt sich als abgeschlossen markieren und bleibt nach dem Export nach Bestätigung bearbeitbar.
Die Oberfläche ist per Tastatur vollständig bedienbar und erfüllt WCAG 2.1 AA (Farbkontraste).

17. Deployment, environments & secrets

Umgebung: Vorerst nur lokal auf dem Entwicklungsrechner, kein Test- oder Produktivsystem und kein öffentliches Hosting.
Secrets: Lokale Konfigurationsdatei (.env), nicht im Repository.
Später: Ein Test- oder Produktivsystem mit Hosting wird bei Bedarf in einem späteren Schritt ergänzt.

18. Open questions & assumptions

Offen: Wie gut die automatische Erkennung aus PDF-Skripten sein muss, und was bei gescannten PDFs ohne Text passiert.
Default: Die Bildannotation, Versuchs- und Protokoll-Vorlagen, Anhänge, Rechtschreibprüfung und Zitierhilfe sind Later.