Copilot Instructions — itc.pidi-3-docs

LaTeX-Dokumentation für PidI 3 (Praktikum in der Industrie, 3. Durchlauf) von Linus Nagel, ITC Dortmund / WorkSimple GmbH.

Status: Das Repository ist noch leer (kein Commit auf main). Struktur, Klasse und Build-Setup werden aus ~/repos/itc.pidi-2-docs übernommen. Dort nachschlagen, bevor etwas neu erfunden wird.

Projektinhalt

Thema: Houston „Dokumente" — ein kundenseitiger Dokumentenbereich im Kundenportal Houston (ASP.NET Core, Razor Pages), der Dokumente aus einem S3-Speicher (NetApp StorageGRID, betrieben von Advanced Unibyte) ausliefert. Kernthemen: Document Explorer, Suche (S3 SelectObject), Typfilter, Icons, PDF-Preview-Modal, Einzel- und ZIP-Download, Share-Link-Previews, .url-Dateien, Pagination, automatische Anlage der Kundenordnerstruktur, Kundenordner-Lookup über Efecte-Namen.

Zentraler Architekturkonflikt (in der Doku als Problemstellung relevant): Houston autorisiert über die Efecte Company-ID, das CSM pflegt S3-Ordner aber über den Kundennamen; S3 bietet keinen Lookup über Metadatenfelder.

Quellenlage: Zettelkasten

Sämtliches Rohmaterial (Teams-Nachrichten, E-Mails, Azure-DevOps-Items) liegt in ~/zettelkasten/Notes/. Einstieg ist immer die Hubnote note-1779659534579.md („Praktikum in der Industrie - PIDI 3"). Von dort verlinkt:

note-1787656700350 — chronologische Teams-/E-Mail-Absprachen
note-1787657238720 — Azure-DevOps-Historie: Feature 484, PBIs 9294–10134, PRs 2154–2196, Chronologie und Beteiligte; verlinkt Einzelnoten pro PBI/PR mit Original-Kommentaren, Review-Diskussionen und einem Abschnitt „Erkenntnisse für die Doku"
Session-Notizen zu Absprachen, Feature-Analyse und S3-Recherche

Noten sind über note-<id>.md verlinkt; IDs immer per Dateiname auflösen, nicht raten. Inhalte aus Notizen sind Primärquelle — keine Projektfakten, Namen oder Daten erfinden.

Formale Anforderungen (PidI 3)

10 ECTS, 24 Manntage / 192 Arbeitsstunden (doppelt so viel wie PidI 1/2) (In diesem Projekt: etwa 26.07.2026 bis 21.08.2026 für die Implementierung)
mindestens 40 Seiten Kerninhalt (Verzeichnisse zählen nicht mit)
Die \confirmationpage in pidi-thesis.cls nennt in PidI 2 noch „12 Manntage" — für PidI 3 auf 24 anpassen. Ebenso \course (Default Praktikum in der Industrie (PidI 1)).
Abgabedateiname: <Nachname> PidI 3 <Kurzform des Titels>.pdf

Build

Nix + direnv (.envrc = use nix), shell.nix liefert TeX Live, latexrun, mermaid-cli und Times Newer Roman (wird per shellHook nach ~/.local/share/fonts/ kopiert — Fontconfig findet den Nix-Store-Pfad sonst nicht).

direnv allow          # einmalig
latexmk               # .latexmkrc: lualatex ($pdf_mode=4), biber, $out_dir=out
latexmk -c            # aufräumen

Ausgabe landet in out/; out/, .direnv/ sind gitignored.
minted wird verwendet → LuaLaTeX braucht Shell-Escape (-shell-escape), sonst brechen die Code-Listings.
.biber.conf zeigt Biber auf out/ als In- und Output-Verzeichnis.

Struktur & Konventionen

main.tex              Einstieg: Metadaten + \input aller Kapitel
pidi-thesis.cls       erzwingt das komplette Layout — Formatierung gehört hierhin, nicht in Kapitel
frontmatter/          abstract, acknowledgments, usage-of-ai
chapters/<teil>/*.tex je eine Datei pro \section
appendix/             appendix.tex bündelt tables/diagrams/pics/code
figures/code/*.cs|...  Quelltext-Ausschnitte als echte Dateien (kein inline-Code)
references.bib        biblatex/biber

Kapitelgliederung aus PidI 2 (als Vorlage weiterverwenden): company → overview → execution (preparation, requirements, backlog, implementation, testing, releases, time-man) → closure (evaluation, outlook) → Anhang.

Sprache: Deutsch (\selectlanguage{ngerman}), sachlich-formal, Vergangenheitsform.
Kapiteldateien beginnen mit \section{...} + \label{sec:...}; Nummerierung und Reihenfolge steuert ausschließlich main.tex.
Label-Präfixe: sec:, fig:, tab:, chap:.
\emph{} ist auf fett umdefiniert — kursiv gibt es nicht.
Bezeichner, Klassen, Dateinamen im Fließtext in \texttt{}; # in C# escapen (C\#).
Code-Listings: Datei unter figures/code/ ablegen und im Anhang per \captionof{listing}{...} + \label{fig:...} + \inputminted[breaklines, fontsize=\small]{<lang>}{...} in einer center-Umgebung einbinden, getrennt durch \vfill. Im Fließtext nur per Abbildung~\ref{fig:...} referenzieren.
Tabellen: tabularx + booktabs (\toprule/\midrule/\addlinespace/\bottomrule), [H].
frontmatter/usage-of-ai.tex ist Pflicht und muss die tatsächliche KI-Nutzung wahrheitsgemäß auf die erlaubten Zwecke (LaTeX-Syntax, Umformulierung eigener Inhalte) eingrenzen.

4.8 KiB Raw Blame History Unescape Escape