From 6d231ee8bf35d02177359b19caeb984521c3a4f2 Mon Sep 17 00:00:00 2001 From: Till JS Date: Tue, 24 Mar 2026 12:30:58 +0100 Subject: [PATCH] docs: document ManaScore extended metrics and add to root CLAUDE.md Update about page with Score Trend, Lighthouse, Dependency Health, API Conformity, and Cross-App Consistency documentation. Add ManaScore section to root CLAUDE.md for discoverability. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 32 ++++++++++ .../landing/src/content/manascore/about.md | 61 +++++++++++++++++++ 2 files changed, 93 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index bd74f5104..81b71efe5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -676,6 +676,38 @@ pnpm dev:landing-builder See `services/mana-landing-builder/CLAUDE.md` for full documentation. +## ManaScore (Production Readiness) + +ManaScore is the internal quality assessment system for all ManaCore apps. Each app is rated on a 0-100 scale across 8 categories plus extended metrics. + +**Location:** `apps/manacore/apps/landing/src/content/manascore/` +**Live:** https://manacore-landing.pages.dev/manascore +**Methodology:** https://manacore-landing.pages.dev/manascore/about + +### Core Categories (8) + +Backend, Frontend, Database, Testing, Deployment, Documentation, Security, UX + +### Extended Metrics + +| Metric | Description | +|--------|-------------| +| **Score Trend** | Historical score changes with sparkline visualization | +| **Lighthouse** | Performance, Accessibility, Best Practices, SEO | +| **Dependency Health** | Outdated packages, vulnerabilities by severity | +| **API Conformity** | 7 checks (responses, errors, pagination, versioning, docs, health, validation) | +| **Cross-App Consistency** | Shared package usage (auth, ui, theme, branding, i18n, error-tracking) | + +### Maturity Levels + +| Level | Score | Meaning | +|-------|-------|---------| +| Prototype | 0-25 | Proof of concept | +| Alpha | 26-50 | Basic functionality | +| Beta | 51-70 | Functional with gaps | +| Production | 71-85 | Stable, deployable | +| Mature | 86-100 | Fully production-ready | + ## Server Access ### Mac Mini Production Server diff --git a/apps/manacore/apps/landing/src/content/manascore/about.md b/apps/manacore/apps/landing/src/content/manascore/about.md index a3809433a..01ab955df 100644 --- a/apps/manacore/apps/landing/src/content/manascore/about.md +++ b/apps/manacore/apps/landing/src/content/manascore/about.md @@ -159,6 +159,67 @@ Bewertet die User Experience und Accessibility. --- +## Erweiterte Metriken + +Zusätzlich zu den 8 Kern-Kategorien erfasst der ManaScore weitere Metriken, die auf der Detail-Seite jeder App angezeigt werden. + +### Score-Trend + +Zeigt die Entwicklung des Gesamtscores über Zeit als Sparkline-Chart (Übersicht) oder Area-Chart (Detail). Jede Score-Änderung wird in der `history` gespeichert. + +### Lighthouse Scores + +Direkt von Google Lighthouse übernommene Werte in 4 Kategorien: + +| Kategorie | Beschreibung | +| ------------------ | ----------------------------------------------------- | +| **Performance** | Ladezeit, First Contentful Paint, Time to Interactive | +| **Accessibility** | ARIA, Kontraste, Keyboard-Navigation, Screenreader | +| **Best Practices** | HTTPS, keine Deprecated APIs, Error Logging | +| **SEO** | Meta Tags, Crawlbarkeit, Mobile-Friendly | + +### Dependency Health + +Automatisierbar per `pnpm outdated` und `pnpm audit`: + +| Metrik | Beschreibung | +| ------------------- | ---------------------------------------------------------------- | +| **Total** | Gesamtanzahl der Abhängigkeiten | +| **Outdated** | Pakete mit verfügbaren Updates | +| **Vulnerabilities** | Aufgeschlüsselt nach Schweregrad (Critical, High, Moderate, Low) | +| **Health %** | Anteil aktueller Pakete: `(total - outdated) / total * 100` | + +### API Conformity + +Prüft 7 Konsistenz-Kriterien der Backend-API: + +| Check | Beschreibung | +| ------------------------- | ------------------------------------------------------- | +| **Konsistente Responses** | Alle Endpoints nutzen `ApiResult` Format | +| **Error Codes** | Konsistente HTTP Status Codes (400, 401, 403, 404, 500) | +| **Pagination** | Offset/Cursor-basierte Pagination wo nötig | +| **Versioning** | API-Versionierung via `/api/v1/` | +| **Dokumentation** | Swagger/OpenAPI automatisch generiert | +| **Health Endpoint** | `/health` Endpoint vorhanden | +| **Validation** | DTO-Validation mit class-validator auf allen Inputs | + +### Cross-App Consistency + +Misst wie konsequent eine App die shared Packages des Monorepos nutzt: + +| Package | Typ | Beschreibung | +| ----------------------- | -------- | ----------------------------------------------------------- | +| `shared-auth` | Core | JWT-Authentifizierung via mana-core-auth | +| `shared-ui` | Core | Gemeinsame UI-Komponenten (Modal, ContextMenu, Toast, etc.) | +| `shared-theme` | Core | Theme-System (Dark/Light, Varianten) | +| `shared-branding` | Core | App-Icons, Farben, URLs | +| `shared-i18n` | Core | Internationalisierung (Sprach-Utilities) | +| `shared-error-tracking` | Core | GlitchTip Error Tracking | +| `shared-storage` | Optional | S3/MinIO Datei-Upload (nur wenn relevant) | +| `shared-llm` | Optional | LLM-Integration (nur wenn AI-Features) | + +--- + ## Reifegradstufen | Stufe | Score | Bedeutung |