reperio.Parts

Visuelle Ähnlichkeitssuche für CAD-Werkstücke

Status: BETA

---

Überblick

reperio.Parts ist eine Enterprise-Anwendung zur visuellen Ähnlichkeitssuche von CAD-Werkstücken. Die Anwendung kombiniert CLIP-basierte Embeddings mit FAISS-Vektorsuche, um geometrisch und visuell ähnliche Teile in grossen Katalogen zu identifizieren.

Kernfunktionen:

• Visuelle Ähnlichkeitssuche -- CLIP-Embeddings (512-dim, L2-normalisiert) mit stufenlosem Score (0--1)
• Blazor Server UI -- Kachel-Ansicht mit Detail-Sidebar, Tag-System, Feedback-Paare
• 3D BREP-Viewer -- opencascade.js mit Messtools (9 Messmodi), als iframe integriert
• Tag-System -- Manuelle und automatische Tags mit Versionierung, manuell hat Vorrang
• Windows Auth -- AD/SSO mit LDAP-Gruppenprüfung für Unternehmenseinsatz
• Air-Gapped Deployment -- Konzipiert für Windows Server 2019+ ohne Internetzugang (IIS)
• Bild-Upload -- Ähnlichkeitssuche anhand hochgeladener Fotos oder Skizzen

---

Architektur

                                  ┌─────────────────────────────────┐
                                  │          Browser                │
                                  │  Blazor Server + 3D Viewer      │
                                  └───────────┬─────────────────────┘
                                              │
                                              │ SignalR / HTTPS
                                              ▼
┌──────────────────┐   HTTP/REST   ┌─────────────────────────────────┐
│  ML-Service      │ ◄──────────── │  ASP.NET Core 8.0               │
│  (FastAPI)       │ ────────────▶ │  IIS In-Process / Kestrel       │
│                  │               │  Port 5000 (HTTP) / 5001 (HTTPS)│
│  - CLIP          │               │                                 │
│  - FAISS         │               │  - Blazor Server UI             │
│  - Training      │               │  - REST-API (8 Controller)      │
│  Port 8100       │               │  - OData v4                     │
└──────────────────┘               │  - Windows Auth + DevAuth       │
                                   └──────┬──────────┬───────────────┘
                                          │          │
                                          ▼          ▼
                                   ┌───────────┐  ┌──────────────────┐
                                   │ SQLite DB  │  │ CADAnsichten/    │
                                   │ (WAL-Modus)│  │ 3800+ Ordner    │
                                   │ reperio.db │  │ je 7 JPG + .txt │
                                   └───────────┘  └──────────────────┘

3D Viewer: /viewer/ (iframe, gebaut aus reperio-viewer-brep)

• ASP.NET Core = Haupt-Backend (Blazor Server + REST-API + OData)
• ML-Service = Eigenständiger HTTP-Dienst (FastAPI, separates Repository, ADR-011)
• SQLite = Gemeinsame Datenbank im WAL-Modus

---

Tech Stack

Komponente	Technologie	Version
Runtime	.NET	8.0
Web-UI	Blazor Server	8.0
ORM / DB	EF Core SQLite	8.0.11
API-Doku	Swashbuckle (Swagger)	6.9.0
Query	Microsoft.AspNetCore.OData	8.2.5
Auth	Windows Negotiate + LDAP	8.0.11
Bildverarbeitung	SixLabors.ImageSharp	3.1.12
Embedding-Vergleich	System.Numerics.Tensors	9.0.0
LDAP	System.DirectoryServices.AccountManagement	8.0.1

---

Voraussetzungen

• .NET 8 SDK (oder .NET 8 Runtime für Produktion)
• ML-Service -- separates Repository reperio-embedding-service (FastAPI, CLIP, FAISS)
• CADAnsichten-Verzeichnis -- Werkstück-Ordner mit JPG-Ansichten und Attributes.txt
• Optional: Node.js 18+ (nur bei Entwicklung am 3D Viewer, Repository reperio-viewer-brep)

---

Schnellstart (Entwicklung)

# 1. Repository klonen
git clone https://github.com/swissYoshi/reperio-parts.git
cd reperio-parts

# 2. ML-Service starten (separates Repository)
#    Siehe: https://github.com/swissYoshi/reperio-embedding-service
#    Der Service muss auf Port 8100 erreichbar sein.

