Administrator-Handbuch¶

Audience: Admin
You will learn: - Zentrale Icon-Bibliothek verwalten und erweitern - Neue Icons hinzufügen und organisieren - Kategorisierung und Metadaten pflegen - System-Wartung und Updates durchführen

Pre-requisites: - Entwickler-Setup abgeschlossen - Admin-Rechte auf dem Icon Tool Repository - Grundkenntnisse in Node.js und Python

Systemverwaltung¶

Icon-Bibliothek erweitern¶

1. Neue Icons hinzufügen¶

# 1. FontAwesome Icon-Namen identifizieren
# Besuche: https://fontawesome.com/icons (Free + Solid Filter)
# Beispiel: faNewIcon → faNewIcon

# 2. extract-icons.js erweitern
nano extract-icons.js

In extract-icons.js hinzufügen:

const icons = {
  // Bestehende Icons...
  'faNewIcon': 'new-icon.svg',           // Neues Icon
  'faAnotherIcon': 'another-icon.svg',   // Weiteres Icon
};

Icons extrahieren:

node extract-icons.js

Erwartetes Ergebnis:

✓ faNewIcon → new-icon.svg erstellt
✓ 163 Icons extrahiert (vorher: 162)
✓ ZIP erstellt: 70.234 bytes

Evidenz: extract-icons.js:9-270, docs/USAGE.md:137-154

2. Kategorisierung aktualisieren¶

# icons.json erweitern
nano icons.json

Kategorie hinzufügen/erweitern:

{
  "Navigation & Direction": [
    "arrow-up.svg",
    "new-icon.svg"
  ],
  "Neue Kategorie": [
    "another-icon.svg"
  ]
}

Validierung:

# Flask-Server starten und prüfen
python app.py

# Browser öffnen: http://localhost:5000
# Neue Icons in korrekter Kategorie prüfen

Evidenz: icons.json:1-206, app.py:7-43

Qualitätssicherung¶

1. Icon-Konsistenz prüfen¶

# Alle SVG-Dateien auf korrekte Struktur prüfen
find static/icons -name "*.svg" -exec grep -L "currentColor" {} \;

# Sollte leer sein - alle Icons müssen currentColor haben

2. Kategorisierung validieren¶

# Python-Skript für Kategorie-Validierung
python3 -c "
import json
import os

# icons.json laden
with open('icons.json') as f:
    categories = json.load(f)

# Alle kategorisierten Icons sammeln
categorized = set()
for cat_icons in categories.values():
    categorized.update(cat_icons)

# Tatsächliche SVG-Dateien
actual = set(os.listdir('static/icons'))

# Unterschiede finden
missing = actual - categorized
uncategorized = categorized - actual

print(f'Kategorisierte Icons: {len(categorized)}')
print(f'Tatsächliche Icons: {len(actual)}')
print(f'Fehlende Kategorisierung: {missing}')
print(f'Kategorisiert aber nicht vorhanden: {uncategorized}')
"

Evidenz: app.py:22-43, icons.json:1-206

Version-Management¶

1. Icon-Versionen verfolgen¶

# Git-Tracking für Icon-Änderungen
git add static/icons/ icons.json extract-icons.js
git commit -m "feat: Add new icons for transportation category

- Added faNewIcon → new-icon.svg
- Added category 'Transportation Extended'
- Total icons: 163 (+1)
- ZIP size: 70KB (+1KB)"

# Tag für Releases
git tag -a v1.1.0 -m "Icon release v1.1.0 - Transportation icons"

2. Changelog pflegen¶

CHANGELOG.md aktualisieren:

## [1.1.0] - 2025-08-24

### Added
- new-icon.svg (Transportation category)
- Extended transportation icon collection

### Changed
- ZIP archive size: 69KB → 70KB

### Technical
- Total icons: 162 → 163
- Categories: 20 → 21

Administrative Tasks¶

1. Benutzer-Feedback verwalten¶

Icon-Anfragen dokumentieren:

# GitHub Issues für Icon-Requests nutzen
# Template: .github/ISSUE_TEMPLATE/icon-request.md

---
name: Icon Request
about: Request new icons for the library
labels: enhancement, icons

**Icon Name:** [FontAwesome icon name]
**Use Case:** [Project/feature description]
**Category:** [Suggested category]
**Priority:** [High/Medium/Low]
---

2. Performance-Monitoring¶

# ZIP-Größen überwachen
ls -lh *.zip

# Expected output:
# -rw-r--r-- 1 user user  69K Aug 24 10:30 turkiye-atlasi-icons.zip
# -rw-r--r-- 1 user user 8.2K Aug 24 10:30 selected-icons.zip

# Warnung bei > 100KB ZIP-Größe

3. Dependency-Updates¶

