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)
|