mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 20:21:09 +02:00
0686300243
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) <noreply@anthropic.com>
602 lines
28 KiB
Markdown
602 lines
28 KiB
Markdown
# 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.*
|