chore: 3-Zielgruppen-Docs + .copilot-no-tests angelegt
This commit is contained in:
parent
a7f71ebc9b
commit
048805302d
5 changed files with 287 additions and 0 deletions
0
.copilot-no-tests
Normal file
0
.copilot-no-tests
Normal file
112
docs/ADMIN.md
Normal file
112
docs/ADMIN.md
Normal file
|
|
@ -0,0 +1,112 @@
|
||||||
|
# Administrator-Handbuch – [PROJEKT_NAME]
|
||||||
|
|
||||||
|
> Zielgruppe: **Administratoren** – Menschen, die das System betreiben, deployen und konfigurieren.
|
||||||
|
> Voraussetzung: Grundkenntnisse in Linux, Docker und dem eingesetzten Stack.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Systemvoraussetzungen
|
||||||
|
|
||||||
|
<!-- TODO: Anforderungen an Host/Server -->
|
||||||
|
|
||||||
|
| Komponente | Mindestanforderung | Empfohlen |
|
||||||
|
|---|---|---|
|
||||||
|
| OS | … | … |
|
||||||
|
| RAM | … | … |
|
||||||
|
| Disk | … | … |
|
||||||
|
| Dependencies | … | … |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Deployment
|
||||||
|
|
||||||
|
### Erstes Aufsetzen
|
||||||
|
|
||||||
|
<!-- TODO: Schritt-für-Schritt Deployment -->
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Beispiel
|
||||||
|
git clone <repo> /opt/service
|
||||||
|
cd /opt/service
|
||||||
|
cp .env.example .env
|
||||||
|
# .env ausfüllen!
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
### Updates einspielen
|
||||||
|
|
||||||
|
<!-- TODO: Update-Prozedur -->
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git pull
|
||||||
|
docker compose pull
|
||||||
|
docker compose up -d --force-recreate
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Konfiguration
|
||||||
|
|
||||||
|
### Umgebungsvariablen (`.env`)
|
||||||
|
|
||||||
|
<!-- TODO: Alle relevanten Env-Vars dokumentieren -->
|
||||||
|
|
||||||
|
| Variable | Pflicht | Default | Beschreibung |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `EXAMPLE_VAR` | ✓ | – | Beschreibung |
|
||||||
|
|
||||||
|
### Persistente Daten (`/data/`)
|
||||||
|
|
||||||
|
Alle persistenten Daten liegen unter `/data/<service>/` im Repo-Root:
|
||||||
|
|
||||||
|
<!-- TODO: Alle Service-Unterordner und was drin liegt -->
|
||||||
|
|
||||||
|
| Pfad | Inhalt | Backup-Priorität |
|
||||||
|
|---|---|---|
|
||||||
|
| `data/<service>/` | … | hoch/mittel/niedrig |
|
||||||
|
|
||||||
|
**Backup-Hinweise:**
|
||||||
|
- `/data/` komplett sichern vor jedem Update
|
||||||
|
- Empfehlung: tägliches Backup via Cron / Restic / rsync
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Monitoring & Logs
|
||||||
|
|
||||||
|
<!-- TODO: Wie überwacht man das System? Wo sind die Logs? -->
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Logs ansehen
|
||||||
|
docker compose logs -f <service>
|
||||||
|
|
||||||
|
# Status prüfen
|
||||||
|
docker compose ps
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sicherheit
|
||||||
|
|
||||||
|
<!-- TODO: Firewall-Regeln, Portfreigaben, TLS-Setup etc. -->
|
||||||
|
|
||||||
|
- Offene Ports: …
|
||||||
|
- TLS: …
|
||||||
|
- Zugriffskontrolle: …
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
| Symptom | Ursache | Lösung |
|
||||||
|
|---|---|---|
|
||||||
|
| … | … | … |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Disaster Recovery
|
||||||
|
|
||||||
|
<!-- TODO: Was tun wenn es brennt? -->
|
||||||
|
|
||||||
|
1. Dienst stoppen: `docker compose down`
|
||||||
|
2. Backup einspielen: …
|
||||||
|
3. Dienst neu starten: `docker compose up -d`
|
||||||
105
docs/MAINTAINER.md
Normal file
105
docs/MAINTAINER.md
Normal file
|
|
@ -0,0 +1,105 @@
|
||||||
|
# Maintainer-Handbuch – [PROJEKT_NAME]
|
||||||
|
|
||||||
|
> Zielgruppe: **Entwickler & Maintainer** – Menschen, die den Code verstehen, erweitern oder reviewen.
|
||||||
|
> Voraussetzung: Entwicklungserfahrung mit dem eingesetzten Stack.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architektur
|
||||||
|
|
||||||
|
<!-- TODO: Beschreibe die Architektur (C4, Hexagonal, Event-Driven, etc.) -->
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────────────────────────────────────────────────────┐
|
||||||
|
│ TODO: Architektur-Diagramm (ASCII oder Mermaid) │
|
||||||
|
└──────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Wichtige Komponenten:**
|
||||||
|
|
||||||
|
| Komponente | Verantwortlichkeit | Ort |
|
||||||
|
|---|---|---|
|
||||||
|
| … | … | `src/…` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Projektstruktur
|
||||||
|
|
||||||
|
```
|
||||||
|
[PROJEKT_NAME]/
|
||||||
|
├── data/ ← Persistente Daten (gitignored)
|
||||||
|
│ └── <service>/ ← Ein Unterordner pro Service
|
||||||
|
├── docs/
|
||||||
|
│ ├── USER.md ← Endnutzer-Dokumentation
|
||||||
|
│ ├── ADMIN.md ← Administrator-Dokumentation
|
||||||
|
│ └── MAINTAINER.md ← Dieses Dokument
|
||||||
|
├── history/
|
||||||
|
│ ├── prompts/ ← Vollständige Agent-Konversationen (gitignored)
|
||||||
|
│ └── summary/
|
||||||
|
│ └── PROJECT_CONTEXT.md ← Aktueller Projektzustand für Agent-Kontext
|
||||||
|
└── … ← Source Code
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Entwicklungsumgebung aufsetzen
|
||||||
|
|
||||||
|
<!-- TODO: Wie richtet man die lokale Entwicklungsumgebung ein? -->
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone <repo>
|
||||||
|
cd <repo>
|
||||||
|
# Dependencies installieren
|
||||||
|
# Dev-Server starten
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architekturentscheidungen (ADRs)
|
||||||
|
|
||||||
|
ADR-Dateien liegen unter `docs/adr/`. Format: `NNN-titel.md`.
|
||||||
|
|
||||||
|
| Nr. | Titel | Status | Datum |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 000 | Template | accepted | … |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Coding-Konventionen
|
||||||
|
|
||||||
|
<!-- TODO: Projektspezifische Konventionen -->
|
||||||
|
|
||||||
|
- **Branches:** `feat/<ticket>-beschreibung`, `fix/<ticket>-beschreibung`
|
||||||
|
- **Commits:** Conventional Commits (`feat|fix|chore|docs|refactor|test|ci`)
|
||||||
|
- **Tests:** `tests/` spiegelt Source-Struktur, ≥ 80% Coverage
|
||||||
|
- **Linting:** …
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Agent-Kontext & History
|
||||||
|
|
||||||
|
Der Agent liest beim Start immer `history/summary/PROJECT_CONTEXT.md`.
|
||||||
|
Nach Abschluss einer Aufgabe wird dort der Projektzustand aktualisiert.
|
||||||
|
|
||||||
|
- Vollständige Konversationen: `history/prompts/` (committed – History bleibt vollständig erhalten)
|
||||||
|
- Komprimierter Kontext: `history/summary/PROJECT_CONTEXT.md` (committed)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Neues Feature hinzufügen
|
||||||
|
|
||||||
|
1. `history/summary/PROJECT_CONTEXT.md` lesen – aktuellen Stand verstehen
|
||||||
|
2. Issue / Ticket anlegen
|
||||||
|
3. Branch: `git checkout -b feat/<ticket>-beschreibung`
|
||||||
|
4. Implementieren + Tests schreiben
|
||||||
|
5. Dokumentation in `docs/USER.md` oder `docs/ADMIN.md` aktualisieren
|
||||||
|
6. `git commit` – Quality Gate läuft automatisch (pre-commit hook)
|
||||||
|
7. PR erstellen + Review
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Designentscheidungen
|
||||||
|
|
||||||
|
| Entscheidung | Begründung |
|
||||||
|
|---|---|
|
||||||
|
| … | … |
|
||||||
57
docs/USER.md
Normal file
57
docs/USER.md
Normal file
|
|
@ -0,0 +1,57 @@
|
||||||
|
# Benutzerhandbuch – [PROJEKT_NAME]
|
||||||
|
|
||||||
|
> Zielgruppe: **Endnutzer** – Menschen, die das Produkt täglich verwenden.
|
||||||
|
> Keine Kenntnisse über interne Architektur oder Deployment notwendig.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Was macht dieses Projekt?
|
||||||
|
|
||||||
|
<!-- TODO: 1-2 Sätze was das Projekt tut und welches Problem es löst -->
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Voraussetzungen
|
||||||
|
|
||||||
|
<!-- TODO: Was muss der Nutzer installiert haben / wissen? -->
|
||||||
|
|
||||||
|
- [ ] Anforderung 1
|
||||||
|
- [ ] Anforderung 2
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Erste Schritte
|
||||||
|
|
||||||
|
### Schritt 1: Installation / Zugang
|
||||||
|
|
||||||
|
<!-- TODO: Wie kommt der Nutzer an das System? -->
|
||||||
|
|
||||||
|
### Schritt 2: Erste Nutzung
|
||||||
|
|
||||||
|
<!-- TODO: Walkthrough für den häufigsten Use Case -->
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Hauptfunktionen
|
||||||
|
|
||||||
|
<!-- TODO: Wichtigste Features beschreiben, mit Beispielen -->
|
||||||
|
|
||||||
|
### Feature 1
|
||||||
|
|
||||||
|
### Feature 2
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Häufige Probleme & Lösungen
|
||||||
|
|
||||||
|
<!-- TODO: FAQ / Troubleshooting aus Nutzerperspektive -->
|
||||||
|
|
||||||
|
| Problem | Lösung |
|
||||||
|
|---------|--------|
|
||||||
|
| … | … |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
<!-- TODO: Wo bekommt der Nutzer Hilfe? Issue-Tracker, Kontakt, etc. -->
|
||||||
|
|
@ -257,3 +257,16 @@ git push
|
||||||
- [ ] Satellit-Download (download-satellite.py) noch nicht gestartet
|
- [ ] Satellit-Download (download-satellite.py) noch nicht gestartet
|
||||||
- [ ] NPM-Konfiguration (Cache-Header) manuell setzen
|
- [ ] NPM-Konfiguration (Cache-Header) manuell setzen
|
||||||
- [ ] Hook auf andere Repos verteilen (install-hooks.sh fehlt noch)
|
- [ ] Hook auf andere Repos verteilen (install-hooks.sh fehlt noch)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Prompt (Copilot-Setup Agent)
|
||||||
|
Agent hat rd13_tile_server nach `git copilot-update` analysiert und fehlende Dateien nachgezogen.
|
||||||
|
|
||||||
|
### Antwort (Copilot-Setup Agent)
|
||||||
|
Fehlende Dateien im Repo angelegt:
|
||||||
|
- `docs/USER.md`, `docs/ADMIN.md`, `docs/MAINTAINER.md` (Templates aus rd13_copilot_setup)
|
||||||
|
- `.copilot-no-tests` (kein Test-Framework, Docker/Config-Repo)
|
||||||
|
|
||||||
|
`copilot-update.sh`/`.fish` um Schritt 4c erweitert → fehlende 3-Zielgruppen-Docs
|
||||||
|
werden künftig automatisch angelegt wenn `docs/` vorhanden ist.
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue