Upload via Git Manager GUI

2026-05-14 08:07:13 +02:00
parent c2273b5e44
commit 3c112ea75f
1 changed files with 535 additions and 0 deletions
--- a/DEV_GUIDE.md
+++ b/DEV_GUIDE.md
@@ -0,0 +1,535 @@
 # Entwicklerhandbuch — Git Manager Explorer Pro
 Dieses Dokument richtet sich an Entwickler, die an **Git Manager Explorer Pro** beitragen oder das Projekt erweitern möchten.
 ---
 ## Inhaltsverzeichnis
 1. [Projektstruktur](#projektstruktur)
 2. [Setup & Abhängigkeiten](#setup--abhängigkeiten)
 3. [Entwicklung starten](#entwicklung-starten)
 4. [Wichtige Module](#wichtige-module)
 5. [Neue Features hinzufügen](#neue-features-hinzufügen)
 6. [Build & Release](#build--release)
 7. [Debugging & Testing](#debugging--testing)
 8. [Code-Konventionen](#code-konventionen)
 9. [Häufige Aufgaben](#häufige-aufgaben)
 ---
 ## Projektstruktur
 ```
 git-manager-gui/
 ├── main.js                 # Electron Main Process — Fenster, Menü, IPC
 ├── preload.js             # Preload Script — sichere Electron API für Renderer
 ├── renderer/              # Frontend (React/Vanilla JS)
 │   ├── App.jsx            # React-Komponente (optional, optional genutzt)
 │   ├── Settings.jsx       # Settings-Modal
 │   ├── index.html         # HTML Entry Point
 │   ├── index.js           # Renderer Init
 │   ├── renderer.js        # Hauptlogik: UI, Grid, Editor, API-Calls
 │   ├── style.css          # Styling
 │   └── modules/           # Feature-Module
 │       ├── editor.js      # Editor-Funktion (Syntax Highlighting, etc.)
 │       ├── gitea.js       # Gitea API Wrapper
 │       ├── github.js      # GitHub API Wrapper
 │       ├── progress.js    # Progress-Bar & Ladeindikatoren
 │       ├── state.js       # State Management (Favoriten, Verlauf, etc.)
 │       └── ui.js          # UI Helpers (Dialoge, Toast, etc.)
 ├── src/                   # Backend (Node.js Main Process)
 │   ├── git/              
 │   │   ├── gitHandler.js  # Git CLI Wrapper (Commits, Tags, etc.)
 │   │   └── apiHandler.js  # Gitea/GitHub API HTTP Client
 │   ├── backup/
 │   │   ├── BackupManager.js    # Backup/Restore Logik
 │   │   ├── BackupProvider.js   # Provider Interface
 │   │   └── LocalProvider.js    # Lokale Datei-Provider
 │   └── utils/
 │       └── helpers.js     # Allgemeine Hilfsfunktionen
 ├── __tests__/
 │   └── gitHandler.test.js # Jest Unit Tests
 ├── updater.js            # App-Update-Logik
 ├── package.json          # Dependencies & Scripts
 ├── HANDBUCH.html         # Benutzerhandbuch (HTML)
 └── README.md             # Projekt-Übersicht
 ```
 ---
 ## Setup & Abhängigkeiten
 ### Voraussetzungen
 - **Node.js** 16+ (empfohlen: LTS)
 - **npm** 7+
 - **Git** (für Git-Operationen)
 - **Visual Studio Code** (optional, empfohlen)
 ### Installation
 ```bash
 # Repository klonen
 git clone https://github.com/dein-username/git-manager-gui.git
 cd git-manager-gui
 # Dependencies installieren
 npm install
 # App starten
 npm start
 ```
 ### Wichtige Dependencies
 | Package | Verwendung |
 |---------|-----------|
 | `electron` | Desktop-Framework |
 | `sqlite3` | Lokale Datenspeicherung (Favoriten, Verlauf) |
 | `axios` | HTTP-Requests zu Gitea/GitHub APIs |
 | `crypto` | Verschlüsselung von Credentials |
 | `jest` | Testing Framework |
 ---
 ## Entwicklung starten
 ### Dev-Server / Hot Reload
 Es gibt aktuell keinen automatischen Hot Reload. Nach Code-Änderungen:
 ```bash
 # App neu starten
 npm start
 # Oder im laufenden Fenster: DevTools öffnen
 # Strg+Shift+I → Reload (Strg+R)
 ```
 ### DevTools debuggen
 ```javascript
 // In main.js, beim Erstellen des Fensters:
 mainWindow.webContents.openDevTools();
 // Oder per Shortcut im laufenden Fenster:
 // Strg+Shift+I
 ```
 ### Logs anschauen
 ```bash
 # Logs der letzten Session anschauen:
 # Windows: %APPDATA%\git-manager-gui\logs\
 # oder direkt im app data folder
 # Mit Winston logger (falls implementiert):
 npm run logs
 ```
 ---
 ## Wichtige Module
 ### `renderer/renderer.js` — Hauptlogik
 Das Herzstück der App. Enthält:
 - **Globale State-Variablen**: `favorites`, `recentRepos`, `currentState`, `pinnedRepos`
 - **Grid-Rendering**: `loadRepos()`, `loadGiteaRepos()`, `loadGithubRepos()`
 - **Kontext-Menü**: `showRepoContextMenu()`
 - **Datei-Explorer**: `loadRepoContents()`, `renderExplorer()`
 - **Editor**: `openFileEditor()`, mit Speichern & Syntax-Highlighting
 - **Favoriten/Verlauf**: `addToFavorites()`, `addToRecent()`
 **Wichtige Funktionen:**
 ```javascript
 // Repository-Liste laden
 loadRepos() → loadGiteaRepos() oder loadGithubRepos()
 // Repository öffnen (Datei-Explorer)
 loadRepoContents(owner, repo, path)
 // Datei bearbeiten
 openFileEditor(owner, repo, path, content)
 // Favoriten hinzufügen
 async addToFavorites(owner, repo, cloneUrl, platform)
 // Settings speichern
 async saveSettings(settings)
 ```
 ### `src/git/gitHandler.js` — Git-Operationen
 Wrapper um Git CLI. Beispiele:
 ```javascript
 // Commits einsehen
 const commits = await getCommitLog(repoPath, branch);
 // Tags auflisten
 const tags = await getTagList(repoPath);
 // Branch wechseln
 await checkoutBranch(repoPath, branchName);
 // Lokales Repo klonen
 await cloneRepository(cloneUrl, targetPath);
 ```
 ### `src/git/apiHandler.js` — API-Calls
 HTTP-Wrapper für Gitea/GitHub APIs.
 ```javascript
 // Gitea Repositories auflisten
 const repos = await getGiteaRepos(url, token, username);
 // GitHub Repositories
 const repos = await getGithubRepos(token);
 // Repository erstellen
 await createGiteaRepo(url, token, { name, description, private });
 // Datei speichern
 await updateGiteaFile(url, token, owner, repo, path, content, message);
 ```
 ### `renderer/modules/state.js` — State Management
 Persistiert Favoriten, Verlauf und Settings.
 ```javascript
 // State laden/speichern
 loadState() → returns { favorites, recent, pinnedRepos }
 saveState(state) → speichert lokal
 // Helpers
 addFavorite(repo)
 removeFavorite(repo)
 addRecentRepo(repo)
 clearRecent()
 ```
 ---
 ## Neue Features hinzufügen
 ### Beispiel: Neuer API-Endpoint integrieren
 #### Schritt 1: API-Wrapper in `src/git/apiHandler.js` ergänzen
 ```javascript
 /**
 * Gitea Webhook auflisten
 */
 async function getGiteaWebhooks(url, token, owner, repo) {
    const path = `/api/v1/repos/${owner}/${repo}/hooks`;
    return axios.get(`${url}${path}`, {
        headers: { 'Authorization': `token ${token}` }
    }).then(r => r.data);
 }
 module.exports = { getGiteaWebhooks, /* ... other functions */ };
 ```
 #### Schritt 2: IPC-Handler in `main.js` ergänzen
 ```javascript
 // In ipcMain.handle() Bereich:
 ipcMain.handle('getGiteaWebhooks', async (event, { url, token, owner, repo }) => {
    try {
        const webhooks = await apiHandler.getGiteaWebhooks(url, token, owner, repo);
        return { ok: true, webhooks };
    } catch (err) {
        return { ok: false, error: err.message };
    }
 });
 ```
 #### Schritt 3: UI in `renderer/renderer.js` hinzufügen
 ```javascript
 // Button im Repo-Kontextmenü:
 if (option === 'webhooks') {
    const webhooks = await window.electronAPI.getGiteaWebhooks({
        url: currentState.giteaUrl,
        token: credentials.giteaToken,
        owner,
        repo
    });
    if (webhooks.ok) {
        showWebhookList(webhooks.webhooks);
    } else {
        showError('Webhooks laden fehlgeschlagen: ' + webhooks.error);
    }
 }
 ```
 ---
 ## Build & Release
 ### Production Build
 ```bash
 # Electron App als .exe packagen
 npm run build
 # Output: dist/git-manager-gui-Setup-2.x.x.exe
 ```
 ### Version erhöhen
 1. Version in `package.json` updaten: `"version": "2.1.4"`
 2. Changelog aktualisieren (optional)
 3. Build ausführen
 4. GitHub Release erstellen mit der .exe
 ---
 ## Debugging & Testing
 ### Unit Tests schreiben
 Jest ist konfiguriert. Test-Datei Vorlage:
 ```javascript
 // __tests__/myFeature.test.js
 const { myFunction } = require('../src/git/gitHandler');
 describe('Git Handler', () => {
    it('should parse commit log', () => {
        const result = myFunction(testData);
        expect(result.length).toBe(3);
        expect(result[0].sha).toMatch(/^[a-f0-9]{7}/);
    });
 });
 ```
 Tests starten:
 ```bash
 npm test
 # Mit Coverage:
 npm test -- --coverage
 # Watch Mode:
 npm test -- --watch
 ```
 ### Debugging im DevTools
 ```javascript
 // Im renderer.js oder irgendwo im Renderer:
 console.log('Debug Info:', data);
 // Öffne DevTools: Strg+Shift+I
 // Console Tab → alle Logs sichtbar
 ```
 ### Main Process debuggen
 ```javascript
 // In main.js:
 console.log('Main Process Log:', data);
 // Logs erscheinen in der Terminal-Console
 // wenn die App mit npm start gestartet wurde
 ```
 ---
 ## Code-Konventionen
 ### Variablen & Funktionen
 ```javascript
 // camelCase für Variablen und Funktionen
 const repoName = "mein-projekt";
 function loadRepositories() { }
 // SCREAMING_SNAKE_CASE für Konstanten
 const MAX_RETRIES = 5;
 const DEFAULT_TIMEOUT = 3000;
 // Präfixe für Boolean-Variablen
 const isPrivate = true;
 const hasCredentials = false;
 const shouldRetry = true;
 ```
 ### Async/Await
 ```javascript
 // Immer try-catch für async Funktionen
 async function loadData() {
    try {
        const data = await fetchFromAPI();
        return { ok: true, data };
    } catch (error) {
        console.error('Error:', error);
        return { ok: false, error: error.message };
    }
 }
 ```
 ### Kommentare
 ```javascript
 // Kurze Inline-Kommentare über Code
 const delay = 1000; // Millisekunden
 /**
 * Längere Beschreibung vor Funktion
 * @param {string} repoName - Name des Repositories
 * @returns {Promise<Object>} Result mit { ok, data, error }
 */
 async function loadRepository(repoName) {
    // Implementierung
 }
 ```
 ### Fehlerbehandlung
 ```javascript
 // Immer aussagekräftige Fehlermeldungen
 if (!token) {
    return { ok: false, error: 'missing-token' };
 }
 // Oder sprechend für Benutzer:
 if (!token) {
    return { ok: false, error: 'Gitea Token nicht gespeichert. Bitte Settings öffnen.' };
 }
 ```
 ---
 ## Häufige Aufgaben
 ### Neue Einstellung hinzufügen
 1. **In `Settings.jsx` UI-Control hinzufügen**
   ```jsx
   <label>Neue Option</label>
   <input type="checkbox" onChange={(e) => setSetting('newOption', e.target.checked)} />
   ```
 2. **In `renderer.js` speichern**
   ```javascript
   async function saveSettings(settings) {
       const result = await window.electronAPI.saveSettings(settings);
       // ...
   }
   ```
 3. **In `main.js` Handler**
   ```javascript
   ipcMain.handle('saveSettings', async (event, settings) => {
       // Validation und Speicherung
       return { ok: true };
   });
   ```
 ### Neuer Button in der Toolbar
 1. **In `index.html` Button hinzufügen**
   ```html
   <button id="btnMyFeature" title="Mein Feature">🎯 Feature</button>
   ```
 2. **In `renderer.js` Event-Handler**
   ```javascript
   if ($('btnMyFeature')) {
       $('btnMyFeature').onclick = () => {
           myFeatureHandler();
       };
   }
   ```
 ### Neue Kontextmenü-Option
 1. **In `showRepoContextMenu()` Item hinzufügen**
   ```javascript
   items.push({
       label: '🎯 Meine Aktion',
       click: () => myActionHandler(owner, repo)
   });
   ```
 2. **Handler implementieren**
   ```javascript
   function myActionHandler(owner, repo) {
       // Logik...
   }
   ```
 ### Neue API-Methode aufrufen
 1. **In `src/git/apiHandler.js` ergänzen**
 2. **In `main.js` IPC-Handler anlegen**
 3. **In `renderer.js` aufrufen:**
   ```javascript
   const result = await window.electronAPI.myNewMethod({ param1, param2 });
   ```
 ---
 ## Troubleshooting für Entwickler
 ### App startet nicht
 ```bash
 # Node/npm Version prüfen
 node --version  # sollte >= 16
 npm --version   # sollte >= 7
 # Dependencies neu installieren
 rm -r node_modules
 npm install
 npm start
 ```
 ### Fehler: "Cannot find module"
 ```bash
 # Dependencies aktualisieren
 npm install
 # Cache löschen
 npm cache clean --force
 ```
 ### Axios/API-Calls schlagen fehl
 - URL/Token in Settings prüfen
 - Gitea-Server online? `curl https://git.example.com/api/v1/user`
 - Token noch gültig? Im Gitea-Interface regenerieren
 - Firewall/VPN blockiert?
 ### Datei-Upload funktioniert nicht
 - Lokale Temp-Pfade prüfen (in `main.js`)
 - Git-Auth konfiguriert?
 - Ausreichend Festplatte?
 ---
 ## Ressourcen
 - [Electron Dokumentation](https://www.electronjs.org/docs)
 - [Gitea API](https://docs.gitea.io/en-us/api-usage/)
 - [GitHub API v3](https://docs.github.com/en/rest)
 - [Jest Testing](https://jestjs.io/docs/getting-started)
 ---
 ## Lizenz & Beitragen
 Dieses Projekt ist unter der **MIT-Lizenz** lizenziert.  
 Für Beiträge bitte einen **Pull Request** einreichen mit aussagekräftiger Beschreibung.
 ---
 **Letzte Aktualisierung:** 13. Mai 2026 | **Ersteller:** M_Viper