Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
6c7c24e887
shinkan-jinkendo/docs/jinkendo-family/design-principles/WIKI_IMPORT_DESIGN_PRINCIPLES.md
Lars 6c7c24e887
All checks were successful
Deploy Development / deploy (push) Successful in 48s
Details
Test Suite / pytest-backend (push) Successful in 45s
Details
Test Suite / lint-backend (push) Successful in 1s
Details
Test Suite / build-frontend (push) Successful in 15s
Details
Test Suite / k6 /health Baseline (push) Successful in 34s
Details
Test Suite / playwright-tests (push) Successful in 1m35s
Details
Add Jinkendo family design principles and entitlement model docs. 
Document cross-app architecture patterns, Mitai alignment, and family entitlement standards. Documentation only; no runtime changes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-14 09:12:48 +02:00

4.1 KiB
Raw Blame History

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 (#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