reperio Developer Guide

Regelwerk, Checklisten und Cookbook fuer die Entwicklung von reperio-Modulen -- interne Enterprise-Tools fuer die Fertigung bei thyssenkrupp.

---

Zweck

Dieses Repository enthaelt projektuebergreifende Standards und Patterns, die bei der Entwicklung von reperio-Modulen gelten. Die Regeln wurden aus ueber 8 Entwicklungsphasen von reperio.Parts (visuelle Aehnlichkeitssuche fuer CAD-Werkstuecke) extrahiert und verallgemeinert.

Zielgruppe: Entwickler (Mensch und KI-Agent), die neue reperio-Module aufbauen oder bestehende erweitern. Jeder KI-Agent (Claude, Copilot, etc.) muss diese Regeln als verbindlich behandeln.

Kontext:

• Interne Enterprise-Anwendungen fuer Fertigungsumgebungen
• Technologie-Stack: ASP.NET Core (C#) + Python (ML/FastAPI) + TypeScript (3D-Viewer)
• Deployment auf Air-Gapped Windows Server (kein Internet-Zugang)
• Corporate Design: thyssenkrupp AppFactory Guideline
• Authentifizierung: Windows Negotiate (AD-Gruppen) in Produktion

---

Verzeichnisstruktur

reperio-dev-guide/
|
|-- README.md                          Dieses Dokument
|
|-- onboarding/
|   |-- onboarding-domain.md           KI-Onboarding: Domaene, Organisation, Prozesse
|   |-- onboarding-technical.md        KI-Onboarding: Architektur, Code-Patterns, Technik
|   |-- samples/
|       |-- FAUF.pdf                   Beispiel-FAUF (Fertigungsplan, 3 Seiten)
|       |-- ZG_2220221_000_.pdf        Beispiel-Zeichnung (Adapter, SolidWorks)
|
|-- standards/
|   |-- development-rules.md           Kern-Regelwerk fuer alle reperio-Module
|   |-- naming-conventions.md          Namenskonventionen (C#, Python, TypeScript)
|   |-- security-checklist.md          Sicherheits-Checkliste fuer Reviews
|
|-- patterns/
|   |-- mqtt-event-bus.md              MQTT Event-Bus Architektur-Evaluation
|   |-- sse-protocol.md                Server-Sent Events Protokoll-Spezifikation
|   |-- auth-hierarchy.md              Auth-Modell (Rollen, AD-Gruppen, Policies)
|   |-- settings-cascade.md            Settings-Prioritaet (DB > Config > Default)
|   |-- atomic-writes.md               Atomic Write Pattern fuer persistente Daten
|   |-- air-gapped-deployment.md       Deployment-Patterns fuer Offline-Server
|
|-- checklists/
|   |-- new-module.md                  Checkliste: Neues reperio-Modul aufsetzen
|   |-- new-controller.md             Checkliste: Neuen ASP.NET Controller anlegen
|   |-- pre-deployment.md             Checkliste: Vor dem Deployment
|   |-- code-review.md                Checkliste: Code-Review Kriterien
|
|-- cookbook/
|   |-- csharp-gotchas.md             Bekannte Fallstricke in C# / ASP.NET / EF Core
|   |-- python-gotchas.md             Bekannte Fallstricke in Python / FastAPI
|   |-- typescript-gotchas.md         Bekannte Fallstricke in TypeScript / Vite
|   |-- sqlite-multi-service.md       SQLite mit mehreren Services (WAL, Concurrency)
|
|-- templates/
|   |-- adr-template.md               Vorlage fuer Architecture Decision Records
|   |-- claude-md-template.md         Vorlage fuer CLAUDE.md (projektspezifisch)

Hinweis: Noch nicht alle Dateien existieren. Die Struktur ist das Ziel. standards/development-rules.md ist das primaere Dokument und sofort nutzbar.

---

Schnelleinstieg

1. Neuer KI-Agent / Entwickler? Mit dem Onboarding starten:

   • onboarding-domain.md -- Firma, Branche, Prozesse, Rollen
   • onboarding-technical.md -- Architektur, Code-Patterns, Deployment
   • samples/ -- Echte Beispiel-Dokumente (FAUF, Zeichnung)

2. Pflichtlektuere: standards/development-rules.md -- das Kern-Regelwerk fuer alle reperio-Module.

3. Bei neuem Modul: Checkliste checklists/new-module.md durcharbeiten.

4. Bei Architekturentscheidung: ADR erstellen (Template unter templates/adr-template.md), im selben Commit wie die Implementierung.

5. Bei UI-Aenderungen: Corporate Design pruefen (Brand Blue nur als Akzent, Light Theme, Segoe UI).

---

Herkunft

Die Regeln stammen aus der Entwicklung von reperio.Parts, das ueber 8 Phasen gewachsen ist:

Phase	Inhalt
1	CLIP-Embeddings (512-dim, L2-normalisiert)
2	FAISS-Suche + Flask Web-UI
2.5--2.7	Feedback-System, UI-Redesign, Auto-Tagging
3	C# ASP.NET Backend (Blazor Server + REST-API)
4.1--4.3	Training-Controller, SSE, OData, Swagger
5	Bild-Upload, Windows Auth, Admin-Settings
6	Import, Scheduler
7	Deployment-Dokumentation + Setup-Skripte
8--8.1	3D-Viewer-Integration (STEP/BREP, opencascade.js)

Jede Phase hat Lessons Learned produziert, die in diesem Guide konsolidiert sind. Projektspezifische Details (Datenformat, BMN-Schema, Bildauswahl-Kette) verbleiben im jeweiligen Projekt-Repository.

---

Prinzipien

• Planen vor Implementieren. Kein Code ohne bestaetigten Plan.
• Inkrementell. Kleine Schritte, haeufige Commits, keine grossen Rewrites.
• Why, not What. Kommentare begruenden Entscheidungen, beschreiben nicht den Ablauf.
• Sicherheit zuerst. OWASP Top 10, keine Credentials in Code oder Logs.
• Offline-faehig. Alles muss auf Air-Gapped Servern funktionieren.
• Keine KI-Spuren in Git. Kein Co-Authored-By, kein KI-Mention.

---

Verwandte Repositories

Repository	Beschreibung
reperio-parts	Visuelle Aehnlichkeitssuche (C# Backend + Blazor UI)
reperio-embedding-service	ML-Service (CLIP, FAISS, FastAPI, Python)
reperio-viewer-brep	3D-STEP-Viewer (opencascade.js v2, TypeScript)
reperio-works	NC-Programmverwaltung + Fertigungswissen (Konzeptphase)

---

Mitarbeit

Ergaenzungen und Korrekturen sind willkommen. Dabei gelten die gleichen Regeln wie fuer reperio-Module: Branch pro Aenderung, Commit-Messages auf Deutsch, keine KI-Hinweise in Git.