From fdf2d741a12f3a710f01df31e86067792f801598 Mon Sep 17 00:00:00 2001 From: opencode Date: Mon, 3 Aug 2026 22:52:14 +0200 Subject: [PATCH] feat(docs): standalone docs page, Hilfe nav entry, rewritten user guide - docs route renders without the app shell (own header, back-to-app link, theme toggle) - nav entry renamed to Hilfe (de) / Help (en) - reference links now case-insensitive (schema/tag slugs) - handbook rewritten as 17-page user guide with links into the API reference - release notes v0.8.1 added --- .../toolrate/src/components/breadcrumbs.tsx | 25 ----- artifacts/toolrate/src/i18n/locales/de.json | 15 ++- artifacts/toolrate/src/i18n/locales/en.json | 15 ++- artifacts/toolrate/src/pages/docs.tsx | 72 +++++++++---- docs/handbook/administration.md | 90 ++++++++-------- docs/handbook/analytics.md | 46 ++++---- docs/handbook/bewerten.md | 43 ++++++++ docs/handbook/bewertungen.md | 45 -------- docs/handbook/datenmodell.md | 100 ++++++++++-------- docs/handbook/getting-started.md | 35 +++--- docs/handbook/index.md | 50 +++++---- docs/handbook/konto.md | 57 ++++++++++ docs/handbook/kosten.md | 39 +++++++ docs/handbook/papierkorb.md | 45 ++++++++ docs/handbook/plaene.md | 45 ++++++++ docs/handbook/redundanz.md | 42 ++++++++ docs/handbook/tastatur.md | 40 +++++++ docs/handbook/tool-anlegen.md | 67 ++++++------ docs/handbook/tool-bearbeiten.md | 37 +++++++ docs/handbook/tools-finden.md | 71 +++++++++++++ docs/handbook/vergleichen-watchlist.md | 46 -------- docs/handbook/vergleichen.md | 46 ++++++++ docs/handbook/watchlist.md | 38 +++++++ docs/releases/v0.8.1.md | 47 ++++++++ 24 files changed, 833 insertions(+), 323 deletions(-) create mode 100644 docs/handbook/bewerten.md delete mode 100644 docs/handbook/bewertungen.md create mode 100644 docs/handbook/konto.md create mode 100644 docs/handbook/kosten.md create mode 100644 docs/handbook/papierkorb.md create mode 100644 docs/handbook/plaene.md create mode 100644 docs/handbook/redundanz.md create mode 100644 docs/handbook/tastatur.md create mode 100644 docs/handbook/tool-bearbeiten.md create mode 100644 docs/handbook/tools-finden.md delete mode 100644 docs/handbook/vergleichen-watchlist.md create mode 100644 docs/handbook/vergleichen.md create mode 100644 docs/handbook/watchlist.md create mode 100644 docs/releases/v0.8.1.md diff --git a/artifacts/toolrate/src/components/breadcrumbs.tsx b/artifacts/toolrate/src/components/breadcrumbs.tsx index 12f686c..bc4c537 100644 --- a/artifacts/toolrate/src/components/breadcrumbs.tsx +++ b/artifacts/toolrate/src/components/breadcrumbs.tsx @@ -37,31 +37,6 @@ function buildCrumbs(location: string, t: TFunction): Crumb[] { crumbs.push({ label: t("compare.title") }); } else if (location.startsWith("/analytics")) { crumbs.push({ label: t("nav.analytics") }); - } else if (location.startsWith("/docs")) { - crumbs.push({ href: "/docs", label: t("docs.title") }); - const m = location.replace(/^\/docs\/?/, ""); - if (m.startsWith("handbook/")) { - crumbs.push({ href: "/docs/handbook", label: t("docs.guides") }); - const slug = m.replace(/^handbook\//, "").split("#")[0]; - if (slug) crumbs.push({ label: slug }); - } else if (m.startsWith("reference/")) { - crumbs.push({ href: "/docs/reference/endpoints", label: t("docs.reference") }); - const rest = m.replace(/^reference\//, "").split("#")[0]; - if (rest.startsWith("schemas/")) { - crumbs.push({ label: t("docs.schemas") }); - const name = rest.replace(/^schemas\//, ""); - if (name) crumbs.push({ label: name }); - } else { - const tag = rest.replace(/^endpoints\//, ""); - if (tag) crumbs.push({ label: tag }); - } - } else if (m.startsWith("releases/")) { - crumbs.push({ href: "/docs/releases", label: t("docs.releases") }); - const version = m.replace(/^releases\//, "").split("#")[0]; - if (version) crumbs.push({ label: version }); - } else if (m) { - crumbs.push({ label: m }); - } } else if (location.startsWith("/login")) { crumbs.push({ label: t("auth.signIn") }); } diff --git a/artifacts/toolrate/src/i18n/locales/de.json b/artifacts/toolrate/src/i18n/locales/de.json index 5bc3fae..2c3ddb4 100644 --- a/artifacts/toolrate/src/i18n/locales/de.json +++ b/artifacts/toolrate/src/i18n/locales/de.json @@ -12,7 +12,7 @@ "trash": "Papierkorb", "admin": "Admin", "redundancy": "Redundanz", - "docs": "Doku", + "docs": "Hilfe", "search": "Tools suchen…" }, "auth": { @@ -198,7 +198,18 @@ "reference": "API-Referenz", "referenceIntro": "Automatisch aus der OpenAPI-Spezifikation generiert — alle Endpunkte und Datenfelder der aktuellen Version.", "onThisPage": "Auf dieser Seite", - "searchPlaceholder": "Doku durchsuchen…" + "searchPlaceholder": "Doku durchsuchen…", + "backToApp": "Zur App", + "field": "Feld", + "type": "Typ", + "required": "Pflicht", + "description": "Beschreibung", + "status": "Status", + "schema": "Schema", + "parameter": "Parameter", + "noResults": "Keine Treffer", + "fields": "Felder", + "fieldHelpHint": "Hinweis: Formular-Felder verlinken per ?-Icon direkt zu den jeweiligen Zeilen dieser Tabelle." }, "command": { "navigate": "Navigation", diff --git a/artifacts/toolrate/src/i18n/locales/en.json b/artifacts/toolrate/src/i18n/locales/en.json index 9085362..daff754 100644 --- a/artifacts/toolrate/src/i18n/locales/en.json +++ b/artifacts/toolrate/src/i18n/locales/en.json @@ -12,7 +12,7 @@ "trash": "Trash", "admin": "Admin", "redundancy": "Redundancy", - "docs": "Docs", + "docs": "Help", "search": "Search tools…" }, "auth": { @@ -198,7 +198,18 @@ "reference": "API reference", "referenceIntro": "Generated automatically from the OpenAPI spec — all endpoints and data fields of the current version.", "onThisPage": "On this page", - "searchPlaceholder": "Search docs…" + "searchPlaceholder": "Search docs…", + "backToApp": "Back to app", + "field": "Field", + "type": "Type", + "required": "Required", + "description": "Description", + "status": "Status", + "schema": "Schema", + "parameter": "Parameter", + "noResults": "No results", + "fields": "Fields", + "fieldHelpHint": "Note: form fields link via the ? icon directly to the respective rows of this table." }, "command": { "navigate": "Navigate", diff --git a/artifacts/toolrate/src/pages/docs.tsx b/artifacts/toolrate/src/pages/docs.tsx index 238bfb2..ccde318 100644 --- a/artifacts/toolrate/src/pages/docs.tsx +++ b/artifacts/toolrate/src/pages/docs.tsx @@ -3,11 +3,11 @@ import { Link, useLocation } from "wouter"; import { Marked } from "marked"; import DOMPurify from "dompurify"; import { useTranslation } from "react-i18next"; -import { Layout } from "@/components/layout"; import { Skeleton } from "@/components/ui/skeleton"; import { Badge } from "@/components/ui/badge"; import { Input } from "@/components/ui/input"; import { Button } from "@/components/ui/button"; +import { ThemeToggle } from "@/components/theme-toggle"; import { Select, SelectContent, @@ -17,6 +17,7 @@ import { } from "@/components/ui/select"; import { useGetVersion, getGetVersionQueryKey } from "@workspace/api-client-react"; import { + ArrowLeft, BookOpen, CalendarDays, ExternalLink, @@ -27,6 +28,7 @@ import { Search, Server, Tag, + Wrench, type LucideIcon, } from "lucide-react"; @@ -485,15 +487,16 @@ function FieldTypeChip({ type }: { type: FieldType }) { } function FieldTable({ fields }: { fields: Field[] }) { + const { t } = useTranslation(); return (
- - - - + + + + @@ -529,6 +532,7 @@ function FieldTable({ fields }: { fields: Field[] }) { } function SchemaView({ schema }: { schema: SchemaModel }) { + const { t } = useTranslation(); const headings: Heading[] = schema.fields.map((f) => ({ id: f.name, text: f.name, level: 2 })); return (
@@ -540,15 +544,16 @@ function SchemaView({ schema }: { schema: SchemaModel }) {

- Hinweis: Formular-Felder verlinken per ?-Icon direkt zu den jeweiligen Zeilen dieser Tabelle. + {t("docs.fieldHelpHint")}

- + ); } function EndpointTagView({ tag }: { tag: TagGroup }) { + const { t } = useTranslation(); const headings: Heading[] = tag.endpoints.map((e) => ({ id: e.operationId, text: `${e.method} ${e.path}`, @@ -577,16 +582,16 @@ function EndpointTagView({ tag }: { tag: TagGroup }) { {ep.parameters.length > 0 && (
-

Parameter

+

{t("docs.parameter")}

FeldTypPflichtBeschreibung{t("docs.field")}{t("docs.type")}{t("docs.required")}{t("docs.description")}
- - - + + + @@ -623,9 +628,9 @@ function EndpointTagView({ tag }: { tag: TagGroup }) {
Name InTypPflichtBeschreibung{t("docs.type")}{t("docs.required")}{t("docs.description")}
- - - + + + @@ -642,7 +647,7 @@ function EndpointTagView({ tag }: { tag: TagGroup }) { ))} - + ); } @@ -737,12 +742,13 @@ function useDocsSearch(query: string) { } function SearchOverlay({ query, onClose }: { query: string; onClose: () => void }) { + const { t } = useTranslation(); const { results } = useDocsSearch(query); if (!query.trim()) return null; return (
{results.length === 0 ? ( -

Keine Treffer

+

{t("docs.noResults")}

) : ( results.map((r) => ( ; } else if (section === "reference" && param === "endpoints" && path[2]) { - const tag = reference?.tags.find((tg) => tg.name === path[2]); + const tag = reference?.tags.find( + (tg) => tg.name.toLowerCase() === path[2].toLowerCase(), + ); content = tag ? ( ) : refError || (reference && !tag) ? ( @@ -858,7 +866,9 @@ export default function Docs() { ); } else if (section === "reference" && param === "schemas" && path[2]) { - const schema = reference?.schemas.find((s) => s.name === path[2]); + const schema = reference?.schemas.find( + (s) => s.name.toLowerCase() === path[2].toLowerCase(), + ); content = schema ? ( ) : refError || (reference && !schema) ? ( @@ -923,8 +933,28 @@ export default function Docs() { const showSearch = version === null && section !== "releases"; return ( - -
+
+
+
+ + + toolr + + + {t("docs.backToApp")} + + +
+ +
+
+
+ +
{content}
- +
); } diff --git a/docs/handbook/administration.md b/docs/handbook/administration.md index 6c9357c..bdfd844 100644 --- a/docs/handbook/administration.md +++ b/docs/handbook/administration.md @@ -1,61 +1,65 @@ --- -title: Administration & Papierkorb -order: 7 +title: Administration +order: 13 --- -# Administration & Papierkorb +# Administration -Diese Bereiche sind nur für **Administrator:innen** sichtbar und nutzbar. +Der Bereich **Admin** (`/admin`) ist ausschließlich für Admins zugänglich. +Ohne Admin-Rolle erscheint eine Zugriffsverweigerung. -## Nutzerverwaltung +> Oben rechts führt die Schaltfläche **Redundanz-Dashboard** zur automatischen +> Doppelungs-Erkennung (siehe [Redundanz](/docs/handbook/redundanz)). -Unter **Admin → Nutzer** kannst du: +## Tab „Nutzer" -- **Lokale Nutzer anlegen** (Benutzername, Passwort, E-Mail, Rolle, Tier). -- **Rollen/Tier ändern** (`admin`/`user`, `free`/`premium`/`enterprise`). -- **Passwörter zurücksetzen** (nur lokale Nutzer). -- **Nutzer löschen**. +Verwaltung der lokalen Konten. -Zugehörige Endpunkte (Admin-only): +- **Nutzer hinzufügen:** Benutzername (Pflicht), Passwort (mind. 6 Zeichen), + E-Mail (optional), **Rolle** (User/Admin), **Tarif** (Free/Premium/Enterprise). +- **Nutzer bearbeiten:** Rolle, Tarif und (für lokale Konten) ein neues Passwort + setzen. Für OIDC-Konten wird die Passwortverwaltung im Identitätsanbieter + (z. B. Keycloak) angeboten. +- **Nutzer löschen:** Entfernt das Konto endgültig (nicht für das eigene Konto). -- [`GET /users`](/docs/reference/endpoints/users#listusers) -- [`POST /users`](/docs/reference/endpoints/users#createuser) -- [`PATCH /users/{id}`](/docs/reference/endpoints/users#updateuser) -- [`DELETE /users/{id}`](/docs/reference/endpoints/users#deleteuser) -- [`PATCH /users/{id}/password`](/docs/reference/endpoints/users#setuserpassword) +API-Referenz: +[`POST /users`](/docs/reference/endpoints/users#createUser), +[`PATCH /users/{id}`](/docs/reference/endpoints/users#updateUser), +[`DELETE /users/{id}`](/docs/reference/endpoints/users#deleteUser). -## Audit-Log +## Tab „Tools" -Das **Audit-Log** protokolliert sicherheitsrelevante Änderungen (wer hat wann -was geändert). Es ist über -[`GET /audit-logs`](/docs/reference/endpoints/audit#listauditlogs) abrufbar und -filterbar nach Entitätstyp, Entitäts-ID und Limit. +Zentraler Zugriff auf den Tool-Katalog. -## Papierkorb (Trash) +- **Suchen** nach Tools. +- Tools einzeln ansehen, bearbeiten oder in den Papierkorb verschieben. +- **Massenaktion:** mehrere Tools auswählen und in den Papierkorb verschieben + (Bestätigungsdialog; soft gelöschte Tools sind aus allen öffentlichen Ansichten + entfernt und können wiederhergestellt oder endgültig gelöscht werden). -Tools werden nicht sofort gelöscht, sondern zuerst **soft gelöscht** (in den -Papierkorb verschoben): +## Tab „Audit-Log" -- **Liste:** [`GET /tools/trash`](/docs/reference/endpoints/tools#listtrashedtools) -- **In den Papierkorb verschieben:** [`POST /tools/trash`](/docs/reference/endpoints/tools#trashtools) -- **Wiederherstellen:** [`POST /tools/trash/restore`](/docs/reference/endpoints/tools#restoretools) -- **Endgültig löschen (einzeln):** [`DELETE /tools/trash`](/docs/reference/endpoints/tools#deletetrashedtools) -- **Papierkorb leeren:** [`POST /tools/trash/empty`](/docs/reference/endpoints/tools#emptytrash) +Chronologisches Protokoll aller Anlage-, Änderungs- und Löschvorgänge +(max. 100 Einträge): Aktion, Entität + ID, Zeitstempel, ausführende Person und +geänderte Felder. -> Die Aufbewahrungsfrist des Papierkorbs (in Tagen) ist im -> [`VersionInfo`](/docs/reference/schemas/versioninfo)-Schema als -> `trashRetentionDays` verfügbar. +API-Referenz: [`GET /audit-logs`](/docs/reference/endpoints/audit#listAuditLogs). -## Felder im Überblick +## Tab „System" -### User +Versionsinformationen der laufenden Instanz: -| Feld | Typ | Bedeutung | -| --- | --- | --- | -| `id` | integer | Eindeutige Nutzer-ID. | -| `username` | string | Anmeldename. | -| `email` | string? | E-Mail-Adresse. | -| `role` | string | `admin` oder `user`. | -| `tier` | string | `free`, `premium` oder `enterprise`. | -| `authProvider` | string | `local` oder `oidc`. | -| `createdAt` | date-time | Erstellungszeitpunkt. | +- **Version** (z. B. `v0.8.1`), +- **Commit** (7-stelliger SHA, verlinkt zum Repository), +- **Build-Datum**, +- **Papierkorb-Aufbewahrung** („N Tage" oder „Für immer"). + +## Tool-Verknüpfungen (Admin) + +Auf der Detailseite eines Tools kannst du als Admin **Verknüpfungen** +(eigene/„manual" sowie automatisch erkannte) verwalten: + +- **Tool verknüpfen:** Dialog mit Tool-ID, **Beziehungstyp** + (Ähnlich / Ersetzt / Abgelöst durch) und optionalen Notizen. +- Beziehungstypen werden als Badges auf der Detailseite angezeigt. +- Manuelle Verknüpfungen lassen sich per Papierkorb-Icon wieder entfernen. diff --git a/docs/handbook/analytics.md b/docs/handbook/analytics.md index 367228e..ddbbda0 100644 --- a/docs/handbook/analytics.md +++ b/docs/handbook/analytics.md @@ -1,37 +1,33 @@ --- title: Analytics -order: 6 +order: 10 --- # Analytics -Der Bereich **Analytics** fasst die Plattform-Statistiken zusammen — für alle -Nutzer:innen ohne Einschränkung sichtbar. +Der Bereich **Analytics** (`/analytics`) ist ein öffentliches Dashboard mit +Kennzahlen und Diagrammen auf Basis aller Tools und Bewertungen. -## Übersicht +## Kennzahlen (KPI-Karten) -| Widget | Quelle (Endpunkt) | Inhalt | -| --- | --- | --- | -| **Plattform-Kennzahlen** | [`GET /analytics/summary`](/docs/reference/endpoints/analytics#getanalyticssummary) | Gesamtzahl Tools, Bewertungen, Durchschnittswerte, Kategorienzahl. | -| **Top-Tools** | [`GET /analytics/top-tools`](/docs/reference/endpoints/analytics#gettoppertools) | Bestbewertete Tools nach wählbarer Metrik (Nützlichkeit, Bedienbarkeit, kombiniert). | -| **Nach Kategorie** | [`GET /analytics/by-category`](/docs/reference/endpoints/analytics#getanalyticsbycategory) | Kennzahlen je Kategorie. | -| **Verteilung** | [`GET /analytics/rating-distribution`](/docs/reference/endpoints/analytics#getratingdistribution) | Verteilung der Bewertungswerte (optional je Tool). | +- **Anzahl Tools** — wie viele Tools sind im Katalog erfasst. +- **Anzahl Bewertungen** — wie viele Bewertungen wurden insgesamt abgegeben. +- **Aktive Kategorien** — wie viele Kategorien existieren. +- **Durchschnittliche Bewertung** — globaler kombinierter Wert. -## Datenfelder +## Diagramme -### AnalyticsSummary +| Diagramm | Inhalt | +| --- | --- | +| **Top 8 Tools** | Balkendiagramm der Tools mit der höchsten kombinierten Punktzahl (0–5) | +| **Tools je Kategorie** | Radar-Diagramm der Tool-Anzahl pro Kategorie | +| **Punkteverteilung** | Zwei horizontale Balken-Diagramme (Nützlichkeit & Bedienbarkeit) pro Stern | -| Feld | Typ | Bedeutung | -| --- | --- | --- | -| `totalTools` | integer | Anzahl aller Tools. | -| `totalRatings` | integer | Anzahl aller Bewertungen. | -| `avgUsefulness` | number? | Durchschnittliche Nützlichkeit. | -| `avgUsability` | number? | Durchschnittliche Bedienbarkeit. | -| `avgCombined` | number? | Durchschnitt kombinierter Wert. | -| `categoriesCount` | integer | Anzahl der Kategorien. | -| `mostRatedTool` | ToolWithStats | Das meistbewertete Tool. | +Die Diagramme sind interaktiv (Tooltips beim Überfahren). -Vollständige Feldlisten: [`AnalyticsSummary`](/docs/reference/schemas/analyticssummary), -[`TopToolEntry`](/docs/reference/schemas/topptoolentry), -[`CategoryStats`](/docs/reference/schemas/categorystats), -[`RatingDistribution`](/docs/reference/schemas/ratingdistribution). +## API + +- [`GET /analytics/summary`](/docs/reference/endpoints/analytics#getAnalyticsSummary) +- [`GET /analytics/top-tools`](/docs/reference/endpoints/analytics#getTopTools) +- [`GET /analytics/by-category`](/docs/reference/endpoints/analytics#getAnalyticsByCategory) +- [`GET /analytics/rating-distribution`](/docs/reference/endpoints/analytics#getRatingDistribution) diff --git a/docs/handbook/bewerten.md b/docs/handbook/bewerten.md new file mode 100644 index 0000000..a17e48b --- /dev/null +++ b/docs/handbook/bewerten.md @@ -0,0 +1,43 @@ +--- +title: Bewerten +order: 7 +--- + +# Bewerten + +Auf der Detailseite eines Tools kannst du deine Erfahrung teilen. Klicke auf +**Bewertung abgeben** (erfordert ein Konto). + +## Formularfelder + +| Feld | Pflicht | Hinweise | +| --- | --- | --- | +| **Nützlichkeit** | Ja | 1–5 Sterne | +| **Bedienbarkeit** | Ja | 1–5 Sterne | +| **Kommentar** | Nein | Freitext | +| **Name** | Nein | Standard „Anonym" | + +Neben den Feldern führt das **?‑Icon** direkt zur zugehörigen Feldbeschreibung +in der [Datenmodell-Referenz](/docs/reference/schemas/ratinginput). + +## Was passiert nach dem Abgeben? + +- Deine Bewertung wird sofort gespeichert und erscheint in der + **Bewertungsliste** der Detailseite. +- Die **Durchschnittswerte** (Nützlichkeit, Bedienbarkeit, Kombiniert) und die + **Punkteverteilung** werden aktualisiert. +- Die **Statistiken** im Bereich [Analytics](/docs/handbook/analytics) werden + neu berechnet. + +## Statistik-Bereiche auf der Detailseite + +- **Bewertungsübersicht:** Nützlichkeit & Bedienbarkeit als Durchschnitt mit + Fortschrittsbalken. +- **Punkteverteilung:** Anzahl der Bewertungen pro Stern (1★–5★). +- **Verlauf:** Linienchart der kombinierten/Teilwerte über die Zeit + (erst ab mehreren Bewertungen sichtbar). + +## API + +- [`POST /tools/{id}/ratings`](/docs/reference/endpoints/ratings#createRating) — Bewertung abgeben +- [`GET /tools/{id}/ratings`](/docs/reference/endpoints/ratings#listToolRatings) — Bewertungen eines Tools diff --git a/docs/handbook/bewertungen.md b/docs/handbook/bewertungen.md deleted file mode 100644 index ce69ae9..0000000 --- a/docs/handbook/bewertungen.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Bewertungen -order: 4 ---- - -# Bewertungen - -Bewertungen sind das Herz von toolr: Sie zeigen, wie nützlich und wie gut -bedienbar ein Tool in den Augen der Community ist. - -## Wie funktioniert die Bewertung? - -Auf der Detailseite eines Tools vergibst du zwei Werte (1–5 Sterne): - -- **Nützlichkeit** — Wie gut löst das Tool sein Kernproblem? -- **Bedienbarkeit** — Wie einfach ist es zu bedienen? - -Optional kannst du einen **Kommentar** und deinen **Namen** hinterlassen. Die -Eingabefelder entsprechen dem Schema -[`RatingInput`](/docs/reference/schemas/ratinginput). - -## Was passiert mit meiner Bewertung? - -- Deine Bewertung wird sofort gespeichert und in den Durchschnittswerten des - Tools berücksichtigt. -- Jede Bewertung ist über [`GET /tools/{id}/ratings`](/docs/reference/endpoints/ratings#listtoolratings) - abrufbar. -- Der **Rating-Verlauf** über die Zeit ist über - [`GET /tools/{id}/rating-history`](/docs/reference/endpoints/tools#gettoolratinghistory) - einsehbar (grafisch auf der Detailseite). - -## Datenfelder - -Eine Bewertung besteht aus diesen Feldern -([`Rating`](/docs/reference/schemas/rating)): - -| Feld | Typ | Bedeutung | -| --- | --- | --- | -| `id` | integer | Eindeutige ID der Bewertung. | -| `toolId` | integer | ID des bewerteten Tools. | -| `usefulness` | integer (1–5) | Nützlichkeitsbewertung. | -| `usability` | integer (1–5) | Bedienbarkeitsbewertung. | -| `comment` | string? | Optionaler Kommentar. | -| `reviewerName` | string? | Optionaler Anzeigename des Bewerters. | -| `createdAt` | date-time | Zeitpunkt der Bewertung. | diff --git a/docs/handbook/datenmodell.md b/docs/handbook/datenmodell.md index 5a2273f..fb0d996 100644 --- a/docs/handbook/datenmodell.md +++ b/docs/handbook/datenmodell.md @@ -1,60 +1,74 @@ --- -title: Datenmodell & Felder -order: 8 +title: Datenmodell +order: 17 --- -# Datenmodell & Felder +# Datenmodell -Dieses Handbuch erklärt die zentralen Objekte von toolr auf verständliche -Weise. Die **vollständige, maschinell generierte Feld-Referenz** findest du in -der [Referenz](/docs/reference/schemas/tool) — dort sind alle Typen, Pflicht- -angaben und Constraints der aktuellen Version dokumentiert. +Dieses Kapitel erklärt die zentralen Datenobjekte von toolr auf Ebene der +Anwendung. Die vollständige, automatisch generierte Referenz aller Felder, +Typen und Constraints findest du in der +[API-Referenz](/docs/reference/schemas/tool). -> Die Referenz ist **versionsgebunden**: Über das Versions-Dropdown oben -> kannst du ältere API-Stände einsehen. +## Tool -## Die wichtigsten Objekte +Das Herzstück: ein im Katalog erfasstes Werkzeug. -### Tool - -Ein Tool ist der zentrale Eintrag im Katalog -([Feld-Referenz](/docs/reference/schemas/tool)): - -| Feld | Bedeutung | +| Eigenschaft | Beschreibung | | --- | --- | -| `id` | Eindeutige ID. | -| `name` | Anzeigename. | -| `description` | Kurzbeschreibung. | -| `category` | Kategorie-Zuordnung. | -| `websiteUrl` / `iconUrl` | Offizielle Website bzw. Logo-Link (optional). | -| `createdBy` | Nutzer, der das Tool angelegt hat (optional). | -| `features` / `tags` | Listen von Schlüsselfähigkeiten bzw. Schlagwörtern. | -| `createdAt` / `updatedAt` | Zeitstempel. | -| `deletedAt` / `deletedBy` | Soft-Delete-Informationen (Papierkorb). | +| `id` | Eindeutige Kennung | +| `name` | Anzeigename | +| `description` | Beschreibung (Was macht das Tool?) | +| `category` | Kategorie-Zuordnung | +| `websiteUrl` | Offizielle Website (optional) | +| `iconUrl` | Logo-/Icon-URL (optional) | +| `features` | Liste von Fähigkeiten | +| `tags` | Liste von Schlagwörtern | +| `createdAt` / `updatedAt` | Zeitstempel | +| `createdBy` | Erstellende Person | +| `deletedAt` / `deletedBy` | Soft-Löschung (Papierkorb) | -> **ToolWithStats** erweitert `Tool` um die Aggregatwerte `ratingCount`, -> `avgUsefulness`, `avgUsability` und `avgCombined` (siehe -> [Feld-Referenz](/docs/reference/schemas/toolwithstats)). +Eingabe-Formulare verwenden die abgeleiteten Schemas +[`ToolInput`](/docs/reference/schemas/toolinput) und +[`ToolUpdate`](/docs/reference/schemas/toolupdate). +Aggregierte Ansichten liefert [`ToolWithStats`](/docs/reference/schemas/toolwithstats) +(z. B. mit Durchschnittsbewertung). -### Rating +## Rating (Bewertung) -Eine Bewertung (`Rating`) besteht aus `usefulness` und `usability` (jeweils -1–5) sowie optionalem Kommentar und Bewerternamen. Details unter -[Bewertungen](/docs/handbook/bewertungen). +Eine einzelne Bewertung zu einem Tool: -### User / AuthUser +- `usefulness` (Nützlichkeit, 1–5) und `usability` (Bedienbarkeit, 1–5) +- optional `comment` und ein Anzeigename (`reviewerName`) +- Zeitstempel -- **User** (Admin-Sicht): `id`, `username`, `email`, `role`, `tier`, - `authProvider`, `createdAt` — siehe [Administration](/docs/handbook/administration). -- **AuthUser** (Eigenansicht): `sub`, `email`, `name`, `preferredUsername`, - `role`, `tier`, `entitlements`, `isLocal`. +Eingabe-Schema: [`RatingInput`](/docs/reference/schemas/ratinginput). -### VersionInfo +## User & Auth -`GET /version` liefert `version`, `commitSha`, `buildDate` und -`trashRetentionDays` (siehe [Feld-Referenz](/docs/reference/schemas/versioninfo)). +- [`User`](/docs/reference/schemas/user) — Benutzerkonto mit Rolle (User/Admin) + und Tarif (Free/Premium/Enterprise). +- [`AuthUser`](/docs/reference/schemas/authuser) — das angemeldete Profil + inklusive `entitlements` (verfügbare Features). +- [`UserPreferences`](/docs/reference/schemas/userpreferences) — Ansichts- und + Dichte-Präferenzen sowie die `watchlist` (Liste von Tool-IDs). -## Referenz selber durchsuchen +## Analytics -Nutze das **Suchfeld** in der Doku-Seitenleiste: Es durchsucht Handbuch, -Endpunkt- und Feldbeschreibungen und springt direkt zum passenden Anker. +Die Statistik-Endpunkte liefern aggregierte Daten: + +- [`AnalyticsSummary`](/docs/reference/schemas/analyticssummary) — globale + Kennzahlen (Anzahl Tools/Bewertungen, Kategorien, Durchschnitt). +- [`TopToolEntry`](/docs/reference/schemas/TopToolEntry) — ein Eintrag der + Top-Tools.- [`CategoryStats`](/docs/reference/schemas/categorystats) — Tool-Anzahl je + Kategorie. +- [`RatingDistribution`](/docs/reference/schemas/ratingdistribution) — + Punkteverteilung (Nützlichkeit & Bedienbarkeit). +- [`ScoreBucket`](/docs/reference/schemas/scorebucket) — ein Werte-Bucket. + +## Weitere + +- [`VersionInfo`](/docs/reference/schemas/versioninfo) — Version, Commit-SHA, + Build-Datum und Papierkorb-Aufbewahrung der laufenden Instanz. +- [`AuditLog`](/docs/reference/schemas/auditlog) — ein Protokolleintrag + (Aktion, Entität, Zeitstempel, Akteur, Änderungen). diff --git a/docs/handbook/getting-started.md b/docs/handbook/getting-started.md index e1fa460..fe5061c 100644 --- a/docs/handbook/getting-started.md +++ b/docs/handbook/getting-started.md @@ -10,45 +10,48 @@ Besuch bis zum Anlegen und Bewerten eines Tools. ## 1. Anmelden -Die meisten Aktionen (Tool anlegen, bewerten, Watchlist) erfordern ein -Konto. Klicke oben rechts auf **Anmelden**. Je nach Konfiguration der Instanz -hast du zwei Möglichkeiten: +Die meisten Aktionen (Tool anlegen, bewerten, Watchlist, Vergleichen) erfordern +ein Konto. Klicke unten links auf **Anmelden**. Je nach Konfiguration der +Instanz hast du zwei Möglichkeiten: - **Lokale Konten:** Benutzername + Passwort. Der Zugang wird von einem Admin angelegt (siehe [Administration](/docs/handbook/administration)). -- **OIDC (SSO):** Anmelden mit dem konfigurierten Identitätsanbieter. +- **OIDC (SSO):** Anmelden mit dem konfigurierten Identitätsanbieter (z. B. + Keycloak). -Welcher Modus aktiv ist, steht im [Endpunkt -`GET /auth/mode`](/docs/reference/endpoints/auth#getauthmode). +Welcher Modus aktiv ist, steht im Endpunkt +[`GET /auth/mode`](/docs/reference/endpoints/auth#getAuthMode). Details findest +du im Abschnitt [Anmelden & Konto](/docs/handbook/konto). ## 2. Tools finden Öffne den Bereich **Tools durchsuchen**: -- **Suchen** — Volltextsuche über Name & Beschreibung. -- **Filtern** — nach Kategorie, Tags und Features; zusätzlich - Mindestbewertung (`minRating`). +- **Suchen** — Volltextsuche über Name & Beschreibung (Tastenkürzel `/`). +- **Filtern** — nach Kategorie, Tags, Features und Mindestbewertung + (`minRating`). - **Sortieren** — nach Aktualität, Top-Bewertung, meistbewertet, Name (auf-/absteigend) oder letztem Update. -Die Such-, Filter- und Sortierparameter entsprechen den Query-Parametern von -[`GET /tools`](/docs/reference/endpoints/tools#listtools). +Alle Optionen im Detail: [Tools finden & durchsuchen](/docs/handbook/tools-finden). ## 3. Tool anlegen Gehe auf **Tool hinzufügen** und fülle das Formular aus. Details zu jedem Feld -findest du im [Handbuch "Tool anlegen"](/docs/handbook/tool-anlegen) und in der +findest du im Abschnitt [Tool anlegen](/docs/handbook/tool-anlegen) und in der [Feld-Referenz](/docs/reference/schemas/toolinput). ## 4. Bewerten -Auf der Detailseite eines Tools kannst du **Nützlichkeit** und -**Bedienbarkeit** (jeweils 1–5) vergeben und optional einen Kommentar -hinterlassen. Deine Bewertung fließt sofort in die Statistiken ein. +Auf der Detailseite eines Tools kannst du **Nützlichkeit** und **Bedienbarkeit** +(jeweils 1–5) vergeben und optional einen Kommentar hinterlassen. Deine +Bewertung fließt sofort in die Statistiken ein. +Siehe [Bewerten](/docs/handbook/bewerten). ## 5. Weiterführend - [Tools vergleichen](/docs/handbook/vergleichen) - [Watchlist](/docs/handbook/watchlist) - [Analytics](/docs/handbook/analytics) -- [Administration & Papierkorb](/docs/handbook/administration) +- [Pläne & Berechtigungen](/docs/handbook/plaene) +- [Administration](/docs/handbook/administration) diff --git a/docs/handbook/index.md b/docs/handbook/index.md index 941ac5b..adea4d6 100644 --- a/docs/handbook/index.md +++ b/docs/handbook/index.md @@ -16,35 +16,41 @@ die richtige Wahl zu treffen. | --- | --- | --- | | **Tools durchsuchen** | Katalog filtern, sortieren und durchsuchen | Alle | | **Tool anlegen** | Neues Tool mit Beschreibung, Kategorie, Features & Tags eintragen | Angemeldet | +| **Tool bearbeiten/löschen** | Eigene Tools pflegen (Ersteller:in oder Admin) | Angemeldet | | **Bewerten** | Nützlichkeit & Bedienbarkeit (1–5) plus Kommentar vergeben | Angemeldet | -| **Vergleichen** | Tools nebeneinander gegenüberstellen | Premium | | **Watchlist** | Tools als Favoriten speichern | Premium | +| **Vergleichen** | Tools nebeneinander gegenüberstellen | Premium | +| **Kosten erfassen** | Lizenz- und Kostenmodelle je Tool eintragen | Premium | | **Analytics** | Statistiken, Top-Tools, Verteilungen | Alle | -| **Admin** | Nutzerverwaltung, Audit-Log, Papierkorb | Admin | -| **Trash** | Soft-gelöschte Tools wiederherstellen oder endgültig löschen | Admin | +| **Papierkorb** | Soft-gelöschte Tools wiederherstellen oder endgültig löschen | Premium | +| **Admin** | Nutzerverwaltung, Audit-Log, Systeminformationen | Admin | +| **Redundanz** | Automatische Doppelungs-Erkennung | Admin | -## Funktionen & Felder im Detail +## Wie diese Doku aufgebaut ist -Die **Referenz** ist automatisch aus der OpenAPI-Spezifikation generiert und -deckt damit garantiert *alle* Endpunkte und Datenfelder der aktuellen Version -ab: +- **User Guide** (diese Seiten): Schritt-für-Schritt-Anleitungen für alle + Funktionen — von den [Ersten Schritten](/docs/handbook/getting-started) bis + zur [Administration](/docs/handbook/administration). +- **API-Referenz**: automatisch aus der OpenAPI-Spezifikation generiert — alle + [Endpunkte](/docs/reference/endpoints/tools) und + [Datenfelder](/docs/reference/schemas/toolinput) der aktuellen Version. +- **Release-Notes**: Was ist in welcher [Version](/docs/releases/v0.8.1) neu. -- [Endpunkte](/docs/reference/endpoints/tools) — jede API-Operation mit - Parametern und Antwort-Schemas. -- [Datenmodell & Felder](/docs/reference/schemas/tool) — jedes Feld mit Typ, - Pflichtstatus und Bedeutung. +## Der Einstieg -> Die Referenz ist **versionsgebunden**: Wähle oben rechts eine ältere Version, -> um den API-Stand dieses Releases zu sehen. +Der schnellste Weg: -## Erste Schritte +1. **Anmelden** — ohne Konto kannst du nur stöbern + (siehe [Erste Schritte](/docs/handbook/getting-started#1-anmelden)). +2. **Tools finden** — Suche, Filter und Sortierung im Bereich + [Tools durchsuchen](/docs/handbook/tools-finden). +3. **Tool anlegen** — über „Tool hinzufügen" + ([Anleitung](/docs/handbook/tool-anlegen)). +4. **Bewerten** — auf der Detailseite eines Tools + ([Anleitung](/docs/handbook/bewerten)). -- Neu hier? Starte mit dem [Erste-Schritte-Guide](/docs/handbook/getting-started). -- Möchtest du ein Tool eintragen? Siehe [Tool anlegen](/docs/handbook/tool-anlegen). -- Formulare zeigen neben jedem Feld ein **Hilfe-Icon (?)**, das direkt zur - Erklärung des Felds in der Doku springt. +## Kontakt & Quellcode -## Wo ist der Quellcode? - -Über das **Repository-Logo oben rechts** gelangst du direkt zum Quellcode auf -GitHub. +Der Quellcode liegt unter +[git.kubebase.de/admin/tool-evaluator](https://git.kubebase.de/admin/tool-evaluator) — +über das Repository-Icon oben rechts erreichst du ihn jederzeit. diff --git a/docs/handbook/konto.md b/docs/handbook/konto.md new file mode 100644 index 0000000..096e0c9 --- /dev/null +++ b/docs/handbook/konto.md @@ -0,0 +1,57 @@ +--- +title: Anmelden & Konto +order: 3 +--- + +# Anmelden & Konto + +## Anmelden + +Klicke unten links in der Seitenleiste auf **Anmelden**. Je nach Konfiguration +der Instanz: + +- **Lokale Konten:** Benutzername und Passwort eingeben. Die Konten werden von + einem Admin angelegt (siehe [Administration](/docs/handbook/administration)). +- **OIDC (SSO):** Du wirst an den konfigurierten Identitätsanbieter + weitergeleitet und meldest dich dort an. + +Der aktive Modus steht im Endpunkt +[`GET /auth/mode`](/docs/reference/endpoints/auth#getAuthMode). + +> Die Login-Seite erreichst du direkt unter `/login`. Nach erfolgreicher +> Anmeldung wirst du zur ursprünglich aufgerufenen Seite zurückgeleitet. + +## Benutzerprofil + +Dein Profil (Avatar, Name, E-Mail, Tarif) siehst du unten links im +Benutzermenü. Dort stehen dir folgende Aktionen zur Verfügung: + +- **Watchlist** — deine gespeicherten Tools (nur mit dem entsprechenden Tarif). +- **Papierkorb** — wiederherstellbare, gelöschte Tools (Premium/Enterprise). +- **Passwort ändern** — für lokale Konten direkt in toolr; für OIDC-Konten wird + die Passwortverwaltung im Identitätsanbieter angeboten. +- **Abmelden** — beendet deine Sitzung. + +## Passwort ändern (lokales Konto) + +1. Öffne das Benutzermenü unten links. +2. Wähle **Passwort ändern**. +3. Gib das **aktuelle** sowie ein **neues** Passwort ein (mind. 6 Zeichen) und + bestätige es. +4. Speichern — das Passwort wird sofort übernommen. + +API-Referenz: [`POST /auth/me/password`](/docs/reference/endpoints/auth#changeMyPassword). + +## Anzeigeeinstellungen + +Über die Schaltflächen oben rechts kannst du: + +- **Sprache** wechseln (Deutsch / Englisch), +- **Theme** umschalten (Hell / Dunkel / System), +- die **Listenansicht** und **Dichte** im Bereich Tools durchsuchen anpassen + (siehe [Tools finden & durchsuchen](/docs/handbook/tools-finden)). + +Deine Präferenzen (inkl. Watchlist) werden im Endpunkt +[`GET /auth/me/preferences`](/docs/reference/endpoints/auth#getMePreferences) +gespeichert und über [`PUT /auth/me/preferences`](/docs/reference/endpoints/auth#updateMePreferences) +aktualisiert. diff --git a/docs/handbook/kosten.md b/docs/handbook/kosten.md new file mode 100644 index 0000000..ef11774 --- /dev/null +++ b/docs/handbook/kosten.md @@ -0,0 +1,39 @@ +--- +title: Kosten erfassen +order: 12 +--- + +# Kosten erfassen + +Auf der Detailseite eines Tools kannst du Kosten- und Lizenzmodelle eintragen, +damit die Gesamtkosten je Tool transparent werden. + +> Kosten ist ein **Premium-Feature** (`costs`, Premium/Enterprise). Admins +> haben immer Zugriff. + +## Kosten hinzufügen + +Klicke auf **Kosten hinzufügen** im Kosten-Bereich der Detailseite und fülle +das Formular aus: + +| Feld | Hinweise | +| --- | --- | +| **Lizenztyp** | Free / Subscription / One-Time / Usage-Based | +| **Abrechnungszeitraum** | Nur für „Subscription": Monatlich / Quartalsweise / Jährlich | +| **Kosten** | Betrag als Zahl | +| **Währung** | EUR / USD / GBP / CHF | +| **Notizen** | Optionaler Freitext | + +Speichern legt den Eintrag an. Jeder Kosten-Eintrag wird als Karte mit +Lizenz-Badge, Abrechnungszeitraum, Betrag (`Betrag Währung` bzw. „Free") und +Notizen angezeigt. + +## Kosten bearbeiten & löschen + +Beim Überfahren einer Kosten-Karte erscheinen die Aktionen **Bearbeiten** +(Bleistift) und **Löschen** (Papierkorb). + +## API + +Die Kosten-Daten werden über die Tool-Endpunkte verwaltet +(siehe [API-Referenz](/docs/reference/endpoints/tools)). diff --git a/docs/handbook/papierkorb.md b/docs/handbook/papierkorb.md new file mode 100644 index 0000000..e7d4708 --- /dev/null +++ b/docs/handbook/papierkorb.md @@ -0,0 +1,45 @@ +--- +title: Papierkorb +order: 15 +--- + +# Papierkorb + +Der **Papierkorb** (`/trash`) enthält soft gelöschte Tools. Mit Papierkorb-Zugang +können sie wiederhergestellt werden; endgültiges Löschen ist Admins vorbehalten. + +> Der Papierkorb ist ein **Premium-Feature** (`trash`, Premium/Enterprise). +> Admins haben immer Zugriff. + +## Zugang + +Der Papierkorb ist über das Benutzermenü oder die Seitenleiste erreichbar. +Ohne `trash`-Berechtigung erscheint ein Hinweis auf den Tarifwechsel. + +## Wiederherstellen + +- Markiere ein oder mehrere Tools (Checkboxen). +- Klicke auf **Wiederherstellen (N)** — die Tools erscheinen wieder in allen + öffentlichen Ansichten. + +> Wiederherstellen steht jeder Person mit Papierkorb-Zugang zur Verfügung. + +## Endgültig löschen (nur Admin) + +- **Löschen (N)** entfernt die ausgewählten Tools **endgültig** — inklusive + aller Bewertungen, Kosten und Verknüpfungen. Das kann nicht rückgängig + gemacht werden. +- **Papierkorb leeren** entfernt alle soft gelöschten Tools endgültig. + +## Tabelle + +Der Papierkorb listet: Name, Kategorie, **Gelöscht am** (`tt.MM.jjjj HH:mm`), +**Gelöscht von** sowie Aktionen (Wiederherstellen; Löschen nur Admin). Die Suche +filtert nach Namen. + +## API + +- [`GET /tools/trash`](/docs/reference/endpoints/tools#listTrashedTools) — Liste +- [`POST /tools/trash/restore`](/docs/reference/endpoints/tools#restoreTools) — Wiederherstellen +- [`DELETE /tools/trash`](/docs/reference/endpoints/tools#deleteTrashedTools) — Endgültig löschen (Admin) +- [`POST /tools/trash/empty`](/docs/reference/endpoints/tools#emptyTrash) — Papierkorb leeren (Admin) diff --git a/docs/handbook/plaene.md b/docs/handbook/plaene.md new file mode 100644 index 0000000..daac109 --- /dev/null +++ b/docs/handbook/plaene.md @@ -0,0 +1,45 @@ +--- +title: Pläne & Berechtigungen +order: 11 +--- + +# Pläne & Berechtigungen + +toolr unterscheidet **Tarife** (Tier) und **Rollen**. Admins umgehen alle +Feature-Beschränkungen. + +## Tarife + +| Tarif | Beschreibung | +| --- | --- | +| **Free** | Grundfunktionen: suchen, filtern, ansehen, Analytics | +| **Premium** | Zusätzlich Watchlist, Vergleichen, Papierkorb, Kosten | +| **Enterprise** | Alle Premium-Features + erweiterter Support | + +### Feature-Berechtigungen + +Premium/Enterprise schalten folgende Features frei: + +| Feature | Funktion | Mehr erfahren | +| --- | --- | --- | +| `compare` | Tools vergleichen | [Vergleichen](/docs/handbook/vergleichen) | +| `watchlist` | Favoritenliste | [Watchlist](/docs/handbook/watchlist) | +| `trash` | Papierkorb (soft gelöschte Tools) | [Papierkorb](/docs/handbook/papierkorb) | +| `costs` | Kosten-/Lizenzmodelle erfassen | [Kosten erfassen](/docs/handbook/kosten) | + +Fehlt dir ein Feature, zeigt die App einen **Upgrade-Hinweis** mit Link zur +Tarifverwaltung. + +## Rollen + +| Rolle | Berechtigungen | +| --- | --- | +| **User** | Standard-Konto: Tools anlegen/bewerten, eigene Tools bearbeiten | +| **Admin** | Alle User-Rechte + Verwaltung, Audit-Log, Redundanz, Papierkorb leeren, Tool-Verknüpfungen | + +Admins passieren **alle** Feature-Checks — auch ohne Premium-Tarif. + +## Tarif-/Rollenverwaltung + +Die Zuordnung von Rolle und Tarif wird durch Admins im Bereich +[Administration](/docs/handbook/administration) (Tab „Nutzer") verwaltet. diff --git a/docs/handbook/redundanz.md b/docs/handbook/redundanz.md new file mode 100644 index 0000000..9468ead --- /dev/null +++ b/docs/handbook/redundanz.md @@ -0,0 +1,42 @@ +--- +title: Redundanz-Dashboard +order: 14 +--- + +# Redundanz-Dashboard + +Das **Redundanz-Dashboard** (`/admin/redundancy`) ist ein Admin-Werkzeug zur +automatischen Erkennung doppelter oder stark überlappender Tools — jeweils +pro Kategorie — inklusive Kosten- und Bewertungsvergleich. + +> Der Zugriff ist ausschließlich Admins vorbehalten (die API ist +> admin-geschützt). + +## Aufbau + +- **Pro Kategorie** wird eine Gruppe angezeigt: Name der Kategorie, + Anzahl Tools und Vergleiche sowie ggf. die **gesamten monatlichen Kosten** + (z. B. `€X.XX/mo gesamt`). +- Jedes Tool wird als Karte dargestellt: Name, monatliche Kosten, Anzahl der + Bewertungen, kombinierte Bewertung, Lizenz-Badges und Feature-Anzahl. + +## Vergleiche & Empfehlungen + +Für jedes Tool-Paar erscheint: + +- Tool A vs. Tool B, jeweils mit Bewertung (`X.X ★`) und monatlichen Kosten. +- **Überlappung** in Prozent (Fortschrittsbalken in der Mitte). +- Eine **Empfehlung** mit Konfidenz-Farbe: + - **hoch** (grün), **mittel** (gelb), **niedrig** (grau) +- Das empfohlene, bessere Tool wird mit „Daumen hoch" markiert und begründet. + +## Manuelle Bewertung + +Du kannst ein Paar manuell bewerten: Klicke auf Tool A oder Tool B, um +festzuhalten, welches besser ist. Die Auswahl wird gespeichert und die +Darstellung aktualisiert. + +## API + +- [`GET /api/admin/redundancy`](#) — Daten laden (admin-geschützt) +- [`POST /api/admin/redundancy/evaluate`](#) — manuelle Bewertung speichern diff --git a/docs/handbook/tastatur.md b/docs/handbook/tastatur.md new file mode 100644 index 0000000..7d463de --- /dev/null +++ b/docs/handbook/tastatur.md @@ -0,0 +1,40 @@ +--- +title: Tastenkürzel & Kommandopalette +order: 16 +--- + +# Tastenkürzel & Kommandopalette + +## Kommandopalette + +Die Kommandopalette ist die zentrale Schnellnavigation: + +- Öffnen mit **`⌘K`** (macOS) bzw. **`Ctrl+K`** (Windows/Linux). +- Alternativ über die Suchleiste oben rechts („Tools suchen… ⌘K") oder das + Such-Icon auf Mobilgeräten. + +### Leerer Zustand + +Ohne Eingabe zeigt die Palette: + +- **Zuletzt angesehen** — die letzten 5 Tools, die du besucht hast. +- **Navigation** — Tools durchsuchen, Tool hinzufügen, Analytics sowie + (abhängig von Berechtigungen) Watchlist, Papierkorb und Admin. + +### Suche + +Tippe, um live nach Tools zu suchen (max. 10 Ergebnisse, inkl. Bewertung +`X.X★`). + +## Tastenkürzel im Überblick + +| Kürzel | Aktion | +| --- | --- | +| `⌘K` / `Ctrl+K` | Kommandopalette öffnen | +| `/` | Suche im Bereich „Tools durchsuchen" fokussieren | + +## Weitere Hinweise + +- **Zuletzt angesehen** wird lokal im Browser gespeichert (max. 5 Einträge). +- Die Seitenleiste (linke Navigation) ist auf Desktop einklappbar; der + Breadcrumb oben zeigt deinen aktuellen Ort. diff --git a/docs/handbook/tool-anlegen.md b/docs/handbook/tool-anlegen.md index 1381208..e8a2eab 100644 --- a/docs/handbook/tool-anlegen.md +++ b/docs/handbook/tool-anlegen.md @@ -1,49 +1,50 @@ --- -title: Tool anlegen & bearbeiten -order: 3 +title: Tool anlegen +order: 5 --- -# Tool anlegen & bearbeiten +# Tool anlegen -## Neues Tool anlegen +Um ein neues Tool zum Katalog hinzuzufügen, klicke auf **Tool hinzufügen** +(`/tools/new`). Das Anlegen erfordert ein Konto — ohne Anmeldung erscheint ein +Hinweis mit Login-Button. -Unter **Tool hinzufügen** legst du ein neues Tool an. Die Felder entsprechen -dem Eingabeschema [`ToolInput`](/docs/reference/schemas/toolinput): +## Formularfelder -| Feld | Pflicht | Bedeutung | +| Feld | Pflicht | Hinweise | | --- | --- | --- | -| **Name** | ja | Anzeigename des Tools (min. 2 Zeichen). | -| **Beschreibung** | ja | Was tut das Tool, warum nutzen es Leute? (min. 10 Zeichen) | -| **Kategorie** | ja | Zugeordnete Kategorie (aus bestehenden Kategorien wählbar). | -| **Website-URL** | nein | Offizielle Website (`https://…`). | -| **Icon-/Logo-URL** | nein | Direktlink zu einem Logo-Bild. | -| **Features** | nein | Schlüsselfähigkeiten, z. B. „Echtzeit-Kollaboration“. Bereits bekannte Features sind auswählbar. | -| **Tags** | nein | Schlagwörter zum Auffinden. Bereits bekannte Tags sind auswählbar. | +| **Name** | Ja | Mind. 2 Zeichen | +| **Kategorie** | Ja | Auswahlliste; neue Kategorien lassen sich direkt anlegen | +| **Website URL** | Nein | Gültige URL (z. B. `https://...`) | +| **Icon / Logo URL** | Nein | Gültige URL; Vorschau wird live angezeigt | +| **Beschreibung** | Ja | Mind. 10 Zeichen; beschreibe, was das Tool tut | +| **Features** | Nein | Dynamische Liste mit Autovervollständigung (max. 6) | +| **Tags** | Nein | Dynamische Liste mit Autovervollständigung | -> Hinter jedem Label findest du ein **Hilfe-Icon (?)** — es verlinkt direkt -> zur Feldbeschreibung in dieser Doku. +Neben jedem Feld führt das **?‑Icon** direkt zur zugehörigen Feldbeschreibung +in der [Datenmodell-Referenz](/docs/reference/schemas/toolinput). -### Hinweise +### Kategorie -- **Features & Tags** sind Listen. Über **+ Feature / + Tag** fügst du weitere - Einträge hinzu; über das ✕-Symbol entfernst du sie. -- URLs müssen absolut und gültig sein. -- Leere Einträge in Feature-/Tag-Listen werden beim Speichern verworfen. +- Tippe, um nach bestehenden Kategorien zu suchen. +- Wähle **+ Erstelle „..."**, um eine neue Kategorie anzulegen. -## Tool bearbeiten +### Features & Tags -Auf der Detailseite eines Tools öffnet **Bearbeiten** das Formular mit den -aktuellen Werten. Du kannst Name, Beschreibung, Kategorie, URLs, Features und -Tags ändern. Nur angemeldete Nutzer:innen können Tools bearbeiten. +- **Feature hinzufügen** / **Tag hinzufügen** hängt eine neue Zeile an. +- Die Eingabefelder schlagen bestehende Features/Tags vor + (Autovervollständigung, max. 6 Vorschläge). +- Mit dem **×**‑Button entfernst du einzelne Zeilen. +- Features und Tags helfen beim Filtern und Wiederfinden. -## Tool löschen +## Speichern -Über die Detailseite kannst du ein Tool **in den Papierkorb verschieben** -(Soft-Delete). Es verschwindet aus dem Katalog, bleibt aber im Papierkorb -erhalten. Siehe [Administration & Papierkorb](/docs/handbook/administration). +Klicke auf **Tool hinzufügen**. Nach erfolgreicher Anlage wirst du auf die +Detailseite des neuen Tools weitergeleitet. -## Zugehörige Endpunkte +## API -- [`POST /tools`](/docs/reference/endpoints/tools#createtool) — Tool anlegen -- [`PATCH /tools/{id}`](/docs/reference/endpoints/tools#updatetool) — Tool bearbeiten -- [`DELETE /tools/{id}`](/docs/reference/endpoints/tools#deletetool) — Tool löschen +- [`POST /tools`](/docs/reference/endpoints/tools#createTool) — Tool anlegen +- [`GET /categories`](/docs/reference/endpoints/tools#listCategories) — Kategorien +- [`GET /features/all`](/docs/reference/endpoints/tools#listAllFeatures) — Features +- [`GET /tags/all`](/docs/reference/endpoints/tools#listAllTags) — Tags diff --git a/docs/handbook/tool-bearbeiten.md b/docs/handbook/tool-bearbeiten.md new file mode 100644 index 0000000..70d1344 --- /dev/null +++ b/docs/handbook/tool-bearbeiten.md @@ -0,0 +1,37 @@ +--- +title: Tool bearbeiten & löschen +order: 6 +--- + +# Tool bearbeiten & löschen + +## Bearbeiten + +Auf der Detailseite eines Tools findest du die Schaltfläche **Bearbeiten** +(nur für die Person, die das Tool angelegt hat, sowie für Admins). + +Die Bearbeitungsseite (`/tools/:id/edit`) enthält dieselben Felder wie beim +Anlegen (Name, Kategorie, Website/Icon-URL, Beschreibung, Features, Tags) — +bereits mit den aktuellen Werten befüllt. + +- **Speichern** übernimmt die Änderungen. +- **Abbrechen** führt zurück zur Detailseite. + +API-Referenz: [`PATCH /tools/{id}`](/docs/reference/endpoints/tools#updateTool). + +## Löschen + +Über **Löschen** auf der Detailseite wird das Tool entfernt. Das Verhalten +hängt von deinem Tarif ab: + +- **Mit Papierkorb-Zugang** (Premium/Enterprise oder Admin): Das Tool wird + **soft gelöscht** — es verschwindet aus allen öffentlichen Ansichten, kann + aber im [Papierkorb](/docs/handbook/papierkorb) wiederhergestellt oder + endgültig gelöscht werden. +- **Ohne Papierkorb-Zugang:** Das Tool wird **endgültig** gelöscht und kann + nicht wiederhergestellt werden. + +Die Löschung ist nur für die Person, die das Tool angelegt hat, sowie für +Admins möglich. + +API-Referenz: [`DELETE /tools/{id}`](/docs/reference/endpoints/tools#deleteTool). diff --git a/docs/handbook/tools-finden.md b/docs/handbook/tools-finden.md new file mode 100644 index 0000000..6b76e0a --- /dev/null +++ b/docs/handbook/tools-finden.md @@ -0,0 +1,71 @@ +--- +title: Tools finden & durchsuchen +order: 4 +--- + +# Tools finden & durchsuchen + +Der Bereich **Tools durchsuchen** (`/tools`) ist der Einstieg in den Katalog. +Hier kombinierst du Suche, Filter und Sortierung, um genau die Tools zu finden, +die dich interessieren. + +## Suche + +- Die **Suchleiste** durchsucht Name und Beschreibung (Volltext). +- Tastenkürzel: Drücke **`/`**, um die Suche zu fokussieren. +- Die Eingabe ist deaktiviert (Debounce), damit bei jedem Tastendruck sofort + nachgefiltert wird. + +## Filtern + +Über die Schaltfläche **Filter** (mit Badge für die Anzahl aktiver Filter) +öffnest du den Filter-Popover mit: + +- **Tags** — Auswahl über Checkboxen (scrollbare Liste). +- **Features** — Auswahl über Checkboxen. +- **Mindestbewertung** — Schieberegler von 0 bis 5 (Schritte von 0,5); zeigt + z. B. „3.0+" an. + +Aktive Filter erscheinen als **entfernbare Chips** über der Ergebnisliste. +Mit **Filter zurücksetzen** bzw. **Alle entfernen** räumst du sie wieder auf. + +## Sortieren + +Über das Dropdown **Sortieren** stehen folgende Optionen zur Verfügung: + +| Sortierung | Beschreibung | +| --- | --- | +| Neueste | Neue Tools zuerst | +| Top bewertet | Nach kombinierter Bewertung | +| Meistbewertet | Nach Anzahl der Bewertungen | +| Name (A–Z) | Alphabetisch aufsteigend | +| Name (Z–A) | Alphabetisch absteigend | +| Zuletzt aktualisiert | Nach letztem Update | + +## Ansicht & Dichte + +- **Ansicht wechseln:** Raster / Tabelle / Zeilen. +- **Dichte:** gemütlich / kompakt (Schieberegler). + +Deine Auswahl wird gespeichert — lokal im Browser und für angemeldete Nutzer:innen +zusätzlich serverseitig in den Präferenzen. Ansicht, Dichte, Suche, Filter und +Sortierung werden dabei in die URL übernommen, sodass du Ergebnisse teilen +kannst. + +## Tabellenansicht + +In der Tabellenansicht sind die Spalten **Tool**, **Bewertung** und **Anzahl +Bewertungen** sortierbar. Beim Überfahren einer Zeile erscheint eine Vorschau +mit Bewertungsdetails, Tags und Mini-Balken. + +## Auswählen für Vergleich & Watchlist + +- Auf jeder Karte/Zeile findest du ein **Vergleichs-Icon**, mit dem du Tools zur + [Vergleichsleiste](/docs/handbook/vergleichen) hinzufügst. +- Das **Lesezeichen-Icon** speichert Tools in deiner + [Watchlist](/docs/handbook/watchlist) (nur mit dem entsprechenden Tarif). + +## API + +Alle Such-, Filter- und Sortierparameter entsprechen den Query-Parametern von +[`GET /tools`](/docs/reference/endpoints/tools#listTools). diff --git a/docs/handbook/vergleichen-watchlist.md b/docs/handbook/vergleichen-watchlist.md deleted file mode 100644 index a5dc9db..0000000 --- a/docs/handbook/vergleichen-watchlist.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Vergleichen & Watchlist -order: 5 ---- - -# Vergleichen & Watchlist - -Diese Funktionen sind für **Premium-Nutzer:innen** verfügbar. - -## Tools vergleichen - -Mit **Vergleichen** stellst du mehrere Tools nebeneinander und siehst deren -Daten auf einen Blick — ideal für die Tool-Auswahl. - -1. Füge Tools über die **Vergleichsleiste** (Vergleichs-Icon auf Karten) hinzu. -2. Öffne den Bereich **Vergleichen**. Die Tools erscheinen in der gewählten - Reihenfolge. -3. Die Vergleichsansicht zeigt pro Tool die wichtigsten Felder und - Durchschnittswerte. - -Der zugrunde liegende Endpunkt ist -[`GET /compare`](/docs/reference/endpoints/tools#listcomparetools) mit dem -Parameter `ids` (kommagetrennt). Ohne Premium-Berechtigung liefert er `403`. - -## Watchlist - -Die **Watchlist** ist deine persönliche Favoritenliste: - -- **Hinzufügen/Entfernen:** Nutze das Lesezeichen-Symbol auf der - Tool-Karte oder der Detailseite. -- Die gespeicherte Reihenfolge bleibt erhalten. -- Sie wird über [`GET /auth/me/watchlist`](/docs/reference/endpoints/auth#getmewatchlist) - geladen; das Setzen erfolgt über - [`PUT /auth/me/preferences`](/docs/reference/endpoints/auth#updatemepreferences) - (Feld `watchlist`). - -### Feld `watchlist` - -Das Feld `watchlist` in [`UserPreferences`](/docs/reference/schemas/userpreferences) -ist ein Array von Tool-IDs in gespeicherter Reihenfolge: - -| Feld | Typ | Bedeutung | -| --- | --- | --- | -| `view` | string | Ansichtsmodus (`grid`, `table`, `rows`). | -| `density` | string | Dichte (`cozy`, `compact`). | -| `watchlist` | integer[] | Tool-IDs in Favoriten-Reihenfolge. | diff --git a/docs/handbook/vergleichen.md b/docs/handbook/vergleichen.md new file mode 100644 index 0000000..ab0a7ed --- /dev/null +++ b/docs/handbook/vergleichen.md @@ -0,0 +1,46 @@ +--- +title: Vergleichen +order: 9 +--- + +# Vergleichen + +Mit der Vergleichsfunktion stellst du mehrere Tools **nebeneinander** gegenüber — +ideal, um eine fundierte Entscheidung zu treffen. + +> Vergleichen ist ein **Premium-Feature** (Premium/Enterprise) und steht Admins +> immer zur Verfügung. + +## Tools auswählen + +1. Im Bereich **Tools durchsuchen** klickst du auf jeder Karte/Zeile auf das + **Vergleichs-Icon** (Waage). +2. Unten erscheint die **Vergleichsleiste** mit den ausgewählten Tools als + Chips. Du kannst einzelne Tools entfernen (×) oder die Auswahl leeren. +3. Klicke auf **Vergleichen (N)**, um zur Vergleichsansicht zu gelangen. + +> Ohne Premium-Tarif ist der Button gesperrt (Schloss-Icon). Über den +> Dialog gelangst du zum Tarifwechsel +> (siehe [Pläne & Berechtigungen](/docs/handbook/plaene)). + +## Die Vergleichsansicht + +Die Ansicht zeigt eine Tabelle mit einer Spalte pro Tool. Zeilen: + +| Zeile | Inhalt | +| --- | --- | +| **Bewertung** | Sterne + Wert (z. B. `4.2/5`) | +| **Nützlichkeit** | Wert (X.X/5) | +| **Bedienbarkeit** | Wert (X.X/5) | +| **Anzahl Bewertungen** | Anzahl | +| **Beschreibung** | Text | +| **Features** | Badges | +| **Tags** | Badges | +| **Zuletzt aktualisiert** | Datum | + +Der **beste Wert** pro Zeile wird hervorgehoben (mit Trophäen-Icon). + +## API + +Die Vergleichsansicht liest die Daten über +[`GET /compare`](/docs/reference/endpoints/tools#listCompareTools). diff --git a/docs/handbook/watchlist.md b/docs/handbook/watchlist.md new file mode 100644 index 0000000..396d5cb --- /dev/null +++ b/docs/handbook/watchlist.md @@ -0,0 +1,38 @@ +--- +title: Watchlist +order: 8 +--- + +# Watchlist + +Die **Watchlist** ist eine persönliche Favoritenliste. Tools darin kannst du +jederzeit per Klick wieder aufrufen und vergleichen. + +> Die Watchlist ist ein **Premium-Feature** (Premium/Enterprise) und steht +> Admins immer zur Verfügung. + +## Voraussetzung + +Du benötigst einen Tarif mit `watchlist`-Berechtigung. Fehlt diese, erscheint +beim Lesezeichen ein Hinweis auf den Tarifwechsel +(siehe [Pläne & Berechtigungen](/docs/handbook/plaene)). + +## Tool speichern + +- Auf jeder Karte/Zeile im Bereich **Tools durchsuchen** findest du das + **Lesezeichen-Icon**. +- Ein Klick speichert das Tool in deiner Watchlist — das Icon wird gefüllt. +- Ein erneuter Klick entfernt es wieder. + +## Watchlist ansehen + +Öffne die Watchlist über das Benutzermenü oder die Seitenleiste. Sie zeigt alle +gespeicherten Tools als Karten. Das gefüllte Lesezeichen auf einer Karte +entfernt das Tool aus der Liste. + +## Wo wird die Watchlist gespeichert? + +Die Watchlist ist eine Liste von Tool-IDs in deinen **Benutzerpräferenzen**. +Damit ist sie geräteübergreifend mit deinem Konto verbunden. + +API-Referenz: [`GET /auth/me/watchlist`](/docs/reference/endpoints/auth#getMeWatchlist). diff --git a/docs/releases/v0.8.1.md b/docs/releases/v0.8.1.md new file mode 100644 index 0000000..bd5ecb4 --- /dev/null +++ b/docs/releases/v0.8.1.md @@ -0,0 +1,47 @@ +# v0.8.1 — Release Notes + +**Datum:** 2026-08-03 · **Tag:** [`v0.8.1`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.8.1) + +## Neue Features + +- **Standalone-Doku-Seite**: Die Dokumentation steht jetzt als eigene, + mkdocs-artige Seite unter `toolr.kubebase.de/docs` — ohne die App-Shell + (eigene Kopfzeile mit Repo-Link, Versions-Dropdown, Suche, Theme-Umschalter + und Link zurück zur App). +- **Navigation umbenannt**: Der Seitenleisten-Eintrag heißt jetzt **„Hilfe"** + und führt zur Standalone-Doku. +- **User Guide komplett überarbeitet**: 17 Handbuch-Seiten mit + Schritt-für-Schritt-Anleitungen für alle Funktionen (Tools finden, Tool + anlegen, Bewerten, Watchlist, Vergleichen, Kosten, Analytics, Pläne, + Administration, Redundanz, Papierkorb, Tastenkürzel, Datenmodell). + +## Fixes & Verbesserungen + +- Referenz-Links sind jetzt unabhängig von Groß-/Kleinschreibung + (Schema-/Endpoint-Slugs wie `toolinput` und `ToolInput` funktionieren beide). +- Handbuch-Links auf Endpunkt-Anker korrigiert (PascalCase-OperationIds). +- Veraltete, kaputte Handbuch-Links (`vergleichen`, `watchlist` …) ersetzt. +- Dokumentations-Tabellenkopfzeilen und Hinweistexte in der Doku-Seite über + i18n internationalisiert (de/en). + +## API-Änderungen + +- Keine Änderungen an der API. + +## Betrieb / Upgrade + +- **Env-Vars:** unverändert. +- **Migration:** keine. +- **Breaking Changes:** keine. Die Doku-Seite ist unter `/docs` erreichbar wie + bisher; lediglich die Darstellung ist nun eigenständig. + +## Bekannte Einschränkungen + +- Handbuch & Referenz gelten für die aktuelle Version; ältere Versionen zeigen + ihre Release-Notes und einen Referenz-Snapshot, sofern beim Release erzeugt + (`node scripts/src/generate-docs.mjs --snapshot vX.Y.Z`). + +## Links + +- Commit: [``](https://git.kubebase.de/admin/tool-evaluator/commit/) +- Tag: [`v0.8.1`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.8.1)
StatusBeschreibungSchema{t("docs.status")}{t("docs.description")}{t("docs.schema")}