--- 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
System A"] trigger --> validate["Daten validieren
System B"] validate --> check{Validierung OK?} check -->|ja| transform["Daten transformieren
System B"] transform --> external["Externe Verarbeitung
System C"] external --> result["Ergebnis zurückliefern
System C"] result --> process["Ergebnis verarbeiten
System B"] process --> respond["Ergebnis an Aufrufer senden
System A"] respond --> ende([Ende]) check -->|nein| logError["Fehler loggen
System B"] logError --> notify["Fehlerbenachrichtigung
System A"] 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 { <> +String id +String name } class 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 `` 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 `` markieren --- ## Offene Fragen | ID | Task | Frage | Priorität | |----|------|-------|-----------| | | | | |