From 0686300243826bf8e4d5313c9c3234c08d26fe38 Mon Sep 17 00:00:00 2001 From: Till JS Date: Thu, 7 May 2026 15:48:45 +0200 Subject: [PATCH] =?UTF-8?q?docs(cards):=20Marktplatz=20Plan=20=E2=80=94=20?= =?UTF-8?q?Vollvision=20mit=20mana-credits=20+=20dual=20verification?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Vollvision-Plan für den Cards-Decks-Marktplatz, basierend auf der Konkurrenz-Analyse vom selben Tag. Bewusst nicht MVP-getrieben — unbegrenzte Ressourcen-Annahme, optimale Lösung als Ziel. Kern-Entscheidungen aus dem User-Briefing: - Versionierte Decks + Live-Updates + Pull-Requests = volle Vision - mana-credits zentral: User kaufen, Authoren verdienen (80/20 Cut, 90/10 für verified-mana) - Verifizierung zweigleisig: Mana-Verein-Kuration UND Community- Schwelle, mit unterschiedlichen Badges (🛡️ und ⭐) - Co-Learn-Sessions explizit auf Phase λ verschoben - Mobile-Apps explizit auf Phase μ verschoben Inhalt: - 17 Tabellen-Schema (Authoren, Decks, Versionen, Karten, Subscriptions, Forks, Stars, PRs, Discussions, Reports, Tags, Käufe, Auszahlungen, AI-Mod-Log) - mana-credits Integration end-to-end (2-phase Reservation, Author-Payout, Refund-Workflow, Buyer-Protection) - Service-Architektur: cards-server (neu), cards-search (neu, später), Erweiterungen an mana-llm/mana-credits/mana-notify/ mana-media - 7 API-Endpoint-Bereiche mit konkreten Routes - 9 Phasen (α–ι) plus 4 explizit-später-Phasen - Cold-Start: Verein-Seed + Anki-Top-100 + Influencer-Outreach - Risiko-Matrix mit Mitigationen - "Was wir NICHT tun"-Sektion (Sterne-Bewertung, Reddit-Voting, Anki-Bashing, Klarname-Pflicht, > 30% Cut) - 7 konkrete Differenzierungs-Hebel gegen die 17 Konkurrenten Co-Authored-By: Claude Opus 4.7 (1M context) --- apps/cards/docs/MARKETPLACE_PLAN.md | 602 ++++++++++++++++++++++++++++ 1 file changed, 602 insertions(+) create mode 100644 apps/cards/docs/MARKETPLACE_PLAN.md diff --git a/apps/cards/docs/MARKETPLACE_PLAN.md b/apps/cards/docs/MARKETPLACE_PLAN.md new file mode 100644 index 000000000..2e7ff40ae --- /dev/null +++ b/apps/cards/docs/MARKETPLACE_PLAN.md @@ -0,0 +1,602 @@ +# Cards-Marktplatz — Plan + +> **Status**: Plan, kein Code. Stand 2026-05-07. +> **Goal-Setting**: Vollvision, kein MVP-Druck. Wir bauen die optimale Lösung. +> **Alignment**: User hat folgende Eckpunkte gesetzt: +> - Versionierte Decks + Live-Updates + Pull-Requests = ja, volle Vision +> - mana-credits zentral, sowohl für User-Käufe als auch Author-Verdienst +> - „Verified" zweigleisig: Mana-Verein-Kuration UND Community-Schwellen, mit unterschiedlichen Badges +> - Co-Learn-Sessions explizit **nicht** für Phase 1 — auf Phase 2 verschoben +> - Mobile-App auch später + +--- + +## 1. Mission + +**Die Karteikarten-Plattform mit der besten Lern-Community im Netz.** Wo qualitativ hochwertige Decks entstehen, gepflegt, geteilt und gelernt werden — und wo Lernende einander helfen. + +## 2. Was wir gegen die Konkurrenz aufbieten + +(verdichtet aus `apps/cards/COMPETITORS_2026-05.md`) + +| Differenzierer | Wir | Wer noch | +|---|---|---| +| Free Cloud-Sync | ✓ | niemand | +| Versionierte Decks mit Live-Updates | ✓ | nur AnkiHub (paywalled, Medizin-only) | +| Pull-Requests auf Decks | ✓ | niemand | +| Card-Discussions (inline pro Karte) | ✓ | niemand | +| AI-Karten + AI-Moderation + AI-Tags | ✓ | fragmentiert bei anderen | +| Open Source PWA | ✓ | nur Anki/Mnemosyne (Desktop) | +| Anki-Migration mit Bildern/Audio | ✓ (vorhanden) | niemand vollständig | +| Author-Followings + Activity-Feed | ✓ | niemand | +| Bezahlte Decks mit Author-Erlös via mana-credits | ✓ | nur Brainscape (eigenes Closed-Pricing) | +| Pseudonym + verifiziert kombinierbar | ✓ | niemand klar | + +## 3. Architektur-Prinzipien + +1. **API ist `/v1` ab Tag 1** — OpenAPI-Spec als Quelle der Wahrheit, Versionierungs-Bewusstsein eingebaut. +2. **Public-Decks leben separat** vom Local-First-Sync-Pfad (eigene Postgres-Tabellen, eigene Service, eigene RLS-Policies). Kein Vermischen mit `mana_sync.sync_changes`. +3. **Subscribed Decks sind unidirektional**: Author → Subscribers. Updates fließen einseitig. Wer ändern will, forkt. +4. **Content-Hash überall.** Jede Karte und jede Version bekommt einen deterministischen SHA-256 → Trust + Cache + Diff kostenlos. +5. **Lizenzen sind explizit + maschinen-lesbar** (SPDX-IDs: `CC0-1.0`, `CC-BY-4.0`, `CC-BY-SA-4.0`, plus eigener `Cards-Personal-Use-1.0` für Default-Käufe und `Cards-Pro-Only-1.0` für paid Decks). +6. **AI ist Moderator, nicht Gatekeeper** — KI-First-Pass + Human-Review-Eskalation. Niemals KI-allein-Take-down. +7. **Search ist von der DB entkoppelt** — Read-Only-Index, asynchron befüllt. Bricht der Search-Service, läuft der Marktplatz weiter. +8. **mana-credits ist die einzige Geld-Schnittstelle** — niemals Stripe direkt im cards-server. Alles geht über `/api/v1/credits/use`, `/credits/grant`, `/credits/reservations/*`. +9. **Anonymisiertes Lern-Verhalten**: aggregierte Stats sichtbar (z.B. „1.200 Lernende"), individuelles Lernverhalten nie öffentlich ohne explizites Opt-in. +10. **Keine Drittanbieter-Tracker.** Telemetrie ausschließlich über mana-analytics, opt-out möglich. + +## 4. Datenmodell + +Neues Schema `cards` in `mana_platform`. Alle Tabellen über `pgSchema('cards').table(...)` (Mana-Konvention). + +### 4.1 Authoren + +```sql +public_authors ( + user_id uuid PRIMARY KEY REFERENCES auth.users(id), + slug text UNIQUE NOT NULL, -- @anna-lang + display_name text NOT NULL, + bio text, + avatar_url text, + joined_at timestamptz DEFAULT now(), + pseudonym boolean DEFAULT false, -- true = klarname versteckt + verified_mana boolean DEFAULT false, -- vom Verein verliehen + verified_community boolean DEFAULT false, -- automatisch ab Schwelle + banned_at timestamptz, -- soft-ban + banned_reason text +) +``` + +Drei Verifizierungs-Stufen mit unterschiedlichen Badges in der UI: + +| Status | Badge | Wer / wie | +|---|---|---| +| `verified_mana = true` | 🛡️ **Mana Verifiziert** | Manuell vom Mana-Verein vergeben (Lehrer, Profis, Sprachschulen, Ärzte). Nicht erkaufbar. | +| `verified_community = true` | ⭐ **Community Verifiziert** | Automatisch bei: ≥ 500 Stars über alle Decks ODER ≥ 3 featured Decks ODER ≥ 200 aktive Subscribers über alle Decks. Periodisch neu evaluiert. | +| beides | 🛡️⭐ Beide Badges | Mana + Community zusammen. | + +### 4.2 Decks + Versionen + +```sql +public_decks ( + id uuid PRIMARY KEY, + slug text UNIQUE NOT NULL, -- /decks/anna-lang/spanish-a2-vocab + title text NOT NULL, + description text, + language text, -- ISO-639-1 + license text NOT NULL, -- SPDX + price_credits integer DEFAULT 0, -- 0 = kostenlos + owner_user_id uuid NOT NULL REFERENCES public_authors(user_id), + latest_version_id uuid, -- → public_deck_versions + is_featured boolean DEFAULT false, + is_takedown boolean DEFAULT false, + takedown_at timestamptz, + takedown_reason text, + created_at timestamptz DEFAULT now(), + CONSTRAINT price_requires_license CHECK (price_credits = 0 OR license = 'Cards-Pro-Only-1.0') +) + +public_deck_versions ( + id uuid PRIMARY KEY, + deck_id uuid NOT NULL REFERENCES public_decks(id), + semver text NOT NULL, -- 1.0.0, 1.1.0, 2.0.0 + changelog text, + content_hash text NOT NULL, -- SHA-256 of canonicalized cards + card_count integer NOT NULL, + published_at timestamptz DEFAULT now(), + deprecated_at timestamptz, + UNIQUE (deck_id, semver) +) + +public_deck_cards ( + id uuid PRIMARY KEY, + version_id uuid NOT NULL REFERENCES public_deck_versions(id), + type text NOT NULL, -- basic, basic-reverse, cloze, type-in + fields jsonb NOT NULL, -- {front, back} oder {text, extra} + ord integer NOT NULL, + content_hash text NOT NULL, -- per Karte: ermöglicht Smart-Merge + UNIQUE (version_id, ord) +) +``` + +### 4.3 Tags + Discovery + +```sql +tag_definitions ( + id uuid PRIMARY KEY, + slug text UNIQUE NOT NULL, + name text NOT NULL, + parent_id uuid REFERENCES tag_definitions(id), -- Hierarchie + description text, + curated boolean DEFAULT false -- vom Mana-Verein gepflegt +) + +deck_tags ( + deck_id uuid REFERENCES public_decks(id), + tag_id uuid REFERENCES tag_definitions(id), + PRIMARY KEY (deck_id, tag_id) +) +``` + +### 4.4 Engagement (Stars, Subscribes, Forks) + +```sql +deck_stars ( + user_id uuid REFERENCES auth.users(id), + deck_id uuid REFERENCES public_decks(id), + starred_at timestamptz DEFAULT now(), + PRIMARY KEY (user_id, deck_id) +) + +deck_subscriptions ( + user_id uuid REFERENCES auth.users(id), + deck_id uuid REFERENCES public_decks(id), + current_version_id uuid REFERENCES public_deck_versions(id), + subscribed_at timestamptz DEFAULT now(), + notify_updates boolean DEFAULT true, + PRIMARY KEY (user_id, deck_id) +) + +deck_forks ( + user_id uuid REFERENCES auth.users(id), + source_deck_id uuid REFERENCES public_decks(id), + source_version_id uuid REFERENCES public_deck_versions(id), + forked_at timestamptz DEFAULT now(), + PRIMARY KEY (user_id, source_deck_id, source_version_id) +) + +author_follows ( + follower_user_id uuid REFERENCES auth.users(id), + author_user_id uuid REFERENCES public_authors(user_id), + since timestamptz DEFAULT now(), + PRIMARY KEY (follower_user_id, author_user_id) +) +``` + +### 4.5 Pull-Requests + Discussions + +```sql +deck_pull_requests ( + id uuid PRIMARY KEY, + deck_id uuid REFERENCES public_decks(id), + author_user_id uuid REFERENCES auth.users(id), + status text NOT NULL, -- open, merged, closed, rejected + title text NOT NULL, + body text, + diff jsonb NOT NULL, -- {add: [...], modify: [...], remove: [...]} + merged_into_version uuid REFERENCES public_deck_versions(id), + created_at timestamptz DEFAULT now(), + resolved_at timestamptz +) + +card_discussions ( + id uuid PRIMARY KEY, + card_content_hash text NOT NULL, -- bindet sich an Karte, nicht an version + deck_id uuid REFERENCES public_decks(id), + author_user_id uuid REFERENCES auth.users(id), + parent_id uuid REFERENCES card_discussions(id), + body text NOT NULL, + hidden boolean DEFAULT false, + created_at timestamptz DEFAULT now() +) +``` + +### 4.6 Moderation + +```sql +deck_reports ( + id uuid PRIMARY KEY, + deck_id uuid REFERENCES public_decks(id), + version_id uuid REFERENCES public_deck_versions(id), + card_content_hash text, -- optional: Karte spezifisch + reporter_user_id uuid REFERENCES auth.users(id), + category text NOT NULL, -- spam, copyright, nsfw, misinformation, other + body text, + status text DEFAULT 'open', -- open, dismissed, actioned + resolved_by uuid, + resolved_at timestamptz, + resolution_notes text, + created_at timestamptz DEFAULT now() +) + +ai_moderation_log ( + id uuid PRIMARY KEY, + version_id uuid REFERENCES public_deck_versions(id), + verdict text NOT NULL, -- pass, flag, block + categories text[], -- spam, csam, hate, nsfw, ... + model text, -- "claude-3-5-sonnet" etc + rationale text, + human_reviewed boolean DEFAULT false, + human_overrode boolean DEFAULT false, + created_at timestamptz DEFAULT now() +) +``` + +### 4.7 mana-credits Integration + +```sql +deck_purchases ( + id uuid PRIMARY KEY, + buyer_user_id uuid REFERENCES auth.users(id), + deck_id uuid REFERENCES public_decks(id), + version_id uuid REFERENCES public_deck_versions(id), + price_credits integer NOT NULL, -- Snapshot zum Zeitpunkt des Kaufs + author_share integer NOT NULL, -- nach Verein-Cut + mana_share integer NOT NULL, + credits_transaction text, -- mana-credits ID + purchased_at timestamptz DEFAULT now(), + refunded_at timestamptz, + UNIQUE (buyer_user_id, deck_id) -- einmal Kauf reicht für Lifetime + alle Versionen +) + +author_payouts ( + id uuid PRIMARY KEY, + author_user_id uuid REFERENCES public_authors(user_id), + source_purchase_id uuid REFERENCES deck_purchases(id), + credits_granted integer NOT NULL, + credits_grant_id text, -- mana-credits grant ID + granted_at timestamptz DEFAULT now() +) +``` + +## 5. mana-credits Integration (Detail) + +Zwei-seitiger Marktplatz. mana-credits ist Single-Source-of-Truth fürs Geld. + +### 5.1 Kauf-Flow (Buyer) + +1. User klickt „Kaufen" auf paid Deck (Preis: z.B. 50 Credits) +2. cards-server checkt: Hat User schon dieses Deck? (deck_purchases) → wenn ja, sofort Zugriff +3. cards-server reserviert Credits via `POST mana-credits/api/v1/credits/reservations` (2-phase) +4. cards-server erstellt deck_purchases-Row (committed) +5. cards-server commit-released die Reservation → Credits abgebucht +6. cards-server erstellt author_payouts-Row → ruft `POST mana-credits/api/v1/internal/credits/grant` für den Author-Anteil +7. User bekommt sofortigen Zugriff: Deck wird in private Liste verschoben (User hat eine eigene Lokal-Kopie als Author-Subscription) + +**Was passiert wenn Author gebannt nach Kauf?** → Refund-Path (Phase γ Implementation): Admin kann Refund triggern → mana-credits → Reverse-Grant → User behält das Deck nicht mehr. + +### 5.2 Author-Auszahlungs-Modell + +- **Standard-Cut**: 80 % Author / 20 % Mana-Verein (Server-, Hosting-, Moderations-Kosten) +- **Verifizierte Authoren** (verified_mana): 90 % / 10 % +- **Mindestauszahlung**: keine — Credits werden direkt im mana-credits-Account gebucht, von dort kann der Author sie selbst nutzen oder per Stripe-Payout (mana-credits-Feature, falls vorhanden) abheben +- **Pricing-Range**: Free (0 Credits), oder 10–500 Credits (entspricht ungefähr 1–50 € — exakte Conversion siehe mana-credits packages) + +### 5.3 Käufer-Lebenszyklus + +- Einmal gekauft = Lifetime-Zugriff auf alle künftigen Versionen +- Bei major Version (e.g. 1.x → 2.0.0) **kein** zweiter Kauf nötig — Author behält die Verbesserungs-Pflicht +- Refund-Window: 30 Tage, automatisch verfügbar wenn ≤ 10 % der Karten gelernt wurden (Quizlet hat das, ist Best-Practice) + +### 5.4 Buyer-Protection bei Take-Down + +- Wenn Deck per Take-Down entfernt wird, behält Buyer Zugriff auf das letzte gesehene Snapshot (DSGVO-konform) +- Refund automatisch wenn Take-Down innerhalb 90 Tagen nach Kauf + +## 6. Service-Architektur + +### 6.1 `cards-server` (neu) + +- **Stack**: Hono + Bun (Mana-Konvention) +- **Port**: 3072 +- **Deps**: PostgreSQL (`mana_platform.cards.*`), Redis (Job-Queue für Indexing/Notifications) +- **Auth**: JWT via JWKS (mana-auth) +- **Routes**: siehe §7 + +### 6.2 `cards-search` (neu, später) + +- Eigene PostgreSQL-Instance mit pg_trgm + tsvector + pgvector +- Async-Indexer hört auf cards-server-Events („deck-published", „deck-updated") +- Optional: Meilisearch wenn Postgres FTS nicht reicht + +### 6.3 mana-llm (existierend, erweitert) + +- Embeddings für semantic search (jeden Deck-Description + Karte → 1536-dim Vector) +- Moderation-First-Pass (Klassifikation in spam/csam/hate/nsfw/etc.) +- Auto-Tag-Suggestions +- Auto-Summary für Deck-Beschreibungen + +### 6.4 mana-credits (existierend, erweitert) + +- Bestehende `/credits/use` und `/credits/reservations/*` für Kauf +- Bestehender `/internal/credits/grant` für Author-Auszahlung +- Vermutlich keine API-Erweiterung nötig + +### 6.5 mana-notify (existierend, erweitert) + +- Push-Notifications für Subscribe-Updates, neue Subscribers, neue Discussions/Replies, neue Stars (vom User konfigurierbar) + +### 6.6 mana-media (existierend) + +- Bilder/Audio in published Decks landen wie heute auch +- Pro Author-Tier ein Soft-Quota: Free 100MB, Verified 1GB, Mana 5GB + +## 7. API-Endpoints (Auswahl) + +OpenAPI-Spec wird die Quelle der Wahrheit; hier die wichtigsten Routes: + +### 7.1 Authoren + +``` +POST /v1/authors/me — Profil anlegen/updaten (slug, displayName, bio, avatar, pseudonym) +GET /v1/authors/:slug — Public Profile + Decks-Liste + Stats +GET /v1/authors/me/dashboard — Eigene Stats: Subscriber, Erlöse, Mod-Inbox +POST /v1/authors/:slug/follow — Folgen +DELETE /v1/authors/:slug/follow — Entfolgen +GET /v1/authors/me/feed — Personal Activity-Feed +``` + +### 7.2 Decks + +``` +POST /v1/decks — Deck als public registrieren (Init-Flow) +GET /v1/decks/:slug — Public Deck mit latest version +GET /v1/decks/:slug/versions — Versionsliste mit Changelogs +GET /v1/decks/:slug/versions/:semver — Specific Version + alle Karten +PATCH /v1/decks/:slug — Metadaten (title, description, license, price) + +POST /v1/decks/:slug/publish — Neue Version publishen (body: cards[], semver, changelog) + → triggert AI-Mod-Pass + → setzt latest_version_id + +POST /v1/decks/:slug/star — Star setzen +DELETE /v1/decks/:slug/star — Star entfernen + +POST /v1/decks/:slug/subscribe — Subscribe (lädt + sync'd Karten in lokale DB) +DELETE /v1/decks/:slug/subscribe — Unsubscribe + +POST /v1/decks/:slug/fork — Fork (lokale Kopie + Author-Lineage) + +POST /v1/decks/:slug/buy — Paid Deck kaufen (mana-credits-Flow) +POST /v1/decks/:slug/refund — Refund anfragen +``` + +### 7.3 Pull-Requests + +``` +GET /v1/decks/:slug/pull-requests — Liste +POST /v1/decks/:slug/pull-requests — Neuer PR (body: title, body, diff) +GET /v1/pull-requests/:id — Details +POST /v1/pull-requests/:id/merge — Author merged → erstellt neue Version +POST /v1/pull-requests/:id/close — Author schließt +POST /v1/pull-requests/:id/comments — Diskussion auf PR-Ebene +``` + +### 7.4 Discussions + +``` +GET /v1/cards/:contentHash/discussions — Threads für eine Karte (über Versionen hinweg) +POST /v1/cards/:contentHash/discussions — Neuer Thread / Reply +POST /v1/discussions/:id/hide — Author/Mod versteckt +``` + +### 7.5 Discovery + Search + +``` +GET /v1/explore — Featured + Trending + Categories (curated) +GET /v1/search?q=…&tag=…&lang=…&sort=… — Volltextsuche (FTS + semantic) +GET /v1/tags — Tag-Hierarchie +GET /v1/decks?author=…&tag=…&sort=…&p=… — Filtered Browse +``` + +### 7.6 Reports + Moderation + +``` +POST /v1/decks/:slug/report — User reportet Deck +POST /v1/cards/:contentHash/report — User reportet Karte +GET /v1/admin/reports — Admin-Inbox (verifizierte Mana-Mods only) +POST /v1/admin/decks/:slug/takedown — Admin entfernt Deck +POST /v1/admin/authors/:slug/ban — Admin sperrt Author +POST /v1/admin/authors/:slug/verify-mana — Mana-Verein-Badge vergeben +``` + +### 7.7 Notifications + +``` +GET /v1/notifications — Unread + recent +POST /v1/notifications/:id/read — Mark read +PATCH /v1/notifications/preferences — Settings (welche Events triggern Push) +``` + +## 8. UI / Routes (Cards-Frontend) + +``` +/explore — Featured + Trending + Tag-Tree + Search-Bar +/explore/search?q=… — Search-Result-Page +/explore/tag/:slug — Tag-Page + +/u/:slug — Author-Profil (Public) +/u/:slug/follow — Follow-Button im Header + +/d/:slug — Public-Deck-Detail-View + (Description, Stats, Latest-Karten-Preview, Subscribe/Fork/Star/Buy, Discussions) +/d/:slug/v/:semver — spezifische Version +/d/:slug/discussions — Alle Discussions zum Deck +/d/:slug/pull-requests — PRs +/d/:slug/pull-requests/:id — PR-Detail mit Diff-View + +/me/decks — Eigene private Decks (heute existiert) +/me/published — Eigene published Decks + Stats +/me/subscribed — Abonnierte Decks (mit Update-Indikator) +/me/forks — Geforkte Decks +/me/dashboard — Author-Dashboard (Erlöse, Subscriber-Wachstum) + +/feed — Personal Activity-Feed (Following-Activity + Updates) + +/admin/reports — Admin-Inbox (verified-mana-only) +/admin/decks — Take-Down-UI +/admin/authors — Verify + Ban +``` + +Zusätzlich: einige bestehende Komponenten erweitern (DeckDetail bekommt Subscribe-Button etc.). + +## 9. Cold-Start-Strategie + +Marktplatz ohne Decks ist nutzlos. Drei parallele Hebel: + +1. **Verein-Seed-Decks**: 50 hochwertige Decks selbst erstellen — sprachen (Top-3000 Vokabeln pro Sprache), Geschichte (TimeLine-Karten), Allgemeinwissen, Programmierung. Vom Mana-Team published, alle mit `verified_mana`-Badge. +2. **Anki-Top-100-Import-Service**: Wir bieten an, populäre Anki-Web-Decks (mit korrekter CC-BY-Lizenz) zu importieren und mit Original-Author-Attribution als Public-Decks anzulegen. Original-Author bekommt das `verified_mana`-Badge wenn er sich registriert. +3. **Influencer-Outreach**: Direkte Ansprache von 10-20 Anki-Power-Authoren (AnKing, etc.) mit dem Angebot eines verified-Status + sehr Author-freundlichem Cut. Wenn 1-2 wechseln, kommt ein Lawineneffekt. + +## 10. Risiken + Mitigationen + +| Risiko | Mitigation | +|---|---| +| Cold-Start (Marktplatz leer) | Seed + Anki-Import + Influencer (siehe §9) | +| Spam / Junk-Decks | AI-Mod-First-Pass + Report-System + Author-Ban-Flow | +| Copyright-Klagen (Lehrbuch-Karten) | Lizenz-Pflichtangabe + DMCA-Process + Take-Down-Workflow | +| Server-Kosten (Storage von Bildern/Audio) | Soft-Quotas pro Author-Tier (§6.6) + lossy compression im mana-media | +| AnkiHub als Konkurrent (Live-Updates Medizin) | „Alle Fachgebiete + gratis" als Counter; Med-Decks aktiv akquirieren | +| Mana-Credits-Verein-Cut zu hoch oder zu niedrig | A/B-Test verschiedener Cut-Verhältnisse; Best-Practice: ~80/20 für Standard, ~90/10 für Verified | +| Author-Frustration über fehlende Mobile-App | Klarer Roadmap-Hinweis + Mobile-Push-Notifications via PWA (heute geht das schon) | +| Discussions werden Toxic | Author-Owns-Their-Discussions (kann hide); Community-Mod (Verified-User können flaggen); klar dokumentierte Community-Guidelines | +| Mining/Scraping der Decks | Rate-limit auf API + Auth-Required für full-content; offene Snippets aber paywall am Voll-Inhalt | + +## 11. Phasenplan + +> **Co-Learn explizit ausgeklammert.** Mobile-App auch. + +### Phase α — Daten-Skelett (cards-server v0.1) + +- `services/cards-server/` SvelteKit-style Service-Setup, Hono + Bun + Drizzle +- Alle Schema-Tabellen + Migrationen (§4) +- API-Routes (CRUD-Niveau): Authoren, Decks, Versionen, Stars, Subscriptions +- OpenAPI-Spec +- Integration-Tests (Drizzle + Vitest) +- mana-auth-JWT-Middleware (`@mana/shared-hono`) +- Container in `docker-compose.macmini.yml` +- Cloudflare-Tunnel-Route `cards-api.mana.how` → `:3072` + +### Phase β — Author-Workflow + +- „Author werden"-Flow im Frontend (Profil anlegen, slug claimen) +- „Publish"-Aktion auf Deck-Detail-Seite + - Lizenz-Picker (SPDX-Auswahl) + - Beschreibung + Tags + - Optional: Preis in Credits +- Versioning: semver-Auto-Suggest (1.0.0 Erst-Publish, dann patch/minor/major) +- Changelog-Editor +- AI-First-Pass-Moderation (mana-llm classify) +- Author-Dashboard (eigene Decks, Subscriber-Counts, Erlöse) + +### Phase γ — Discovery-Frontend + +- `/explore`-Seite mit Featured + Trending + Tag-Tree +- Volltext-Suche (Postgres FTS via tsvector) +- Tag-Hierarchie + Filter-UI +- Author-Profile + Follow-Button + Activity-Feed +- Star-System + +### Phase δ — Subscribe + Updates + Smart-Merge + +- „Abonnieren"-Button → lädt aktuelle Version in lokale Cards-DB +- Update-Detection: cards-server WebSocket (oder Polling) → „Neue Version verfügbar"-Toast +- **Smart-Merge**: Diff zwischen Versionen → unveränderte Karten behalten FSRS-State, neue Karten kommen frisch dazu, gelöschte Karten werden ausgeblendet (mit „Karte aus Update entfernt"-Hinweis) +- Diff-View für User: „3 neue Karten, 2 geändert, 1 entfernt — Update jetzt anwenden?" +- Push-Notifications via mana-notify + +### Phase ε — Pull-Requests + Discussions + +- PR-Erstellen-UI im Deck-Detail („Karte verbessern" / „Karte hinzufügen") +- PR-Diff-View (GitHub-Style) +- Author-Merge-Workflow → erstellt neue Version automatisch +- Inline-Discussion-Threads pro Karte (während des Lernens und im Detail-View) +- Mention-System (@username triggert mana-notify) + +### Phase ζ — mana-credits Marketplace + +- Paid-Deck-Workflow End-to-End (siehe §5) +- Author-Auszahlungs-Pipeline +- Refund-Workflow +- Buyer-Dashboard mit Käufen +- Author-Payouts-Reporting (CSV-Export für Steuern) + +### Phase η — Moderation + Trust + +- Report-Buttons überall (Deck, Karte, Discussion) +- Admin-Inbox-UI für verified-mana-only-Mods +- Take-Down-Workflow mit Public-Changelog +- Verified-Badge-Vergabe-UI (Mana-Admin → Author) +- Community-Verified Auto-Calculation (Cron-Job) +- Author-Ban-Process + +### Phase θ — Deep AI + +- Auto-Tag-Suggestions beim Publish (mana-llm) +- Auto-Summary für Decks (mana-llm Markdown-Render-tauglich) +- Audio-Vertonung mit mana-tts (Author opt-in: alle Karten als Audio generieren) +- Semantic-Search via Embeddings (mana-llm + pgvector) +- Personalized-Discovery („Empfohlen für dich" basierend auf Lern-Historie) + +### Phase ι — Optimierung + Skalierung + +- Search-Service als separater Pod (Meilisearch wenn Postgres FTS limitiert) +- CDN für public-deck-content (Cache + Geo-Distribution) +- Rate-Limiting + Anti-Scraping +- Real-time-Stats-Aggregation (Materialized Views) + +### Phasen die später kommen (explizit nicht in diesem Plan) + +- **Phase λ — Co-Learn-Sessions**: WebSocket-Multiplayer, gemeinsam lernen, Sehen-was-andere-machen +- **Phase μ — Mobile-Apps**: Expo-App (Cards-Standalone-Mobile) +- **Phase ν — Author-Tools**: Bulk-Edit-UI für Authoren mit großen Decks, Style-Templates, Author-Analytics-Deep-Dive +- **Phase ξ — Lern-Battles**: Asynchroner Wettkampf-Modus + +## 12. Konkrete Differenzierungs-Hebel — was geht wirklich nur bei uns + +1. **Gratis Cloud-Sync + Live-Updates auf abonnierte Decks**. Niemand sonst hat beides ohne Paywall. +2. **Pull-Requests auf Decks**. AnkiHub erlaubt das nicht so flüssig, andere gar nicht. „Lerne und verbessere mit" als Modus. +3. **Card-Discussions inline** — wenn ich beim Lernen eine Karte unverständlich finde, kann ich direkt fragen / ergänzen. Anki hat Plugin dafür, RemNote auch nicht. +4. **Authoren verdienen via mana-credits** — wir behandeln Authoren als 1st-Class-Konstrukt mit Erlös-Möglichkeit. Quizlet macht das nicht, AnkiWeb macht das nicht, Brainscape paywalled stattdessen die User. +5. **Open Source PWA** mit klarer Roadmap-Transparenz — Vertrauensvorsprung vs. Quizlet (closed, Trustpilot 1.4/5) und gegenüber AnkiPro/AnkiApp (closed-source, Brand-Sniper). +6. **Doppelte Verifizierungs-Stufen** mit unterschiedlichen Badges — Anki-Foren machen das ad-hoc; wir formalisieren es. +7. **AI als Moderator + Generator + Indexer** ohne Paywall — wir haben den eigenen mana-llm-Stack, Konkurrenten zahlen OpenAI per Call. + +## 13. Was wir NICHT tun + +- **Kein Decks-Bewertungssystem mit 1-5 Sternen**. Stars (Bookmarks) ja, Bewertungen nein — die werden gegamed (Quizlet-Erfahrung), und führen zu Author-Frust + Review-Bombing. +- **Kein Reddit-Style-Voting auf Karten / PRs / Discussions**. Wirkt cool, ruiniert die Community (Hacker-News-Effekt). Lieber „helpful"-Reactions in begrenzten Kategorien. +- **Kein „Karten der Woche" allein-algorithmisch**. Editorial-Pick (Mana-Verein) + Trending-Liste, aber niemals nur Algo, das landet immer beim niederschwelligsten Content. +- **Kein Anki-Bashing im Marketing**. Anki ist OSS, ehrlich, und wir wollen nicht ihre Audience entfremden — wir wollen sie ergänzen. Bridge nicht Burning. +- **Keine Pflicht-Klarnamen**. Pseudonyme bleiben gleichberechtigt. Verifizierung ist Bonus, nicht Pflicht. +- **Kein Marketplace-Cut über 30 %**. Apple-App-Store-Hass ist real, wir bleiben fair. + +## 14. Offene Punkte die später entschieden werden müssen + +- **Mobile-Push-Notifications** für Subscribe-Updates: native PWA-Push reicht aktuell, aber Browser-API ist hin- und her — könnte Phase ι in einen eigenen Push-Service auslagern müssen. +- **Slack/Discord-Bots für Author-Updates**: nice-to-have, irgendwann. +- **Embed-Widget**: „Lerne dieses Deck auf meiner Webseite" mit IFrame — könnte Reichweite stark boosten. +- **API-Public**: API-Keys für Drittentwickler die eigene Tools rund um Cards bauen. +- **Backup für Subscriber**: Wenn ein Author published-Deck depubliziert, behalten Subscriber das letzte Snapshot (DSGVO-pflicht eh). +- **Internationalisierung der UI** (heute nur DE): nötig fürs internationale Publikum. + +## 15. Nächste Aktion + +Wenn Plan freigegeben ist: +1. **Phase α starten** — `services/cards-server/` Skelett erstellen + Schema-Migrationen +2. Plan in monatlichen Updates pflegen — Lessons-Learned + Anpassungen +3. Phasen-Demos jeweils auf `cards.mana.how` deployen, parallel mit Existing-Workflow + +--- + +*Plan erstellt: 2026-05-07. Owner: @till. Reviewer: TBD.*