Mirror of https://forge.levinkeller.de/levin/dorfarchiv.git
725ecacf0941a21079c7832b92cb054c4e62e5d3
| 1 | # CLAUDE.md - Entwicklungsrichtlinien für das Dorfarchiv-Projekt |
| 2 | |
| 3 | ## Über dieses Projekt |
| 4 | |
| 5 | Das Dorfarchiv ist eine Docusaurus-basierte Dokumentationswebsite für die Dorfpflege Rossing. Es dient zur Verwaltung und Präsentation von Dorf-relevanten Dokumenten, Informationen und Archiven. |
| 6 | |
| 7 | ## Technologie-Stack |
| 8 | |
| 9 | - **Framework**: Docusaurus 3.8.1 |
| 10 | - **Sprache**: TypeScript 5.6 |
| 11 | - **Runtime**: Node.js 22.0+ |
| 12 | - **Paketmanager**: npm |
| 13 | - **Backend**: PocketBase 0.26.2 |
| 14 | - **UI-Framework**: React 19.0 |
| 15 | - **Linting**: Biome |
| 16 | |
| 17 | ## Projektstruktur |
| 18 | |
| 19 | ``` |
| 20 | dorfarchiv/ |
| 21 | ├── docs/ # Dokumentationsinhalte (Markdown) |
| 22 | ├── blog/ # Blog-Beiträge |
| 23 | ├── src/ # React-Komponenten und Seiten |
| 24 | ├── static/ # Statische Assets (Bilder, Dateien) |
| 25 | ├── .devcontainer/ # Development Container Konfiguration |
| 26 | ├── .github/ # GitHub Actions und Workflows |
| 27 | ├── docusaurus.config.ts # Docusaurus-Hauptkonfiguration |
| 28 | ├── sidebars.ts # Sidebar-Navigation |
| 29 | ├── package.json # Projekt-Abhängigkeiten |
| 30 | ├── biome.json # Biome-Linter-Konfiguration |
| 31 | └── tsconfig.json # TypeScript-Konfiguration |
| 32 | ``` |
| 33 | |
| 34 | ## Entwicklungs-Workflow |
| 35 | |
| 36 | ### Installation |
| 37 | |
| 38 | ```bash |
| 39 | npm install |
| 40 | ``` |
| 41 | |
| 42 | ### Entwicklungsserver starten |
| 43 | |
| 44 | ```bash |
| 45 | npm start |
| 46 | ``` |
| 47 | |
| 48 | Der Entwicklungsserver läuft standardmäßig unter `http://localhost:3000`. |
| 49 | |
| 50 | ### Build erstellen |
| 51 | |
| 52 | ```bash |
| 53 | npm run build |
| 54 | ``` |
| 55 | |
| 56 | Der Build-Prozess: |
| 57 | 1. Kopiert PocketBase UMD-Datei nach `static/public/` |
| 58 | 2. Erstellt eine produktionsreife statische Website im `build/`-Verzeichnis |
| 59 | |
| 60 | ### Weitere nützliche Befehle |
| 61 | |
| 62 | ```bash |
| 63 | npm run serve # Produktions-Build lokal testen |
| 64 | npm run clear # Cache und generierte Dateien löschen |
| 65 | npm run typecheck # TypeScript-Typenprüfung durchführen |
| 66 | ``` |
| 67 | |
| 68 | ## Coding-Standards |
| 69 | |
| 70 | ### Sprache |
| 71 | |
| 72 | - **Code und Kommentare**: Englisch |
| 73 | - **Dokumentationsinhalte**: Deutsch (Standard für das Dorfarchiv) |
| 74 | - **Commit-Messages**: Deutsch (mit englischen GitHub-Keywords wie `fix`, `feat`, etc.) |
| 75 | - **Pull Request Titel/Beschreibungen**: Deutsch |
| 76 | |
| 77 | ### Code-Stil |
| 78 | |
| 79 | - Das Projekt verwendet **Biome** für Linting und Formatierung |
| 80 | - TypeScript-strict-Mode ist aktiviert |
| 81 | - Folgen Sie den React-Best-Practices für Komponenten |
| 82 | |
| 83 | ### Commit-Konventionen |
| 84 | |
| 85 | Verwenden Sie konventionelle Commit-Messages mit deutschen Beschreibungen: |
| 86 | |
| 87 | - `feat: [Beschreibung]` - Neue Features |
| 88 | - `fix: [Beschreibung]` - Fehlerbehebungen |
| 89 | - `docs: [Beschreibung]` - Dokumentationsänderungen |
| 90 | - `style: [Beschreibung]` - Code-Formatierung (keine funktionalen Änderungen) |
| 91 | - `refactor: [Beschreibung]` - Code-Refactoring |
| 92 | - `test: [Beschreibung]` - Tests hinzufügen oder ändern |
| 93 | - `chore: [Beschreibung]` - Wartungsaufgaben |
| 94 | |
| 95 | Beispiele: |
| 96 | ``` |
| 97 | feat: Navigation für Archiv-Kategorien hinzugefügt |
| 98 | fix: Darstellungsfehler in der mobilen Ansicht behoben |
| 99 | docs: Anleitung für neue Mitglieder erweitert |
| 100 | ``` |
| 101 | |
| 102 | ## Dokumentation schreiben |
| 103 | |
| 104 | ### Markdown-Dateien |
| 105 | |
| 106 | - Alle Dokumentationsdateien liegen in `docs/` |
| 107 | - Verwenden Sie Frontmatter für Metadaten: |
| 108 | |
| 109 | ```markdown |
| 110 | --- |
| 111 | id: eindeutige-id |
| 112 | title: Seitentitel |
| 113 | sidebar_label: Label in der Sidebar |
| 114 | --- |
| 115 | |
| 116 | # Überschrift |
| 117 | |
| 118 | Inhalt hier... |
| 119 | ``` |
| 120 | |
| 121 | ### Bilder und Assets |
| 122 | |
| 123 | - Statische Assets in `static/img/` ablegen |
| 124 | - Referenzierung in Markdown: `/img/dateiname.png` |
| 125 | |
| 126 | ### Interne Links |
| 127 | |
| 128 | ```markdown |
| 129 | [Link-Text](./andere-seite.md) |
| 130 | [Link zu Section](./seite.md#section-id) |
| 131 | ``` |
| 132 | |
| 133 | ## Docker-Unterstützung |
| 134 | |
| 135 | Das Projekt kann mit Docker betrieben werden: |
| 136 | |
| 137 | ```bash |
| 138 | docker compose up --build |
| 139 | ``` |
| 140 | |
| 141 | Die Konfiguration befindet sich in: |
| 142 | - `Dockerfile` - Container-Definition |
| 143 | - `docker-compose.yaml` - Multi-Container-Setup |
| 144 | - `.devcontainer/` - VS Code Dev Container |
| 145 | |
| 146 | ## PocketBase Integration |
| 147 | |
| 148 | Das Projekt nutzt PocketBase für Backend-Funktionalität: |
| 149 | |
| 150 | - PocketBase UMD-Datei wird beim Build automatisch kopiert |
| 151 | - Konfiguration für Authentifizierung und Datenverwaltung |
| 152 | |
| 153 | ## Testing und Qualitätssicherung |
| 154 | |
| 155 | ### Vor dem Commit |
| 156 | |
| 157 | 1. TypeScript-Prüfung durchführen: `npm run typecheck` |
| 158 | 2. Build testen: `npm run build` |
| 159 | 3. Entwicklungsserver testen: `npm start` |
| 160 | |
| 161 | ### Pull Requests |
| 162 | |
| 163 | - Beschreiben Sie Änderungen auf Deutsch |
| 164 | - Referenzieren Sie relevante Issues mit `closes #<issue-nummer>` oder `fixes #<issue-nummer>` |
| 165 | - Stellen Sie sicher, dass der Build erfolgreich ist |
| 166 | - Fügen Sie Screenshots hinzu bei UI-Änderungen |
| 167 | |
| 168 | ## Häufige Aufgaben |
| 169 | |
| 170 | ### Neue Dokumentationsseite hinzufügen |
| 171 | |
| 172 | 1. Markdown-Datei in `docs/` erstellen |
| 173 | 2. Frontmatter hinzufügen |
| 174 | 3. Bei Bedarf `sidebars.ts` aktualisieren |
| 175 | |
| 176 | ### Blog-Post erstellen |
| 177 | |
| 178 | 1. Datei in `blog/` erstellen mit Format: `YYYY-MM-DD-titel.md` |
| 179 | 2. Frontmatter mit `author`, `title`, `tags` hinzufügen |
| 180 | |
| 181 | ### Styling anpassen |
| 182 | |
| 183 | - CSS-Variablen in `src/css/custom.css` bearbeiten |
| 184 | - Komponenten-Styles in jeweiligen `.module.css` Dateien |
| 185 | |
| 186 | ## Hilfreiche Links |
| 187 | |
| 188 | - [Docusaurus Dokumentation](https://docusaurus.io/docs) |
| 189 | - [Markdown Guide](https://www.markdownguide.org/) |
| 190 | - [React Dokumentation](https://react.dev/) |
| 191 | - [TypeScript Handbook](https://www.typescriptlang.org/docs/) |
| 192 | |
| 193 | ## Support und Fragen |
| 194 | |
| 195 | - Issues auf GitHub erstellen für Bugs oder Feature-Anfragen |
| 196 | - Diskussionen für allgemeine Fragen nutzen |
| 197 | |
| 198 | ## Hinweise für Claude AI |
| 199 | |
| 200 | ### Bevorzugte Vorgehensweise |
| 201 | |
| 202 | - Lesen Sie immer zuerst die bestehenden Dateien, bevor Sie Änderungen vornehmen |
| 203 | - Verwenden Sie `Edit` für Änderungen an bestehenden Dateien statt `Write` |
| 204 | - Testen Sie Änderungen mit `npm run typecheck` und `npm run build` |
| 205 | - Halten Sie sich an die Projektstruktur und bestehende Patterns |
| 206 | |
| 207 | ### Wichtige Einschränkungen |
| 208 | |
| 209 | - Ändern Sie keine Dateien in `.github/workflows/` (erfordert spezielle Berechtigungen) |
| 210 | - Behalten Sie die deutsche Sprache für Dokumentationsinhalte bei |
| 211 | - Verwenden Sie englische GitHub-Keywords (`fix`, `fixes`, `closes`, etc.) in Commit-Messages |
| 212 | |
| 213 | ### Testing-Workflow |
| 214 | |
| 215 | Nach Änderungen sollten folgende Befehle erfolgreich durchlaufen: |
| 216 | |
| 217 | ```bash |
| 218 | npm run typecheck # TypeScript-Prüfung |
| 219 | npm run build # Build-Test |
| 220 | ``` |
| 221 | |
| 222 | Falls diese Befehle aufgrund fehlender Berechtigungen nicht ausgeführt werden können, dokumentieren Sie dies im Pull Request, damit der Benutzer die Tests manuell durchführen kann. |