initial scaffold: structure, build setup, chapter stubs, diagrams

figures/diagrams/ado-workflow.mmd

@@ -0,0 +1,10 @@
+stateDiagram-v2
+    [*] --> New
+    New --> ToApprove : Linus reicht PBI ein
+    ToApprove --> Approved : Approval-Team
+    Approved --> Committed : Sprint-Planung
+    Committed --> DevCompleted : PR gemerged
+    DevCompleted --> TestCompleted : Abnahme bestanden
+    TestCompleted --> [*]
+    ToApprove --> Removed : Verworfen
+    Removed --> New : Wiederhergestellt

figures/diagrams/auth-sequence.mmd

@@ -0,0 +1,18 @@
+sequenceDiagram
+    participant B as Browser
+    participant H as Houston
+    participant AAD as Entra ID
+    participant S3 as S3-Speicher
+
+    B->>H: GET /documents
+    H->>H: Prüfe Claim Documents.Read
+    alt Keine Rolle
+        H-->>B: 403 Forbidden
+    else Rolle vorhanden
+        H->>H: Lese efecte:company_id aus Claim
+        H->>S3: ResolveCustomerPrefixAsync(orgId)
+        S3-->>H: Kundenordner-Prefix
+        H->>S3: ListObjectsV2(prefix)
+        S3-->>H: Objektliste
+        H-->>B: Documents-Seite
+    end

figures/diagrams/gantt-plan.mmd

@@ -0,0 +1,18 @@
+gantt
+    title Zeitplanung PidI 3 (Sprints 15–17.2026)
+    dateFormat YYYY-MM-DD
+    section Planung
+        Feature-Analyse          :done, 2026-06-18, 1d
+        Anforderungen & Backlog  :done, 2026-07-07, 5d
+    section Sprint 15.2026
+        Document Explorer        :done, 2026-07-27, 5d
+        Icons & Suche            :done, 2026-08-01, 12d
+        Downloads & PDF-Modal    :done, 2026-08-15, 7d
+    section Sprint 16.2026
+        Typfilter & Pagination   :done, 2026-08-18, 4d
+        Ordner-Lookup            :active, 2026-08-17, 8d
+    section Sprint 17.2026
+        Race Conditions (10070)  :2026-08-26, 5d
+    section Qualitätssicherung
+        Abnahmetest              :done, 2026-08-13, 12d
+        Release                  :2026-08-26, 3d

figures/diagrams/lookup-flow.mmd

@@ -0,0 +1,10 @@
+flowchart TD
+    A[ResolveCustomerPrefixAsync\norgId, orgName] --> B{Fast-Path:\nGetObjectMetadata\nslug-name/}
+    B -->|Gefunden & ID passt| Z[✓ Fertig\n1 Request]
+    B -->|Nicht gefunden oder\nID passt nicht| C{Kollisions-Fast-Path:\nslug-name orgId /}
+    C -->|Gefunden| Z2[✓ Fertig\n2 Requests]
+    C -->|Nicht gefunden| D[Fallback: O-n\nListObjectsV2 alle\nTop-Level-Prefixes]
+    D -->|Ordner mit\npAssender ID gefunden| E[Rename auf\nkanonischen Namen]
+    E --> Z3[✓ Fertig\nnächster Lookup O-1]
+    D -->|Kein Ordner| F[Anlegen: Ordner +\nUnterstruktur 9560]
+    F --> Z4[✓ Fertig\nSeite leer]

figures/diagrams/module-components.mmd

@@ -0,0 +1,29 @@
+classDiagram
+    class DocumentsPage {
+        +OnGetAsync()
+        +OnGetDownloadAsync()
+        +OnGetZipAsync()
+    }
+    class DocumentsService {
+        +ListDocumentsAsync(orgId, search, type, token)
+        +GetDownloadUrlAsync(orgId, key)
+        +GetZipStreamAsync(orgId, keys)
+        +ResolveCustomerPrefixAsync(orgId, orgName)
+    }
+    class S3DocumentsClient {
+        -IAmazonS3 _s3
+        +ListObjectsAsync(prefix, delimiter, token)
+        +GetObjectMetadataAsync(key)
+        +GetPresignedUrlAsync(key)
+    }
+    class OrgSlug {
+        +Slugify(name) string
+    }
+    class S3Settings {
+        +BucketName string
+        +ServiceUrl string
+    }
+    DocumentsPage --> DocumentsService
+    DocumentsService --> S3DocumentsClient
+    DocumentsService --> OrgSlug
+    S3DocumentsClient --> S3Settings