# 3. ASP.NET Backend starten (Development-Modus mit DevAuth)
cd src/web
dotnet run --project Reperio.Parts.Api --environment Development

# 4. Browser öffnen
#    http://localhost:5000
#    Swagger UI: http://localhost:5000/swagger

Im Development-Modus ist DevAuth aktiv -- es wird keine Windows-Authentifizierung benötigt. Die Rolle kann in appsettings.Development.json konfiguriert werden (Auth.DevRole).

---

Konfiguration

Die Konfiguration erfolgt über appsettings.json mit Environment-spezifischen Overrides:

{
  "ConnectionStrings": {
    "Reperio": "Data Source=./outputs/reperio.db"
  },
  "Catalog": {
    "DataDir": "",              // Pfad zu CADAnsichten (UNC oder lokal)
    "OutputDir": "./outputs"    // Ausgabeverzeichnis (DB, Logs)
  },
  "MlService": {
    "BaseUrl": "http://localhost:8100",
    "TimeoutSeconds": 60,
    "TrainingTimeoutSeconds": 600
  },
  "Auth": {
    "DevMode": false,           // true = DevAuth ohne AD
    "DevRole": "Admin",         // Rolle im DevMode
    "AdGroupViewer": "reperio-viewer",
    "AdGroupAnnotator": "reperio-annotator",
    "AdGroupAdmin": "reperio-admin",
    "CacheMinutes": 5           // Cache für AD-Gruppenabfragen
  },
  "Server": {
    "BaseUrl": "https://localhost:5001"
  }
}

Datei	Zweck
appsettings.json	Basis-Konfiguration (alle Environments)
appsettings.Development.json	Entwicklung: DevAuth, lokale Pfade
appsettings.Production.json	Produktion: Windows Auth, AD-Gruppen

---

Projektstruktur

reperio-parts/
├── src/web/
│   ├── Reperio.Parts.Api/          ASP.NET Web-App (Blazor + REST-API)
│   │   ├── Auth/                   DevAuth, Windows Auth, LDAP, Rollen
│   │   ├── Components/             Blazor Razor Pages und Layouts
│   │   │   ├── Pages/              Home, Admin, Viewer
│   │   │   ├── Search/             Such-Komponenten
│   │   │   ├── Shared/             Wiederverwendbare UI-Komponenten
│   │   │   └── Layout/             App-Layout
│   │   ├── Controllers/            8 REST-Controller + OData
│   │   ├── Data/                   EF Core DbContext, Migrationen
│   │   ├── OData/                  OData-Konfiguration
│   │   ├── Services/               Business-Logik, ML-Client, Scheduler
│   │   └── wwwroot/viewer/         3D Viewer (gebaut aus reperio-viewer-brep)
│   ├── Reperio.Parts.Core/         DTOs, Interfaces, Models, Options
│   ├── Reperio.Parts.Tests/        xUnit Tests
│   └── Reperio.Parts.sln           Solution-Datei
├── docs/                            Architektur, API, Deployment, ADRs
│   └── adr/                        12 Architecture Decision Records
├── deploy/                          PowerShell Setup-Skripte
│   ├── Build-OfflinePackage.ps1    Offline-Paket erstellen (Entwickler)
│   └── Setup-ReperioParts.ps1      Installation auf Zielserver (Systemtechniker)
└── scripts/                         Hilfsskripte

---

API-Übersicht

REST-Controller

Controller	Endpunkte	Beschreibung
SearchController	GET /api/search/bmn/{bmn}, POST /api/search/image	Ähnlichkeitssuche nach BMN oder Bild-Upload
PartsController	GET /api/parts, GET /api/parts/{bmn}, GET /api/suggestions	Werkstück-Katalog und Vorschläge
TagsController	GET /api/tags, POST /api/annotations/tags, ...	Tag-Verwaltung, Annotationen
TrainingController	POST /api/train/clip, GET /api/train/stream	Training starten, SSE-Fortschritt
ImportController	POST /api/import/upload, POST /api/import/scan	Daten-Import und Katalog-Scan
ThumbnailController	GET /api/thumbnails/{bmn}	Werkstück-Vorschaubilder
StepController	GET /api/step/{bmn}	STEP-Dateien für 3D-Viewer
SystemController	GET /api/health, GET /api/status, GET /api/settings	Health-Check, System-Status, Settings

