Add automatic documentation synchronization system

Implements Option C (Hybrid) solution to prevent outdated documentation:

New Features:
- Pre-commit git hook that validates documentation before every commit
- npm run docs:check - Validates README against current project state
- npm run docs:sync - Automatically updates NPM Scripts section in README

What gets checked:
- NPM Scripts in package.json vs README
- API routes in app/api/* vs README
- App structure (directories in app/) vs README
- Components vs README
- Scripts vs README

Workflow:
1. Make code changes
2. git commit triggers pre-commit hook
3. Hook warns if documentation is outdated
4. Run docs:sync to auto-update or edit manually
5. Commit with updated README

Benefits:
- No more forgetting to update README
- Non-blocking (can use --no-verify if needed)
- Automatic NPM scripts synchronization
- Clear warnings show exactly what needs updating

Scripts added:
- scripts/check-docs.js - Validation script
- scripts/sync-docs.js - Synchronization script
- .git/hooks/pre-commit - Git hook (not tracked)

Documentation:
- Added complete workflow section in README
- Examples and usage tips included

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2025-12-04 12:27:52 +00:00
parent 4fcc5b989f
commit 17aaf130a8
4 changed files with 458 additions and 0 deletions

View File

@@ -1072,16 +1072,95 @@ npm run start # Production Server
npm run db:init # Beide DBs initialisieren
npm run db:init:app # Nur database.sqlite
npm run db:init:locations # Nur locations.sqlite
npm run db:init:geofence # Nur Geofence-Tabellen
npm run db:cleanup # Cleanup 7 Tage
npm run db:cleanup:7d # Cleanup 7 Tage
npm run db:cleanup:30d # Cleanup 30 Tage
# Testing
npm run test:location # Test-Location hinzufügen
npm run test:geofence # Geofence Detektion testen
npm run test:geofence:email # Geofence Email testen
npm run test:geofence:mqtt # MQTT Geofence testen
# Documentation
npm run docs:check # Dokumentation validieren
npm run docs:sync # Dokumentation synchronisieren
# Email Development
npm run email:dev # Email Template Dev Server
# Linting
npm run lint # ESLint ausführen
```
---
## 📚 Automatische Dokumentations-Synchronisation
Diese App verwendet **automatische Checks**, um sicherzustellen, dass die README-Dokumentation immer aktuell bleibt.
### 🔍 **Wie es funktioniert**
**Pre-Commit Hook (automatisch):**
- Läuft automatisch vor jedem `git commit`
- Prüft ob Projektstruktur, API-Routes, oder NPM Scripts aktualisiert werden müssen
- Warnt dich, wenn Änderungen erkannt werden
**Manuell Dokumentation prüfen:**
```bash
npm run docs:check
```
**Dokumentation automatisch aktualisieren:**
```bash
npm run docs:sync
```
### ⚙️ **Workflow-Beispiel**
```bash
# 1. Du änderst Code oder fügst API-Routes hinzu
git add .
git commit -m "Add new feature"
# 2. Pre-commit Hook warnt (falls README veraltet ist)
⚠️ Documentation may be outdated:
- New API Route: /api/foo/bar
- New npm script: test:foo
# 3. Du hast 3 Optionen:
# Option A: Automatisch synchronisieren
npm run docs:sync
git add README.md
git commit -m "Update documentation"
# Option B: Manuell README bearbeiten
# ... edit README.md ...
git add README.md
git commit -m "Update documentation"
# Option C: Hook überspringen (nicht empfohlen)
git commit --no-verify
```
### 🎯 **Was wird geprüft?**
- **NPM Scripts** - Alle package.json Scripts dokumentiert?
- **API Routes** - Alle app/api/* Routen erwähnt?
- **App Struktur** - Alle app/* Verzeichnisse in Projektstruktur?
- **Components** - Alle Komponenten dokumentiert?
- **Scripts** - Alle scripts/*.js Dateien erwähnt?
### 💡 **Tipps**
- Der Hook ist **nicht blockierend** - du kannst mit `--no-verify` überspringen
- `docs:sync` aktualisiert nur NPM Scripts (weitere Bereiche können später hinzugefügt werden)
- Warnungen sind manchmal "false positives" - das ist okay, besser zu vorsichtig!
---
## 📄 Lizenz
MIT License - Open Source