AzuTear
225 lines
9.4 KiB
Markdown
225 lines
9.4 KiB
Markdown
# Nexus – Projektanalyse
|
||
|
||
**Analysestand:** 2026-07-26
|
||
**Repository:** `https://git.noveria.net/bao/nexus.git`
|
||
**Branch / Commit:** `main` / `3bc7622977f4a6c2f2e98ab4aa856a2e45c3cf49`
|
||
**Version im Repository:** `0.2.56` (`v0.2.56-91-g3bc7622`)
|
||
**Urteil:** Gute technische Grundlage, aber wegen zweier P0-Zugriffskontrollrisiken
|
||
und schwerer Frontend-/Responsive-Brüche aktuell nicht produktionsreif.
|
||
|
||
## 1. Kurzfassung
|
||
|
||
Nexus ist deutlich mehr als ein UI-Prototyp: Das Repository enthält ein
|
||
geschichtetes ASP.NET-Core-Backend, eine persistente PostgreSQL-Domäne,
|
||
OpenClaw-Adapter, eine strukturierte Agent-Task-Bridge, eine Vue-Anwendung sowie
|
||
CI-, Deployment-, Backup- und Rollback-Workflows. Die Backend- und
|
||
Operations-Basis ist der stärkste Teil des Projekts.
|
||
|
||
Die aktuelle Produktqualität wird jedoch von vier systemischen Problemen
|
||
bestimmt:
|
||
|
||
1. Die API hat keine globale Authentifizierungsanforderung. Mehrere Controller
|
||
sind dadurch ohne Token erreichbar; darunter befindet sich ein mutierender
|
||
Agent-Command-Endpunkt.
|
||
2. Die öffentlich weitergeleitete Bridge akzeptiert eine bekannte
|
||
`X-Agent-Id` allein als Identitätsnachweis.
|
||
3. Das Frontend besteht aus zwei visuell und technisch auseinanderlaufenden
|
||
Shells. Dashboard-Navigation, Dateninitialisierung und mobile Breakpoints
|
||
sind nicht konsistent.
|
||
4. Die Testabdeckung ist im Backend fokussiert, im Frontend mit einer
|
||
Testdatei aber zu schmal für 18 registrierte Seiten und mehrere kritische
|
||
Interaktionspfade.
|
||
|
||
Die vollständige Bewertung steht in
|
||
[`PROJECT_EVALUATION_2026-07-26.md`](PROJECT_EVALUATION_2026-07-26.md), das
|
||
visuelle Seitenaudit in
|
||
[`audits/2026-07-26/PAGE_AUDIT.md`](audits/2026-07-26/PAGE_AUDIT.md), und die
|
||
Zugriffskontrollanalyse in
|
||
[`SECURITY_SPOT_CHECK_2026-07-26.md`](SECURITY_SPOT_CHECK_2026-07-26.md).
|
||
|
||
## 2. Technischer Bestand
|
||
|
||
| Bereich | Befund |
|
||
|---|---|
|
||
| Umfang | 253 getrackte Dateien |
|
||
| Frontend | Vue 3, TypeScript, Pinia, Vue Router, Vite, Tailwind 4, Lucide |
|
||
| Backend | ASP.NET Core 10, EF Core 10, PostgreSQL 17 |
|
||
| Integration | `IAgentRuntime`, OpenClaw-Adapter, MCP- und HTTP-Task-Bridge |
|
||
| Persistenz | 9 fachliche EF-Core-Migrationen |
|
||
| Betrieb | Docker Compose, Nginx, Traefik, Gitea Actions |
|
||
| Backend-Code | 107 C#-Dateien plus 12 C#-Testdateien |
|
||
| Frontend-Code | 87 Dateien unter `frontend/src`, davon 51 Vue-Dateien |
|
||
| Frontend-Tests | 1 Testdatei mit 2 Tests |
|
||
| CI-Baseline | .NET 10, Node.js 24, pnpm 10.12.1 |
|
||
|
||
## 3. Architektur
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
UI["Vue SPA<br/>Routes, Views, Pinia"] -->|JWT / REST / SSE| API["ASP.NET Core API"]
|
||
API --> CTRL["Controller"]
|
||
CTRL --> SVC["Domain and application services"]
|
||
SVC --> REPO["Repositories / EF Core"]
|
||
REPO --> DB["PostgreSQL"]
|
||
SVC --> RUNTIME["IAgentRuntime"]
|
||
RUNTIME --> OPENCLAW["OpenClaw adapter"]
|
||
GATEWAY["Trusted agent gateway"] -->|Bridge commands| BRIDGE["GatewayBridgeController"]
|
||
BRIDGE --> TASKBRIDGE["ITaskBridgeService"]
|
||
TASKBRIDGE --> REPO
|
||
```
|
||
|
||
### Backend
|
||
|
||
Positiv:
|
||
|
||
- Controller, Services und Repositories sind klar getrennt.
|
||
- Task-Mutationen werden über eine strukturierte
|
||
`ITaskBridgeService`-Fassade gebündelt.
|
||
- EF-Core-Migrationen, Health Checks und DTOs sind vorhanden.
|
||
- JWT-Prüfung validiert Signatur, Issuer, Audience und Laufzeit.
|
||
- Refresh Tokens werden rotiert und gehasht gespeichert.
|
||
- Rate Limiting, CSP und weitere Security Header sind eingerichtet.
|
||
|
||
Risiken:
|
||
|
||
- `AddAuthorization()` besitzt keine Fallback Policy. Sicherheit hängt damit
|
||
vollständig von jedem einzelnen `[Authorize]`-Attribut ab.
|
||
- Das Backend targetiert `net10.0`, aber es gibt kein `global.json`, das die
|
||
erwartete SDK-Familie lokal festlegt.
|
||
- Produktionspfade für Workspace-Mounts und Deployment sind stark an einen
|
||
konkreten Host gekoppelt.
|
||
- Das einmalige Bootstrap-Passwort wird in den Prozess-Logs ausgegeben. Das ist
|
||
operativ bequem, erzeugt aber einen sensiblen Log-Artefakt.
|
||
|
||
### Frontend
|
||
|
||
Positiv:
|
||
|
||
- API-Clients, Stores, Mapper, Views und UI-Komponenten sind grundsätzlich
|
||
getrennt.
|
||
- Es gibt eigenständige Oberflächen für Tasks, Agenten, Memory, Dokumente,
|
||
Security, Incidents, Calendar, Notifications und Settings.
|
||
- Settings und Teile der Legacy-Shell verhalten sich auf kleinen Viewports
|
||
bereits brauchbar.
|
||
|
||
Risiken:
|
||
|
||
- `/dashboard` verwendet `NexusLayout` und `FlowBoard`; fast alle anderen
|
||
Seiten verwenden `AppSidebar`, `AppHeader` und teils `ModuleView`. Das führt
|
||
zu einem sichtbaren Design- und Navigationsbruch.
|
||
- Die neue Sidebar verlinkt `/orchestration`, `/research`, `/hosts` und
|
||
`/costs`, obwohl keine dieser Routen registriert ist. Der Wildcard-Redirect
|
||
maskiert den Fehler und führt zurück zum Dashboard.
|
||
- `AgentDetailView` navigiert über `/team`; auch diese Route existiert nicht.
|
||
- Der Operations Store wird in `App.vue` nur beim ersten Mount aktualisiert,
|
||
wenn zu diesem Zeitpunkt bereits Authentifizierung vorliegt. Nach normalem
|
||
Login bleiben Projects, Models und Activity zunächst leer, bis der Nutzer
|
||
manuell „Refresh“ auswählt.
|
||
- `liveSync.ts` und `live-sync.ts` implementieren denselben Pinia-Store mit
|
||
derselben ID. Das ist ein unnötiger Drift- und Importfehler-Risikofaktor.
|
||
- Task-Daten unterstützen `Critical`; die Prioritätsauswahl in Task Board und
|
||
Task Detail bietet aber nur High, Medium und Low. Ein bestehender
|
||
`Critical`-Wert erscheint deshalb als leere Auswahl.
|
||
- Mehrere sichtbare Controls sind Platzhalter: Suche, „Ask Iris“ und Logout in
|
||
der neuen Dashboard-Shell haben keine vollständige Aktion.
|
||
- Zahlreiche Icon-Buttons besitzen keinen zugänglichen Namen.
|
||
|
||
## 4. Daten- und Produktfluss
|
||
|
||
Der zentrale Betriebsfluss ist sinnvoll modelliert:
|
||
|
||
1. Das Frontend lädt einen Operations-Snapshot und spezialisierte
|
||
Detailressourcen.
|
||
2. Nutzer ändern Projekte und Tasks über authentifizierte API-Routen.
|
||
3. Agenten sollen strukturierte Commands über die Bridge an
|
||
`ITaskBridgeService` senden.
|
||
4. Services validieren Zustände und schreiben über Repositories in PostgreSQL.
|
||
5. Activity- und Live-Updates werden wieder in der Oberfläche dargestellt.
|
||
|
||
Die Schwäche liegt nicht im Domänenfluss, sondern an seinen Grenzen:
|
||
Browser-Authentifizierung, Service-Authentifizierung und UI-Initialisierung
|
||
sind nicht durchgehend als verbindliche Verträge umgesetzt.
|
||
|
||
## 5. Qualität nach Bereich
|
||
|
||
### Architektur und Wartbarkeit
|
||
|
||
Die Backend-Struktur ist nachvollziehbar und erweiterbar. Der aktuelle
|
||
Frontend-Zustand deutet dagegen auf eine laufende V2-Migration ohne klares
|
||
Migrationsende hin. Zwei Shells, tote Routen, ein verwaistes `TeamView` und
|
||
doppelte Stores erhöhen die Änderungs- und Regressionkosten.
|
||
|
||
### Tests
|
||
|
||
Die zwölf Backend-Testdateien decken insbesondere Auth-, Task-, Bridge- und
|
||
MCP-Verhalten ab. Die Frontend-Suite besteht aktuell aus einer Testdatei mit
|
||
zwei Tests. Es fehlen mindestens:
|
||
|
||
- Router- und Navigationsverträge,
|
||
- Store-Hydration nach Login,
|
||
- Critical-Priority-Roundtrip,
|
||
- Keyboard-/Accessible-Name-Prüfungen,
|
||
- Komponenten- und Viewport-Regressionstests,
|
||
- visuelle Smoke-Checks für alle Kernrouten.
|
||
|
||
### CI/CD und Betrieb
|
||
|
||
Die Gitea-Pipeline ist für die Projektgröße gut ausgebaut:
|
||
|
||
- getrennte Backend-, Frontend- und Security-Jobs,
|
||
- Build und Tests vor Deployment,
|
||
- serielles Production Deployment,
|
||
- separate Backup- und Rollback-Workflows.
|
||
|
||
Der Security-Job sucht jedoch nur heuristisch nach Secrets. Er ersetzt weder
|
||
Dependency-/Container-Scanning noch eine Zugriffskontrollprüfung. Außerdem
|
||
deployt ein grüner Push auf `main` automatisch; deshalb müssen P0-Sicherheits-
|
||
und UI-Regressionsgates vor einem Merge verbindlich sein.
|
||
|
||
### Dokumentation
|
||
|
||
README, Phasen-, Architektur- und Betriebsdokumentation sind umfangreich, aber
|
||
teilweise nicht mehr synchron mit dem Code:
|
||
|
||
- README behauptet Authentifizierung für alle `/api/v1`-Operationsrouten, die
|
||
Controller-Attribute erfüllen diesen Vertrag nicht.
|
||
- Frontend-Routen und Komponentenbeschreibungen spiegeln die V2-/Legacy-Mischung
|
||
nicht vollständig.
|
||
- `VERSION` ist `0.2.56`, das Frontend-Paket meldet `0.1.0`, und der aktuelle
|
||
Commit liegt 91 Commits hinter dem letzten Tag.
|
||
|
||
## 6. Validierungsstand
|
||
|
||
Erfolgreich ausgeführt:
|
||
|
||
- `pnpm test`: 1 Datei, 2 Tests bestanden.
|
||
- `pnpm build`: TypeScript-/Vue-Typecheck und Vite-Production-Build bestanden.
|
||
- `dotnet test` im offiziellen .NET-10-SDK-Container: 189 Tests bestanden,
|
||
0 fehlgeschlagen, 0 übersprungen.
|
||
- Browser-Audit aller 18 registrierten Seiten mit repräsentativen lokalen
|
||
API-Fixtures.
|
||
- Responsive Sichtprüfung bei 320, 375, 768, 1024, 1440 und 1920 Pixeln.
|
||
|
||
Nicht als bestanden gewertet:
|
||
|
||
- Kein Live-End-to-End-Test gegen PostgreSQL, OpenClaw, SSE und die
|
||
Produktions-Proxykette.
|
||
- Kein Penetrationstest und keine vollständige WCAG-Konformitätsprüfung.
|
||
|
||
Der Windows-Host stellt direkt nur .NET SDK 9.0.301 bereit. Der erfolgreiche
|
||
Backend-Lauf erfolgte deshalb reproduzierbar im offiziellen
|
||
`mcr.microsoft.com/dotnet/sdk:10.0`-Container.
|
||
|
||
## 7. Empfehlung
|
||
|
||
Nexus sollte nicht neu gebaut werden. Die vorhandene Backend- und
|
||
Operationsbasis ist wertvoll. Sinnvoll ist eine fokussierte
|
||
Stabilisierungsphase:
|
||
|
||
1. Zugriffskontrollen schließen und durch negative Tests absichern.
|
||
2. Eine einzige Frontend-Shell und eine einzige kanonische Navigation festlegen.
|
||
3. Login-Hydration, tote Routen, Critical-Priority und doppelte Stores beheben.
|
||
4. Dashboard und Task Board für 375–1024 px strukturell neu ordnen.
|
||
5. Frontend-Tests und visuelle Route-/Breakpoint-Gates etablieren.
|
||
6. README, Versionierung und SDK-Pinning auf den tatsächlichen Stand bringen.
|