ankn/Orchestrator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2973c1ebee3c30120b40d6dcce95cf69cfeb680f
Orchestrator/bahn/aisupport/steering/onboarding-dokumentation.md
T
ankn a5f8fb49ab Migrate all repos into monorepo context folders 
Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp,
      Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit,
      Projekt-KIQ-HP, teamlandkarte-mcp
Dhive: Jury-Voting
Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation)
Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more
Shared/references: symphony (read-only)

Bahn repos remain available as independent remotes - this monorepo
pulls them in via subtree, the originals are untouched.
2026-06-30 20:39:52 +02:00

410 lines
12 KiB
Markdown
Raw Blame History

---
inclusion: manual
---
# Onboarding-Dokumentation erstellen
> **Nutzung:** Referenziere diese Datei mit `#onboarding-dokumentation` im Chat und sage:
> "Erstelle eine Onboarding-Dokumentation für dieses Projekt anhand des Plans."
---
## Ziel
Automatische Erstellung einer Onboarding-/Migrationsdokumentation mit Fokus auf:
- Fachliche End-to-End-Flüsse
- Externe Schnittstellen
- Zentrale Datenobjekte
## Diagramm-Standard
**WICHTIG:** Alle Diagramme MÜSSEN als Mermaid-Diagramme erstellt werden. PlantUML ist NICHT erlaubt.
Mermaid-Diagramme werden direkt in Markdown-Dateien als Codeblöcke eingebettet ( `mermaid ).
Es werden KEINE separaten Diagramm-Dateien erzeugt.
## Ausgabestruktur
```
docs/
index.md # Überblick, Schnellstart
assumptionAndRisks.md # Annahmen, Risiken, offene Fragen
architecture/
context.md # Architekturkontext (mit eingebetteten Mermaid-Diagrammen)
domain/
data_model.md # Datenmodell (mit eingebetteten Mermaid-Diagrammen)
processes/
[prozessname].md # Je ein Dokument pro Fluss (mit eingebetteten Mermaid-Diagrammen)
interfaces/
external.md # Externe Schnittstellen
nfr.md # Nicht-funktionale Anforderungen
```
---
## Fortschritt
| Task | Status | Ergebnis |
|------|--------|----------|
| 1. Inventar & Autodetektion | Offen | - |
| 2. Architektur-Kontext | Offen | - |
| 3. Fachliche Flüsse | Offen | - |
| 4. Externe Schnittstellen | Offen | - |
| 5. Datenmodell | Offen | - |
| 6. NFRs & Monitoring | Offen | - |
| 7. Abschluss & Konsolidierung | Offen | - |
**Legende:** Offen | In Arbeit | Erledigt | Blockiert
**Ermittelte Systeminfos (Task 1 ausfüllen):**
- Systemname: _[wird ermittelt]_
- Systemtyp: _[wird ermittelt]_
- Haupttechnologien: _[wird ermittelt]_
---
## Task 1: Inventar & Autodetektion
### Aufgaben
- [ ] 1.1 Systemname ermitteln (aus pom.xml, package.json, .csproj, oder Verzeichnisname)
- [ ] 1.2 Systemtyp bestimmen (Integrationssystem / Microservices / Monolith / Batch)
- [ ] 1.3 Repository scannen nach Quellcode und Konfigurationen
- [ ] 1.4 Technologien erkennen (Sprachen, Frameworks, Integrationsplattformen)
- [ ] 1.5 Inventar-Tabelle erstellen
- [ ] 1.6 `docs/index.md` erstellen
- [ ] 1.7 `docs/assumptionAndRisks.md` erstellen
### Suchmuster für Technologien
| Typ | Dateien/Patterns |
|-----|------------------|
| Java | `.java`, `pom.xml`, `build.gradle` |
| .NET | `.cs`, `.csproj`, `.sln` |
| JavaScript/TypeScript | `.js`, `.ts`, `package.json` |
| Python | `.py`, `requirements.txt`, `pyproject.toml` |
| TIBCO | `.process`, `.xpdl`, Adapter-Configs |
| Integration | WSDL, XSD, JMS/JDBC/HTTP/FTP Configs |
### Systemtyp-Heuristik
| Indikator | Systemtyp |
|-----------|-----------|
| TIBCO .process, MuleSoft, Camel | Integrationssystem |
| Mehrere Services, Docker/K8s | Microservices |
| Ein Deployment, klare Module | Modularer Monolith |
| Ein Deployment, keine Module | Monolith |
| Scheduler, Jobs | Batch-System |
### Ausgabe: `docs/index.md`
```markdown
# Projektdokumentation: [Systemname]
## Überblick
| Attribut | Wert |
|----------|------|
| Systemname | ... |
| Systemtyp | ... |
| Hauptsprache(n) | ... |
| Frameworks | ... |
[2-3 Sätze zum Projektzweck]
## Modulübersicht
| Modul | Zweck | Technologie | Pfad |
|-------|-------|-------------|------|
## Dokumentation
- [Architektur](architecture/context.md)
- [Datenmodell](domain/data_model.md)
- [Prozesse](processes/)
- [Schnittstellen](interfaces/external.md)
- [NFRs](nfr.md)
```
Nach Abschluss: Status auf , Systeminfos eintragen, weiter mit Task 2
---
## Task 2: Architektur-Kontext
### Aufgaben
- [ ] 2.1 Externe Systeme identifizieren (HTTP, Messaging, DB, Datei, Mail)
- [ ] 2.2 Interne Komponenten gruppieren (Core, Integration, Data Access)
- [ ] 2.3 Kommunikationsarten dokumentieren (Protokoll, Richtung, sync/async)
- [ ] 2.4 `docs/architecture/context.md` erstellen (mit eingebetteten Mermaid-Diagrammen)
### Suchmuster
| Typ | Suche nach |
|-----|------------|
| HTTP/SOAP | URLs, WSDL, REST-Clients, `@WebService` |
| Messaging | JMS-Queues, Kafka-Topics, RV-Subjects |
| Datenbank | JDBC-URLs, DataSource-Configs |
| Datei/FTP | FTP-Hosts, SFTP-Configs, Dateipfade |
| Mail | SMTP/IMAP-Server |
### Mermaid-Template: Architekturkontext
```mermaid
graph TB
subgraph system["[Systemname]"]
core["Core Processing"]
integration["Integration Layer"]
data["Data Access"]
end
subgraph external["Externe Systeme"]
http["HTTP/SOAP Endpoint"]
mq["Message Broker"]
db[("Datenbank")]
end
integration -->|REST/SOAP| http
integration -->|JMS| mq
data -->|JDBC| db
```
Nach Abschluss: Status auf , weiter mit Task 3
---
## Task 3: Fachliche Flüsse
### Aufgaben
- [ ] 3.1 Zentrale End-to-End-Flüsse identifizieren (3-7 Stück)
- [ ] 3.2 Pro Fluss: Trigger, Schritte, Entscheidungen, Fehlerbehandlung analysieren
- [ ] 3.3 Pro Fluss: `docs/processes/[name].md` erstellen (mit eingebetteten Mermaid-Diagrammen)
### Priorisierung
1. Geschäftskritische Prozesse
2. Häufig ausgeführte Flüsse
3. Komplexe Integrationsflüsse
### Analyse pro Fluss
| Aspekt | Fragen |
|--------|--------|
| Trigger | Was startet den Fluss? |
| Eingaben | Welche Daten? |
| Schritte | Welche Verarbeitung? |
| Entscheidungen | Welche Verzweigungen? |
| Fehler | Wie behandelt? |
| Ausgaben | Was produziert? |
### Mermaid-Template: Prozessfluss (Flowchart)
**WICHTIG:** Prozessdiagramme MÜSSEN als Mermaid Flowcharts erstellt werden.
```mermaid
flowchart TD
start([Start]) --> trigger["Trigger empfangen<br/><i>System A</i>"]
trigger --> validate["Daten validieren<br/><i>System B</i>"]
validate --> check{Validierung OK?}
check -->|ja| transform["Daten transformieren<br/><i>System B</i>"]
transform --> external["Externe Verarbeitung<br/><i>System C</i>"]
external --> result["Ergebnis zurückliefern<br/><i>System C</i>"]
result --> process["Ergebnis verarbeiten<br/><i>System B</i>"]
process --> respond["Ergebnis an Aufrufer senden<br/><i>System A</i>"]
respond --> ende([Ende])
check -->|nein| logError["Fehler loggen<br/><i>System B</i>"]
logError --> notify["Fehlerbenachrichtigung<br/><i>System A</i>"]
notify --> fehlerEnde([Ende])
style start fill:#2d6a4f,color:#fff
style ende fill:#2d6a4f,color:#fff
style fehlerEnde fill:#d00000,color:#fff
style check fill:#ffd166,color:#000
```
### Alternativ: Mermaid Sequenzdiagramm (für Nachrichtenflüsse)
```mermaid
sequenceDiagram
participant A as System A
participant B as System B
participant C as System C
A->>B: Trigger senden
B->>B: Daten validieren
alt Validierung OK
B->>C: Externe Verarbeitung
C-->>B: Ergebnis
B-->>A: Erfolgsantwort
else Validierung fehlgeschlagen
B-->>A: Fehlerbenachrichtigung
end
```
### Mermaid Flowchart-Elemente
| Element | Syntax | Verwendung |
|---------|--------|------------|
| Start/Ende | `([Text])` | Prozessbeginn/-ende (Stadion-Form) |
| Aktion | `["Text"]` | Einzelner Schritt (Rechteck) |
| Entscheidung | `{Text}` | Verzweigung (Raute) |
| Richtung | `-->` / `-->|Label|` | Verbindung mit optionalem Label |
| Subgraph | `subgraph Name ... end` | Gruppierung/Swimlane |
| Styling | `style nodeId fill:#color` | Visuelle Hervorhebung |
Nach Abschluss: Status auf , weiter mit Task 4
---
## Task 4: Externe Schnittstellen
### Aufgaben
- [ ] 4.1 Alle Schnittstellen aus Task 2 detailliert dokumentieren
- [ ] 4.2 Pro Schnittstelle: Endpunkt, Format, Auth, Operationen erfassen
- [ ] 4.3 Fehlerbehandlung dokumentieren (Retry, DLQ, Timeout)
- [ ] 4.4 `docs/interfaces/external.md` erstellen
### Dokumentation pro Schnittstelle
| Feld | Beschreibung |
|------|--------------|
| ID | IF-001, IF-002, ... |
| Name | Sprechender Name |
| Typ | HTTP/JMS/JDBC/FTP/SMTP |
| Richtung | IN/OUT/BIDI |
| Endpunkt | URL/Queue/Tabelle/Pfad |
| Format | XML/JSON/CSV |
| Auth | Basic/OAuth/Cert |
| Fehlerbehandlung | Retry, Timeout, DLQ |
Nach Abschluss: Status auf , weiter mit Task 5
---
## Task 5: Datenmodell
### Aufgaben
- [ ] 5.1 Domänenobjekte identifizieren (Entities, Value Objects, DTOs)
- [ ] 5.2 Nach Domänenbereichen gruppieren
- [ ] 5.3 Beziehungen analysieren (Assoziation, Aggregation, Vererbung)
- [ ] 5.4 `docs/domain/data_model.md` erstellen (mit eingebetteten Mermaid-Diagrammen)
### Quellen
- Java/C# Klassen
- XML/XSD Schemata
- WSDL Types
- DB-Tabellen/Views
- JSON Schemas
### Mermaid-Template: Datenmodell (Klassendiagramm)
```mermaid
classDiagram
class Entity {
<<Entity>>
+String id
+String name
}
class ValueObject {
<<ValueObject>>
+Type field
}
Entity "1" *-- "*" ValueObject
note for Entity "Quelle: path/to/file"
```
### Mermaid-Template: Entity-Relationship-Diagramm
```mermaid
erDiagram
ENTITY ||--o{ VALUE_OBJECT : enthält
ENTITY {
string id PK
string name
}
VALUE_OBJECT {
string field
}
```
Nach Abschluss: Status auf , weiter mit Task 6
---
## Task 6: Nicht-funktionale Anforderungen & Monitoring
### Aufgaben
- [ ] 6.1 Performance-Configs suchen (Timeouts, Pools, Caching)
- [ ] 6.2 Resilienz-Configs suchen (Retry, Circuit Breaker, DLQ)
- [ ] 6.3 Sicherheits-Configs suchen (Auth, Verschlüsselung, Audit)
- [ ] 6.4 Observability-Configs suchen (Logging, Metriken, Health)
- [ ] 6.5 Monitoring & Alerting analysieren (siehe unten)
- [ ] 6.6 `docs/nfr.md` erstellen
**Wichtig:** Nur explizit konfigurierte NFRs dokumentieren!
### Monitoring & Alerting
**Hinweis:** Dieser Bereich wird nur dokumentiert, wenn im Projekt tatsächlich Monitoring- oder Alerting-Konfigurationen vorhanden sind. Nicht alle Projekte haben dies implementiert — das ist ein valides Ergebnis und sollte als Lücke in `docs/assumptionAndRisks.md` festgehalten werden.
#### Suchmuster
| Typ | Dateien/Patterns |
|-----|------------------|
| Metriken | Prometheus-Configs, Micrometer, `@Timed`, `@Counted`, Custom Metrics |
| Health Checks | `/actuator/health`, Liveness/Readiness Probes, Health-Endpoints |
| Alerting | Alert-Rules, Grafana-Dashboards, PagerDuty/OpsGenie-Configs |
| Logging | Log-Level-Configs, Structured Logging, ELK/Splunk-Configs |
| Tracing | OpenTelemetry, Jaeger, Zipkin, Correlation-IDs |
#### Dokumentation (falls vorhanden)
| Feld | Beschreibung |
|------|--------------|
| Metriken | Welche Metriken werden exponiert? |
| Dashboards | Gibt es vorkonfigurierte Dashboards? |
| Alerts | Welche Alert-Regeln sind definiert? |
| Health Checks | Welche Health-Endpoints existieren? |
| Log-Strategie | Structured Logging, Log-Level, Ziel-System |
Nach Abschluss: Status auf , weiter mit Task 7
---
## Task 7: Abschluss & Konsolidierung
### Aufgaben
- [ ] 7.1 `docs/assumptionAndRisks.md` aktualisieren mit Erkenntnissen aus allen Tasks
- [ ] 7.2 Alle `<!-- TODO: -->` aus Dokumenten sammeln
- [ ] 7.3 Querverweise zwischen Dokumenten prüfen
- [ ] 7.4 `docs/index.md` finalisieren
- [ ] 7.5 Gesamtdokumentation auf Vollständigkeit prüfen
### Checkliste für Annahmen/Risiken
| Task | Typische Themen |
|------|-----------------|
| 1 | Unklare Modulzwecke, veraltete Abhängigkeiten |
| 2 | Unbekannte externe Systeme |
| 3 | Fehlende Fehlerbehandlung, unklare Regeln |
| 4 | Fehlende Auth-Doku, unklare SLAs |
| 5 | Inkonsistente Schemata |
| 6 | Implizite Annahmen |
Nach Abschluss: Alle Status auf , Dokumentation fertig!
---
## Globale Regeln
### Diagramme
**Alle Diagramme MÜSSEN als Mermaid-Diagramme erstellt werden.** PlantUML ist NICHT erlaubt.
Diagramme werden direkt in die jeweiligen Markdown-Dokumente eingebettet keine separaten Diagramm-Dateien.
Empfohlene Mermaid-Diagrammtypen:
| Zweck | Mermaid-Typ | Syntax |
|-------|-------------|--------|
| Architekturübersicht | Flowchart | `graph TB` / `graph LR` |
| Komponentenbeziehungen | Klassendiagramm | `classDiagram` |
| Prozessflüsse | Flowchart | `flowchart TD` |
| Nachrichtenflüsse | Sequenzdiagramm | `sequenceDiagram` |
| Datenmodell | Klassendiagramm / ER | `classDiagram` / `erDiagram` |
| Zustandsübergänge | State-Diagramm | `stateDiagram-v2` |
### Quellenverweise
Jede Aussage mit Dateipfad belegen: `[Quelle: path/to/file:zeile]`
### Unklarheiten
Mit `<!-- TODO: Beschreibung -->` markieren
---
## Offene Fragen
| ID | Task | Frage | Priorität |
|----|------|-------|-----------|
| | | | |
Reference in New Issue View Git Blame Copy Permalink