# Wiki Import – Designprinzipien (Extraktion)

**Status:** Analyse / Arbeitspapier  
**Stand:** 2026-07-04  
**Geltungsbereich:** Modul „MediaWiki Import“ — SMW-Ingest, Mapping, Tracking

**Serie:** Designprinzipien für Produktfamilie · Shinkan Dokument 11 von 15  
**Mitai-Vergleich:** [UNIVERSAL_IMPORT_DESIGN_PRINCIPLES.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/UNIVERSAL_IMPORT_DESIGN_PRINCIPLES.md) (#6)

**Kernkomponenten:**

| Bereich | Pfade |
|---------|-------|
| Router | `backend/routers/import_wiki.py`, `import_wiki_admin.py` |
| Client | `backend/smw_client.py` |
| Mapper | `backend/smw_mapper.py` |
| Tracking | `wiki_import_log`, `wiki_import_references` |
| Spec | `.claude/docs/technical/MEDIAWIKI_IMPORT_SPEC.md` |

---

## Modul

**Wiki Import (Semantic MediaWiki)**

Import von Übungen, Fähigkeiten, Methoden und Reifegradmodellen aus externem Wiki via API — Preview, Dry-Run, Duplikat-Erkennung, Admin-only.

---

## Designprinzipien

### 1. Ingest ≠ Interpretation

| | |
|---|---|
| **Prinzip** | `SmwClient` holt Rohdaten; `smw_mapper` mappt auf Shinkan-Modelle — getrennte Schichten. |
| **Begründung** | Analog Mitai Import: Transport/Parser ≠ Domänen-Insert. |
| **Quelle** | `import_wiki.py`; Mitai Universal Import |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | Keine generische Import-Registry wie Mitai CSV — wiki-spezifisch. |

### 2. Preview und Dry-Run vor Execute

| | |
|---|---|
| **Prinzip** | `/preview` zeigt Kandidaten; `dry_run=true` ohne DB-Schreiben. |
| **Begründung** | Admin sieht Auswirkungen; sichere Iteration. |
| **Quelle** | `ImportExecuteRequest` |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | — |

### 3. Duplikat-Tracking über Wiki-Referenzen

| | |
|---|---|
| **Prinzip** | `wiki_import_references` speichert Wiki-Titel ↔ Shinkan-ID für Re-Import. |
| **Begründung** | Idempotenz und Update statt blindem Duplicate. |
| **Quelle** | Domain Model Import-Tabellen |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | Gap-Analyse in `SMW_IMPORTER_GAP_ANALYSIS.md` beachten. |

### 4. Import-Typ als expliziter Parameter

| | |
|---|---|
| **Prinzip** | `import_type`: `exercise` \| `skill` \| `method` \| Modelle — eigener Mapper-Pfad. |
| **Begründung** | Klare Verantwortung pro Ziel-Entität. |
| **Quelle** | `map_wiki_to_*` in `smw_mapper.py` |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | Kein Plug-in-Registry-Pattern wie Mitai Module-Registry. |

### 5. Superadmin/Admin-only Execute

| | |
|---|---|
| **Prinzip** | `require_admin` auf Execute — Massenimport ist Plattform-Risiko. |
| **Begründung** | Governance und Datenqualität. |
| **Quelle** | `import_wiki.py` |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | — |

### 6. Kategorie aus Env mit Fallback

| | |
|---|---|
| **Prinzip** | `MEDIAWIKI_CATEGORY_*` Env-Variablen; leere Query → Default je Typ. |
| **Begründung** | Wiki-Struktur konfigurierbar ohne Code-Deploy. |
| **Quelle** | `CATEGORY_EXERCISES` etc. |
| **Tragfähigkeit** | **mittel** |
| **Einschränkung** | Hardcoded Wiki-URL in Doku — Umgebungsspezifisch halten. |

### 7. Background Tasks für lange Imports

| | |
|---|---|
| **Prinzip** | FastAPI `BackgroundTasks` für Execute — HTTP nicht blockieren. |
| **Begründung** | Große Kategorien ohne Timeout. |
| **Quelle** | Execute-Endpoint |
| **Tragfähigkeit** | **mittel** |
| **Einschränkung** | Kein Job-Status-Polling-UI wie Mitai — Log-Tabelle nutzen. |

---

## Nicht übernehmen

1. **Rohe Wiki-HTML ungemappt in DB** — immer Mapper.
2. **Import ohne Log/Re-Import-Referenz** — Duplikat-Chaos.
3. **Trainer-self-service Wiki-Import** — Admin-only.
4. **Skill-Scoring beim Insert** — Scores gehören in `skill_scoring`-Schicht.

---

## Verwandte Dokumentation

- [MEDIAWIKI_IMPORT_SPEC.md](../../../.claude/docs/technical/MEDIAWIKI_IMPORT_SPEC.md)
- [EXERCISE_CATALOG_DESIGN_PRINCIPLES.md](./EXERCISE_CATALOG_DESIGN_PRINCIPLES.md)
- Mitai: [UNIVERSAL_IMPORT_DESIGN_PRINCIPLES.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/UNIVERSAL_IMPORT_DESIGN_PRINCIPLES.md)
- [DESIGN_PRINCIPLES_INDEX.md](./DESIGN_PRINCIPLES_INDEX.md)