# Node.js Dependencies prüfen
npm audit
npm outdated

# FontAwesome Updates
npm update @fortawesome/fontawesome-svg-core
npm update @fortawesome/free-solid-svg-icons

# Python Dependencies
pip list --outdated
pip install --upgrade flask

Evidenz: package.json:12-16, pyproject.toml:6-8

Batch-Operationen¶

1. Mehrere Icons gleichzeitig hinzufügen¶

// bulk-add-icons.js
const newIcons = {
  'faTransportCategory1': 'transport-bus.svg',
  'faTransportCategory2': 'transport-train.svg',
  'faTransportCategory3': 'transport-ship.svg',
  // ... weitere Icons
};

// In extract-icons.js integrieren

2. Kategorien reorganisieren¶

# Python-Skript für Kategorie-Migration
python3 -c "
import json

# Aktuelle Kategorien laden
with open('icons.json') as f:
    categories = json.load(f)

# Migration: 'Transport' → 'Transportation & Logistics'
if 'Transport' in categories:
    categories['Transportation & Logistics'] = categories.pop('Transport')

# Speichern
with open('icons.json', 'w') as f:
    json.dump(categories, f, indent=2)

print('✓ Kategorien migriert')
"

Monitoring & Wartung¶

1. System-Health prüfen¶

# Flask-App Health Check
curl -f http://localhost:5000/api/icons || echo "❌ API nicht erreichbar"

# Icon-Anzahl prüfen
python3 -c "
import json
with open('icons.json') as f:
    cats = json.load(f)
total = sum(len(icons) for icons in cats.values())
print(f'📊 Total kategorisierte Icons: {total}')
"

# Dateisystem prüfen
find static/icons -name "*.svg" | wc -l

2. Backup-Strategien¶

# Tägliches Backup der Icon-Bibliothek
tar -czf "backup-$(date +%Y%m%d).tar.gz" \
    static/icons/ \
    icons.json \
    extract-icons.js \
    create-selected-icons.js

# Retention: 30 Tage
find . -name "backup-*.tar.gz" -mtime +30 -delete

Troubleshooting für Admins¶

Problem: Icons werden nach Update nicht angezeigt¶

Lösung:

# 1. Cache leeren
rm -rf static/icons/*
node extract-icons.js

# 2. Flask-Server neu starten
pkill -f "python app.py"
python app.py &

# 3. Browser-Cache leeren (Benutzer informieren)

Problem: Kategorisierung funktioniert nicht¶

Lösung:

# icons.json Syntax prüfen
python3 -c "import json; json.load(open('icons.json'))" \
  && echo "✓ JSON valid" || echo "❌ JSON invalid"

# Flask-Logs prüfen
tail -f flask.log  # wenn logging konfiguriert

Problem: ZIP-Archiv zu groß¶

Lösung:

# Icon-Optimierung (optional, mit svgo)
npm install -g svgo
find static/icons -name "*.svg" -exec svgo {} \;

# Alternative: Kategorien aufteilen
node create-category-zips.js  # Separate ZIPs pro Kategorie

Integration in CI/CD¶

1. Automatisierte Tests¶

# .github/workflows/icon-validation.yml
name: Icon Validation

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Validate Icons
        run: |
          # JSON-Syntax prüfen
          python -c "import json; json.load(open('icons.json'))"

          # Icon-Anzahl prüfen
          node extract-icons.js

          # ZIP-Größe begrenzen
          test $(stat -c%s "turkiye-atlasi-icons.zip") -lt 100000

2. Automatische Updates¶

# Wöchentliche FontAwesome Updates
# .github/workflows/weekly-update.yml
- name: Update FontAwesome
  run: |
    npm update @fortawesome/free-solid-svg-icons
    node extract-icons.js
    git diff --exit-code || echo "UPDATE_AVAILABLE=true" >> $GITHUB_ENV

Evidenz: replit.md:91 (Development Considerations)

Best Practices¶

1. Icon-Namenskonventionen¶

Konsistente Benennung: category-action.svg
Keine Leerzeichen: Bindestriche statt Leerzeichen
Beschreibende Namen: user-edit.svg statt edit.svg

2. Kategorisierung¶

Funktionale Gruppierung: Nach Anwendungsfall, nicht nach Aussehen
Maximale Kategorie-Größe: 15-20 Icons pro Kategorie
Eindeutige Zuordnung: Ein Icon pro Kategorie

3. Performance¶

ZIP-Größe überwachen: < 100KB für komplette Sammlung
Selektive Downloads: Projektspezifische Icon-Sets bevorzugen
Caching: Browser-Caching für Icon-Dateien konfigurieren

Nächste Schritte: - Entwickler-Setup für erweiterte Anpassungen - Operations-Runbook für Produktivbetrieb