Compare commits
7 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 opencode
|
a65e2eb92c | ||
|
opencode
|
b886246808 | ||
|
opencode
|
3bb4598d04 | ||
|
opencode
|
d23990e322 | ||
|
opencode
|
33cf261777 | ||
|
opencode
|
56f1edd613 | ||
|
opencode
|
fdf2d741a1 |
@@ -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") });
|
||||
}
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
import { BookOpen } from "lucide-react";
|
||||
import { Link } from "wouter";
|
||||
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
|
||||
|
||||
export function GuideHelp({
|
||||
guide,
|
||||
label,
|
||||
}: {
|
||||
guide: string;
|
||||
label: string;
|
||||
}) {
|
||||
return (
|
||||
<Tooltip>
|
||||
<TooltipTrigger asChild>
|
||||
<Link
|
||||
href={`/docs/handbook/${guide}`}
|
||||
target="_blank"
|
||||
rel="noreferrer"
|
||||
aria-label={`Help: ${label}`}
|
||||
data-testid={`guide-${guide}`}
|
||||
className="inline-flex shrink-0 text-muted-foreground hover:text-foreground transition-colors"
|
||||
>
|
||||
<BookOpen className="h-3.5 w-3.5" />
|
||||
</Link>
|
||||
</TooltipTrigger>
|
||||
<TooltipContent>{label} — Anleitung in der Dokumentation</TooltipContent>
|
||||
</Tooltip>
|
||||
);
|
||||
}
|
||||
@@ -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",
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -6,6 +6,7 @@ import {
|
||||
GetTopToolsMetric
|
||||
} from "@workspace/api-client-react";
|
||||
import { Layout } from "@/components/layout";
|
||||
import { GuideHelp } from "@/components/guide-help";
|
||||
import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
|
||||
import { Skeleton } from "@/components/ui/skeleton";
|
||||
import {
|
||||
@@ -48,7 +49,10 @@ export default function Analytics() {
|
||||
<Layout>
|
||||
<div className="space-y-6 pb-10">
|
||||
<div>
|
||||
<h1 className="text-3xl font-bold tracking-tight mb-2">Platform Analytics</h1>
|
||||
<h1 className="text-3xl font-bold tracking-tight mb-2 flex items-center gap-2">
|
||||
Platform Analytics
|
||||
<GuideHelp guide="analytics" label="Platform Analytics" />
|
||||
</h1>
|
||||
<p className="text-muted-foreground">Macro-level insights into tool performance and community engagement.</p>
|
||||
</div>
|
||||
|
||||
|
||||
@@ -8,6 +8,7 @@ import { Link, useSearch } from "wouter";
|
||||
import { Layout } from "@/components/layout";
|
||||
import { useAuth } from "@/hooks/use-auth";
|
||||
import { RatingStars } from "@/components/rating-stars";
|
||||
import { GuideHelp } from "@/components/guide-help";
|
||||
import { Badge } from "@/components/ui/badge";
|
||||
import { Button } from "@/components/ui/button";
|
||||
import { Skeleton } from "@/components/ui/skeleton";
|
||||
@@ -101,7 +102,10 @@ export default function Compare() {
|
||||
<Layout>
|
||||
<div className="space-y-6 pb-10">
|
||||
<div>
|
||||
<h1 className="text-3xl font-bold tracking-tight mb-2">{t("compare.title")}</h1>
|
||||
<h1 className="text-3xl font-bold tracking-tight mb-2 flex items-center gap-2">
|
||||
{t("compare.title")}
|
||||
<GuideHelp guide="vergleichen" label={t("compare.title")} />
|
||||
</h1>
|
||||
<p className="text-muted-foreground">{t("compare.subtitle", { count: list.length })}</p>
|
||||
</div>
|
||||
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
import { useEffect, useMemo, useState } from "react";
|
||||
import { useEffect, useMemo, useState, createContext, useContext } from "react";
|
||||
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,
|
||||
@@ -15,8 +15,15 @@ import {
|
||||
SelectTrigger,
|
||||
SelectValue,
|
||||
} from "@/components/ui/select";
|
||||
import {
|
||||
Sheet,
|
||||
SheetContent,
|
||||
SheetTitle,
|
||||
SheetTrigger,
|
||||
} from "@/components/ui/sheet";
|
||||
import { useGetVersion, getGetVersionQueryKey } from "@workspace/api-client-react";
|
||||
import {
|
||||
ArrowLeft,
|
||||
BookOpen,
|
||||
CalendarDays,
|
||||
ExternalLink,
|
||||
@@ -24,15 +31,32 @@ import {
|
||||
GitBranch,
|
||||
HelpCircle,
|
||||
Library,
|
||||
Menu,
|
||||
Search,
|
||||
Server,
|
||||
Tag,
|
||||
Wrench,
|
||||
type LucideIcon,
|
||||
} from "lucide-react";
|
||||
|
||||
const DOCS_BASE = `${import.meta.env.BASE_URL.replace(/\/$/, "")}/docs`;
|
||||
const REPO_URL = "https://git.kubebase.de/admin/tool-evaluator";
|
||||
|
||||
// Active docs version (null = current docs). Shared via context so every
|
||||
// sub-view builds versioned links and file paths.
|
||||
const DocsVersionContext = createContext<string | null>(null);
|
||||
const useDocsVersion = () => useContext(DocsVersionContext);
|
||||
|
||||
// Full in-app URL for a docs path, prefixed with the active version.
|
||||
function docsHref(version: string | null, path: string) {
|
||||
return version === null ? `/docs/${path}` : `/docs/${version}/${path}`;
|
||||
}
|
||||
|
||||
// Static file path under /docs, prefixed with the versioned snapshot dir.
|
||||
function docsFile(version: string | null, relPath: string) {
|
||||
return version === null ? relPath : `versions/${version}/${relPath}`;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Types
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -79,6 +103,7 @@ type ReleaseDoc = {
|
||||
title: string;
|
||||
date: string | null;
|
||||
hasReference: boolean;
|
||||
hasHandbook: boolean;
|
||||
};
|
||||
|
||||
type HandbookPage = { slug: string; file: string; title: string; order: number };
|
||||
@@ -221,8 +246,11 @@ function isLinkableType(t: FieldType): boolean {
|
||||
}
|
||||
|
||||
function resolveTypeHref(t: FieldType): string | null {
|
||||
if (t.kind === "ref") return `/docs/reference/schemas/${t.value}`;
|
||||
if (t.kind === "array" && /^[A-Z]/.test(t.value)) return `/docs/reference/schemas/${t.value}`;
|
||||
const version = useDocsVersion();
|
||||
const href = (v: string | null) =>
|
||||
v === null ? `/docs/reference/schemas/${t.value}` : `/docs/${v}/reference/schemas/${t.value}`;
|
||||
if (t.kind === "ref") return href(version);
|
||||
if (t.kind === "array" && /^[A-Z]/.test(t.value)) return href(version);
|
||||
return null;
|
||||
}
|
||||
|
||||
@@ -319,14 +347,14 @@ function DocsNav({
|
||||
|
||||
const groups: { label: string; icon: LucideIcon; items: { href: string; label: string; active: boolean }[] }[] = [];
|
||||
|
||||
if (handbook && handbook.length > 0 && version === null) {
|
||||
if (handbook && handbook.length > 0) {
|
||||
groups.push({
|
||||
label: t("docs.guides"),
|
||||
icon: BookOpen,
|
||||
items: handbook.map((p) => ({
|
||||
href: `/docs/handbook/${p.slug}`,
|
||||
href: docsHref(version, `handbook/${p.slug}`),
|
||||
label: p.title,
|
||||
active: navLink(`/docs/handbook/${p.slug}`),
|
||||
active: navLink(docsHref(version, `handbook/${p.slug}`)),
|
||||
})),
|
||||
});
|
||||
}
|
||||
@@ -336,18 +364,18 @@ function DocsNav({
|
||||
label: t("docs.endpoints"),
|
||||
icon: Server,
|
||||
items: reference.tags.map((tag) => ({
|
||||
href: `/docs/reference/endpoints/${tag.name}`,
|
||||
href: docsHref(version, `reference/endpoints/${tag.name}`),
|
||||
label: tag.name,
|
||||
active: navLink(`/docs/reference/endpoints/${tag.name}`),
|
||||
active: navLink(docsHref(version, `reference/endpoints/${tag.name}`)),
|
||||
})),
|
||||
});
|
||||
groups.push({
|
||||
label: t("docs.schemas"),
|
||||
icon: Library,
|
||||
items: reference.schemas.map((s) => ({
|
||||
href: `/docs/reference/schemas/${s.name}`,
|
||||
href: docsHref(version, `reference/schemas/${s.name}`),
|
||||
label: s.name,
|
||||
active: navLink(`/docs/reference/schemas/${s.name}`),
|
||||
active: navLink(docsHref(version, `reference/schemas/${s.name}`)),
|
||||
})),
|
||||
});
|
||||
}
|
||||
@@ -356,9 +384,7 @@ function DocsNav({
|
||||
label: t("docs.releases"),
|
||||
icon: Tag,
|
||||
items: versions.map((v) => ({
|
||||
href: v.version === (version ?? versions[0]?.version) && version !== null
|
||||
? `/docs/releases/${v.version}`
|
||||
: `/docs/releases/${v.version}`,
|
||||
href: `/docs/releases/${v.version}`,
|
||||
label: v.version,
|
||||
active: navLink(`/docs/releases/${v.version}`),
|
||||
})),
|
||||
@@ -485,15 +511,16 @@ function FieldTypeChip({ type }: { type: FieldType }) {
|
||||
}
|
||||
|
||||
function FieldTable({ fields }: { fields: Field[] }) {
|
||||
const { t } = useTranslation();
|
||||
return (
|
||||
<div className="overflow-x-auto rounded-lg border">
|
||||
<table className="w-full text-sm">
|
||||
<thead>
|
||||
<tr className="border-b bg-muted/50 text-left text-xs uppercase tracking-wider text-muted-foreground">
|
||||
<th className="px-3 py-2 font-semibold">Feld</th>
|
||||
<th className="px-3 py-2 font-semibold">Typ</th>
|
||||
<th className="px-3 py-2 font-semibold">Pflicht</th>
|
||||
<th className="px-3 py-2 font-semibold">Beschreibung</th>
|
||||
<th className="px-3 py-2 font-semibold">{t("docs.field")}</th>
|
||||
<th className="px-3 py-2 font-semibold">{t("docs.type")}</th>
|
||||
<th className="px-3 py-2 font-semibold">{t("docs.required")}</th>
|
||||
<th className="px-3 py-2 font-semibold">{t("docs.description")}</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
@@ -529,6 +556,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 (
|
||||
<div className="flex flex-col lg:flex-row gap-8">
|
||||
@@ -540,15 +568,16 @@ function SchemaView({ schema }: { schema: SchemaModel }) {
|
||||
<FieldTable fields={schema.fields} />
|
||||
<p className="text-xs text-muted-foreground">
|
||||
<HelpCircle className="h-3.5 w-3.5 inline mr-1" />
|
||||
Hinweis: Formular-Felder verlinken per ?-Icon direkt zu den jeweiligen Zeilen dieser Tabelle.
|
||||
{t("docs.fieldHelpHint")}
|
||||
</p>
|
||||
</div>
|
||||
<Toc headings={headings} title="Felder" />
|
||||
<Toc headings={headings} title={t("docs.fields")} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
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 +606,16 @@ function EndpointTagView({ tag }: { tag: TagGroup }) {
|
||||
|
||||
{ep.parameters.length > 0 && (
|
||||
<div className="mb-3">
|
||||
<p className="mb-1 text-xs font-semibold uppercase tracking-wider text-muted-foreground">Parameter</p>
|
||||
<p className="mb-1 text-xs font-semibold uppercase tracking-wider text-muted-foreground">{t("docs.parameter")}</p>
|
||||
<div className="overflow-x-auto rounded-lg border">
|
||||
<table className="w-full text-sm">
|
||||
<thead>
|
||||
<tr className="border-b bg-muted/50 text-left text-xs uppercase tracking-wider text-muted-foreground">
|
||||
<th className="px-3 py-2 font-semibold">Name</th>
|
||||
<th className="px-3 py-2 font-semibold">In</th>
|
||||
<th className="px-3 py-2 font-semibold">Typ</th>
|
||||
<th className="px-3 py-2 font-semibold">Pflicht</th>
|
||||
<th className="px-3 py-2 font-semibold">Beschreibung</th>
|
||||
<th className="px-3 py-2 font-semibold">{t("docs.type")}</th>
|
||||
<th className="px-3 py-2 font-semibold">{t("docs.required")}</th>
|
||||
<th className="px-3 py-2 font-semibold">{t("docs.description")}</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
@@ -623,9 +652,9 @@ function EndpointTagView({ tag }: { tag: TagGroup }) {
|
||||
<table className="w-full text-sm">
|
||||
<thead>
|
||||
<tr className="border-b bg-muted/50 text-left text-xs uppercase tracking-wider text-muted-foreground">
|
||||
<th className="px-3 py-2 font-semibold">Status</th>
|
||||
<th className="px-3 py-2 font-semibold">Beschreibung</th>
|
||||
<th className="px-3 py-2 font-semibold">Schema</th>
|
||||
<th className="px-3 py-2 font-semibold">{t("docs.status")}</th>
|
||||
<th className="px-3 py-2 font-semibold">{t("docs.description")}</th>
|
||||
<th className="px-3 py-2 font-semibold">{t("docs.schema")}</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
@@ -642,7 +671,7 @@ function EndpointTagView({ tag }: { tag: TagGroup }) {
|
||||
</section>
|
||||
))}
|
||||
</div>
|
||||
<Toc headings={headings} title="Endpunkte" />
|
||||
<Toc headings={headings} title={t("docs.endpoints")} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -696,7 +725,7 @@ function ReleaseNoteView({ version }: { version: string }) {
|
||||
<Tag className="h-4 w-4" />
|
||||
<span className="font-mono">{version}</span>
|
||||
<a
|
||||
href={`${REPO_URL}/tags/${version}`}
|
||||
href={`${REPO_URL}/releases/tag/${version}`}
|
||||
target="_blank"
|
||||
rel="noreferrer"
|
||||
className="inline-flex items-center gap-1 hover:text-foreground"
|
||||
@@ -711,8 +740,9 @@ function ReleaseNoteView({ version }: { version: string }) {
|
||||
}
|
||||
|
||||
function HandbookView({ slug }: { slug: string }) {
|
||||
const version = useDocsVersion();
|
||||
const handbookFile = `${slug}.md`;
|
||||
return <MarkdownView file={`handbook/${handbookFile}`} />;
|
||||
return <MarkdownView file={docsFile(version, `handbook/${handbookFile}`)} />;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -737,12 +767,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 (
|
||||
<div className="mt-3 rounded-lg border bg-card p-2 shadow-md max-h-96 overflow-auto">
|
||||
{results.length === 0 ? (
|
||||
<p className="px-3 py-2 text-sm text-muted-foreground">Keine Treffer</p>
|
||||
<p className="px-3 py-2 text-sm text-muted-foreground">{t("docs.noResults")}</p>
|
||||
) : (
|
||||
results.map((r) => (
|
||||
<Link
|
||||
@@ -776,6 +807,12 @@ export default function Docs() {
|
||||
const [location, setLocation] = useLocation();
|
||||
const { t } = useTranslation();
|
||||
const [searchQuery, setSearchQuery] = useState("");
|
||||
const [navOpen, setNavOpen] = useState(false);
|
||||
|
||||
// Close the mobile nav drawer after navigating.
|
||||
useEffect(() => {
|
||||
setNavOpen(false);
|
||||
}, [location]);
|
||||
|
||||
const { version, path } = useMemo(() => parseDocsPath(location), [location]);
|
||||
|
||||
@@ -784,9 +821,11 @@ export default function Docs() {
|
||||
});
|
||||
|
||||
const { data: releases, error: releasesError } = useJson<ReleaseDoc[]>(`${DOCS_BASE}/index.json`);
|
||||
const { data: handbook, error: handbookError } = useJson<HandbookPage[]>(
|
||||
version === null ? `${DOCS_BASE}/handbook/index.json` : null,
|
||||
);
|
||||
|
||||
const activeRelease = releases?.find((r) => r.version === version) ?? null;
|
||||
const handbookAvailable = version === null || activeRelease?.hasHandbook;
|
||||
const handbookUrl = handbookAvailable ? `${DOCS_BASE}/${docsFile(version, "handbook/index.json")}` : null;
|
||||
const { data: handbook, error: handbookError } = useJson<HandbookPage[]>(handbookUrl);
|
||||
|
||||
const isCurrentVersion =
|
||||
version === null ||
|
||||
@@ -795,7 +834,7 @@ export default function Docs() {
|
||||
|
||||
const refUrl = version === null
|
||||
? `${DOCS_BASE}/reference.json`
|
||||
: releases?.find((r) => r.version === version)?.hasReference
|
||||
: activeRelease?.hasReference
|
||||
? `${DOCS_BASE}/versions/${version}.json`
|
||||
: null;
|
||||
|
||||
@@ -813,30 +852,37 @@ export default function Docs() {
|
||||
return null;
|
||||
}, [releases, versionInfo]);
|
||||
|
||||
// Redirect old-style /docs/vX.Y.Z to /docs/releases/vX.Y.Z
|
||||
useEffect(() => {
|
||||
if (version !== null && path.length === 0) {
|
||||
setLocation(`/docs/releases/${version}`, { replace: true });
|
||||
}
|
||||
}, [version, path, setLocation]);
|
||||
|
||||
const handleVersionChange = (v: string | null) => {
|
||||
setSearchQuery("");
|
||||
if (v === null || v === currentVersion) {
|
||||
setLocation("/docs");
|
||||
return;
|
||||
}
|
||||
setLocation(`/docs/releases/${v}`);
|
||||
setLocation(`/docs/${v}`);
|
||||
};
|
||||
|
||||
// ---- route resolution ----
|
||||
const section = path[0] ?? "home";
|
||||
const param = path[1];
|
||||
|
||||
// Version shown in the header dropdown: an explicit first-segment version
|
||||
// (/docs/vX.Y.Z) or the releases route (/docs/releases/vX.Y.Z).
|
||||
const headerVersion =
|
||||
version !== null
|
||||
? version
|
||||
: section === "releases" && param
|
||||
? param
|
||||
: null;
|
||||
|
||||
let content: React.ReactNode = null;
|
||||
|
||||
if (version !== null && path.length === 0) {
|
||||
content = <ReleaseNoteView version={version} />;
|
||||
content =
|
||||
handbook && handbook.length > 0 ? (
|
||||
<HandbookView slug={handbook[0].slug} />
|
||||
) : (
|
||||
<ReleaseNoteView version={version} />
|
||||
);
|
||||
} else if (section === "home") {
|
||||
content =
|
||||
handbook && handbook.length > 0 ? (
|
||||
@@ -849,7 +895,9 @@ export default function Docs() {
|
||||
} else if (section === "handbook" && param) {
|
||||
content = <HandbookView slug={param} />;
|
||||
} 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 ? (
|
||||
<EndpointTagView tag={tag} />
|
||||
) : refError || (reference && !tag) ? (
|
||||
@@ -858,7 +906,9 @@ export default function Docs() {
|
||||
<Skeleton className="h-64 w-full" />
|
||||
);
|
||||
} 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 ? (
|
||||
<SchemaView schema={schema} />
|
||||
) : refError || (reference && !schema) ? (
|
||||
@@ -881,7 +931,7 @@ export default function Docs() {
|
||||
{reference.tags.map((tg) => (
|
||||
<Link
|
||||
key={tg.name}
|
||||
href={`/docs/reference/endpoints/${tg.name}`}
|
||||
href={docsHref(version, `reference/endpoints/${tg.name}`)}
|
||||
className="rounded-lg border p-3 text-sm hover:bg-accent/50"
|
||||
>
|
||||
<span className="font-medium">{tg.name}</span>
|
||||
@@ -898,7 +948,7 @@ export default function Docs() {
|
||||
{reference.schemas.map((s) => (
|
||||
<Link
|
||||
key={s.name}
|
||||
href={`/docs/reference/schemas/${s.name}`}
|
||||
href={docsHref(version, `reference/schemas/${s.name}`)}
|
||||
className="rounded-lg border p-3 text-sm font-mono hover:bg-accent/50"
|
||||
>
|
||||
{s.name}
|
||||
@@ -923,31 +973,77 @@ export default function Docs() {
|
||||
const showSearch = version === null && section !== "releases";
|
||||
|
||||
return (
|
||||
<Layout>
|
||||
<div className="mx-auto max-w-6xl space-y-6 pb-10">
|
||||
<DocsHeader
|
||||
versions={releases ?? []}
|
||||
activeVersion={version}
|
||||
onVersionChange={handleVersionChange}
|
||||
onSearchChange={showSearch ? setSearchQuery : undefined}
|
||||
/>
|
||||
|
||||
{showSearch && <SearchOverlay query={searchQuery} onClose={() => setSearchQuery("")} />}
|
||||
|
||||
<div className="grid grid-cols-1 lg:grid-cols-[240px_minmax(0,1fr)] gap-8">
|
||||
<aside className="hidden lg:block">
|
||||
<div className="sticky top-20 max-h-[calc(100vh-6rem)] overflow-auto">
|
||||
<DocsNav
|
||||
version={version}
|
||||
handbook={handbook}
|
||||
reference={reference}
|
||||
versions={releases ?? []}
|
||||
/>
|
||||
<DocsVersionContext.Provider value={version}>
|
||||
<div className="min-h-screen bg-background flex flex-col">
|
||||
<header className="border-b bg-card shrink-0">
|
||||
<div className="mx-auto max-w-6xl px-4 md:px-6 h-14 flex items-center justify-between gap-3">
|
||||
<div className="flex items-center gap-1 min-w-0">
|
||||
<Sheet open={navOpen} onOpenChange={setNavOpen}>
|
||||
<SheetTrigger asChild>
|
||||
<Button
|
||||
variant="ghost"
|
||||
size="icon"
|
||||
className="lg:hidden -ml-1 shrink-0"
|
||||
title={t("docs.nav")}
|
||||
data-testid="button-docs-nav-mobile"
|
||||
>
|
||||
<Menu className="h-5 w-5" />
|
||||
</Button>
|
||||
</SheetTrigger>
|
||||
<SheetContent side="left" className="w-80 overflow-y-auto p-4">
|
||||
<SheetTitle className="sr-only">{t("docs.nav")}</SheetTitle>
|
||||
<DocsNav
|
||||
version={version}
|
||||
handbook={handbook}
|
||||
reference={reference}
|
||||
versions={releases ?? []}
|
||||
/>
|
||||
</SheetContent>
|
||||
</Sheet>
|
||||
<Link
|
||||
href="/"
|
||||
className="inline-flex items-center gap-2 text-primary font-bold text-lg min-w-0"
|
||||
data-testid="link-docs-back"
|
||||
>
|
||||
<Wrench className="w-5 h-5 shrink-0" />
|
||||
<span className="truncate">toolr</span>
|
||||
<span className="hidden md:inline-flex items-center gap-1 text-xs font-normal text-muted-foreground border-l pl-2 ml-1">
|
||||
<ArrowLeft className="w-3.5 h-3.5" />
|
||||
{t("docs.backToApp")}
|
||||
</span>
|
||||
</Link>
|
||||
</div>
|
||||
</aside>
|
||||
<div className="min-w-0">{content}</div>
|
||||
<div className="flex items-center gap-1.5 shrink-0">
|
||||
<ThemeToggle />
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<div className="mx-auto max-w-6xl w-full flex-1 space-y-6 px-4 md:px-6 py-6 pb-12">
|
||||
<DocsHeader
|
||||
versions={releases ?? []}
|
||||
activeVersion={headerVersion}
|
||||
onVersionChange={handleVersionChange}
|
||||
onSearchChange={showSearch ? setSearchQuery : undefined}
|
||||
/>
|
||||
|
||||
{showSearch && <SearchOverlay query={searchQuery} onClose={() => setSearchQuery("")} />}
|
||||
|
||||
<div className="grid grid-cols-1 lg:grid-cols-[240px_minmax(0,1fr)] gap-8">
|
||||
<aside className="hidden lg:block">
|
||||
<div className="sticky top-20 max-h-[calc(100vh-6rem)] overflow-auto">
|
||||
<DocsNav
|
||||
version={version}
|
||||
handbook={handbook}
|
||||
reference={reference}
|
||||
versions={releases ?? []}
|
||||
/>
|
||||
</div>
|
||||
</aside>
|
||||
<div className="min-w-0">{content}</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</Layout>
|
||||
</DocsVersionContext.Provider>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -61,6 +61,7 @@ import {
|
||||
import { customFetch } from "@workspace/api-client-react";
|
||||
import { recordRecentTool } from "@/lib/recent-tools";
|
||||
import { FieldHelp } from "@/components/field-help";
|
||||
import { GuideHelp } from "@/components/guide-help";
|
||||
|
||||
const ratingSchema = z.object({
|
||||
usefulness: z.number().min(1).max(5),
|
||||
@@ -615,7 +616,10 @@ export default function ToolDetail() {
|
||||
<Dialog open={costDialogOpen} onOpenChange={(o) => { if (!o) setCostDialogOpen(false); }}>
|
||||
<DialogContent>
|
||||
<DialogHeader>
|
||||
<DialogTitle>{editCost ? t("detail.edit") + " " + t("detail.costs") : t("detail.addCost")}</DialogTitle>
|
||||
<DialogTitle className="flex items-center gap-2">
|
||||
{editCost ? t("detail.edit") + " " + t("detail.costs") : t("detail.addCost")}
|
||||
<GuideHelp guide="kosten" label={t("detail.costs")} />
|
||||
</DialogTitle>
|
||||
<DialogDescription>Manage license cost information for this tool.</DialogDescription>
|
||||
</DialogHeader>
|
||||
<div className="space-y-4 py-2">
|
||||
@@ -765,7 +769,10 @@ export default function ToolDetail() {
|
||||
{isReviewFormOpen && (
|
||||
<Card className="border-primary shadow-sm">
|
||||
<CardHeader>
|
||||
<CardTitle>{t("detail.addReview")}</CardTitle>
|
||||
<CardTitle className="flex items-center gap-2">
|
||||
{t("detail.addReview")}
|
||||
<GuideHelp guide="bewerten" label={t("detail.addReview")} />
|
||||
</CardTitle>
|
||||
<CardDescription>Share your experience with {tool.name}</CardDescription>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
|
||||
@@ -31,6 +31,7 @@ import { FeatureInput } from "@/components/feature-input";
|
||||
import { TagInput } from "@/components/tag-input";
|
||||
import { useAuth } from "@/hooks/use-auth";
|
||||
import { FieldHelp } from "@/components/field-help";
|
||||
import { GuideHelp } from "@/components/guide-help";
|
||||
|
||||
const toolSchema = z.object({
|
||||
name: z.string().min(2, "Name must be at least 2 characters"),
|
||||
@@ -160,6 +161,7 @@ export default function ToolEdit() {
|
||||
<CardTitle className="flex items-center gap-2">
|
||||
<Pencil className="w-5 h-5 text-primary" />
|
||||
Tool Details
|
||||
<GuideHelp guide="tool-bearbeiten" label="Tool Details" />
|
||||
</CardTitle>
|
||||
<CardDescription>Modify the tool information below.</CardDescription>
|
||||
</CardHeader>
|
||||
|
||||
@@ -19,6 +19,7 @@ import { FeatureInput } from "@/components/feature-input";
|
||||
import { TagInput } from "@/components/tag-input";
|
||||
import { useAuth } from "@/hooks/use-auth";
|
||||
import { FieldHelp } from "@/components/field-help";
|
||||
import { GuideHelp } from "@/components/guide-help";
|
||||
|
||||
const toolSchema = z.object({
|
||||
name: z.string().min(2, "Name must be at least 2 characters"),
|
||||
@@ -123,6 +124,7 @@ export default function ToolNew() {
|
||||
<CardTitle className="flex items-center gap-2">
|
||||
<Wrench className="w-5 h-5 text-primary" />
|
||||
Tool Details
|
||||
<GuideHelp guide="tool-anlegen" label="Tool Details" />
|
||||
</CardTitle>
|
||||
<CardDescription>Provide the basic information about the tool.</CardDescription>
|
||||
</CardHeader>
|
||||
|
||||
@@ -6,6 +6,7 @@ import { useAuth } from "@/hooks/use-auth";
|
||||
import { useWatchlist } from "@/hooks/use-watchlist";
|
||||
import { Layout } from "@/components/layout";
|
||||
import { ToolCard } from "@/components/tool-card";
|
||||
import { GuideHelp } from "@/components/guide-help";
|
||||
import { Button } from "@/components/ui/button";
|
||||
import { Skeleton } from "@/components/ui/skeleton";
|
||||
import { ShieldAlert, Bookmark } from "lucide-react";
|
||||
@@ -42,7 +43,10 @@ export default function Watchlist() {
|
||||
<Layout>
|
||||
<div className="space-y-6 pb-10">
|
||||
<div>
|
||||
<h1 className="text-3xl font-bold tracking-tight mb-2">{t("watchlist.title")}</h1>
|
||||
<h1 className="text-3xl font-bold tracking-tight mb-2 flex items-center gap-2">
|
||||
{t("watchlist.title")}
|
||||
<GuideHelp guide="watchlist" label={t("watchlist.title")} />
|
||||
</h1>
|
||||
<p className="text-muted-foreground">{t("watchlist.subtitle")}</p>
|
||||
</div>
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
+21
-25
@@ -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)
|
||||
|
||||
@@ -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
|
||||
@@ -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. |
|
||||
@@ -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).
|
||||
|
||||
@@ -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)
|
||||
|
||||
+28
-22
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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)).
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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. |
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -5,7 +5,7 @@
|
||||
> nicht zutreffen entfernen. Die Seite wird unter `/docs/vX.Y.Z` in der App
|
||||
> angezeigt.
|
||||
|
||||
**Datum:** YYYY-MM-DD · **Tag:** [`vX.Y.Z`](https://git.kubebase.de/admin/tool-evaluator/tags/vX.Y.Z)
|
||||
**Datum:** YYYY-MM-DD · **Tag:** [`vX.Y.Z`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/vX.Y.Z)
|
||||
|
||||
## Neue Features
|
||||
|
||||
@@ -32,4 +32,4 @@
|
||||
## Links
|
||||
|
||||
- Commit: [`<short-sha>`](https://git.kubebase.de/admin/tool-evaluator/commit/<short-sha>)
|
||||
- Tag: [`vX.Y.Z`](https://git.kubebase.de/admin/tool-evaluator/tags/vX.Y.Z)
|
||||
- Tag: [`vX.Y.Z`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/vX.Y.Z)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# v0.6.0 — Release Notes
|
||||
|
||||
**Datum:** 2026-08-03 · **Tag:** [`v0.6.0`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.6.0)
|
||||
**Datum:** 2026-08-03 · **Tag:** [`v0.6.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.6.0)
|
||||
|
||||
## Neue Features
|
||||
|
||||
@@ -34,4 +34,4 @@
|
||||
## Links
|
||||
|
||||
- Commit: [`2f66fff`](https://git.kubebase.de/admin/tool-evaluator/commit/2f66fff)
|
||||
- Tag: [`v0.6.0`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.6.0)
|
||||
- Tag: [`v0.6.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.6.0)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# v0.7.0 — Release Notes
|
||||
|
||||
**Datum:** 2026-08-03 · **Tag:** [`v0.7.0`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.7.0)
|
||||
**Datum:** 2026-08-03 · **Tag:** [`v0.7.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.7.0)
|
||||
|
||||
## Neue Features
|
||||
|
||||
@@ -32,4 +32,4 @@
|
||||
## Links
|
||||
|
||||
- Commit: [`520f917`](https://git.kubebase.de/admin/tool-evaluator/commit/520f917)
|
||||
- Tag: [`v0.7.0`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.7.0)
|
||||
- Tag: [`v0.7.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.7.0)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# v0.8.0 — Release Notes
|
||||
|
||||
**Datum:** 2026-08-03 · **Tag:** [`v0.8.0`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.8.0)
|
||||
**Datum:** 2026-08-03 · **Tag:** [`v0.8.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.0)
|
||||
|
||||
## Neue Features
|
||||
|
||||
@@ -43,4 +43,4 @@
|
||||
## Links
|
||||
|
||||
- Commit: [`6c92b63`](https://git.kubebase.de/admin/tool-evaluator/commit/6c92b63)
|
||||
- Tag: [`v0.8.0`](https://git.kubebase.de/admin/tool-evaluator/tags/v0.8.0)
|
||||
- Tag: [`v0.8.0`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.0)
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
# v0.8.1 — Release Notes
|
||||
|
||||
**Datum:** 2026-08-03 · **Tag:** [`v0.8.1`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/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: [`fdf2d74`](https://git.kubebase.de/admin/tool-evaluator/commit/fdf2d74)
|
||||
- Tag: [`v0.8.1`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.1)
|
||||
@@ -0,0 +1,61 @@
|
||||
|
||||
# Administration
|
||||
|
||||
Der Bereich **Admin** (`/admin`) ist ausschließlich für Admins zugänglich.
|
||||
Ohne Admin-Rolle erscheint eine Zugriffsverweigerung.
|
||||
|
||||
> Oben rechts führt die Schaltfläche **Redundanz-Dashboard** zur automatischen
|
||||
> Doppelungs-Erkennung (siehe [Redundanz](/docs/handbook/redundanz)).
|
||||
|
||||
## Tab „Nutzer"
|
||||
|
||||
Verwaltung der lokalen Konten.
|
||||
|
||||
- **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).
|
||||
|
||||
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).
|
||||
|
||||
## Tab „Tools"
|
||||
|
||||
Zentraler Zugriff auf den Tool-Katalog.
|
||||
|
||||
- **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).
|
||||
|
||||
## Tab „Audit-Log"
|
||||
|
||||
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.
|
||||
|
||||
API-Referenz: [`GET /audit-logs`](/docs/reference/endpoints/audit#listAuditLogs).
|
||||
|
||||
## Tab „System"
|
||||
|
||||
Versionsinformationen der laufenden Instanz:
|
||||
|
||||
- **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.
|
||||
@@ -0,0 +1,29 @@
|
||||
|
||||
# Analytics
|
||||
|
||||
Der Bereich **Analytics** (`/analytics`) ist ein öffentliches Dashboard mit
|
||||
Kennzahlen und Diagrammen auf Basis aller Tools und Bewertungen.
|
||||
|
||||
## Kennzahlen (KPI-Karten)
|
||||
|
||||
- **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.
|
||||
|
||||
## Diagramme
|
||||
|
||||
| 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 |
|
||||
|
||||
Die Diagramme sind interaktiv (Tooltips beim Überfahren).
|
||||
|
||||
## 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)
|
||||
@@ -0,0 +1,39 @@
|
||||
|
||||
# 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
|
||||
@@ -0,0 +1,70 @@
|
||||
|
||||
# Datenmodell
|
||||
|
||||
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).
|
||||
|
||||
## Tool
|
||||
|
||||
Das Herzstück: ein im Katalog erfasstes Werkzeug.
|
||||
|
||||
| Eigenschaft | Beschreibung |
|
||||
| --- | --- |
|
||||
| `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) |
|
||||
|
||||
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 (Bewertung)
|
||||
|
||||
Eine einzelne Bewertung zu einem Tool:
|
||||
|
||||
- `usefulness` (Nützlichkeit, 1–5) und `usability` (Bedienbarkeit, 1–5)
|
||||
- optional `comment` und ein Anzeigename (`reviewerName`)
|
||||
- Zeitstempel
|
||||
|
||||
Eingabe-Schema: [`RatingInput`](/docs/reference/schemas/ratinginput).
|
||||
|
||||
## User & Auth
|
||||
|
||||
- [`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).
|
||||
|
||||
## Analytics
|
||||
|
||||
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).
|
||||
@@ -0,0 +1,53 @@
|
||||
|
||||
# Erste Schritte
|
||||
|
||||
Diese Seite führt dich durch die wichtigsten Abläufe in toolr — vom ersten
|
||||
Besuch bis zum Anlegen und Bewerten eines Tools.
|
||||
|
||||
## 1. Anmelden
|
||||
|
||||
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 (z. B.
|
||||
Keycloak).
|
||||
|
||||
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 (Tastenkürzel `/`).
|
||||
- **Filtern** — nach Kategorie, Tags, Features und Mindestbewertung
|
||||
(`minRating`).
|
||||
- **Sortieren** — nach Aktualität, Top-Bewertung, meistbewertet, Name
|
||||
(auf-/absteigend) oder letztem Update.
|
||||
|
||||
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 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.
|
||||
Siehe [Bewerten](/docs/handbook/bewerten).
|
||||
|
||||
## 5. Weiterführend
|
||||
|
||||
- [Tools vergleichen](/docs/handbook/vergleichen)
|
||||
- [Watchlist](/docs/handbook/watchlist)
|
||||
- [Analytics](/docs/handbook/analytics)
|
||||
- [Pläne & Berechtigungen](/docs/handbook/plaene)
|
||||
- [Administration](/docs/handbook/administration)
|
||||
@@ -0,0 +1,104 @@
|
||||
[
|
||||
{
|
||||
"slug": "index",
|
||||
"file": "index.md",
|
||||
"title": "Überblick",
|
||||
"order": 1
|
||||
},
|
||||
{
|
||||
"slug": "getting-started",
|
||||
"file": "getting-started.md",
|
||||
"title": "Erste Schritte",
|
||||
"order": 2
|
||||
},
|
||||
{
|
||||
"slug": "konto",
|
||||
"file": "konto.md",
|
||||
"title": "Anmelden & Konto",
|
||||
"order": 3
|
||||
},
|
||||
{
|
||||
"slug": "tools-finden",
|
||||
"file": "tools-finden.md",
|
||||
"title": "Tools finden & durchsuchen",
|
||||
"order": 4
|
||||
},
|
||||
{
|
||||
"slug": "tool-anlegen",
|
||||
"file": "tool-anlegen.md",
|
||||
"title": "Tool anlegen",
|
||||
"order": 5
|
||||
},
|
||||
{
|
||||
"slug": "tool-bearbeiten",
|
||||
"file": "tool-bearbeiten.md",
|
||||
"title": "Tool bearbeiten & löschen",
|
||||
"order": 6
|
||||
},
|
||||
{
|
||||
"slug": "bewerten",
|
||||
"file": "bewerten.md",
|
||||
"title": "Bewerten",
|
||||
"order": 7
|
||||
},
|
||||
{
|
||||
"slug": "watchlist",
|
||||
"file": "watchlist.md",
|
||||
"title": "Watchlist",
|
||||
"order": 8
|
||||
},
|
||||
{
|
||||
"slug": "vergleichen",
|
||||
"file": "vergleichen.md",
|
||||
"title": "Vergleichen",
|
||||
"order": 9
|
||||
},
|
||||
{
|
||||
"slug": "analytics",
|
||||
"file": "analytics.md",
|
||||
"title": "Analytics",
|
||||
"order": 10
|
||||
},
|
||||
{
|
||||
"slug": "plaene",
|
||||
"file": "plaene.md",
|
||||
"title": "Pläne & Berechtigungen",
|
||||
"order": 11
|
||||
},
|
||||
{
|
||||
"slug": "kosten",
|
||||
"file": "kosten.md",
|
||||
"title": "Kosten erfassen",
|
||||
"order": 12
|
||||
},
|
||||
{
|
||||
"slug": "administration",
|
||||
"file": "administration.md",
|
||||
"title": "Administration",
|
||||
"order": 13
|
||||
},
|
||||
{
|
||||
"slug": "redundanz",
|
||||
"file": "redundanz.md",
|
||||
"title": "Redundanz-Dashboard",
|
||||
"order": 14
|
||||
},
|
||||
{
|
||||
"slug": "papierkorb",
|
||||
"file": "papierkorb.md",
|
||||
"title": "Papierkorb",
|
||||
"order": 15
|
||||
},
|
||||
{
|
||||
"slug": "tastatur",
|
||||
"file": "tastatur.md",
|
||||
"title": "Tastenkürzel & Kommandopalette",
|
||||
"order": 16
|
||||
},
|
||||
{
|
||||
"slug": "datenmodell",
|
||||
"file": "datenmodell.md",
|
||||
"title": "Datenmodell",
|
||||
"order": 17
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,52 @@
|
||||
|
||||
# Willkommen bei toolr
|
||||
|
||||
toolr ist eine Plattform zum **Entdecken, Bewerten und Vergleichen von
|
||||
Entwicklungstools**. Nutzer:innen pflegen einen gemeinsamen Katalog von Tools,
|
||||
vergeben Bewertungen (Nützlichkeit & Bedienbarkeit) und nutzen Statistiken, um
|
||||
die richtige Wahl zu treffen.
|
||||
|
||||
## Was kannst du mit toolr tun?
|
||||
|
||||
| Funktion | Beschreibung | Sichtbarkeit |
|
||||
| --- | --- | --- |
|
||||
| **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 |
|
||||
| **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 |
|
||||
| **Papierkorb** | Soft-gelöschte Tools wiederherstellen oder endgültig löschen | Premium |
|
||||
| **Admin** | Nutzerverwaltung, Audit-Log, Systeminformationen | Admin |
|
||||
| **Redundanz** | Automatische Doppelungs-Erkennung | Admin |
|
||||
|
||||
## Wie diese Doku aufgebaut ist
|
||||
|
||||
- **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.
|
||||
|
||||
## Der Einstieg
|
||||
|
||||
Der schnellste Weg:
|
||||
|
||||
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)).
|
||||
|
||||
## Kontakt & Quellcode
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,53 @@
|
||||
|
||||
# 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.
|
||||
@@ -0,0 +1,35 @@
|
||||
|
||||
# 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)).
|
||||
@@ -0,0 +1,41 @@
|
||||
|
||||
# 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)
|
||||
@@ -0,0 +1,41 @@
|
||||
|
||||
# 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.
|
||||
@@ -0,0 +1,38 @@
|
||||
|
||||
# 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
|
||||
@@ -0,0 +1,36 @@
|
||||
|
||||
# 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.
|
||||
@@ -0,0 +1,46 @@
|
||||
|
||||
# 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.
|
||||
|
||||
## Formularfelder
|
||||
|
||||
| Feld | Pflicht | Hinweise |
|
||||
| --- | --- | --- |
|
||||
| **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 |
|
||||
|
||||
Neben jedem Feld führt das **?‑Icon** direkt zur zugehörigen Feldbeschreibung
|
||||
in der [Datenmodell-Referenz](/docs/reference/schemas/toolinput).
|
||||
|
||||
### Kategorie
|
||||
|
||||
- Tippe, um nach bestehenden Kategorien zu suchen.
|
||||
- Wähle **+ Erstelle „..."**, um eine neue Kategorie anzulegen.
|
||||
|
||||
### Features & Tags
|
||||
|
||||
- **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.
|
||||
|
||||
## Speichern
|
||||
|
||||
Klicke auf **Tool hinzufügen**. Nach erfolgreicher Anlage wirst du auf die
|
||||
Detailseite des neuen Tools weitergeleitet.
|
||||
|
||||
## API
|
||||
|
||||
- [`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
|
||||
@@ -0,0 +1,33 @@
|
||||
|
||||
# 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).
|
||||
@@ -0,0 +1,67 @@
|
||||
|
||||
# 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).
|
||||
@@ -0,0 +1,42 @@
|
||||
|
||||
# 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).
|
||||
@@ -0,0 +1,34 @@
|
||||
|
||||
# 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).
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,36 @@
|
||||
# v0.8.2 — Release Notes
|
||||
|
||||
**Datum:** 2026-08-04 · **Tag:** [`v0.8.2`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.2)
|
||||
|
||||
## Fixes & Verbesserungen
|
||||
|
||||
- **Mobile Navigation in der Doku**: Die linke Navigationsleiste (Handbuch,
|
||||
Endpunkte, Schemas) wurde unterhalb von `lg` (1024px) komplett ausgeblendet.
|
||||
Es gibt jetzt einen Menü-Button im Kopfbereich, der ein seitliches
|
||||
Navigations-Drawer mit demselben Inhalt öffnet — auf kleinen Bildschirmen
|
||||
bleibt die Doku voll navigierbar.
|
||||
- **Versions-Dropdown zeigt die gewählte Version an**: Beim Wechsel zu einem
|
||||
anderen Release (`/docs/releases/vX.Y.Z`) blieb das Dropdown fälschlich auf
|
||||
„aktuell". Die angezeigte Version wird jetzt auch aus der releases-Route
|
||||
abgeleitet.
|
||||
|
||||
## API-Änderungen
|
||||
|
||||
- Keine Änderungen an der API.
|
||||
|
||||
## Betrieb / Upgrade
|
||||
|
||||
- **Env-Vars:** unverändert.
|
||||
- **Migration:** keine.
|
||||
- **Breaking Changes:** keine.
|
||||
|
||||
## 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: [`33cf261`](https://git.kubebase.de/admin/tool-evaluator/commit/33cf261)
|
||||
- Tag: [`v0.8.2`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.2)
|
||||
@@ -0,0 +1,61 @@
|
||||
|
||||
# Administration
|
||||
|
||||
Der Bereich **Admin** (`/admin`) ist ausschließlich für Admins zugänglich.
|
||||
Ohne Admin-Rolle erscheint eine Zugriffsverweigerung.
|
||||
|
||||
> Oben rechts führt die Schaltfläche **Redundanz-Dashboard** zur automatischen
|
||||
> Doppelungs-Erkennung (siehe [Redundanz](/docs/handbook/redundanz)).
|
||||
|
||||
## Tab „Nutzer"
|
||||
|
||||
Verwaltung der lokalen Konten.
|
||||
|
||||
- **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).
|
||||
|
||||
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).
|
||||
|
||||
## Tab „Tools"
|
||||
|
||||
Zentraler Zugriff auf den Tool-Katalog.
|
||||
|
||||
- **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).
|
||||
|
||||
## Tab „Audit-Log"
|
||||
|
||||
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.
|
||||
|
||||
API-Referenz: [`GET /audit-logs`](/docs/reference/endpoints/audit#listAuditLogs).
|
||||
|
||||
## Tab „System"
|
||||
|
||||
Versionsinformationen der laufenden Instanz:
|
||||
|
||||
- **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.
|
||||
@@ -0,0 +1,29 @@
|
||||
|
||||
# Analytics
|
||||
|
||||
Der Bereich **Analytics** (`/analytics`) ist ein öffentliches Dashboard mit
|
||||
Kennzahlen und Diagrammen auf Basis aller Tools und Bewertungen.
|
||||
|
||||
## Kennzahlen (KPI-Karten)
|
||||
|
||||
- **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.
|
||||
|
||||
## Diagramme
|
||||
|
||||
| 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 |
|
||||
|
||||
Die Diagramme sind interaktiv (Tooltips beim Überfahren).
|
||||
|
||||
## 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)
|
||||
@@ -0,0 +1,39 @@
|
||||
|
||||
# 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
|
||||
@@ -0,0 +1,70 @@
|
||||
|
||||
# Datenmodell
|
||||
|
||||
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).
|
||||
|
||||
## Tool
|
||||
|
||||
Das Herzstück: ein im Katalog erfasstes Werkzeug.
|
||||
|
||||
| Eigenschaft | Beschreibung |
|
||||
| --- | --- |
|
||||
| `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) |
|
||||
|
||||
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 (Bewertung)
|
||||
|
||||
Eine einzelne Bewertung zu einem Tool:
|
||||
|
||||
- `usefulness` (Nützlichkeit, 1–5) und `usability` (Bedienbarkeit, 1–5)
|
||||
- optional `comment` und ein Anzeigename (`reviewerName`)
|
||||
- Zeitstempel
|
||||
|
||||
Eingabe-Schema: [`RatingInput`](/docs/reference/schemas/ratinginput).
|
||||
|
||||
## User & Auth
|
||||
|
||||
- [`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).
|
||||
|
||||
## Analytics
|
||||
|
||||
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).
|
||||
@@ -0,0 +1,53 @@
|
||||
|
||||
# Erste Schritte
|
||||
|
||||
Diese Seite führt dich durch die wichtigsten Abläufe in toolr — vom ersten
|
||||
Besuch bis zum Anlegen und Bewerten eines Tools.
|
||||
|
||||
## 1. Anmelden
|
||||
|
||||
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 (z. B.
|
||||
Keycloak).
|
||||
|
||||
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 (Tastenkürzel `/`).
|
||||
- **Filtern** — nach Kategorie, Tags, Features und Mindestbewertung
|
||||
(`minRating`).
|
||||
- **Sortieren** — nach Aktualität, Top-Bewertung, meistbewertet, Name
|
||||
(auf-/absteigend) oder letztem Update.
|
||||
|
||||
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 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.
|
||||
Siehe [Bewerten](/docs/handbook/bewerten).
|
||||
|
||||
## 5. Weiterführend
|
||||
|
||||
- [Tools vergleichen](/docs/handbook/vergleichen)
|
||||
- [Watchlist](/docs/handbook/watchlist)
|
||||
- [Analytics](/docs/handbook/analytics)
|
||||
- [Pläne & Berechtigungen](/docs/handbook/plaene)
|
||||
- [Administration](/docs/handbook/administration)
|
||||
@@ -0,0 +1,104 @@
|
||||
[
|
||||
{
|
||||
"slug": "index",
|
||||
"file": "index.md",
|
||||
"title": "Überblick",
|
||||
"order": 1
|
||||
},
|
||||
{
|
||||
"slug": "getting-started",
|
||||
"file": "getting-started.md",
|
||||
"title": "Erste Schritte",
|
||||
"order": 2
|
||||
},
|
||||
{
|
||||
"slug": "konto",
|
||||
"file": "konto.md",
|
||||
"title": "Anmelden & Konto",
|
||||
"order": 3
|
||||
},
|
||||
{
|
||||
"slug": "tools-finden",
|
||||
"file": "tools-finden.md",
|
||||
"title": "Tools finden & durchsuchen",
|
||||
"order": 4
|
||||
},
|
||||
{
|
||||
"slug": "tool-anlegen",
|
||||
"file": "tool-anlegen.md",
|
||||
"title": "Tool anlegen",
|
||||
"order": 5
|
||||
},
|
||||
{
|
||||
"slug": "tool-bearbeiten",
|
||||
"file": "tool-bearbeiten.md",
|
||||
"title": "Tool bearbeiten & löschen",
|
||||
"order": 6
|
||||
},
|
||||
{
|
||||
"slug": "bewerten",
|
||||
"file": "bewerten.md",
|
||||
"title": "Bewerten",
|
||||
"order": 7
|
||||
},
|
||||
{
|
||||
"slug": "watchlist",
|
||||
"file": "watchlist.md",
|
||||
"title": "Watchlist",
|
||||
"order": 8
|
||||
},
|
||||
{
|
||||
"slug": "vergleichen",
|
||||
"file": "vergleichen.md",
|
||||
"title": "Vergleichen",
|
||||
"order": 9
|
||||
},
|
||||
{
|
||||
"slug": "analytics",
|
||||
"file": "analytics.md",
|
||||
"title": "Analytics",
|
||||
"order": 10
|
||||
},
|
||||
{
|
||||
"slug": "plaene",
|
||||
"file": "plaene.md",
|
||||
"title": "Pläne & Berechtigungen",
|
||||
"order": 11
|
||||
},
|
||||
{
|
||||
"slug": "kosten",
|
||||
"file": "kosten.md",
|
||||
"title": "Kosten erfassen",
|
||||
"order": 12
|
||||
},
|
||||
{
|
||||
"slug": "administration",
|
||||
"file": "administration.md",
|
||||
"title": "Administration",
|
||||
"order": 13
|
||||
},
|
||||
{
|
||||
"slug": "redundanz",
|
||||
"file": "redundanz.md",
|
||||
"title": "Redundanz-Dashboard",
|
||||
"order": 14
|
||||
},
|
||||
{
|
||||
"slug": "papierkorb",
|
||||
"file": "papierkorb.md",
|
||||
"title": "Papierkorb",
|
||||
"order": 15
|
||||
},
|
||||
{
|
||||
"slug": "tastatur",
|
||||
"file": "tastatur.md",
|
||||
"title": "Tastenkürzel & Kommandopalette",
|
||||
"order": 16
|
||||
},
|
||||
{
|
||||
"slug": "datenmodell",
|
||||
"file": "datenmodell.md",
|
||||
"title": "Datenmodell",
|
||||
"order": 17
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,52 @@
|
||||
|
||||
# Willkommen bei toolr
|
||||
|
||||
toolr ist eine Plattform zum **Entdecken, Bewerten und Vergleichen von
|
||||
Entwicklungstools**. Nutzer:innen pflegen einen gemeinsamen Katalog von Tools,
|
||||
vergeben Bewertungen (Nützlichkeit & Bedienbarkeit) und nutzen Statistiken, um
|
||||
die richtige Wahl zu treffen.
|
||||
|
||||
## Was kannst du mit toolr tun?
|
||||
|
||||
| Funktion | Beschreibung | Sichtbarkeit |
|
||||
| --- | --- | --- |
|
||||
| **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 |
|
||||
| **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 |
|
||||
| **Papierkorb** | Soft-gelöschte Tools wiederherstellen oder endgültig löschen | Premium |
|
||||
| **Admin** | Nutzerverwaltung, Audit-Log, Systeminformationen | Admin |
|
||||
| **Redundanz** | Automatische Doppelungs-Erkennung | Admin |
|
||||
|
||||
## Wie diese Doku aufgebaut ist
|
||||
|
||||
- **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.
|
||||
|
||||
## Der Einstieg
|
||||
|
||||
Der schnellste Weg:
|
||||
|
||||
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)).
|
||||
|
||||
## Kontakt & Quellcode
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,53 @@
|
||||
|
||||
# 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.
|
||||
@@ -0,0 +1,35 @@
|
||||
|
||||
# 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)).
|
||||
@@ -0,0 +1,41 @@
|
||||
|
||||
# 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)
|
||||
@@ -0,0 +1,41 @@
|
||||
|
||||
# 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.
|
||||
@@ -0,0 +1,38 @@
|
||||
|
||||
# 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
|
||||
@@ -0,0 +1,36 @@
|
||||
|
||||
# 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.
|
||||
@@ -0,0 +1,46 @@
|
||||
|
||||
# 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.
|
||||
|
||||
## Formularfelder
|
||||
|
||||
| Feld | Pflicht | Hinweise |
|
||||
| --- | --- | --- |
|
||||
| **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 |
|
||||
|
||||
Neben jedem Feld führt das **?‑Icon** direkt zur zugehörigen Feldbeschreibung
|
||||
in der [Datenmodell-Referenz](/docs/reference/schemas/toolinput).
|
||||
|
||||
### Kategorie
|
||||
|
||||
- Tippe, um nach bestehenden Kategorien zu suchen.
|
||||
- Wähle **+ Erstelle „..."**, um eine neue Kategorie anzulegen.
|
||||
|
||||
### Features & Tags
|
||||
|
||||
- **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.
|
||||
|
||||
## Speichern
|
||||
|
||||
Klicke auf **Tool hinzufügen**. Nach erfolgreicher Anlage wirst du auf die
|
||||
Detailseite des neuen Tools weitergeleitet.
|
||||
|
||||
## API
|
||||
|
||||
- [`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
|
||||
@@ -0,0 +1,33 @@
|
||||
|
||||
# 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).
|
||||
@@ -0,0 +1,67 @@
|
||||
|
||||
# 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).
|
||||
@@ -0,0 +1,42 @@
|
||||
|
||||
# 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).
|
||||
@@ -0,0 +1,34 @@
|
||||
|
||||
# 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).
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,49 @@
|
||||
# v0.8.3 — Release Notes
|
||||
|
||||
**Datum:** 2026-08-04 · **Tag:** [`v0.8.3`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.3)
|
||||
|
||||
## Neue Features
|
||||
|
||||
- **Versionsbasierte Dokumentation**: Jedes Release trägt jetzt einen
|
||||
vollständigen Doku-Snapshot (Handbuch + API-Referenz). Über das
|
||||
Versions-Dropdown gelangst du zur Doku der jeweiligen Version
|
||||
(`/docs/vX.Y.Z/…`) — inklusive Handbuch und Referenz, wie sie zum
|
||||
Release-Zeitpunkt galten. Die letzten 7 Versionen bleiben verfügbar.
|
||||
- **Hilfe-Buttons in Formularen (NetBox-Stil)**: Bei Bewertung, Tool
|
||||
anlegen/bearbeiten, Kosten, Vergleichen, Watchlist und Analytics gibt es
|
||||
jetzt ein Hilfe-Icon, das direkt zur passenden Anleitung im Handbuch führt.
|
||||
|
||||
## Fixes & Verbesserungen
|
||||
|
||||
- **Gitea-Tag-Links korrigiert**: `…/tags/vX.Y.Z` war eine 404-Seite; die
|
||||
korrekte URL lautet `/releases/tag/vX.Y.Z` (in allen Release-Notes und der
|
||||
Doku-Seite).
|
||||
- Versions-Wechsel führt jetzt zur Doku der gewählten Version statt direkt
|
||||
nur zur Release-Seite; alte `/docs/vX.Y.Z`-Redirects entfallen.
|
||||
- Doku-Generator: `--snapshot` erzeugt Handbuch + Referenz pro Version; beim
|
||||
Build werden die Snapshots der letzten 7 Versionen eingespielt.
|
||||
|
||||
## API-Änderungen
|
||||
|
||||
- Keine Änderungen an der API.
|
||||
|
||||
## Betrieb / Upgrade
|
||||
|
||||
- **Env-Vars:** unverändert.
|
||||
- **Migration:** keine.
|
||||
- **Breaking Changes:** keine. Neue Release-Notes müssen den korrekten
|
||||
Tag-Link verwenden (siehe `docs/releases/TEMPLATE.md`). Für Versionen vor
|
||||
diesem Release können Snapshots nachträglich erzeugt werden:
|
||||
`node scripts/src/generate-docs.mjs --snapshot vX.Y.Z`.
|
||||
|
||||
## Bekannte Einschränkungen
|
||||
|
||||
- Ältere Releases ohne Snapshot (z. B. v0.6.0) zeigen nur ihre Release-Notes,
|
||||
kein Handbuch/keine Referenz. Mit `--snapshot` nachpflegen.
|
||||
- Die Doku-Version entspricht dem Doku-Stand zum Zeitpunkt der Erstellung des
|
||||
Snapshots; Änderungen am Handbuch gelten ab dem jeweils nächsten Release.
|
||||
|
||||
## Links
|
||||
|
||||
- Commit: [`3bb4598`](https://git.kubebase.de/admin/tool-evaluator/commit/3bb4598)
|
||||
- Tag: [`v0.8.3`](https://git.kubebase.de/admin/tool-evaluator/releases/tag/v0.8.3)
|
||||
@@ -196,7 +196,7 @@ function slugify(name) {
|
||||
return name.replace(/\.md$/, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-");
|
||||
}
|
||||
|
||||
async function buildHandbookIndex() {
|
||||
async function readHandbookPages() {
|
||||
let files;
|
||||
try {
|
||||
files = (await readdir(handbookDir)).filter(isHandbookFile);
|
||||
@@ -213,13 +213,35 @@ async function buildHandbookIndex() {
|
||||
file,
|
||||
title: frontmatter.title ?? extractTitle(body) ?? basename(file),
|
||||
order: typeof frontmatter.order === "number" ? frontmatter.order : 999,
|
||||
body,
|
||||
});
|
||||
await writeFile(join(targetDir, "handbook", file), body);
|
||||
}
|
||||
pages.sort((a, b) => a.order - b.order || a.title.localeCompare(b.title));
|
||||
return pages;
|
||||
}
|
||||
|
||||
async function writeHandbookTo(dir) {
|
||||
const pages = await readHandbookPages();
|
||||
await mkdir(dir, { recursive: true });
|
||||
for (const page of pages) {
|
||||
await writeFile(join(dir, page.file), page.body);
|
||||
}
|
||||
await writeFile(
|
||||
join(dir, "index.json"),
|
||||
JSON.stringify(
|
||||
pages.map(({ slug, file, title, order }) => ({ slug, file, title, order })),
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
return pages;
|
||||
}
|
||||
|
||||
async function buildHandbookIndex() {
|
||||
const pages = await writeHandbookTo(join(targetDir, "handbook"));
|
||||
return pages;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Search index
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -295,7 +317,8 @@ async function writeSnapshot(version) {
|
||||
const dir = join(releasesDir, version);
|
||||
await mkdir(dir, { recursive: true });
|
||||
await writeFile(join(dir, "reference.json"), JSON.stringify(reference, null, 2));
|
||||
console.log(`[generate-docs] snapshot ${version} -> ${join(dir, "reference.json")}`);
|
||||
await writeHandbookTo(join(dir, "handbook"));
|
||||
console.log(`[generate-docs] snapshot ${version} -> ${dir}/ (reference.json + handbook)`);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -343,27 +366,48 @@ async function main() {
|
||||
JSON.stringify(handbookPages, null, 2),
|
||||
);
|
||||
|
||||
// 3. Release notes + versioned reference snapshots
|
||||
// 3. Release notes + versioned docs snapshots (last 7 versions)
|
||||
const versions = [];
|
||||
for (const name of releaseNames) {
|
||||
for (const name of releaseNames.slice(0, 7)) {
|
||||
const version = parseVersion(name);
|
||||
const content = await readFile(join(releasesDir, name), "utf8");
|
||||
await copyFile(join(releasesDir, name), join(targetDir, "releases", name));
|
||||
const hasSnapshot = await stat(join(releasesDir, version, "reference.json"))
|
||||
const snapDir = join(releasesDir, version);
|
||||
const hasReference = await stat(join(snapDir, "reference.json"))
|
||||
.then(() => true)
|
||||
.catch(() => false);
|
||||
if (hasSnapshot) {
|
||||
const hasHandbook = await stat(join(snapDir, "handbook", "index.json"))
|
||||
.then(() => true)
|
||||
.catch(() => false);
|
||||
if (hasReference) {
|
||||
await copyFile(
|
||||
join(releasesDir, version, "reference.json"),
|
||||
join(snapDir, "reference.json"),
|
||||
join(targetDir, "versions", `${version}.json`),
|
||||
);
|
||||
}
|
||||
if (hasHandbook) {
|
||||
await mkdir(join(targetDir, "versions", version, "handbook"), { recursive: true });
|
||||
await copyFile(
|
||||
join(snapDir, "handbook", "index.json"),
|
||||
join(targetDir, "versions", version, "handbook", "index.json"),
|
||||
);
|
||||
const pages = JSON.parse(
|
||||
await readFile(join(snapDir, "handbook", "index.json"), "utf8"),
|
||||
);
|
||||
for (const page of pages) {
|
||||
await copyFile(
|
||||
join(snapDir, "handbook", page.file),
|
||||
join(targetDir, "versions", version, "handbook", page.file),
|
||||
);
|
||||
}
|
||||
}
|
||||
versions.push({
|
||||
version,
|
||||
file: `releases/${name}`,
|
||||
title: extractTitle(content) ?? version,
|
||||
date: extractDate(content) ?? null,
|
||||
hasReference: hasSnapshot,
|
||||
hasReference,
|
||||
hasHandbook,
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user