Lars
6c7c24e887
All checks were successful
Deploy Development / deploy (push) Successful in 48s
Test Suite / pytest-backend (push) Successful in 45s
Test Suite / lint-backend (push) Successful in 1s
Test Suite / build-frontend (push) Successful in 15s
Test Suite / k6 /health Baseline (push) Successful in 34s
Test Suite / playwright-tests (push) Successful in 1m35s
Document cross-app architecture patterns, Mitai alignment, and family entitlement standards. Documentation only; no runtime changes. Co-authored-by: Cursor <cursoragent@cursor.com>
119 lines
4.1 KiB
Markdown
119 lines
4.1 KiB
Markdown
# 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)
|