OData

Endpunkt	Beschreibung
/odata/Parts	OData v4 mit $filter, $select, $orderby, $count, $top, $skip

Vollständige API-Dokumentation:

• Swagger UI: /swagger (interaktiv im Browser)
• Detaillierte Spezifikation: docs/api-guide.md

---

Authentifizierung

Drei Rollen mit abgestuften Berechtigungen:

Rolle	Berechtigung	AD-Gruppe (Standard)
Viewer	Suche, Katalog-Ansicht, 3D-Viewer	reperio-viewer
Annotator	+ Tags setzen, Feedback geben	reperio-annotator
Admin	+ Training, Import, Settings, Admin-Seite	reperio-admin

Entwicklung: DevAuth -- konfigurierbare Rolle ohne AD (Auth.DevMode: true)

Produktion: Windows Negotiate + LDAP-Gruppenprüfung (ADR-012). AD-Gruppen sind in appsettings.json konfigurierbar. IIS benötigt sowohl Windows Authentication als auch Anonymous Authentication (ADR-003).

---

Tests

cd src/web && dotnet test

• Framework: xUnit + Moq + InMemory EF Core
• Umfang: ~128 Tests
• Abdeckung: Auth-Policies, Katalog-Service, Feedback, Suche, Scheduler, STEP-Controller, LDAP-Integration

---

Deployment

Aspekt	Detail
Zielplattform	Windows Server 2019+ (Air-Gapped, kein Internet)
Hosting	IIS In-Process
Auth	Windows Negotiate + Anonymous (beide aktiviert)
CLIP-Modell	Offline via HF_HOME-Umgebungsvariable
Build-Skript	deploy/Build-OfflinePackage.ps1 (erstellt Offline-Paket auf Entwickler-PC)
Setup-Skript	deploy/Setup-ReperioParts.ps1 (Installation durch Systemtechniker auf Zielserver)
Dokumentation	docs/deployment-guide.md (10 Kapitel, Troubleshooting, Update-Anleitung)

---

Verwandte Repositories

Repository	Beschreibung	Status
reperio-embedding-service	Python ML-Service (FastAPI, CLIP, FAISS)	Aktiv
reperio-viewer-brep	3D BREP-Viewer (TypeScript, opencascade.js v2)	Aktiv
cad-ml-project	Python ML-Pipeline (Vorgänger, Prototyp)	Archiv

---

Architecture Decision Records (ADRs)

Alle Architekturentscheidungen sind als ADRs dokumentiert unter docs/adr/.

Nr.	Titel	Status
001	Python als Subprocess statt dauerhafter Dienst	Ersetzt durch ADR-011
002	SQLite statt SQL Server	Akzeptiert
003	IIS Windows Auth + Anonymous Auth gleichzeitig	Akzeptiert
004	CLIP CPU-only in Produktion	Akzeptiert
005	Manuelle Tags haben immer Vorrang vor Auto-Tags	Akzeptiert
006	Blazor Server statt SPA-Framework	Akzeptiert
007	Embeddings direkt im Speicher statt FAISS-Server	Akzeptiert
008	CLIP-Modell via HF_HOME statt eingebettet	Akzeptiert
009	3D-Viewer als iframe-Integration	Akzeptiert
010	BREP-Viewer ersetzt einfachen Viewer	Akzeptiert
011	ML-Service als eigenständiger HTTP-Dienst	Akzeptiert (ersetzt ADR-001)
012	LDAP-Abfrage statt Kerberos-Token für AD-Gruppenprüfung	Akzeptiert

---

Dokumentation

Weiterführende Dokumentation unter docs/:

Dokument	Inhalt
architecture.md	System-Architektur, Datenfluss, Komponenten
deployment-guide.md	Deployment auf Windows Server (IIS, Air-Gapped)
api-guide.md	REST-API und OData-Referenz
ui-specification.md	UI-Design, Kacheln, Sidebar, Tag-Cloud
backend-specification.md	Backend-Services, DB-Schema, Auth-Flow
configuration.md	Konfigurationsreferenz (appsettings)
WINDOWS-SETUP.md	Windows-Entwicklungsumgebung einrichten

---

Lizenz

Proprietär -- Interne Unternehmensanwendung.