# 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)
- **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).

```sh
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.