figures/diagrams/race-condition-a.mmd

@@ -0,0 +1,15 @@
+sequenceDiagram
+    participant A as Request A
+    participant S3 as S3-Speicher
+    participant B as Request B
+
+    Note over A,B: Ordner AltName/ mit 200 Objekten, Zielname: Kunde GmbH/
+    A->>S3: CanClaim(Kunde GmbH) → Missing → true
+    B->>S3: CanClaim(Kunde GmbH) → Missing → true
+    A->>S3: Kopiere 200 Objekte nach Kunde GmbH/
+    B->>S3: Kopiere Objekte #1–60 nach Kunde GmbH/
+    A->>S3: DeleteObjects(AltName/*) ✓
+    B->>S3: Kopie #61 → NoSuchKey ✗
+    B->>S3: catch: DeleteObjects(copiedKeys #1–60)
+    Note over S3: 60 Objekte aus Kunde GmbH/ gelöscht!
+    Note over S3: AltName/ existiert nicht mehr → Datenverlust

figures/diagrams/s3-layout.mmd

@@ -0,0 +1,9 @@
+flowchart TD
+    B[(S3-Bucket\ndocuments-houston-prod)]
+    B --> KA["Kunde A/\n[meta: efecte_org-id=42]"]
+    B --> KB["Kunde B/\n[meta: efecte_org-id=77]"]
+    KA --> D1[doc1.pdf\nuntyped]
+    KA --> T1["Service-Protokoll/"]
+    KA --> T2["Vertragsunterlagen/"]
+    T1 --> D2[bericht-2026-07.pdf]
+    T2 --> D3[SLA-2026.pdf]

figures/diagrams/system-context.mmd

@@ -0,0 +1,18 @@
+flowchart LR
+    subgraph Kunde
+        K[Kundenportal\nHouston]
+    end
+    subgraph WorkSimple
+        H[Houston\nASP.NET Core]
+        F[Filestash\nS3-Browser]
+    end
+    subgraph Infrastruktur
+        E[Efecte\nCMDB]
+        S3[(S3-Speicher\nStorageGRID)]
+        AAD[Microsoft\nEntra ID]
+    end
+    K -->|HTTPS| H
+    H -->|REST| E
+    H -->|AWS SDK| S3
+    H -->|OpenID Connect| AAD
+    F -->|S3-API| S3

figures/diagrams/timeline-infra.mmd

@@ -0,0 +1,10 @@
+%%{init: {'theme': 'base'}}%%
+timeline
+    title Infrastrukturbeschaffung S3-Speicher
+    2026-07-22 : Service Request erstellt (Maschinenraum)
+    2026-07-23 : Request Alexander Wagner zugewiesen
+    2026-07-27 : 3 Buckets durch AU erstellt, Credentials in Passbolt
+    2026-07-30 : Anfrage S3 Select + Search Integration
+    2026-08-04 : Lennart Meinert kontaktiert AU
+    2026-08-07 : S3 Select für alle 3 Buckets aktiviert
+    2026-08-17 : Search Integration von AU abgelehnt

figures/diagrams/zip-stream.mmd

@@ -0,0 +1,15 @@
+sequenceDiagram
+    participant B as Browser
+    participant P as PageModel
+    participant S as DocumentsService
+    participant S3 as S3-Speicher
+
+    B->>P: POST /documents?handler=Zip&keys=[...]
+    P->>S: GetZipStreamAsync(orgId, keys)
+    loop je Dokument
+        S->>S3: GetObjectAsync(key)
+        S3-->>S: Stream
+        S->>S: ZipArchive.CreateEntry + CopyToAsync
+    end
+    S-->>P: ZipStream
+    P-->>B: application/zip (streaming)