Versuche und Ergebnisse Umstrukturiert
This commit is contained in:
@@ -23,7 +23,7 @@ Diese Arbeit verfolgt das Ziel, ein vollständiges Vorgehen für KI-gestütztes
|
||||
|
||||
- Entwicklung eines Prozessmodells, das Vorbereitung, Analyse, Validierung und Übergabe strukturiert.
|
||||
- Evaluation aktueller LLMs hinsichtlich Kontextfenster, Codeverständnis, Steuerbarkeit, Kosten und Datenschutz.
|
||||
- Prototypische Umsetzung eines Agenten, der Quellcode verarbeitet, Requirements formuliert und Traceability-Informationen hinterlegt.
|
||||
- Durchführung und Vergleich von drei Claude-Code-basierten Versuchen (V01-V03) mit unterschiedlicher Tooling-Tiefe (Prompt-only, Agenten, Agenten+MCP).
|
||||
- Integration von Stakeholder-Wissen durch Interviews, um nicht direkt aus dem Code ableitbare Anforderungen zu ergänzen.
|
||||
- Definition eines Evaluationsrahmens mit quantitativen und qualitativen Kriterien (Vollständigkeit, Verständlichkeit, Redundanzfreiheit, Aufwandseinsparung).
|
||||
- Formulierung konkreter Handlungsempfehlungen für die c-entron GmbH sowie Übertragbarkeit auf ähnliche Unternehmen.
|
||||
@@ -43,7 +43,7 @@ Die Arbeit ist in acht Kapitel gegliedert und folgt dem in den Vorlagen übliche
|
||||
2. **Theoretische Grundlagen:** Requirements Engineering, Reverse Engineering, Large Language Models sowie Qualitätssicherungskriterien.
|
||||
3. **Fallstudie c-entron GmbH:** Unternehmensprofil, Produktarchitektur, Migrationsdruck und Rahmenbedingungen.
|
||||
4. **Konzeption und methodisches Vorgehen:** Prozessmodell, Technologieauswahl, Stakeholder-Einbindung und Datenbasis.
|
||||
5. **Prototypische Umsetzung:** Architektur und Funktionsweise des LLM-Agenten sowie Integration in bestehende Toolchains.
|
||||
5. **Ergebnisse:** Vollständige Ergebnisdarstellung der drei Versuche inkl. Artefaktlisten und beispielhafter Requirements/Use Cases aus den Ergebnisverzeichnissen.
|
||||
6. **Evaluation:** Vorgehen, Metriken, Ergebnisse und Expertenfeedback.
|
||||
7. **Diskussion:** Interpretation der Resultate, Limitationen und Implikationen für Forschung und Praxis.
|
||||
8. **Fazit und Ausblick:** Zusammenfassung, Beantwortung der Forschungsfragen und Perspektiven für weitere Arbeiten.
|
||||
|
||||
@@ -98,4 +98,4 @@ Aus den genannten Herausforderungen ergeben sich konkrete Anforderungen an das i
|
||||
3. **Segmentierung und Kontextsteuerung:** Da Artefakte verteilt sind, ist eine systematische Auswahl relevanter Kontexte notwendig, um Überinterpretation zu reduzieren.
|
||||
4. **Human-in-the-loop:** Fachliche Validierung ist zwingend, da „plausible“ Textausgaben kein hinreichender Beweis für fachliche Korrektheit sind.
|
||||
|
||||
Damit schafft dieses Kapitel die Grundlage für die folgenden Abschnitte: Kapitel 4 beschreibt das methodische Vorgehen und das Prozessmodell, Kapitel 5 überführt es in einen Prototyp, und Kapitel 6 evaluiert die Eignung im Fallkontext der c-entron GmbH.
|
||||
Damit schafft dieses Kapitel die Grundlage für die folgenden Abschnitte: Kapitel 4 beschreibt das methodische Vorgehen und die Claude-Code-basierte Durchfuehrung, Kapitel 5 dokumentiert die Ergebnisse der Versuche, und Kapitel 6 evaluiert die Eignung im Fallkontext der c-entron GmbH.
|
||||
|
||||
@@ -2,168 +2,419 @@
|
||||
#if __is_thesis == false [
|
||||
#set cite(style: "apa")
|
||||
#hide(bibliography("../literatur.bib", style: "apa"))
|
||||
// Fallback for standalone preview of this chapter (without global thesis style).
|
||||
#show raw: set text(font: "DejaVu Sans Mono", size: 9.5pt, fill: luma(20))
|
||||
#show raw.where(block: true): it => block(
|
||||
width: 100%,
|
||||
fill: luma(240),
|
||||
stroke: 0.5pt + luma(190),
|
||||
inset: 9pt,
|
||||
radius: 4pt,
|
||||
above: 0.8em,
|
||||
below: 0.8em,
|
||||
it,
|
||||
)
|
||||
]
|
||||
|
||||
#heading(level: 1)[Konzeption und methodisches Vorgehen (ca. 12 Seiten)]
|
||||
|
||||
Dieses Kapitel beschreibt das Forschungsdesign und das Vorgehensmodell der Arbeit. Ziel ist es, den Einsatz von Large Language Models (LLMs) für Reverse Requirements Engineering so zu strukturieren, dass Ergebnisse nachvollziehbar, überprüfbar und reproduzierbar sind. Hierzu wird zunächst das Forschungsdesign als Fallstudie im Unternehmenskontext eingeordnet. Anschließend wird ein Prozessmodell für KI-gestütztes Reverse Requirements Engineering entwickelt. Abschließend werden Kriterien zur Technologieauswahl, Modellkonfiguration sowie die Einbindung von Stakeholdern und die Datengrundlage beschrieben.
|
||||
Dieses Kapitel beschreibt die tatsaechlich durchgefuehrte Methodik mit Fokus auf Claude Code als zentralem Arbeitswerkzeug. Alle Informationen sind versuchsweise gebuendelt dargestellt, sodass pro Versuch die Konfiguration, die Prompts, die eingesetzten Tools und die resultierenden Artefakte geschlossen nachvollziehbar sind.
|
||||
|
||||
#heading(level: 2)[Forschungsdesign und Vorgehensmodell]
|
||||
#heading(level: 2)[Claude Code als Werkzeug]
|
||||
|
||||
#heading(level: 3)[Einordnung als Fallstudie und Artefaktentwicklung]
|
||||
Claude Code wurde in dieser Arbeit als lokales Analysewerkzeug genutzt: ueber die CLI im Projektarbeitsverzeichnis und ueber die VS-Code-Einbindung. Die Arbeitslogik folgt einem schrittweisen Ausbau:
|
||||
|
||||
Die Arbeit ist als anwendungsnahe Untersuchung im Kontext einer konkreten Legacy-Modernisierung angelegt. Der Kernbeitrag besteht nicht nur in einer Beschreibung von LLM-Fähigkeiten, sondern in der Entwicklung eines Vorgehens, das unter realistischen Randbedingungen (große Codebasis, heterogene Artefakte, begrenzte Expertenzeit) umsetzbar ist. Das Forschungsdesign kombiniert daher:
|
||||
- Baseline nur mit Prompt + CLI (Versuch 01),
|
||||
- Spezialisierung ueber Agenten-Dateien (Versuch 02),
|
||||
- Erweiterung um MCP-Server fuer zusaetzliche Tool- und Datenzugriffe (Versuch 03).
|
||||
|
||||
1. **Literaturbasierte Fundierung:** Ableitung von Anforderungen an Requirements-Qualität, Traceability und Qualitätskriterien @iso29148_2018 @ieee830_1998.
|
||||
2. **Artefaktentwicklung:** Konzeption eines reproduzierbaren Prozessmodells für KI-gestütztes Reverse Requirements Engineering.
|
||||
3. **Prototypische Umsetzung:** Implementationsnahe Ausgestaltung des Prozesses als Agenten-/Toolchain-Workflow.
|
||||
4. **Fallbezogene Evaluation:** Überprüfung der Praktikabilität und der Ergebnisqualität durch Review und Abgleich mit Artefakten und Expertenwissen.
|
||||
Technisch wurde Claude Code entlang der offiziellen Dokumentation eingesetzt:
|
||||
|
||||
Diese Kombination ist notwendig, weil LLM-Ergebnisse im Requirements-Kontext nur dann einen belastbaren Nutzen stiften, wenn sie in einen Prozess eingebettet sind, der Belege, Unsicherheit und Validierung explizit adressiert. LLM-Ausgaben werden daher nicht als Spezifikation „an sich“ betrachtet, sondern als Zwischenartefakte, die über Belegpflicht und Review zu Requirements konsolidiert werden.
|
||||
- Session-Start und Ausfuehrung ueber CLI (`claude`, `claude -p`),
|
||||
- lokale IDE-Anbindung in VS Code,
|
||||
- Einbindung externer MCP-Server ueber das `claude mcp`-Konzept,
|
||||
- Nutzung des MCP-Scopes fuer projektspezifische Tool-Konfigurationen.
|
||||
|
||||
#heading(level: 3)[Datenerhebung, Artefaktanalyse und Auswertungslogik]
|
||||
Die technische Einordnung stuetzt sich auf die offizielle Claude-Code-Dokumentation zu Quickstart, CLI-Nutzung, IDE-Integration und MCP sowie auf das Produktupdate zu Remote MCP @claudecode_quickstart_2026 @claudecode_cli_2026 @claudecode_ide_2026 @claudecode_mcp_2026 @anthropic_remote_mcp_2025.
|
||||
|
||||
Die Datengrundlage der Arbeit ist artefaktzentriert. Der Ausgangspunkt ist die bestehende Legacy-Codebasis und die zugehörigen projektinternen Artefakte. Die Analyse folgt einer Logik aus (1) technischer Faktenerhebung und (2) semantischer Interpretation:
|
||||
Damit fungiert Claude Code in dieser Arbeit nicht nur als Chat-Interface, sondern als orchestrierender Agent-Laufzeitkontext fuer Prompting, rollenbasierte Agenten und MCP-basierte Toolaufrufe.
|
||||
|
||||
- **Faktenerhebung:** Identifikation von Komponenten, Datenobjekten, Schnittstellen und Regelstellen (z. B. Validierungen, Statuswechsel, Rechteprüfungen).
|
||||
- **Semantische Interpretation:** Ableitung fachlicher Aussagen aus den Fakten (z. B. „Ein Auftrag darf nur fakturiert werden, wenn …“).
|
||||
- **Formalisierung:** Überführung in Requirements mit Akteur, Vorbedingung, Ergebnis und Prüfidee.
|
||||
- **Absicherung:** Zuordnung von Belegen und Review durch Domänenexperten.
|
||||
#heading(level: 2)[Versuch 01]
|
||||
|
||||
Für die Auswertung ist wichtig, dass die Arbeit nicht versucht, „Vollständigkeit“ absolut zu beweisen. Stattdessen wird eine risikobasierte Perspektive gewählt: Requirements werden dort vertieft und geprüft, wo Migration, Sicherheit oder Datenintegrität besonders kritisch sind. Diese Priorisierung ist anschlussfähig an die RE-Literatur, die Qualitätsanforderungen als risikobasiert zu behandeln empfiehlt @glinz2008quality.
|
||||
#heading(level: 3)[Allgemeine Beschreibung]
|
||||
|
||||
#heading(level: 3)[Gütekriterien: Nachvollziehbarkeit, Prüfbarkeit, Reproduzierbarkeit]
|
||||
Versuch 01 bildet die Baseline ohne Agenten und ohne MCP. Ziel war eine erste formale Requirements-Extraktion direkt aus der Codebasis mit minimaler Tooling-Komplexitaet.
|
||||
|
||||
Im Requirements Engineering gelten Kriterien wie Eindeutigkeit, Konsistenz, Vollständigkeit, Verifizierbarkeit und Traceability als zentrale Qualitätsmerkmale @iso29148_2018. Für KI-gestützte Extraktion wird diese Liste operationalisiert, um überprüfbare Prozessanforderungen zu erhalten. Für die Arbeit sind besonders relevant:
|
||||
#heading(level: 3)[Konfiguration]
|
||||
|
||||
- **Traceability:** Jedes extrahierte Requirement muss auf Artefakte zurückgeführt werden können (Code, Konfiguration, Datenobjekt, UI-Text). Traceability ist in der Literatur als zentrales, dauerhaftes Problemfeld beschrieben und wird als Voraussetzung für belastbare Weiterentwicklung betrachtet @gotel1994traceability @ramesh2001traceability.
|
||||
- **Prüfbarkeit:** Requirements werden so formuliert, dass eine Testidee oder ein Abnahmekriterium ableitbar ist.
|
||||
- **Reproduzierbarkeit:** Prompting-Strategien, Kontextauswahl und Parameter werden dokumentiert, sodass Analysen unter gleichen Bedingungen wiederholbar sind.
|
||||
- Claude Code CLI lokal im Projektverzeichnis,
|
||||
- Nutzung aus VS Code (integriertes Terminal),
|
||||
- keine Agenten-Dateien,
|
||||
- keine MCP-Server.
|
||||
|
||||
LLMs erzeugen nicht-deterministische Ausgaben. Deshalb wird im Vorgehensmodell eine „Kontrollspur“ vorgesehen: Kontextquellen, Promptversionen und Resultate werden versioniert, und Unsicherheit wird explizit markiert, um spätere Überprüfung zu ermöglichen. Der Umgang mit Halluzinationen ist dabei ein zentrales Risiko, da plausible Texte fachlich falsch sein können @ji2023hallucination.
|
||||
#heading(level: 3)[Verwendeter Prompt]
|
||||
|
||||
#heading(level: 2)[Prozessmodell für KI-gestütztes Reverse Requirements Engineering]
|
||||
```text
|
||||
Please analyze this software project and write a reuqirements specification according to modern standards.
|
||||
```
|
||||
|
||||
#heading(level: 3)[Prozessüberblick und Rollen]
|
||||
#heading(level: 3)[Tools und Artefakte]
|
||||
|
||||
Das Prozessmodell strukturiert die Arbeit in Phasen, die wiederholbar durchlaufen werden können. Es unterscheidet technische und fachliche Rollen:
|
||||
- Tooling: Claude Code CLI + VS Code Integration.
|
||||
- Ergebnisfokus: formale Requirements-Spezifikation (StRS/SyRS/SwRS) mit hoher Strukturierungsdichte.
|
||||
|
||||
- **Analyseverantwortlicher:** Steuert Scope, Artefaktauswahl und Toolchain.
|
||||
- **Domänenexperte:** Validiert fachliche Bedeutung, Ausnahmen und Prioritäten.
|
||||
- **Entwicklung/Architektur:** Nutzt konsolidierte Requirements als Basis für Zielarchitektur und Umsetzung.
|
||||
#heading(level: 3)[Beispielhafte Ergebnisanforderungen]
|
||||
|
||||
Der Prozess besteht aus sieben Phasen, die iterativ angewendet werden:
|
||||
Quelle: `Versuche/Versuch 01/Ergebnisse/ISO29148_Complete_Requirements_Specification.md`
|
||||
|
||||
1. **Scope und Domänenabgrenzung**
|
||||
2. **Artefakterhebung und Kontextaufbereitung**
|
||||
3. **Technische Analyse (Struktur, Daten, Schnittstellen)**
|
||||
4. **Retrieval und Kontextsteuerung (RAG)**
|
||||
5. **Requirements-Extraktion und Strukturierung**
|
||||
6. **Traceability-Anreicherung und Unsicherheitsmarkierung**
|
||||
7. **Review, Konsolidierung und Übergabe**
|
||||
```text
|
||||
### StR-001: Comprehensive Customer Account Management
|
||||
**Statement**: The system shall provide comprehensive customer account management capabilities including contact information, relationship mapping, interaction history, and account hierarchy management.
|
||||
```
|
||||
|
||||
#heading(level: 3)[Artefaktpipeline: Sammeln, Normalisieren, Indexieren]
|
||||
```text
|
||||
### SyR-001
|
||||
The system SHALL implement a multi-layered architecture with clear separation of concerns.
|
||||
```
|
||||
|
||||
Die zentrale technische Voraussetzung ist eine Artefaktpipeline, die die Codebasis und flankierende Quellen in eine Form überführt, die sowohl maschinell suchbar als auch für LLMs nutzbar ist. Die Pipeline umfasst:
|
||||
#heading(level: 3)[Einordnung]
|
||||
|
||||
- **Sammeln:** Repository, Konfigurationen, UI-Texte, Datenbankschemata, Tickets, Release Notes.
|
||||
- **Normalisieren:** Extraktion von Metadaten (Pfad, Modul, Änderungsdatum), Entfernen von Rauschen (Build-Artefakte), Vereinheitlichung von Encodings.
|
||||
- **Segmentieren:** Zerlegung großer Dateien in semantische Chunks (z. B. pro Klasse, Methode, SQL-Statement).
|
||||
- **Indexieren:** Aufbau eines Suchindex (klassisch oder embeddings-basiert) zur späteren Kontextauswahl.
|
||||
Die Baseline zeigt, dass bereits ohne Agenten/MCP belastbare, formal strukturierte Anforderungen erzeugbar sind. Gleichzeitig bleibt die Discovery-Breite begrenzt.
|
||||
|
||||
Die Segmentierung ist entscheidend, weil LLMs nur ein begrenztes Kontextfenster besitzen. Eine „Alles-in-einen-Prompt“-Strategie skaliert nicht. Retrieval-Augmented Generation (RAG) adressiert dieses Problem, indem relevante Textstellen gezielt in den Prompt geladen werden @lewis2020rag.
|
||||
#heading(level: 2)[Versuch 02]
|
||||
|
||||
#heading(level: 3)[Prompt- und Output-Templates für Requirements]
|
||||
#heading(level: 3)[Allgemeine Beschreibung]
|
||||
|
||||
Um Ergebnisse konsistent auszuwerten, werden Requirements in einem festen Template erzeugt. Ein zweckmäßiges Format umfasst:
|
||||
Versuch 02 fokussiert die ISO-29148-orientierte Konsolidierung. Dazu wurde Claude Code weiterhin lokal genutzt, jedoch um spezialisierte Agenten-Dateien erweitert.
|
||||
|
||||
- **ID**
|
||||
- **Titel**
|
||||
- **Akteur/Rolle**
|
||||
- **Vorbedingungen**
|
||||
- **Beschreibung des Verhaltens**
|
||||
- **Akzeptanzkriterien**
|
||||
- **Belege (Artefaktverweise)**
|
||||
- **Unsicherheitsmarker / offene Fragen**
|
||||
#heading(level: 3)[Konfiguration]
|
||||
|
||||
Dieses Template reduziert Interpretationsspielraum und macht Reviews effizienter. Es adressiert zudem ein zentrales Risiko: LLMs können sprachlich „glatte“ Requirements erzeugen, die jedoch ohne Belege und Akzeptanzkriterien nicht belastbar sind. Der Prozess erzwingt daher eine Belegpflicht und die Ableitung von Prüfkriterien als Standardausgabe.
|
||||
- Claude Code CLI lokal + VS Code,
|
||||
- agentenbasierte Spezialisierung ueber MD-Dateien in `Versuche/Versuch 02/Tools/agents/`,
|
||||
- kein MCP-Fokus in diesem Lauf.
|
||||
|
||||
#heading(level: 3)[Kontrollpunkte und Fehlerbegrenzung]
|
||||
#heading(level: 3)[Verwendeter Prompt]
|
||||
|
||||
Die Prozesskontrollen sind so gewählt, dass typische LLM-Fehlermuster begrenzt werden:
|
||||
```text
|
||||
Please analyze this software project and write a ISO 29148 compliant reuqirements specification.
|
||||
Use Agents wherever possible.
|
||||
```
|
||||
|
||||
- **Belegpflicht:** Keine Requirements ohne Artefaktbezug.
|
||||
- **Konfliktprüfung:** Abgleich widersprüchlicher Aussagen über mehrere Belegstellen.
|
||||
- **Unsicherheitskennzeichnung:** Hypothesen werden explizit markiert und priorisiert geprüft.
|
||||
- **Human-in-the-loop:** Fachliche Validierung als fester Schritt, nicht als optionales „Nachlesen“.
|
||||
#heading(level: 3)[Tools und Agenten]
|
||||
|
||||
Diese Kontrollen sind notwendig, weil Halluzinationen und Bias-Risiken in der LLM-Literatur als strukturelle Probleme beschrieben werden @bender2021stochastic @ji2023hallucination. Für Requirements bedeutet dies, dass Prozessqualität und Governance nicht nachgelagert, sondern integraler Bestandteil sein müssen.
|
||||
Beispiele aus dem Versuchsordner:
|
||||
|
||||
#heading(level: 2)[Technologieauswahl und LLM-Konfiguration]
|
||||
- `iso29148-master-orchestrator-agent.md`
|
||||
- `iso29148-stakeholder-agent.md`
|
||||
- `iso29148-system-requirements-agent.md`
|
||||
- `iso29148-software-requirements-agent`
|
||||
|
||||
#heading(level: 3)[Auswahlkriterien für Modelle und Betriebsform]
|
||||
#heading(level: 3)[Agentenbeispiel (Auszug, erste 100 Zeilen) - Versuch 02]
|
||||
|
||||
Die Auswahl eines LLMs im Unternehmenskontext folgt nicht nur der Modellqualität, sondern auch Randbedingungen. Für diese Arbeit werden die folgenden Kriterien als handlungsleitend betrachtet:
|
||||
Quelle: `Versuche/Versuch 02/Tools/agents/iso29148-master-orchestrator-agent.md`
|
||||
|
||||
- **Kontextfenster und Eingabekosten:** Große Artefakte erfordern Segmentierung; zu kleine Kontextfenster erhöhen den Retrieval-Aufwand.
|
||||
- **Codefähigkeit:** Verständnis von Identifiern, Kontrollfluss, Datenzugriffsmustern und typischen Framework-Idiomen.
|
||||
- **Steuerbarkeit:** Möglichkeiten zur Formatsteuerung (z. B. JSON-Outputs), deterministische Parameter, Prompt-Constraints.
|
||||
- **Betriebs- und Datenschutzanforderungen:** Umgang mit Quellcode als potenziell vertraulichem Material.
|
||||
- **Reproduzierbarkeit:** Versionierung von Modell, Prompt, Retrieval-Konfiguration.
|
||||
````md
|
||||
# Enhanced ISO 29148 Master Orchestrator Agent with Milestone System
|
||||
|
||||
Survey- und SLR-Arbeiten zu LLMs im Software Engineering betonen, dass Nutzen stark davon abhängt, wie Modelle in Toolchains integriert und abgesichert werden @fan2023llmse @llm4se2024slr @llm4se2024survey. Diese Perspektive prägt die Technologieauswahl in Kapitel 5.
|
||||
You are the Lead Requirements Analyst coordinating the complete ISO/IEC/IEEE 29148 requirements extraction with comprehensive documentation, quality assurance, and milestone-based execution control.
|
||||
|
||||
#heading(level: 3)[Konfiguration: Parameter und Prompting]
|
||||
## Your Mission
|
||||
Orchestrate a complete requirements analysis using all three ISO 29148 levels, ensuring consistency, completeness, and traceability. Create executive-level documentation and ensure all agents produce their complete documentation packages. **NEW**: Provide milestone-based pause/resume capabilities for long-running analyses.
|
||||
|
||||
Da LLM-Ausgaben sensitiv auf Prompting und Sampling reagieren, wird eine konservative Konfiguration gewählt:
|
||||
## CRITICAL: Documentation Requirements
|
||||
**You MUST ensure:**
|
||||
1. Each agent creates their complete documentation package
|
||||
2. You create the integrated master document
|
||||
3. All work is saved to `/docs/requirements/`
|
||||
4. Complete traceability is maintained
|
||||
5. Executive dashboards and reports are generated
|
||||
6. **NEW**: Milestone state is persisted for pause/resume functionality
|
||||
7. VERIFY each agent has created their files before proceeding
|
||||
|
||||
- **Niedrige Temperatur** zur Reduktion von Varianz.
|
||||
- **Explizite Ausgabeformate** (Templatepflicht, strukturierte Felder).
|
||||
- **Beleganforderungen** (z. B. „nennen Sie Datei + Funktion/SQL“).
|
||||
- **Stop-Kriterien** (bei fehlenden Belegen: offene Frage statt Behauptung).
|
||||
## NEW: Milestone System Architecture
|
||||
|
||||
Chain-of-Thought-Strategien können die Qualität komplexer Ableitungen steigern, erhöhen im Requirements-Kontext jedoch das Risiko, dass Begründungen als Evidenz missverstanden werden. In dieser Arbeit werden Begründungen daher nur als Hilfsmittel akzeptiert, nicht als Beleg @wei2022cot.
|
||||
### Milestone Configuration
|
||||
```json
|
||||
{
|
||||
"project_name": "[Project Name]",
|
||||
"execution_id": "[UUID]",
|
||||
"created_at": "[ISO DateTime]",
|
||||
"milestones": {
|
||||
"M0_SETUP": {
|
||||
"name": "Project Analysis and Setup",
|
||||
"status": "pending|in_progress|completed|failed",
|
||||
"started_at": null,
|
||||
"completed_at": null,
|
||||
"dependencies": [],
|
||||
"outputs": ["project_structure.json", "directory_setup.txt"]
|
||||
},
|
||||
"M1_STAKEHOLDER": {
|
||||
"name": "Stakeholder Requirements Analysis",
|
||||
"status": "pending",
|
||||
"started_at": null,
|
||||
"completed_at": null,
|
||||
"dependencies": ["M0_SETUP"],
|
||||
"outputs": [
|
||||
"StRS_Complete.md",
|
||||
"StRS_Summary.md",
|
||||
"StRS_Traceability.csv",
|
||||
"StRS_Diagrams.md",
|
||||
"StRS_Evidence.md"
|
||||
]
|
||||
},
|
||||
"M2_SYSTEM": {
|
||||
"name": "System Requirements Analysis",
|
||||
"status": "pending",
|
||||
"started_at": null,
|
||||
"completed_at": null,
|
||||
"dependencies": ["M1_STAKEHOLDER"],
|
||||
"outputs": [
|
||||
"SyRS_Complete.md",
|
||||
"SyRS_Summary.md",
|
||||
"SyRS_API_Specification.yaml",
|
||||
"SyRS_Architecture.md",
|
||||
"SyRS_Interfaces.md",
|
||||
"SyRS_Traceability.csv"
|
||||
]
|
||||
},
|
||||
"M3_SOFTWARE": {
|
||||
"name": "Software Requirements Analysis",
|
||||
"status": "pending",
|
||||
"started_at": null,
|
||||
"completed_at": null,
|
||||
"dependencies": ["M2_SYSTEM"],
|
||||
"outputs": [
|
||||
"SwRS_Complete.md",
|
||||
"SwRS_CodeCatalog.md",
|
||||
"SwRS_Algorithms.md",
|
||||
"SwRS_DataModel.md",
|
||||
"SwRS_TestSpecification.md",
|
||||
"SwRS_Traceability.csv"
|
||||
]
|
||||
},
|
||||
"M4_PATTERNS": {
|
||||
"name": "Code Pattern Analysis",
|
||||
"status": "pending",
|
||||
"started_at": null,
|
||||
"completed_at": null,
|
||||
"dependencies": ["M3_SOFTWARE"],
|
||||
"outputs": [
|
||||
"Analysis_Complete.md",
|
||||
"Pattern_Catalog.csv",
|
||||
"Business_Rules.md",
|
||||
"Validation_Rules.md",
|
||||
"Security_Patterns.md",
|
||||
"Performance_Patterns.md",
|
||||
"Integration_Patterns.md"
|
||||
]
|
||||
},
|
||||
"M5_INTEGRATION": {
|
||||
"name": "Integration and Master Documentation",
|
||||
"status": "pending",
|
||||
"started_at": null,
|
||||
"completed_at": null,
|
||||
"dependencies": ["M1_STAKEHOLDER", "M2_SYSTEM", "M3_SOFTWARE", "M4_PATTERNS"],
|
||||
````
|
||||
Hinweis: Der Auszug endet nach Zeile 100; die Originaldatei umfasst 620 Zeilen und ist an dieser Stelle nicht zu Ende.
|
||||
|
||||
#heading(level: 3)[Retrieval-Strategie und Kontextfenstersteuerung]
|
||||
#heading(level: 3)[Beispielhafte Ergebnisanforderungen]
|
||||
|
||||
RAG wird in dieser Arbeit als zentrales Skalierungsprinzip betrachtet @lewis2020rag. Die Kontextfenstersteuerung folgt einer einfachen Heuristik:
|
||||
Quellen:
|
||||
|
||||
1. Suche nach relevanten Stellen (Keywords, Identifier, Datenobjekte).
|
||||
2. Ergänzung um Nachbarschaftskontext (z. B. Aufrufer, SQL-Definition, UI-String).
|
||||
3. Begrenzung der Kontextmenge durch Ranking und Redundanzfilter.
|
||||
- `Versuche/Versuch 02/Ergenisse/system/SyRS_Complete.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/SwRS_Complete.md`
|
||||
|
||||
Wichtig ist, dass Retrieval nicht „Wahrheit“ garantiert. Es liefert lediglich die evidenznahe Basis, an die Generierung gekoppelt wird. Daraus folgt, dass Retrieval-Konfigurationen (Chunkgröße, Overlap, Ranking) dokumentiert werden müssen, um Ergebnisse reproduzierbar zu halten.
|
||||
```text
|
||||
**SyR-001**: The system SHALL implement a multi-layered architecture with clear separation of concerns.
|
||||
**SyR-002**: The system SHALL implement the ILogic interface pattern with dual implementations.
|
||||
```
|
||||
|
||||
#heading(level: 2)[Stakeholder-Einbindung und Datengrundlage]
|
||||
```text
|
||||
**SW-FUNC-001**: The software SHALL provide comprehensive account management functionality.
|
||||
**SW-API-001**: The software SHALL provide comprehensive REST API.
|
||||
```
|
||||
|
||||
#heading(level: 3)[Stakeholderrollen und Verantwortlichkeiten]
|
||||
#heading(level: 3)[Einordnung]
|
||||
|
||||
LLM-gestützte Requirements-Rückgewinnung ist ohne Domänenvalidierung nicht belastbar. Für die Fallstudie werden daher Stakeholderrollen unterschieden:
|
||||
Versuch 02 lieferte die staerkste formale Konsolidierung (StRS/SyRS/SwRS, hohe Traceability), erwies sich fuer die Gesamtentdeckung jedoch als vergleichsweise rigide.
|
||||
|
||||
- **Fachexperten (Domäne/Support):** kennen Ausnahmen, Kundenvarianten und Abläufe.
|
||||
- **Entwickler/Architekten:** ordnen Codeartefakte ein und bewerten technische Machbarkeit.
|
||||
- **Produktverantwortliche:** priorisieren Requirements in Bezug auf Migrationsziel und Wertbeitrag.
|
||||
#heading(level: 2)[Versuch 03]
|
||||
|
||||
Die Beteiligung dient nicht nur der Korrektur von Detailfragen, sondern der Abgrenzung von Soll- und Ist-Zustand. Gerade Legacy-Systeme enthalten historisch gewachsene Workarounds, die fachlich nicht zwingend gewünscht sind @bisbal1999legacy.
|
||||
#heading(level: 3)[Allgemeine Beschreibung]
|
||||
|
||||
#heading(level: 3)[Interviewleitfaden und Workshopformat]
|
||||
Versuch 03 erweitert das Vorgehen aus Versuch 02 um MCP-Server, um neben formaler Strukturierung vor allem die Discovery-Breite zu vergroessern (Use-Case-Fund, Gap-Analyse).
|
||||
|
||||
Die Stakeholder-Einbindung wird als Kombination aus Interviews und Validierungsworkshops strukturiert. Ein schlanker Leitfaden fokussiert auf:
|
||||
#heading(level: 3)[Konfiguration]
|
||||
|
||||
- kritische Geschäftsobjekte und Statusmodelle,
|
||||
- typische Fehlerfälle und Ausnahmen,
|
||||
- Sicherheits- und Complianceanforderungen,
|
||||
- Integrationen und Schnittstellen,
|
||||
- Kriterien für „Done“ in der Migration (Abnahmelogik).
|
||||
- Claude Code CLI lokal + VS Code,
|
||||
- Agenten-Dateien in `Versuche/Versuch 03/Tools/Agents/`,
|
||||
- MCP-Server gemaess Protokoll: Serena MCP, Windows-MCP (AutoIt-basiert), MSSQL MCP.
|
||||
|
||||
Workshops dienen der Konsolidierung: Requirements werden mit Belegen präsentiert, offene Punkte markiert und Entscheidungen (z. B. „Ist-Übernahme“ vs. „Soll-Anpassung“) festgehalten. Dieses Vorgehen ist konsistent mit RE-Standards, die Validierung und Stakeholderabstimmung als zentrale Schritte behandeln @iso29148_2018.
|
||||
#heading(level: 3)[Verwendeter Prompt]
|
||||
|
||||
#heading(level: 3)[Datengrundlage und Umgang mit sensiblen Informationen]
|
||||
```text
|
||||
Please analyze this software project and write a reuqirements specification according to modern standards.
|
||||
Use Agents and MCP servers wherever possible.
|
||||
Keep superflous texts to a minimum and concentrate on actual requirements.
|
||||
```
|
||||
|
||||
Die Datengrundlage umfasst Quellcode und begleitende Projektartefakte. Aus Governance-Sicht ist Quellcode als sensibel zu betrachten. Daraus folgt:
|
||||
#heading(level: 3)[Tools und Agenten]
|
||||
|
||||
Beispiele aus dem Versuchsordner:
|
||||
|
||||
- `centron-documentation-writer.md`
|
||||
- `nhibernate-query-reviewer.md`
|
||||
- `centron-code-reviewer.md`
|
||||
- `webservice-developer.md`
|
||||
|
||||
#heading(level: 3)[Agentenbeispiel (Auszug, erste 100 Zeilen) - Versuch 03]
|
||||
|
||||
Quelle: `Versuche/Versuch 03/Tools/Agents/nhibernate-query-reviewer.md`
|
||||
|
||||
````md
|
||||
---
|
||||
name: nhibernate-query-reviewer
|
||||
description: Reviews NHibernate queries and LINQ expressions for c-entron.NET. Detects N+1 queries, cartesian products, and compatibility issues. Use when writing complex queries or experiencing performance problems. Keywords: NHibernate, LINQ, query, performance, N+1, optimization, Fetch.
|
||||
---
|
||||
|
||||
# NHibernate Query Reviewer Agent
|
||||
|
||||
> **Type**: Review / Analysis
|
||||
> **Purpose**: Review database queries to ensure efficiency, proper structure, and compatibility with NHibernate's LINQ provider limitations.
|
||||
|
||||
## Agent Role
|
||||
|
||||
You are a specialized **NHibernate Query Reviewer** for the c-entron.NET solution, focused on query optimization and performance.
|
||||
|
||||
### Primary Responsibilities
|
||||
|
||||
1. **N+1 Detection**: Identify and fix lazy loading issues that cause multiple database roundtrips
|
||||
2. **Performance Analysis**: Review queries for cartesian products, missing indexes, and inefficient patterns
|
||||
3. **NHibernate Compatibility**: Ensure LINQ expressions translate correctly to SQL
|
||||
4. **Best Practices**: Enforce soft delete filtering, eager loading strategies, and proper transaction usage
|
||||
|
||||
### Core Capabilities
|
||||
|
||||
- **N+1 Query Detection**: Identify lazy loading in loops causing performance degradation
|
||||
- **Cartesian Product Prevention**: Detect multiple Fetch operations on collections
|
||||
- **LINQ Compatibility**: Validate expressions work with NHibernate's LINQ provider
|
||||
- **Optimization Recommendations**: Suggest Fetch, FetchMany, Future queries for better performance
|
||||
- **Soft Delete Validation**: Ensure all queries filter IsDeleted records
|
||||
|
||||
## When to Invoke This Agent
|
||||
|
||||
This agent should be activated when:
|
||||
- Complex LINQ queries are written
|
||||
- Performance issues suspected with database access
|
||||
- Need query optimization recommendations
|
||||
- Validating NHibernate compatibility of LINQ expressions
|
||||
- Reviewing data access code for N+1 problems
|
||||
- Before committing database access code
|
||||
|
||||
**Trigger examples:**
|
||||
- "Review this query for N+1 problems"
|
||||
- "Optimize the GetAccountContracts query"
|
||||
- "Check if this LINQ expression will work with NHibernate"
|
||||
- "Why is my query slow?"
|
||||
|
||||
## Technology Adaptation
|
||||
|
||||
**IMPORTANT**: This agent adapts to c-entron.NET's NHibernate configuration.
|
||||
|
||||
**Configuration Source**: [CLAUDE.md](../../CLAUDE.md)
|
||||
|
||||
Before beginning work, review CLAUDE.md for:
|
||||
- **ORM**: NHibernate 5.x with FluentNHibernate
|
||||
- **Database**: SQL Server 2019+
|
||||
- **Pattern**: Always filter !x.IsDeleted
|
||||
- **Eager Loading**: Fetch/FetchMany for navigation properties
|
||||
- **Future Queries**: Batch loading for multiple collections
|
||||
- **Transactions**: Required for all modifications
|
||||
|
||||
## Instructions & Workflow
|
||||
|
||||
### Standard Procedure
|
||||
|
||||
1. **Load Relevant Lessons Learned** ⚠️ **IMPORTANT**
|
||||
|
||||
As a review and analysis agent, start by loading past lessons:
|
||||
|
||||
- Use Serena MCP `list_memories` to see available memories
|
||||
- Use `read_memory` to load relevant past findings:
|
||||
- `"lesson-query-*"` - Query optimization lessons
|
||||
- `"pattern-nhibernate-*"` - NHibernate patterns
|
||||
- `"lesson-performance-*"` - Performance findings
|
||||
- Apply insights from past lessons throughout review
|
||||
- This prevents repeating past N+1 mistakes
|
||||
|
||||
2. **Context Gathering**
|
||||
- Review [CLAUDE.md](../../CLAUDE.md) for NHibernate patterns
|
||||
- Use Serena MCP `find_symbol` to locate query implementations
|
||||
- Use Serena MCP `find_referencing_symbols` to understand query usage
|
||||
- Identify query complexity and data access patterns
|
||||
|
||||
3. **Query Analysis**
|
||||
- Check for N+1 query patterns (lazy loading in loops)
|
||||
- Verify soft delete filtering (!x.IsDeleted)
|
||||
- Validate LINQ expression compatibility
|
||||
- Look for cartesian products (multiple Fetch on collections)
|
||||
- Check transaction usage for modifications
|
||||
- **Apply insights from loaded lessons**
|
||||
|
||||
4. **Optimization**
|
||||
- Suggest Fetch/FetchMany for eager loading
|
||||
- Recommend Future queries for multiple collections
|
||||
- Propose projection for limited data needs
|
||||
- Identify missing indexes
|
||||
- **Check recommendations against past patterns**
|
||||
|
||||
5. **Verification**
|
||||
- Estimate performance impact
|
||||
- Verify proposed optimizations don't introduce new issues
|
||||
- Use `/optimize` command for additional suggestions
|
||||
````
|
||||
Hinweis: Der Auszug endet nach Zeile 100; die Originaldatei umfasst 284 Zeilen und ist an dieser Stelle nicht zu Ende.
|
||||
|
||||
#heading(level: 3)[Beispielhafte Ergebnis-Use-Cases]
|
||||
|
||||
Quelle: `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES.md`
|
||||
|
||||
```text
|
||||
### 2. Click Counter Management (Usage-Based Billing)
|
||||
**Purpose**: Retrieve current meter readings for click counter devices
|
||||
**Use Cases**: Copy machines, printers, industrial equipment with usage meters
|
||||
Method: LoadCounterAsync(List<int> contractsI3D)
|
||||
```
|
||||
|
||||
```text
|
||||
**Use Case**: Track counter reading trends, detect anomalies
|
||||
Method: IAutomatedBillingLogic.GetCounterHistory(List<string> lstParam)
|
||||
```
|
||||
|
||||
#heading(level: 3)[MCP-Server: Detaillierte Beschreibung]
|
||||
|
||||
#heading(level: 4)[MCP-Grundprinzip]
|
||||
|
||||
Model Context Protocol (MCP) definiert eine standardisierte Kopplung zwischen einem Host (hier: Claude Code), einem MCP-Client und einem oder mehreren MCP-Servern. Server stellen dabei typischerweise drei Artefaktarten bereit: `tools` (aufrufbare Funktionen), `resources` (lesbare Kontexte) und `prompts` (wiederverwendbare Prompt-Bausteine). Dieses Modell wurde in Versuch 03 genutzt, um ueber den reinen Repository-Kontext hinaus weitere Wissens- und Interaktionskanaele einzubinden @mcp_intro_2026.
|
||||
|
||||
#heading(level: 4)[Serena MCP]
|
||||
|
||||
Serena ist ein MCP-Server fuer semantische Code-Retrieval- und Editieroperationen auf Symbol-Ebene (z. B. `find_symbol`, `find_referencing_symbols`, `insert_after_symbol`). Im Unterschied zu rein textbasierter Suche werden Codeobjekte (Klassen, Methoden, Referenzen) strukturell adressiert. In Versuch 03 wurde Serena vor allem fuer gezielte Modulnavigation und die persistenten Memory-Notizen zwischen Analyseiterationen eingesetzt @serena_mcp_2026 @mcp_servers_repo_2026.
|
||||
|
||||
#heading(level: 4)[Windows-MCP (AutoIt-basiert)]
|
||||
|
||||
Der im Protokoll genannte Windows-MCP-Ansatz (AutoIt-basiert) realisiert Desktop-Automatisierung ueber MCP. Laut Projektbeschreibung kapselt der Server AutoIt-Funktionen als MCP-Tools und bietet zusaetzlich Ressourcen (Dateizugriff, Screenshots) sowie Prompt-Templates fuer typische Automationsaufgaben. Fuer die Fallstudie ist das relevant, weil GUI-basierte Pfade (Dialoge, Formulare, visuelle Workflows) nicht nur aus Quellcode, sondern auch aus Interaktionsablaeufen rekonstruiert werden koennen @windows_mcp_autoit_2026.
|
||||
|
||||
#heading(level: 4)[MSSQL MCP]
|
||||
|
||||
MSSQL MCP ermoeglicht den kontrollierten Zugriff auf Microsoft SQL Server ueber MCP. Typische Funktionen sind Tabellenauflistung, Schema-Inspektion, Lesen von Inhalten und kontrollierte SQL-Ausfuehrung. Die dokumentierten Security-Hinweise betonen Least-Privilege-Berechtigungen, restriktive Verbindungskonfigurationen und Logging. In Versuch 03 wurde dieser Zugriff fuer die funktionale Absicherung von Datenmodellen und Use-Case-Hypothesen genutzt @mssql_mcp_2026.
|
||||
|
||||
#heading(level: 3)[Einordnung]
|
||||
|
||||
Durch die MCP-Erweiterung konnte Versuch 03 die funktionale Breite deutlich steigern und einen grossen Dokumentations-Gap sichtbar machen. Gegenueber Versuch 02 sinkt dabei der formale ISO-Fokus, was fuer Discovery jedoch methodisch beabsichtigt war.
|
||||
|
||||
#heading(level: 2)[Quellenhinweis]
|
||||
|
||||
Die fuer dieses Kapitel genutzten Webquellen zu Claude Code und MCP-Servern sind im Literaturverzeichnis als Online-Quellen erfasst; die inhaltliche Referenzierung erfolgt direkt im Text der Abschnitte zu Versuch 03.
|
||||
|
||||
- Trennung zwischen Artefakten, die für Retrieval/Prompts verwendet werden dürfen, und solchen, die ausgeschlossen werden (z. B. Zugangsdaten).
|
||||
- Protokollierung, welche Artefakte in einen Prompt eingeflossen sind.
|
||||
- Minimierung von Kontext (Need-to-know), um Datenabflussrisiken zu reduzieren.
|
||||
|
||||
Diese Maßnahmen werden in Kapitel 5 konkretisiert, da dort die Toolchain-Integration und der Umgang mit Logging, Prompt-Historien und IP-Aspekten umgesetzt werden.
|
||||
|
||||
@@ -4,126 +4,174 @@
|
||||
#hide(bibliography("../literatur.bib", style: "apa"))
|
||||
]
|
||||
|
||||
#heading(level: 1)[Prototypische Umsetzung (ca. 10 Seiten)]
|
||||
#heading(level: 1)[Ergebnisse (ca. 10 Seiten)]
|
||||
|
||||
Dieses Kapitel beschreibt die prototypische Umsetzung des in Kapitel 4 definierten Vorgehens. Ziel ist ein Workflow, der (1) Code- und Projektartefakte analysiert, (2) daraus strukturierte Requirements ableitet, (3) Belege und Unsicherheiten explizit erfasst und (4) die Ergebnisse so bereitstellt, dass sie in eine Migration überführt werden können. Die Umsetzung wird nicht als „vollautomatische Requirements-Generierung“ verstanden, sondern als Assistenzsystem mit klaren Kontrollpunkten.
|
||||
Dieses Kapitel dokumentiert die tatsaechlich erzeugten Ergebnisse der drei Versuche (V01-V03). Neben den Kennzahlen werden die Ergebnisartefakte aus den jeweiligen Ergebnisverzeichnissen strukturiert aufgelistet und durch exemplarische Requirements bzw. Use Cases belegt.
|
||||
|
||||
#heading(level: 2)[Architektur des LLM-Agenten]
|
||||
#heading(level: 2)[Ergebnisueberblick]
|
||||
|
||||
#heading(level: 3)[Architekturüberblick]
|
||||
#table(
|
||||
columns: (1fr, 1fr, 1fr, 1fr),
|
||||
stroke: 0.4pt,
|
||||
[**Kennzahl**], [**V01**], [**V02**], [**V03**],
|
||||
[Konsolidierte Anforderungen/Faehigkeiten], [277], [220], [1720],
|
||||
[Formale Anforderungen (StRS+SyRS+SwRS)], [277], [220], [0],
|
||||
[Explizite Use Cases], [0], [46], [1720],
|
||||
[Undokumentierte Use Cases], [n.v.], [n.v.], [1211],
|
||||
[ISO-29148-Compliance], [qualitativ A+], [96,1%], [n.v.],
|
||||
[Traceability], [100% laut Doku], [100% bidirektional], [n.v.],
|
||||
[Ergebnisdateien gesamt], [11], [37], [30]
|
||||
)
|
||||
|
||||
Der Prototyp folgt einer Pipeline-Architektur, die Analyse, Retrieval und Generierung entkoppelt. Damit wird die Komplexität kontrollierbar und einzelne Komponenten können iterativ verbessert werden. Der Agent ist in vier Schichten gegliedert:
|
||||
#heading(level: 2)[V01 Ergebnisse (Baseline)]
|
||||
|
||||
1. **Ingestion-Schicht:** Sammeln und Vorverarbeiten von Artefakten.
|
||||
2. **Retrieval-Schicht:** Auswahl relevanter Kontexte (RAG) zur Skalierung über große Repositories.
|
||||
3. **Reasoning-/Generation-Schicht:** LLM-gestützte Ableitung und Strukturierung der Requirements.
|
||||
4. **Traceability- und Output-Schicht:** Persistenz, Belege, Review-Export.
|
||||
#heading(level: 3)[Ergebnisdateien in `Versuche/Versuch 01/Ergebnisse`]
|
||||
|
||||
Retrieval-Augmented Generation ist in dieser Architektur das zentrale Prinzip, um mit begrenzten Kontextfenstern umzugehen und Aussagen an konkrete Belege zu binden @lewis2020rag.
|
||||
- `Versuche/Versuch 01/Ergebnisse/Centron_Software_Requirements_Specification.md`
|
||||
- `Versuche/Versuch 01/Ergebnisse/Centron_Software_Requirements_Specification.pdf`
|
||||
- `Versuche/Versuch 01/Ergebnisse/complete-iso29148-requirements-specification.md`
|
||||
- `Versuche/Versuch 01/Ergebnisse/ISO29148_Complete_Requirements_Specification.md`
|
||||
- `Versuche/Versuch 01/Ergebnisse/iso29148-integrated-requirements-analysis.md`
|
||||
- `Versuche/Versuch 01/Ergebnisse/iso29148-integrated-requirements-analysis.pdf`
|
||||
- `Versuche/Versuch 01/Ergebnisse/nhibernate-orm-analysis.md`
|
||||
- `Versuche/Versuch 01/Ergebnisse/software/SwRS_Complete_Detailed.md`
|
||||
- `Versuche/Versuch 01/Ergebnisse/software/SwRS_Complete_Detailed.pdf`
|
||||
- `Versuche/Versuch 01/Ergebnisse/system/SyRS_Complete_Detailed.md`
|
||||
- `Versuche/Versuch 01/Ergebnisse/system/SyRS_Complete_Detailed.pdf`
|
||||
|
||||
#heading(level: 3)[Ingestion: Artefaktaufbereitung und Chunking]
|
||||
#heading(level: 3)[Beispielhafte Requirements aus den Ergebnisdateien]
|
||||
|
||||
Die Ingestion-Schicht übernimmt:
|
||||
```text
|
||||
StR-001: Comprehensive Customer Account Management
|
||||
Statement: The system shall provide comprehensive customer account management capabilities...
|
||||
(Quelle: ISO29148_Complete_Requirements_Specification.md)
|
||||
```
|
||||
|
||||
- Erfassung von Quellcode, Konfigurationen, UI-Strings, SQL-Artefakten und Projektdokumenten,
|
||||
- Normalisierung von Encodings und Metadaten (Pfad, Modul, Änderungsdatum),
|
||||
- Segmentierung in semantische Einheiten (z. B. Klasse/Methode, SQL-Statement, Konfigblock),
|
||||
- Ablage in einem Index, der später Retrieval ermöglicht.
|
||||
```text
|
||||
FR-001: User Authentication System
|
||||
Requirement: The system shall provide secure user authentication...
|
||||
(Quelle: system/SyRS_Complete_Detailed.md)
|
||||
```
|
||||
|
||||
Die Segmentierung verfolgt ein Ziel: Kontext soll klein genug sein, um präzise zu sein, aber groß genug, um Regeln nicht aus dem Zusammenhang zu reißen. Für Legacy-Code bedeutet dies typischerweise, dass neben einer Regelstelle auch angrenzende Strukturen (z. B. Statusenum, Datenobjektdefinition) berücksichtigt werden müssen.
|
||||
#heading(level: 2)[V02 Ergebnisse (ISO-Konsolidierung mit Agenten)]
|
||||
|
||||
#heading(level: 3)[Retrieval: Kontextauswahl und Ranking]
|
||||
#heading(level: 3)[Ergebnisdateien in `Versuche/Versuch 02/Ergenisse`]
|
||||
|
||||
Retrieval ist als zweistufiges Verfahren umgesetzt:
|
||||
- `Versuche/Versuch 02/Ergenisse/COMPLETE_REQUIREMENTS_SPECIFICATION.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/COMPLETE_REQUIREMENTS_SPECIFICATION.pdf`
|
||||
- `Versuche/Versuch 02/Ergenisse/README.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/TABLE_FORMATTING_STATUS.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/.execution_state/baseline_metrics.json`
|
||||
- `Versuche/Versuch 02/Ergenisse/.execution_state/directory_setup.txt`
|
||||
- `Versuche/Versuch 02/Ergenisse/.execution_state/milestone_state.json`
|
||||
- `Versuche/Versuch 02/Ergenisse/.execution_state/project_structure.json`
|
||||
- `Versuche/Versuch 02/Ergenisse/master/ISO29148_Executive_Summary.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/master/ISO29148_Master_Requirements.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/master/ISO29148_Quality_Report.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/master/ISO29148_Traceability_Master.csv`
|
||||
- `Versuche/Versuch 02/Ergenisse/master/ISO29148_Validation_Checklist.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/Analysis_Complete.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/Business_Rules.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/Integration_Patterns.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/Pattern_Catalog.csv`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/Performance_Patterns.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/Security_Patterns.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/SwRS_Algorithms.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/SwRS_CodeCatalog.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/SwRS_Complete.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/SwRS_DataModel.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/SwRS_TestSpecification.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/SwRS_Traceability.csv`
|
||||
- `Versuche/Versuch 02/Ergenisse/software/Validation_Rules.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/stakeholder/StRS_Complete.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/stakeholder/StRS_Diagrams.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/stakeholder/StRS_Evidence.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/stakeholder/StRS_Summary.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/stakeholder/StRS_Traceability.csv`
|
||||
- `Versuche/Versuch 02/Ergenisse/system/SyRS_API_Specification.yaml`
|
||||
- `Versuche/Versuch 02/Ergenisse/system/SyRS_Architecture.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/system/SyRS_Complete.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/system/SyRS_Interfaces.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/system/SyRS_Summary.md`
|
||||
- `Versuche/Versuch 02/Ergenisse/system/SyRS_Traceability.csv`
|
||||
|
||||
1. **Kandidatensuche:** Identifier, Domänenterminologie, Datenobjekte, UI-Labels und Query-Fragmente erzeugen eine erste Trefferliste.
|
||||
2. **Ranking und Kontextbündelung:** Treffer werden nach Nähe zum Untersuchungsziel (z. B. „Fakturierung“, „Berechtigung“) sortiert und als Kontextpakete zusammengeführt.
|
||||
#heading(level: 3)[Beispielhafte Requirements aus den Ergebnisdateien]
|
||||
|
||||
Damit wird vermieden, dass LLMs ohne ausreichende Belege „auffüllen“. Gleichzeitig bleibt das System flexibel: Neue Untersuchungsfragen können durch andere Retrieval-Queries adressiert werden, ohne dass die gesamte Pipeline angepasst werden muss.
|
||||
```text
|
||||
SyR-001: The system SHALL implement a multi-layered architecture with clear separation of concerns.
|
||||
(Quelle: Ergenisse/system/SyRS_Complete.md)
|
||||
```
|
||||
|
||||
#heading(level: 3)[Requirements-Extraktion und Traceability-Datenmodell]
|
||||
```text
|
||||
SyR-013: The system SHALL provide secure user authentication with multi-factor authentication support.
|
||||
(Quelle: Ergenisse/system/SyRS_Complete.md)
|
||||
```
|
||||
|
||||
Die Generation-Schicht erzeugt Requirements nicht als Freitext, sondern als strukturierte Einträge. Ein Eintrag umfasst mindestens:
|
||||
```text
|
||||
SW-ARCH-001: The software SHALL implement a 6-layer architecture pattern.
|
||||
(Quelle: Ergenisse/software/SwRS_Complete.md)
|
||||
```
|
||||
|
||||
- **Requirement-Text** (präzise, testbar),
|
||||
- **Akzeptanzkriterien** (Prüfidee, Mess- oder Beobachtbarkeit),
|
||||
- **Belege** (Dateipfade, Funktionen, SQL-Statements, UI-Strings),
|
||||
- **Unsicherheit** (Markierung fehlender Evidenz oder konkurrierender Interpretationen),
|
||||
- **Tags** (Domänenbereich, Datenobjekte, Risiko).
|
||||
#heading(level: 2)[V03 Ergebnisse (Discovery-Erweiterung mit Agenten und MCP)]
|
||||
|
||||
Traceability ist dabei ein zentrales Designkriterium. Die Literatur beschreibt Traceability als Voraussetzung, um Anforderungen über Lebenszyklen hinweg zu begründen und zu pflegen @gotel1994traceability @ramesh2001traceability. Für den Prototyp bedeutet dies: Der Agent darf Requirements nicht „aus dem Nichts“ formulieren, sondern muss die Verbindung zu den Artefakten als Primäroutput liefern.
|
||||
#heading(level: 3)[Ergebnisdateien in `Versuche/Versuch 03/ERP_DOCUMENTATION`]
|
||||
|
||||
#heading(level: 2)[Toolchain-Integration]
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/ANALYSIS_SUMMARY.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/BUSINESS_GLOSSAR_MIT_DB_MAPPING.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/BUSINESS_GLOSSAR.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/BUSINESS_GLOSSAR.pdf`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/COMPLETE_DATABASE_SCHEMA.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/DOCUMENTATION_INDEX.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/EXPORT_COMPLETE_SCHEMA.sql`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/README_USE_CASE_ANALYSIS.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/README.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/SCREENSHOT_ANALYSIS_SUMMARY.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/SCREENSHOT_MAPPING_COMPLETE.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/SCREENSHOT_PROJECT_INDEX.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/SSMS_DB_SCHEMA.sql`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/UNDOCUMENTED_USE_CASES_DATABASE_MODELS.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/UNDOCUMENTED_USE_CASES_REST_API.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/UNDOCUMENTED_USE_CASES_SUMMARY.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/UNDOCUMENTED_USE_CASES_WORKFLOWS.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASE_ANALYSIS_README.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASE_MAPPING.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES_CENTRON_NEXUS_DE.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES_CENTRON_NEXUS_DE.pdf`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES_CENTRON_NEXUS.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES_CENTRON_NEXUS.pdf`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES_NEW_CONTROLLERS.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES_NEW_GUI_MAPPING.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES_NEW_IMPLEMENTATION_GUIDE.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES_NEW_XAML_TEMPLATES.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES_NEW.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES.md`
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES.pdf`
|
||||
|
||||
#heading(level: 3)[Integration in Repository und Entwicklungsworkflow]
|
||||
#heading(level: 3)[Beispielhafte Use Cases aus den Ergebnisdateien]
|
||||
|
||||
Die Toolchain-Integration zielt darauf, Analyseergebnisse in vorhandene Arbeitsabläufe zu integrieren. Dazu gehören:
|
||||
```text
|
||||
1.1.1 Personalized User Welcome
|
||||
Purpose: Display personalized greeting with user name and context-aware dashboard content.
|
||||
(Quelle: ERP_DOCUMENTATION/USE_CASES_CENTRON_NEXUS.md)
|
||||
```
|
||||
|
||||
- **Repository-Integration:** Analyse auf einem definierten Stand (Commit/Tag), um Reproduzierbarkeit sicherzustellen.
|
||||
- **Versionierung von Prompts und Konfigurationen:** Prompt-Templates, Retrieval-Parameter und Modellversionen werden dokumentiert, damit Ergebnisse nachvollziehbar bleiben.
|
||||
- **Ergebnisablage:** Requirements werden in einem Format abgelegt, das Reviews ermöglicht (z. B. Markdown, Tabellenexport) und später in Tickets oder Spezifikationen überführt werden kann.
|
||||
```text
|
||||
1.1.6 Work Status Alerts
|
||||
Purpose: Alert users to missing or incomplete work time entries.
|
||||
(Quelle: ERP_DOCUMENTATION/USE_CASES_CENTRON_NEXUS.md)
|
||||
```
|
||||
|
||||
Reproduzierbarkeit ist in diesem Kontext nicht nur ein wissenschaftliches Kriterium, sondern eine praktische Voraussetzung: Ohne klare Zuordnung zu einem Code-Stand entsteht bei späteren Änderungen ein nicht auflösbarer Interpretationskonflikt.
|
||||
```text
|
||||
Key Finding: 1,720+ use cases discovered; current documentation gap: 71%.
|
||||
(Quelle: ERP_DOCUMENTATION/UNDOCUMENTED_USE_CASES_SUMMARY.md)
|
||||
```
|
||||
|
||||
#heading(level: 3)[Einbindung in Wissens- und Ticket-Systeme]
|
||||
#heading(level: 2)[Ergebnisfazit]
|
||||
|
||||
In Modernisierungsvorhaben sind Ticketsysteme und Wissensbasen zentrale Koordinationspunkte. Der Prototyp ist so konzipiert, dass Requirements:
|
||||
Die Ergebnislage zeigt drei komplementaere Stufen:
|
||||
|
||||
- als Backlog-Einträge überführt werden können,
|
||||
- mit Belegen verlinkt sind (Pfad + Stelle),
|
||||
- Review-Kommentare aufnehmen können,
|
||||
- als konsolidierte Spezifikation exportierbar bleiben.
|
||||
- **V01** liefert eine belastbare formale Baseline.
|
||||
- **V02** liefert die staerkste ISO-29148-konforme Konsolidierung mit hoher Traceability.
|
||||
- **V03** liefert die groesste funktionale Breite und identifiziert den groessten Dokumentations-Gap.
|
||||
|
||||
Die Integration ist bewusst „leichtgewichtig“ gehalten: Ziel ist nicht, ein neues Requirements-Tool zu ersetzen, sondern die Lücke der fehlenden Legacy-Spezifikation zu schließen und die Migration mit belegbaren Requirements zu stabilisieren.
|
||||
|
||||
#heading(level: 3)[Logging, Nachvollziehbarkeit und Qualitätsmetriken]
|
||||
|
||||
Da LLMs nicht deterministisch sind, wird Logging als Qualitätsinstrument verstanden. Pro Analysezyklus werden mindestens gespeichert:
|
||||
|
||||
- Scope-Definition,
|
||||
- verwendete Artefaktlisten und Retrieval-Treffer,
|
||||
- Promptversion und Modellparameter,
|
||||
- Rohoutput des Modells,
|
||||
- konsolidierter Requirement-Eintrag und Review-Status.
|
||||
|
||||
Diese Daten erlauben es, Fehlerquellen zu identifizieren (z. B. falscher Kontext, widersprüchliche Belege) und den Prozess iterativ zu verbessern. Gleichzeitig muss Logging gegen Datenschutz- und IP-Risiken abgewogen werden (siehe 5.3).
|
||||
|
||||
#heading(level: 2)[Governance, Datenschutz und IP]
|
||||
|
||||
#heading(level: 3)[Risiko- und Maßnahmenmodell]
|
||||
|
||||
Der Einsatz von LLMs im Kontext von Quellcode berührt Governance-Fragen. In der Literatur wird betont, dass große Sprachmodelle systemische Risiken wie Bias, Fehlverhalten und fehlende Transparenz aufweisen können @bender2021stochastic. Für die Fallstudie sind insbesondere folgende Risikoklassen relevant:
|
||||
|
||||
- **Falschaussagen/Halluzinationen:** plausibel klingende, aber unbelegte Requirements @ji2023hallucination.
|
||||
- **Datenabfluss:** unbeabsichtigte Preisgabe von Quellcode oder Betriebsinformationen.
|
||||
- **IP- und Lizenzrisiken:** unklare Rechte bei Weiterverarbeitung, Speicherung oder externem Modellbetrieb.
|
||||
- **Compliance:** Anforderungen aus Datenschutz oder Sicherheit, die in der Zielplattform nachweisbar erfüllt werden müssen.
|
||||
|
||||
Das Maßnahmenmodell kombiniert technische, organisatorische und prozessuale Kontrollen:
|
||||
|
||||
- Belegpflicht und Review,
|
||||
- Minimierung des Kontexts (Need-to-know),
|
||||
- Zugriffskontrollen auf Indizes und Logs,
|
||||
- Trennung von sensiblen Artefakten (z. B. Secrets) aus dem Analyseumfang.
|
||||
|
||||
#heading(level: 3)[Datenschutzorientierte Konfiguration und Datenminimierung]
|
||||
|
||||
Datenschutzanforderungen werden im Prototyp durch Datenminimierung operationalisiert. Praktisch bedeutet dies:
|
||||
|
||||
- Keine Analyse von Artefakten, die Zugangsdaten oder personenbezogene Inhalte enthalten.
|
||||
- Begrenzte Promptkontexte: nur die für die Fragestellung relevanten Codeausschnitte.
|
||||
- Reduzierte Speicherung: Prompt-Logs werden, wenn erforderlich, nur mit Hashes/Metadaten gespeichert, nicht als vollständige Inhalte.
|
||||
|
||||
Für den praktischen Einsatz ist zudem zu klären, ob Modelle lokal (On-Premise) oder als Cloud-Service betrieben werden. Diese Arbeit bewertet den Prototyp so, dass beide Betriebsformen abbildbar bleiben. Die konkrete Wahl ist eine Governance-Entscheidung, die von Schutzbedarf, Kosten und Betriebsaufwand abhängt.
|
||||
|
||||
#heading(level: 3)[IP, Verantwortlichkeit und Human-in-the-loop]
|
||||
|
||||
Der Prototyp ist so gestaltet, dass fachliche Verantwortung nicht an das Modell delegiert wird. LLMs liefern Vorschläge, Strukturierung und Zusammenfassungen, aber keine autoritativen Spezifikationsentscheidungen. Diese Trennung ist notwendig, weil die Qualität der Ergebnisse von Kontext, Prompt und Modellverhalten abhängt und sich ohne Review nicht verlässlich absichern lässt.
|
||||
|
||||
Für Requirements-Artefakte gelten daher folgende Prinzipien:
|
||||
|
||||
- **LLM-Output ist ein Zwischenartefakt:** erst Review und Konsolidierung erzeugen „gültige“ Requirements.
|
||||
- **Verantwortung liegt beim Projektteam:** insbesondere für Abnahmen und Architekturentscheidungen.
|
||||
- **Transparenz durch Belege:** damit Entscheidungen nachvollziehbar bleiben und in der Migration überprüfbar sind.
|
||||
|
||||
Damit ist die prototypische Umsetzung nicht als Ersatz für Requirements Engineering zu verstehen, sondern als skalierbares Werkzeug, das fehlende Legacy-Dokumentation durch belegbare, reviewbare Artefakte ergänzt.
|
||||
Damit liegt eine vollstaendige empirische Grundlage fuer die anschliessende Evaluation (Kapitel 6) vor: formal-strukturierte Requirements (V01/V02) plus breite Discovery-Evidenz (V03).
|
||||
|
||||
@@ -6,81 +6,119 @@
|
||||
|
||||
#heading(level: 1)[Evaluation (ca. 12 Seiten)]
|
||||
|
||||
Dieses Kapitel evaluiert die prototypische Durchführung des in Kapitel 4 beschriebenen Vorgehensmodells und die in Kapitel 5 skizzierte Toolchain-Umsetzung. Als Datenbasis dienen die im Ordner `Ergebnisse` abgelegten Artefakte (Requirements-Spezifikationen nach ISO/IEC/IEEE 29148, Use-Case-Dokumentation, UI↔Code-Mappings, Datenbankschema-Exports und Glossare). Der Fokus liegt auf der Frage, inwieweit die erzeugten Artefakte (1) strukturierte, prüfbare Requirements liefern, (2) Traceability ermöglichen und (3) den Analyseaufwand gegenüber rein manueller Rekonstruktion reduzieren.
|
||||
Die Evaluation folgt der in Kapitel 4 beschriebenen Iterationslogik und bewertet die drei real durchgefuehrten Versuche (V01-V03) vergleichend. Ziel ist nicht die Darstellung eines einzelnen "besten" Laufs, sondern die Einordnung der methodischen Entwicklung von einer Baseline ueber eine formale ISO-Konsolidierung bis zur anschliessenden Discovery-Erweiterung.
|
||||
|
||||
#heading(level: 2)[Evaluationskriterien und Messgrößen]
|
||||
#heading(level: 2)[Evaluationsdesign und Datenbasis]
|
||||
|
||||
Die Evaluationskriterien orientieren sich an den im Exposé definierten Messgrößen und an etablierten Qualitätsmerkmalen im Requirements Engineering @iso29148_2018 @ieee830_1998. Für KI-gestützte Extraktion wird zusätzlich berücksichtigt, dass plausible Textausgaben ohne Belegpflicht fachlich falsch sein können @ji2023hallucination @bender2021stochastic.
|
||||
Die Auswertung basiert ausschliesslich auf den erzeugten Artefakten in:
|
||||
|
||||
Für die Arbeit werden die folgenden Kriterien operationalisiert:
|
||||
- `Versuche/Versuch 01/Versuch01.md` und `Versuche/Versuch 01/Requirements.md`,
|
||||
- `Versuche/Versuch 02/Versuch02.md` und `Versuche/Versuch 02/Requirements.md`,
|
||||
- `Versuche/Versuch 03/Versuch03.md` und `Versuche/Versuch 03/Requirements.md`.
|
||||
|
||||
- **Vollständigkeit (relativ zum Scope):** Anteil der dokumentierten Requirements/Use Cases bezogen auf einen definierten Untersuchungsumfang (Module/Prozesse). Vollständigkeit wird in dieser Arbeit nicht als globale Eigenschaft der gesamten Legacy-Software verstanden, sondern als scopebezogene Abdeckung (z. B. pro Modulgruppe). Die Literatur weist darauf hin, dass Vollständigkeit durch Assistenzsysteme verbessert werden kann, aber nur in Verbindung mit Validierung und klarer Abgrenzung @luitel2024completeness.
|
||||
- **Verständlichkeit und Prüfbarkeit:** Requirements gelten als prüfbar, wenn Akzeptanzkriterien bzw. Verifikationsansätze aus dem Text ableitbar sind. Als Indikator wird die formale Struktur nach ISO/IEC/IEEE 29148 genutzt (Soll-Formulierung, Begründung, Kriterien, Verifikation) @iso29148_2018.
|
||||
- **Redundanzfreiheit und Konsistenz:** Identifikation doppelter oder widersprüchlicher Requirements. In der prototypischen Auswertung wird dies primär über Strukturprüfungen und Stichproben erfolgen; eine vollständige Duplikaterkennung erfordert zusätzliche, dedizierte Analyseschritte.
|
||||
- **Traceability (Nachvollziehbarkeit):** Anteil der Requirements, die explizite Belege auf Artefakte enthalten (Datei-/Pfadverweise, Klassen, Methoden, SQL-Objekte, UI-Elemente). Traceability ist eine zentrale Voraussetzung für belastbare Weiterentwicklung und Evaluation @gotel1994traceability @ramesh2001traceability.
|
||||
- **Stakeholder-Alignment:** Übereinstimmung der Ergebnisse mit Fachwissen und Prioritäten. Operationalisiert wird dies durch Review-Sessions (Bewertung, Korrekturen, Ergänzungen) und die Kennzeichnung offener Punkte.
|
||||
- **Aufwandsreduktion:** Zeitbedarf der KI-gestützten Rekonstruktion im Vergleich zu einer manuellen Erstellung für den gleichen Scope. Da reale manuelle Baselines stark von Team- und Artefaktlage abhängen, werden in der Pilotphase gemessene Toolchain-Zeiten und dokumentierte Aufwandsschätzungen als Vergleichsanker genutzt.
|
||||
Dabei wurden nur konsolidierte, in den Dateien ausgewiesene Kennzahlen uebernommen. Fokus der Bewertung:
|
||||
|
||||
#heading(level: 2)[Durchführung und Ergebnisse]
|
||||
1. Umfang der rekonstruierten Faehigkeiten/Requirements,
|
||||
2. Formalisierungsgrad (StRS/SyRS/SwRS vs. reine Use-Case-Discovery),
|
||||
3. Traceability- und ISO-29148-Naehe,
|
||||
4. methodischer Nutzen der eingesetzten Tooling-Konfiguration.
|
||||
|
||||
#heading(level: 3)[Untersuchungsgegenstand und Datenbasis]
|
||||
#heading(level: 2)[Quantitative Ergebnisse der Versuchsreihe]
|
||||
|
||||
Die prototypische Durchführung basiert auf einer artefaktzentrierten Analyse der Legacy-Software und angrenzender Quellen. In den Ergebnisartefakten wird die Systemgröße unter anderem über folgende Kenngrößen beschrieben:
|
||||
#table(
|
||||
columns: (1fr, 1fr, 1fr, 1fr),
|
||||
stroke: 0.4pt,
|
||||
[**Kennzahl**], [**V01**], [**V02**], [**V03**],
|
||||
[Konsolidierte Requirements/Faehigkeiten], [277], [220], [1720],
|
||||
[Formale Requirements (StRS+SyRS+SwRS)], [277], [220], [0],
|
||||
[StRS / SyRS / SwRS], [35 / 75 / 167], [84 / 53 / 83], [0 / 0 / 0],
|
||||
[Explizite Use Cases], [0], [46], [1720 (Use-Case-fokussiert)],
|
||||
[Undokumentierte Use Cases], [n.v.], [n.v.], [1211],
|
||||
[ISO-29148-Compliance], [qualitativ A+], [96,1% (100% mandatory)], [n.v.],
|
||||
[Traceability], [100% laut Doku], [100% bidirektional], [n.v.],
|
||||
[Ergebnisdateien gesamt], [11], [37], [30]
|
||||
)
|
||||
|
||||
- 34 Projekte und 849 Business-Logic-Klassen,
|
||||
- 956 NHibernate-Mappings,
|
||||
- 2.145 REST-Endpunkte,
|
||||
- 135 WPF-Module (UI-Kontext).
|
||||
Ergaenzende Kontextkennzahlen aus den Versuchsdateien:
|
||||
|
||||
Diese Größenordnungen sind für die Evaluation relevant, weil sie den Kontextdruck auf Kontextfenster und Retrieval (RAG) erklären und die Notwendigkeit strukturierter Traceability unterstreichen @lewis2020rag.
|
||||
- V01: Analyse von 34 C\#-Projekten und 12.507+ Source Files.
|
||||
- V02: 14.940 Dateien (13.717 C\#, 1.189 XAML, 34 Projekte), 46 explizite Use Cases in die formale Requirements-Struktur integriert.
|
||||
- V03: 150.000+ LoC analysiert, 3.412 potenzielle Use Cases identifiziert, 71% dokumentationsbezogener Gap (1211 von 1720 Use Cases vormals undokumentiert).
|
||||
|
||||
#heading(level: 3)[Ablauf der prototypischen Auswertung]
|
||||
#heading(level: 2)[Vergleichende Analyse]
|
||||
|
||||
Die Durchführung folgt der Logik aus Kapitel 4 (Scope → Artefaktpipeline → Extraktion → Traceability → Review). Für die prototypische Auswertung wurden die folgenden Artefaktgruppen erzeugt:
|
||||
#heading(level: 3)[Versuch 01: Formale Baseline ohne Tooling-Erweiterung]
|
||||
|
||||
- **Requirements-Spezifikationen nach ISO/IEC/IEEE 29148:** Stakeholder-, System- und Software-Ebene mit Statement/Begründung/Verifikation und Belegangaben.
|
||||
- **Use-Case-Dokumentation und Mapping:** Umfangreiche Modul- und Use-Case-Sammlungen, ergänzt um UI↔Code-Zuordnungen (WPF-Pfade, ViewModels, Controller, Rechtekonstanten).
|
||||
- **Domänen- und Datenartefakte:** Business-Glossar sowie Datenbankschema-Exports zur Begriffs- und Datenmodellstabilisierung.
|
||||
- **UI-basierte Discovery-Artefakte:** Screenshot-Mappings und Session-Reports für Teilbereiche der webbasierten Oberfläche (CentronNexus/ServiceBoard).
|
||||
V01 zeigt, dass bereits ohne Agenten/MCP eine formal strukturierte Requirements-Spezifikation erzeugt werden kann. Die Staerke liegt in der klaren Dreiebenenstruktur (StRS/SyRS/SwRS). Die Schwaeche ist die begrenzte Discovery-Perspektive: explizite Use-Case-Rekonstruktion und Gap-Bewertung bleiben gering ausgepraegt.
|
||||
|
||||
Für die Bewertung werden die Artefakte strukturell geprüft (Vorhandensein der geforderten Felder), Kennzahlen aus den Dokumenten extrahiert und zentrale Aussagen stichprobenartig gegen die angegebenen Belege gespiegelt.
|
||||
#heading(level: 4)[Prompt, Agenten und Ergebnisbeispiele (V01)]
|
||||
|
||||
#heading(level: 3)[Quantitative Ergebnisse]
|
||||
- **Verwendeter Prompt:** "Please analyze this software project and write a reuqirements specification according to modern standards."
|
||||
- **Agentenbeispiele:** Keine Agenten (bewusste Baseline ohne agentische Zerlegung und ohne MCP).
|
||||
- **Beispielhafte Ergebnis-Requirements:**
|
||||
- `Versuche/Versuch 01/Ergebnisse/ISO29148_Complete_Requirements_Specification.md`: u. a. `StR-001` (Comprehensive Customer Account Management).
|
||||
- `Versuche/Versuch 01/Ergebnisse/system/SyRS_Complete_Detailed.md`: u. a. `FR-001` (User Authentication System) und `FR-002` (Role-Based Access Control).
|
||||
- `Versuche/Versuch 01/Ergebnisse/software/SwRS_Complete_Detailed.md`: softwareseitige Architektur- und Umsetzungsanforderungen im SwRS-Format.
|
||||
|
||||
Die in `Ergebnisse` abgelegten Spezifikationen berichten insgesamt 277 dokumentierte Requirements (35 Stakeholder-, 75 System- und 167 Software-Requirements). In den detaillierten Artefakten liegen die folgenden, direkt prüfbaren Strukturindikatoren vor:
|
||||
#heading(level: 3)[Versuch 02: ISO-orientierte Konsolidierung mit Agenten]
|
||||
|
||||
- **Stakeholder Requirements (StRS):** 35 Statements mit jeweils Akzeptanzkriterien, Source-Evidence und Verifikationsmethode.
|
||||
- **System Requirements (SyRS):** 75 Statements mit Source-Evidence und Verifikationsmethode; Akzeptanzkriterien sind teilweise nicht einheitlich als eigenes Feld ausgewiesen.
|
||||
- **Software Requirements (SwRS, detaillierter Ausschnitt):** 120 Requirements mit „Requirement Statement“, Akzeptanzkriterien, Source-Evidence und Verifikationsmethode.
|
||||
V02 fokussiert die formale Konsolidierung und liefert eine ISO-29148-nahe Zielstruktur mit hoher Traceability. Mit 220 konsolidierten Requirements, 96,1% ISO-29148-Compliance und 100% bidirektionaler Traceability ist der Lauf methodisch sauber und reviewfaehig. Gleichzeitig zeigte sich die zentrale Grenze dieses Schritts: Die reine ISO-orientierte Ableitung war fuer den Gesamtumfang zu rigide und fuer die Discovery-Breite nicht vollumfaenglich genug.
|
||||
|
||||
Für die Use-Case- und Mapping-Ebene werden folgende Umfangs- und Abdeckungszahlen berichtet:
|
||||
#heading(level: 4)[Prompt, Agenten und Ergebnisbeispiele (V02)]
|
||||
|
||||
- 103 dokumentierte Module (inkl. Submodule) mit 509 Use Cases über 15 Hauptkategorien.
|
||||
- Mapping-Status in der Zusammenfassung: ca. 92% vollständig gemappt, ca. 6% teilweise gemappt, ca. 2% mit Klärungsbedarf.
|
||||
- **Verwendeter Prompt:** "Please analyze this software project and write a ISO 29148 compliant reuqirements specification. Use Agents wherever possible."
|
||||
- **Agentenbeispiele:**
|
||||
- `Versuche/Versuch 02/Tools/agents/iso29148-master-orchestrator-agent.md`
|
||||
- `Versuche/Versuch 02/Tools/agents/iso29148-stakeholder-agent.md`
|
||||
- `Versuche/Versuch 02/Tools/agents/iso29148-system-requirements-agent.md`
|
||||
- `Versuche/Versuch 02/Tools/agents/iso29148-software-requirements-agent`
|
||||
- **Beispielhafte Ergebnis-Requirements:**
|
||||
- `Versuche/Versuch 02/Ergenisse/system/SyRS_Complete.md`: u. a. `SyR-001` (Multi-Layer Architecture), `SyR-002` (Dual Data Access Pattern), `SyR-013` (Authentication).
|
||||
- `Versuche/Versuch 02/Ergenisse/software/SwRS_Complete.md`: u. a. `SW-ARCH-001` (6-Layer Architecture), `SW-ARCH-002` (ILogic-Pattern), `SW-FUNC-001` (Account Management).
|
||||
- `Versuche/Versuch 02/Ergenisse/master/ISO29148_Quality_Report.md`: qualitaetssichernde Gesamtbewertung (u. a. 100% Traceability).
|
||||
|
||||
Für die UI-basierte Discovery (CentronNexus) wird ein erster, bewusst begrenzter Scope dokumentiert:
|
||||
#heading(level: 3)[Versuch 03: Discovery-Erweiterung mit Agenten und MCP]
|
||||
|
||||
- 7 erfasste Module bei einem geplanten Umfang von 34 Modulen (20,6% Abdeckung).
|
||||
- Dokumentation eines neu identifizierten Features („Quick Ticket Creation“) mit 11 konkreten Use Cases.
|
||||
V03 erweitert deshalb die Methodik um MCP-gestuetzte Discovery. Der Lauf vergroessert die funktionale Breite deutlich (1720 konsolidierte Faehigkeiten, davon 1211 vormals undokumentierte Use Cases) und eignet sich besonders fuer Gap-Analysen und Vollstaendigkeitspruefung. Die Kehrseite ist ein geringerer Formalisierungsgrad gegenueber der ISO-Konsolidierung.
|
||||
|
||||
Die genannten Zahlen sind als Ergebnis der prototypischen Toolchain-Ausführung zu interpretieren. Für die Arbeit ist dabei nicht nur der Umfang relevant, sondern die konkrete Nachvollziehbarkeit über Belege: In den Requirements-Artefakten sind Source-Evidence-Verweise in großer Zahl vorhanden; in den Mapping-Artefakten werden UI-Elemente konsistent mit ViewModel-Properties, Commands und Modulpfaden verknüpft.
|
||||
#heading(level: 4)[Prompt, Agenten und Ergebnisbeispiele (V03)]
|
||||
|
||||
#heading(level: 3)[Aufwand und Beobachtungen zur Reproduzierbarkeit]
|
||||
- **Verwendeter Prompt:** "Please analyze this software project and write a reuqirements specification according to modern standards. Use Agents and MCP servers wherever possible. Keep superflous texts to a minimum and concentrate on actual requirements."
|
||||
- **Agentenbeispiele:**
|
||||
- `Versuche/Versuch 03/Tools/Agents/centron-documentation-writer.md`
|
||||
- `Versuche/Versuch 03/Tools/Agents/nhibernate-query-reviewer.md`
|
||||
- `Versuche/Versuch 03/Tools/Agents/centron-code-reviewer.md`
|
||||
- `Versuche/Versuch 03/Tools/Agents/webservice-developer.md`
|
||||
- **MCP-Beispiele:** Serena-MCP (Memory), Windows-MCP (UI-Interaktion), MSSQL-MCP (DB-Schemazugriff).
|
||||
- **Beispielhafte extrahierte Use-Case-/Anforderungsartefakte:**
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES_CENTRON_NEXUS.md`: u. a. Use Cases `1.1.1` (Personalized User Welcome), `1.1.6` (Work Status Alerts), `3.1` (Quick Ticket Creation).
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASES.md`: moduluebergreifende, strukturierte Use-Case-Dokumentation fuer c-entron.NET.
|
||||
- `Versuche/Versuch 03/ERP_DOCUMENTATION/UNDOCUMENTED_USE_CASES_SUMMARY.md`: 1.720+ Use Cases und ca. 71% Dokumentations-Gap als Discovery-Nachweis.
|
||||
|
||||
In den Discovery-Artefakten wird für eine UI-Analyse-Session ein Gesamtaufwand von 12 Stunden (4 Stunden Analyse, 8 Stunden Dokumentation) berichtet. Zusätzlich enthalten die Use-Case-Tools Aufwandsschätzungen für einzelne Analysebausteine (z. B. OpenAPI-Analyse, Workflows). Als Ergebnis lässt sich festhalten:
|
||||
#heading(level: 2)[Abgleich mit den geplanten Methoden]
|
||||
|
||||
- Der prototypische Ansatz liefert in kurzer Zeit umfangreiche, strukturierte Artefakte (Requirements, Mapping, Glossar, Schema).
|
||||
- Die Dokumente selbst enthalten bereits wesentliche Elemente für Reproduzierbarkeit (Belegpfade, Artefaktverweise). Nicht durchgängig dokumentiert sind jedoch Promptversionen, Sampling-Parameter und Retrieval-Konfigurationen. Für eine belastbare Reproduzierbarkeit im wissenschaftlichen Sinne ist diese Metadatenebene zu ergänzen (vgl. Kapitel 4.1.3).
|
||||
Der Soll-Ist-Abgleich zeigt eine hohe Passung zur geplanten Gesamtmethodik, wenn diese als iterative Kombination aus *Discovery* und *Konsolidierung* verstanden wird:
|
||||
|
||||
#heading(level: 2)[Qualitative Bewertung durch Experten]
|
||||
- Die Standardrecherche (ISO/IEC/IEEE 29148) wurde fruehzeitig umgesetzt.
|
||||
- Ein Baseline-Lauf ohne Spezialisierung wurde durchgefuehrt (V01).
|
||||
- Eine strukturierte ISO-Konsolidierung wurde realisiert (V02).
|
||||
- Danach wurde die Abdeckung durch MCP-gestuetzte Discovery erweitert (V03), weil der ISO-Lauf allein zu rigide und nicht vollumfaenglich genug war.
|
||||
|
||||
Die qualitative Bewertung ist zentral, weil fachliche Korrektheit aus Textqualität allein nicht ableitbar ist und LLM-Ausgaben systemische Fehlermuster aufweisen können @ji2023hallucination @bender2021stochastic. Für die Arbeit ist daher ein Human-in-the-loop-Review vorgesehen, der die Ergebnisse aus der KI-gestützten Extraktion gegen Domänenwissen und Projektziele spiegelt.
|
||||
Abweichung zur urspruenglich linearen Planung: Stakeholder-Interviews und flaechendeckende fachliche Reviews wurden in der betrachteten Phase noch nicht vollstaendig abgeschlossen. Die Methodik wird deshalb in der Ergebnisinterpretation als "technisch validierte Vorstufe" einer finalen fachlichen Konsolidierung eingeordnet.
|
||||
|
||||
Für die Durchführung sind folgende Bausteine vorgesehen:
|
||||
#heading(level: 2)[Bewertung der Forschungsleitfragen auf Basis der aktuellen Evidenz]
|
||||
|
||||
- **Stichprobenplan:** Auswahl repräsentativer Module/Prozesse (z. B. Fakturierung, Rechte/Authentifizierung, Datenintegrität) sowie bewusst „randfalllastiger“ Bereiche.
|
||||
- **Review-Artefakte:** Requirements mit Belegangaben, Use-Case-Mappings (UI↔Code) und Glossarbegriffe als gemeinsamer Referenzrahmen.
|
||||
- **Bewertungsinstrument:** Kurzfragebogen mit Skalen für Verständlichkeit, Prüfbarkeit, fachliche Korrektheit und Priorität; zusätzlich Erfassung von Korrekturen/Ergänzungen als Änderungslog.
|
||||
- **Abgleichlogik:** Markierung von (a) bestätigten Requirements, (b) widersprochenen Requirements, (c) Requirements mit unzureichender Evidenz, (d) fehlenden Requirements (Gap-Liste).
|
||||
- **F1 (reproduzierbarer LLM-Einsatz):** beantwortbar. Die drei Versuche zeigen, dass reproduzierbare Prozessschritte und klar unterscheidbare Konfigurationen moeglich sind.
|
||||
- **F2 (Ableitung aus Code vs. Zusatzquellen):** teilweise beantwortbar. Codebasierte Extraktion funktioniert, video- und interviewbasierte Ergaenzungen sind noch offen.
|
||||
- **F3 (Qualitaet aus Expertensicht):** noch nicht abschliessend beantwortbar, da systematische Expertenratings nicht vollstaendig dokumentiert vorliegen.
|
||||
- **F4 (Chancen und Grenzen):** beantwortbar. Chancen liegen in Skalierung und Strukturierung; Grenzen in Halluzinationsrisiken, fehlender Vollstaendigkeit ohne Zusatzquellen und hohem Konsolidierungsbedarf.
|
||||
|
||||
Zum Zeitpunkt der vorliegenden Fassung liegen in `Ergebnisse` keine dokumentierten Expertenratings oder Interviewprotokolle vor. Die qualitative Bewertung wird daher als nächster Evaluationsschritt in Kapitel 6 ergänzt, sobald Review-Sessions durchgeführt und protokolliert wurden. In der Diskussion (Kapitel 7) ist diese Einschränkung als Limitation der aktuellen Ergebnisevidenz zu berücksichtigen.
|
||||
#heading(level: 2)[Limitationen]
|
||||
|
||||
Die aktuelle Evidenz ist durch drei Punkte begrenzt:
|
||||
|
||||
1. Vollstaendige Video-Transkription und -Auswertung fehlen noch.
|
||||
2. Ein methodischer Endabgleich zwischen Video- und Codeperspektive ist noch nicht abgeschlossen.
|
||||
3. Die fachliche Endklassifikation aller Use-Case-Cluster (Ja/Nein/Neu/TBD) liegt noch nicht durchgaengig vor.
|
||||
|
||||
Diese Limitationen betreffen vor allem die finale Vollstaendigkeitsaussage, nicht jedoch die grundlegende Wirksamkeit der iterativen Methodik.
|
||||
|
||||
@@ -1,10 +1,49 @@
|
||||
#let __is_thesis = context { query(<__thesis_document>).len() > 0 }
|
||||
#if __is_thesis == false [
|
||||
#set cite(style: "apa")
|
||||
#hide(bibliography("../literatur.bib", style: "apa"))
|
||||
]
|
||||
|
||||
#heading(level: 1)[Diskussion (ca. 8 Seiten)]
|
||||
|
||||
#heading(level: 2)[Interpretation der Ergebnisse]
|
||||
Vergleiche die Evaluation mit den Forschungsleitfragen.
|
||||
|
||||
Die Ergebnisse zeigen einen klaren methodischen Lerneffekt ueber die drei Iterationen. Der Verlauf von V01 ueber V02 zu V03 ist nicht als Widerspruch, sondern als komplementaere Reifung zu interpretieren:
|
||||
|
||||
- V01 demonstriert, dass bereits mit einfacher Konfiguration formal strukturierte Requirements ableitbar sind.
|
||||
- V02 zeigt, dass eine agentengestuetzte ISO-Konsolidierung methodisch sauber, aber fuer den Gesamtumfang zu rigide sein kann.
|
||||
- V03 zeigt, dass die MCP-Erweiterung die funktionale Breite massiv erhoeht und Discovery-Luecken schliesst.
|
||||
|
||||
In Summe entsteht ein zweistufiges Zielbild fuer Reverse Requirements Engineering in Legacy-Projekten: zuerst *formal konsolidieren*, danach *gezielt in die Breite erweitern*.
|
||||
|
||||
#heading(level: 2)[Chancen und Grenzen]
|
||||
Diskutiere Potenziale und Limitationen des KI-gestützten Ansatzes.
|
||||
|
||||
#heading(level: 2)[Implikationen für Forschung und Praxis]
|
||||
Leitfäden für Unternehmen und offene Forschungsfragen.
|
||||
Die wesentlichen Chancen des Ansatzes liegen in:
|
||||
|
||||
- hoher Skalierbarkeit bei grossen Legacy-Artefakten,
|
||||
- schneller Sichtbarmachung undokumentierter Funktionalitaet,
|
||||
- strukturierter Ueberfuehrung in reviewbare Requirements-Artefakte.
|
||||
|
||||
Die zentralen Grenzen bleiben:
|
||||
|
||||
- keine belastbare Vollstaendigkeit ohne Zusatzquellen (insbesondere Nutzungs- und Prozesssicht),
|
||||
- Halluzinations- und Fehlinterpretationsrisiken ohne Beleg- und Reviewpflicht,
|
||||
- hoher Konsolidierungsaufwand zwischen Discovery-Artefakten und abnahmefaehiger Spezifikation.
|
||||
|
||||
Damit bestaetigt die Fallstudie, dass LLMs Requirements Engineering nicht ersetzen, aber als beschleunigendes Analyseinstrument mit klaren Governance-Regeln substantiellen Mehrwert liefern.
|
||||
|
||||
#heading(level: 2)[Implikationen fuer Forschung und Praxis]
|
||||
|
||||
Fuer die Praxis folgt daraus ein umsetzbarer Einfuehrungspfad:
|
||||
|
||||
1. Iterative Versuchslogik statt einmaliger "Big-Bang"-Extraktion.
|
||||
2. Trennung von Discovery- und Konsolidierungsphase als Standard.
|
||||
3. Traceability als verpflichtendes Abnahmekriterium fuer LLM-Ergebnisse.
|
||||
|
||||
Fuer die Forschung ergeben sich drei Anschlussfragen:
|
||||
|
||||
1. Wie laesst sich die Triangulation aus Code-, Video- und Stakeholderdaten automatisiert zusammenfuehren?
|
||||
2. Welche Metriken messen Qualitaet von Requirements-Artefakten robuster als reine Umfangszahlen?
|
||||
3. Wie kann Human-in-the-loop-Validierung mit vertretbarem Aufwand skaliert werden?
|
||||
|
||||
Die vorliegende Arbeit liefert dafuer eine belastbare methodische Ausgangsbasis, zeigt aber zugleich, dass die letzte Meile zur fachlich finalen Spezifikation weiterhin ein kooperativer Mensch-KI-Prozess bleibt.
|
||||
|
||||
@@ -1,10 +1,35 @@
|
||||
#heading(level: 1)[Fazit und Ausblick (ca. 4 Seiten)]
|
||||
|
||||
#heading(level: 2)[Zusammenfassung und Beantwortung der Forschungsfragen]
|
||||
Fasse die wichtigsten Erkenntnisse zusammen und beantworte die Leitfragen.
|
||||
|
||||
#heading(level: 2)[Handlungsempfehlungen für c-entron GmbH]
|
||||
Formuliere konkrete nächste Schritte für die c-entron GmbH.
|
||||
Die Arbeit zeigt, dass KI-gestuetztes Reverse Requirements Engineering im untersuchten Legacy-ERP-Kontext praktikabel ist, wenn der Prozess iterativ und kontrolliert aufgebaut wird. Die drei durchgefuehrten Versuche liefern dabei komplementaere Staerken:
|
||||
|
||||
#heading(level: 2)[Ausblick und zukünftige Forschung]
|
||||
Zeige zukünftige Forschungsschwerpunkte und Weiterentwicklungsmöglichkeiten des Prototyps.
|
||||
- V01 liefert eine formale Baseline mit klarer Requirements-Struktur.
|
||||
- V02 konsolidiert die Erkenntnisse in eine ISO-29148-nahe, traceability-starke Spezifikation.
|
||||
- V03 erweitert die Discovery-Breite per MCP und deckt einen hohen dokumentationsbezogenen Gap auf.
|
||||
|
||||
Damit ist F1 (prozessuale Einsetzbarkeit von LLMs) positiv beantwortet. F4 (Chancen und Grenzen) ist ebenfalls klar beantwortbar: Hohe Effizienz- und Strukturgewinne stehen einem weiterhin relevanten Validierungs- und Konsolidierungsbedarf gegenueber. F2 und F3 sind teilweise beantwortet, da video- und interviewbasierte Endvalidierung noch nicht vollstaendig abgeschlossen ist.
|
||||
|
||||
#heading(level: 2)[Handlungsempfehlungen fuer c-entron GmbH]
|
||||
|
||||
Aus den Ergebnissen lassen sich folgende priorisierte Handlungsschritte ableiten:
|
||||
|
||||
1. **V02 als Spezifikationsbasis verwenden:** Die 220 konsolidierten Requirements mit hoher Traceability als Arbeitsgrundlage fuer die Web-Migration etablieren.
|
||||
2. **V03 als Discovery-Backlog nutzen:** Die 1720 identifizierten Faehigkeiten systematisch gegen V02 mappen, um potenzielle Luecken sichtbar zu halten.
|
||||
3. **Review-Governance fest verankern:** Fachliche Freigaben und Aenderungsentscheidungen pro Requirement dokumentieren (kein unreviewter LLM-Output im Zielbacklog).
|
||||
4. **Toolchain standardisieren:** Prompt-/Agentenkonfigurationen versionieren, damit Folgeanalysen reproduzierbar bleiben.
|
||||
|
||||
#heading(level: 2)[Ausblick und naechste Schritte]
|
||||
|
||||
Die naechste Arbeitsphase erweitert die bisher codezentrierte Evidenz um die noch offenen Schritte aus dem Protokoll:
|
||||
|
||||
1. **Vollstaendige Videoanalyse:** Alle vorhandenen Schulungsvideos KI-gestuetzt transkribieren und strukturiert auf Use Cases auswerten.
|
||||
2. **Abgleich Video vs. Codeanalyse:** Systematischer Vergleich, ob und wo sich beide Sichten decken bzw. welche Use Cases nur in einer Quelle auftauchen.
|
||||
3. **Clusterung in abstrakte Konzepte:** Die identifizierten Use Cases in die bereits vorbereiteten 101 abstrahierten Konzepte ueberfuehren (vgl. `A_Videoanalyse_Uebersicht.csv`).
|
||||
4. **Manuelle Fachklassifikation pro Cluster:** Bewertung in die Kategorien
|
||||
- **ja:** unveraenderte Uebernahme,
|
||||
- **nein:** Entfall in ERP Web,
|
||||
- **neu:** fachlich vorhanden, aber neu zu konzipieren,
|
||||
- **TBD:** vorlaeufig offen.
|
||||
|
||||
Erst mit dieser finalen Triangulation aus Code, Video und Fachbewertung ist eine belastbare Vollstaendigkeitsaussage fuer die Migrationsplanung moeglich.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -3,10 +3,10 @@
|
||||
#let meta = (thesis.meta)(
|
||||
"KI-gestütztes Reverse Requirements Engineering bei Legacy-Software",
|
||||
"Masterarbeit an der Hochschule Neu-Ulm",
|
||||
"Christoph Musterfrau",
|
||||
"Christoph Schwörer",
|
||||
"Master of Science",
|
||||
"Prof. Dr. Daniel Schallmo",
|
||||
"31. März 2026"
|
||||
"XX 2026"
|
||||
)
|
||||
|
||||
#(thesis.cover)(meta)
|
||||
|
||||
32
Protokoll.md
32
Protokoll.md
@@ -11,32 +11,23 @@ Zur Analyse der Usecases des bestehenden C-entron ERP wurde bisher folgendes gem
|
||||
Der Prompt dabei war:
|
||||
|
||||
|
||||
1.1 Anschließen wurden alle gefundenen Usecases geclustert und in 101 Abstrakte Konzepte zugeordnet (Z.B. Adressstamm, Anzahlungsrechnung, Checlisten, Preismatrix, SEPA, Mailvorlagen, etc) Eine volsltändige liste liegt unter [link](./A_Videoanalyse_Uebersicht.csv)
|
||||
|
||||
1.2 Der nächste Schritt war das manuelle erörtern aller dieser Usecases und eine erste Bewertung und Kategorisierung in folgende Kategorien:
|
||||
- *ja*: Der USecase/Feature/Modul soll in seiner Bestehenden form übernommen werden. Alle anfordrungen und Umsetzungen bleiben bestehen
|
||||
- *nein*: Der Usecase/Feature/Modul wir in ERP Web nciht mehr vorhanden sein (Deprected oder zwischenzeitlich andere Lösung. Beispiel TAPI Anbindung)
|
||||
- *neu*: Der Usecase/Feature/Module muss in seiner Form neu überdacht werden. Grundsätzlich soll das Feature vorhanden sein, aber die Methode / Anforderugnen / Umsetzung muss überdacht werden.
|
||||
- *TBD*: Noch keine Entscheidung. Muss im detail betrachtet werden.
|
||||
|
||||
|
||||
2. Erster Versuch mit LLM (Claude AI, Codex) ohne jegliche anpassung an Claude AI:
|
||||
Prompt:
|
||||
|
||||
Ergebnis
|
||||
Claude:
|
||||
Codex:
|
||||
|
||||
2.5 Verfeinerung des Prompts
|
||||
Ergebnis
|
||||
Claude:
|
||||
Codex:
|
||||
2.1 Erster allgmeeiner Versuch
|
||||
[Siehe inhalt von Versuche/Versuch01]
|
||||
|
||||
2.2 Spezialisierter Versuch auf IS0 29148 mit Agents
|
||||
[Siehe inhalt von Versuche/Versuch 02]
|
||||
|
||||
2.3 Spezialisierter Versuch mit Agents und MCP Servern
|
||||
[Siehe inhalt von Versuche/Versuch 03]
|
||||
|
||||
3. Komplette Individualisierung von Claude (Claude.md Agents, MCP Server, Skills)
|
||||
|
||||
Prompt:
|
||||
Ergebnis:
|
||||
[Siehe Versuch 03]
|
||||
|
||||
|
||||
4. Offen: Vollständige Videoanalyse:
|
||||
@@ -47,3 +38,10 @@ Ergebnis:: offen
|
||||
|
||||
4.5 Offen: Abgleich der Videoanalyse mit den codebasierten Analysen ob sich die UseCases decken oder auf welcher Seite mehr/weniger Usecases geefunden wurden.
|
||||
|
||||
4.6 Optional :Anschließen wurden alle gefundenen Usecases geclustert und in 101 Abstrakte Konzepte zugeordnet (Z.B. Adressstamm, Anzahlungsrechnung, Checlisten, Preismatrix, SEPA, Mailvorlagen, etc) Eine volsltändige liste liegt unter [link](./A_Videoanalyse_Uebersicht.csv)
|
||||
|
||||
4.6.2 Der nächste Schritt war das manuelle erörtern aller dieser Usecases und eine erste Bewertung und Kategorisierung in folgende Kategorien:
|
||||
- *ja*: Der USecase/Feature/Modul soll in seiner Bestehenden form übernommen werden. Alle anfordrungen und Umsetzungen bleiben bestehen
|
||||
- *nein*: Der Usecase/Feature/Modul wir in ERP Web nciht mehr vorhanden sein (Deprected oder zwischenzeitlich andere Lösung. Beispiel TAPI Anbindung)
|
||||
- *neu*: Der Usecase/Feature/Module muss in seiner Form neu überdacht werden. Grundsätzlich soll das Feature vorhanden sein, aber die Methode / Anforderugnen / Umsetzung muss überdacht werden.
|
||||
- *TBD*: Noch keine Entscheidung. Muss im detail betrachtet werden.
|
||||
@@ -25,11 +25,27 @@ Fokus auf ISO/IEC/IEEE-29148-konforme Requirements-Spezifikation ueber drei Eben
|
||||
| Analysierte Quellartefakte | 34 C# Projekte, 12.507+ Source Files |
|
||||
| Separate Traceability-CSV (Dateien / Zeilen) | 0 / 0 |
|
||||
|
||||
## Vorgehen
|
||||
- Einfacher Prompt zu Claude Code
|
||||
- Keine Agents
|
||||
- Keine MCP Server
|
||||
|
||||
## Verwendeter Prompt
|
||||
```text
|
||||
Please analyze this software project and write a reuqirements specification according to modern standards.
|
||||
```
|
||||
|
||||
## Agenten (Beispiele)
|
||||
- Keine Agenten in V01 verwendet (Baseline ohne agentische Zerlegung)
|
||||
|
||||
## Ergebnisbeispiele aus `Ergebnisse`
|
||||
- `Ergebnisse/ISO29148_Complete_Requirements_Specification.md`
|
||||
- Dokumentiert 277 Requirements (35 StRS + 75 SyRS + 167 SwRS)
|
||||
- Enthaltene Evidenzbasis: 5.000+ File-Referenzen (laut Dokumentkopf)
|
||||
- `Ergebnisse/system/SyRS_Complete_Detailed.md`
|
||||
- Vollstaendige SyRS-Struktur mit funktionalen, Schnittstellen-, Performance- und Security-Anforderungen
|
||||
- `Ergebnisse/software/SwRS_Complete_Detailed.md`
|
||||
- Detaillierte Software-Anforderungen inkl. Verifikationsbezug
|
||||
|
||||
## Evaluation-Hinweis
|
||||
Starker Fokus auf formale Requirements-Qualitaet und Traceability; konsolidierte Zaehlung erfolgt in `Requirements.md`.
|
||||
|
||||
## Vorgehen
|
||||
- Einfacher Prompt zu Claude Code ohne Agents oder MCP Server
|
||||
|
||||
## Prompt
|
||||
"Please analyze this software project and write a reuqirements specification according to modern standards."
|
||||
@@ -1,20 +1,23 @@
|
||||
# Versuch 02 - Requirements (konsolidiert)
|
||||
|
||||
## Konsolidierungsentscheidung
|
||||
Use Cases und Anforderungen werden als gleiches Zielobjekt betrachtet. In Versuch 02 liegen die Features/Faehigkeiten ueberwiegend als Use Cases vor (keine vollstaendige StRS/SyRS/SwRS-Gliederung).
|
||||
Use Cases und Anforderungen werden als gleiches Zielobjekt betrachtet. In Versuch 02 sind Use Cases in den Stakeholder-Diagrammen dokumentiert, aber inhaltlich mit den formalen Anforderungen verknuepft (Traceability auf StR-IDs). Daher erfolgt eine deduplizierte Konsolidierung.
|
||||
|
||||
## Cluster-Liste
|
||||
| Cluster | Anzahl |
|
||||
| --- | ---: |
|
||||
| Formale Anforderungen (StRS+SyRS+SwRS) | 0 |
|
||||
| Dokumentierte Use Cases | 509 |
|
||||
| Neu entdeckte (vormals undokumentierte) Use Cases | 1211 |
|
||||
| Ueberlappung Use Cases <-> Anforderungen (abgezogen) | 0 |
|
||||
| Stakeholder-Anforderungen (StRS) | 84 |
|
||||
| System-Anforderungen (SyRS) | 53 |
|
||||
| Software-Anforderungen (SwRS) | 83 |
|
||||
| Explizite Use Cases (Diagramme) | 46 |
|
||||
| Ueberlappung Use Cases <-> Anforderungen (konservativ abgezogen) | 46 |
|
||||
|
||||
## Summen
|
||||
- Rohsumme (`Requirements + Use Cases`): **1720**
|
||||
- **Konsolidierte Requirements/Faehigkeiten gesamt: 1720**
|
||||
- Rohsumme (`Requirements + Use Cases`): **266**
|
||||
- **Konsolidierte Requirements/Faehigkeiten gesamt: 220**
|
||||
|
||||
## Hinweis
|
||||
- Die Zahl `1720` ist bereits dedupliziert als "Total System Functionality".
|
||||
- Potenzialmetriken pro Extraktionsmethode wurden nicht addiert, um Doppelzaehlungen zu vermeiden.
|
||||
## Use-Case-Cluster (Nachweis)
|
||||
- Sales Management: 13
|
||||
- Helpdesk Management: 17
|
||||
- Financial Management: 16
|
||||
- Summe explizite Use Cases: 46
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# AGENTS.md
|
||||
# AGENTS.md
|
||||
|
||||
This file provides guidance to Codex when working with code in this repository.
|
||||
|
||||
@@ -31,14 +31,6 @@ Available targets:
|
||||
- `run-tests` - Execute all test suites
|
||||
- `create-installers` - Build MSI installers
|
||||
|
||||
## Agent Notes
|
||||
|
||||
- Default shell is PowerShell (`pwsh`). Prefer PowerShell-native commands like `Get-Content`, `Set-Content -Encoding UTF8`, and here-strings (`@'...'@`) instead of Unix tools (`sed`, `nl`, etc.).
|
||||
- Use `rg`/`rg --files` for fast searches—they are available by default.
|
||||
- Repository expects UTF-8 with BOM for C# and XAML; `Set-Content -Encoding UTF8` satisfies this.
|
||||
- Long replacements can rely on PowerShell string operations or single-line `python -c` scripts (heredocs are unavailable in `pwsh`).
|
||||
- `dotnet build Centron.sln` may warn about `libfintx.FinTSConfig`; this is expected and can be ignored for success checks.
|
||||
|
||||
### Publishing
|
||||
- **Publish WPF UI**: `dotnet publish src/centron/Centron.WPF.UI/Centron.WPF.UI.csproj -c Release -r win-x64 --self-contained`
|
||||
- **Publish Web Service**: `dotnet publish src/webservice/Centron.Host.WindowsService/Centron.Host.WindowsService.csproj -c Release -r win-x64 --self-contained`
|
||||
@@ -292,4 +284,4 @@ When adding new documentation to the project:
|
||||
- Supports both standalone and web service deployment modes
|
||||
- Always test database scripts before committing
|
||||
- Use German for all user-facing text with English translations
|
||||
- Follow dual implementation pattern (BL + WS) for all data access
|
||||
- Follow dual implementation pattern (BL + WS) for all data access
|
||||
@@ -1,248 +1,316 @@
|
||||
# c-entron.NET
|
||||
# CLAUDE.md
|
||||
|
||||
> ⚠️ **FOR CLAUDE AI - NOT FOR DEVELOPERS**
|
||||
>
|
||||
> This file contains project conventions and patterns that Claude AI uses to generate correct code.
|
||||
> **Developers**: See [.claude/README.md](.claude/README.md) for user documentation.
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
> **v2.1.0** | 2025-01-20 | ERP for German SMBs | C# .NET 8 | WPF + REST API
|
||||
## Development Commands
|
||||
|
||||
## Stack
|
||||
**Core**: C# 12, .NET 8 | **Frontend**: WPF + Blazor Server, DevExpress 24.2.7 (WPF & Blazor), MVVM | **Backend**: ASP.NET Core 8, SQL Server 2019+, NHibernate 5.x, JWT auth | **Real-Time**: SignalR | **Build**: Azure DevOps, Centron.Scripts, WiX MSI | **Test**: NUnit
|
||||
### Building
|
||||
- **Build entire solution**: `dotnet build Centron.sln`
|
||||
- **Build specific project**: `dotnet build src/centron/Centron.WPF.UI/Centron.WPF.UI.csproj`
|
||||
- **Build for Release**: `dotnet build Centron.sln -c Release`
|
||||
|
||||
### Testing
|
||||
- **Run all tests**: `dotnet test Centron.sln`
|
||||
- **Run specific test project**: `dotnet test tests/backend/Centron.Tests.BL/Centron.Tests.BL.csproj`
|
||||
- **Run integration tests**: `dotnet test tests/Centron.Tests.Integration/Centron.Tests.Integration.csproj`
|
||||
- **Run end-to-end tests**: `dotnet test tests/Centron.Tests.EndToEnd/Centron.Tests.EndToEnd.csproj`
|
||||
|
||||
### Using Centron.Scripts Build System
|
||||
The project uses a custom build system via Centron.Scripts for complete builds:
|
||||
|
||||
```bash
|
||||
cd scripts/Centron.Scripts
|
||||
dotnet run -- <target>
|
||||
```
|
||||
|
||||
Available targets:
|
||||
- `clean` - Clean artifacts and bin/obj directories
|
||||
- `setup-versioning` - Set up version information
|
||||
- `build-web-service` - Build the web service components
|
||||
- `build-centron-net` - Build the WPF client application
|
||||
- `run-tests` - Execute all test suites
|
||||
- `create-installers` - Build MSI installers
|
||||
|
||||
### Publishing
|
||||
- **Publish WPF UI**: `dotnet publish src/centron/Centron.WPF.UI/Centron.WPF.UI.csproj -c Release -r win-x64 --self-contained`
|
||||
- **Publish Web Service**: `dotnet publish src/webservice/Centron.Host.WindowsService/Centron.Host.WindowsService.csproj -c Release -r win-x64 --self-contained`
|
||||
|
||||
## Project Architecture
|
||||
|
||||
### High-Level Structure
|
||||
This is a .NET 8 enterprise application with a multi-layered architecture:
|
||||
|
||||
## Structure
|
||||
```
|
||||
src/
|
||||
├── apis/ - External integrations (FinAPI, GLS, Shipcloud, ITscope, etc.)
|
||||
├── backend/ - BL, DAO, Entities, Interfaces, EDI
|
||||
├── centron/ - WPF UI (Desktop)
|
||||
├── CentronNexus/ - Blazor Server (Web Portal)
|
||||
├── shared/ - Core, Controls
|
||||
└── webservice/ - REST API, Hosts
|
||||
tests/ - BL, DAO, Integration, E2E
|
||||
.claude/ - agents/, commands/, hooks/, settings.json
|
||||
├── apis/ - External API integrations (FinAPI, GLS, Shipcloud, etc.)
|
||||
├── backend/ - Core business logic layer
|
||||
│ ├── Centron.BL/ - Business Logic layer
|
||||
│ ├── Centron.Common/ - Common utilities and helpers
|
||||
│ ├── Centron.DAO/ - Data Access Objects (NHibernate)
|
||||
│ ├── Centron.Entities/ - Domain entities
|
||||
│ ├── Centron.Gateway/ - External service gateways
|
||||
│ └── Centron.Interfaces/ - Service interfaces
|
||||
├── centron/ - WPF client application
|
||||
│ ├── Centron.WPF.UI/ - Main WPF application
|
||||
│ └── Centron.WPF.UI.Extension/ - UI extensions
|
||||
├── shared/ - Shared components and controls
|
||||
│ ├── Centron.Core/ - Core shared functionality
|
||||
│ ├── Centron.Controls/ - Custom UI controls
|
||||
│ └── Centron.Controls.Preview/ - Preview controls
|
||||
└── webservice/ - Web service components
|
||||
├── Centron.Host/ - Web service host
|
||||
├── Centron.Host.Console/ - Console host
|
||||
├── Centron.Host.WindowsService/ - Windows service host
|
||||
├── Centron.WebServices.Core/ - Web service core
|
||||
└── c-entron.misc.ConnectionManager/ - Connection management
|
||||
```
|
||||
|
||||
**Key Files**: `src/centron/Centron.WPF.UI/App.xaml.cs` (WPF), `src/webservice/Centron.Host.WindowsService/Program.cs` (Service), `Centron.sln`, `version.json`
|
||||
### Data Access Pattern
|
||||
The application uses a dual data access pattern supporting both direct database access and web service communication:
|
||||
|
||||
## Naming
|
||||
- **C# Classes**: `PascalCase`, Interfaces: `IPascalCase`, Methods: `PascalCase`, Private: `_camelCase`, Local: `camelCase`
|
||||
- **DB Tables**: `PascalCase` English (new), Keep German (legacy), PK: `I3D` (int IDENTITY), FK: `{Table}I3D`
|
||||
- **Standard Columns**: `CreatedByI3D`, `CreatedDate`, `ChangedByI3D`, `ChangedDate`, `IsDeleted`, `DeletedByI3D`, `DeletedDate`
|
||||
- **BL Pattern**: `I{Module}Logic`, `BL{Module}Logic`, `WS{Module}Logic`, `{Entity}BL`, `{Entity}WebServiceBL`
|
||||
#### WPF UI Architecture (3-layer pattern | ILogic Interface Pattern)
|
||||
All data operations in the UI must use the ILogic interface accessed through ClassContainer:
|
||||
- WPF UI modules use a 3-part data access pattern:
|
||||
- I{Module}Logic interface - Defines the contract
|
||||
- BL{Module}Logic (NHibernate/SQL Server) - Direct database access via NHibernate
|
||||
- WS{Module}Logic (REST API) - Web service access via REST API
|
||||
- Access via ClassContainer.Instance.WithInstance((ILogic logic) => ...).ThrowIfError();
|
||||
- Connection types controlled by AppModuleController:
|
||||
- CentronConnectionType.CentronWebServices ➜ WSLogic
|
||||
- CentronConnectionType.SqlServer ➜ BLLogic
|
||||
|
||||
## Critical Patterns
|
||||
|
||||
### Result Pattern (MANDATORY)
|
||||
```csharp
|
||||
public Result<T> Method() {
|
||||
try {
|
||||
var data = _dao.Get<T>(id);
|
||||
return data == null ? Result.Error<T>("Not found") : Result.Success(data);
|
||||
} catch (Exception ex) { return Result.Error<T>(ex); }
|
||||
}
|
||||
```
|
||||
|
||||
### UI Data Access (MANDATORY)
|
||||
```csharp
|
||||
// Single use
|
||||
var result = await ClassContainer.Instance
|
||||
.WithInstance((IEntityLogic logic) => logic.GetEntity(id))
|
||||
var result = await ClassContainer
|
||||
.Instance
|
||||
.WithInstance((IAccountContractsLogic logic) => logic.GetAccountContracts(filter))
|
||||
.ThrowIfError();
|
||||
|
||||
// Multiple uses (IDisposable)
|
||||
private readonly IEntityLogic _logic;
|
||||
public ViewModel() { _logic = ClassContainer.Instance.GetInstance<IEntityLogic>(); }
|
||||
public void Dispose() { ClassContainer.Instance.ReleaseInstance(_logic); }
|
||||
```
|
||||
|
||||
### Architecture
|
||||
**WPF UI** → `I{Module}Logic` (ClassContainer) → `BL{Module}Logic` (SQL) OR `WS{Module}Logic` (REST)
|
||||
**REST API** → `CentronRestService` → `{Entity}WebServiceBL` (DTO conversion) → `{Entity}BL` (Business Logic) → DAO → NHibernate → SQL Server
|
||||
#### Backend Architecture (2-layer pattern)
|
||||
- Backend uses a 2-layer BL approach for web service implementation:
|
||||
- Base BL class (e.g., AccountDeviceBL) - contains core business logic and database access via DAO
|
||||
- WebService BL class (e.g., AccountDeviceWebServiceBL) - handles DTO conversion and calls base BL
|
||||
- WebService BL pattern:
|
||||
- Inherits from BaseBL and creates instance of corresponding base BL class
|
||||
- Converts DTOs to entities using conversion methods (ConvertAccountDeviceDTOToAccountDevice)
|
||||
- Uses ObjectMapper for entity-to-DTO conversion
|
||||
- Ensures DTO entities are not connected to NHibernate database context for API security
|
||||
- API implementation in ICentronRestService and CentronRestService:
|
||||
- API methods call WebService BL classes
|
||||
- All API operations use DTO entities for data transfer
|
||||
- Example: SaveAccountDevice API method → AccountDeviceWebServiceBL.SaveAccountDevice → AccountDeviceBL.SaveAccountDevice
|
||||
|
||||
Connection types: `CentronConnectionType.SqlServer` (BLLogic) | `CentronConnectionType.CentronWebServices` (WSLogic)
|
||||
### Technology Stack
|
||||
- **.NET 8** - Primary framework
|
||||
- **WPF** - Desktop UI framework
|
||||
- **NHibernate** with **FluentNHibernate** - ORM for database access
|
||||
- **DevExpress 24.2.7** - UI controls and components
|
||||
- **Bullseye** - Build orchestration
|
||||
- **Entity Framework** - Some components use EF alongside NHibernate
|
||||
|
||||
## Database Conventions (MUST FOLLOW)
|
||||
- **PK**: `I3D` [int] IDENTITY(1,1) NOT NULL (auto-created by `ScriptHelpers.AddTableIfNotExists()`)
|
||||
- **FK**: End with `I3D` suffix (e.g., `AccountI3D`)
|
||||
- **Standard Columns**: CreatedByI3D, CreatedDate, ChangedByI3D, ChangedDate, IsDeleted, DeletedByI3D, DeletedDate (all REQUIRED)
|
||||
- **Types**: `nvarchar` (NOT varchar), `datetime2(2)`, `bit`, `decimal(18,2)` for currency
|
||||
- **Naming**: English PascalCase (new), Keep German (legacy), `dbo` schema
|
||||
### Connection Types
|
||||
Modules support different connection types declared in AppModuleController:
|
||||
- `CentronConnectionType.CentronWebServices` - Uses WSLogic implementation
|
||||
- `CentronConnectionType.SqlServer` - Uses BLLogic implementation
|
||||
|
||||
### Creating Database Scripts
|
||||
1. Reserve number in Teams: `c-entron Entwickler` → Files → `Datenbankupdate 2 1.xlsx`
|
||||
2. Create: `src/backend/Centron.BL/Administration/Scripts/ScriptMethods/Scripts/ScriptMethod{number}.cs`
|
||||
3. Implement `BaseScriptMethod` with `GetSqlQueries()`
|
||||
4. Use `ScriptHelpers.*` (AddTableIfNotExists, AddColumnIfNotExists, AddRightIfNotExists, etc.)
|
||||
5. **Convert to UTF-8 with BOM** (C# files require BOM)
|
||||
## Development Guidelines
|
||||
|
||||
## Localization (REQUIRED)
|
||||
- **Primary**: German (`LocalizedStrings.resx`) | **Secondary**: English (`LocalizedStrings.en.resx`)
|
||||
- **Code**: `LocalizedStrings.KeyName` | **XAML**: `{x:Static properties:LocalizedStrings.KeyName}`
|
||||
- **Key Format**: `{ClassName}_{Method}_{Description}`
|
||||
### Code Style and Standards
|
||||
- KISS
|
||||
- DRY
|
||||
- SOLID
|
||||
- Clean Architecture
|
||||
|
||||
## File Encoding (CRITICAL)
|
||||
- **UTF-8 WITH BOM**: `*.cs`, `*.xaml` (MANDATORY)
|
||||
- **UTF-8 NO BOM**: `*.md`, `*.json`, `*.xml`, `*.config`
|
||||
### General Rules
|
||||
- Write self-explanatory code and only comment when absolutely necessary
|
||||
- When updating code, always update DocStrings
|
||||
|
||||
**PowerShell Conversion**:
|
||||
```powershell
|
||||
$file = 'path\to\file.cs'
|
||||
$content = [System.IO.File]::ReadAllText($file)
|
||||
$utf8BOM = New-Object System.Text.UTF8Encoding($true)
|
||||
[System.IO.File]::WriteAllText($file, $content, $utf8BOM)
|
||||
```
|
||||
### Language Requirements
|
||||
- All user-facing content must be in German (primary market)
|
||||
- Support for English through localization files
|
||||
- Use German resource files (LocalizedStrings.resx) and English (LocalizedStrings.en.resx)
|
||||
|
||||
## NHibernate Performance
|
||||
- Use `.Fetch()` for eager loading (prevent N+1)
|
||||
- Always filter: `.Where(x => !x.IsDeleted)`
|
||||
- Use `Future()` for multiple collections
|
||||
- Avoid lazy loading in loops
|
||||
### File Encoding
|
||||
- All C# source files (*.cs) must use UTF-8 with BOM
|
||||
- All XAML files (*.xaml) must use UTF-8 with BOM
|
||||
|
||||
```csharp
|
||||
// Good
|
||||
var accounts = session.Query<Account>()
|
||||
.Where(x => !x.IsDeleted)
|
||||
.Fetch(x => x.AccountType)
|
||||
.Fetch(x => x.PriceList)
|
||||
.ToList();
|
||||
```
|
||||
### Naming Conventions
|
||||
- ILogic interfaces: `I{Module}Logic`
|
||||
- BL implementations: `BL{Module}Logic`
|
||||
- WS implementations: `WS{Module}Logic`
|
||||
- All methods return `Result<T>` or `Task<Result<T>>`
|
||||
|
||||
### Code Signing (Optional)
|
||||
Set environment variables for code signing:
|
||||
- `CENTRON_BUILD_CODE_SIGNING_CERTIFICATE` - Path to certificate
|
||||
- `CENTRON_BUILD_CODE_SIGNING_CERTIFICATE_PASSWORD` - Certificate password
|
||||
|
||||
## Database
|
||||
- Uses NHibernate ORM with SQL Server
|
||||
- Configuration files generated during build process
|
||||
- Test databases required for end-to-end testing
|
||||
|
||||
## Development Processes
|
||||
|
||||
### Database Schema Changes
|
||||
|
||||
#### Creating Database Scripts
|
||||
1. **Reserve script number** in Teams `c-entron Entwickler` group → Files → `Datenbankupdate 2 1.xlsx`
|
||||
2. **Create script class** at `src/backend/Centron.BL/Administration/Scripts/ScriptMethods/Scripts/ScriptMethod{number}.cs`
|
||||
3. **Implement BaseScriptMethod** with `ApplicationVersion` and `GetSqlQueries()` method
|
||||
4. **Use ScriptHelpers** when possible (preferred over raw SQL):
|
||||
- `ScriptHelpers.AddColumnIfNotExists()`
|
||||
- `ScriptHelpers.AddTableIfNotExists()`
|
||||
- `ScriptHelpers.AddRightIfNotExists()`
|
||||
- `ScriptHelpers.AddIndexIfNotExists()`
|
||||
- `ScriptHelpers.AddForeignKeyIfNotExists()`
|
||||
|
||||
#### Database Conventions
|
||||
- **Primary Key**: Every table must have `I3D` [int] IDENTITY(1,1) NOT NULL
|
||||
- **Foreign Keys**: Must end with `I3D` suffix (e.g., `AccountI3D`)
|
||||
- **Standard Columns**: Include `CreatedByI3D`, `CreatedDate`, `ChangedByI3D`, `ChangedDate`, `IsDeleted`, `DeletedByI3D`, `DeletedDate`
|
||||
- **Data Types**: Use `nvarchar` over `varchar`, `datetime2(2)` for timestamps, `bit` for booleans
|
||||
- **Naming**: New tables/columns use English names (historical German names remain unchanged)
|
||||
|
||||
### Settings Management
|
||||
- **Legacy**: `Stammdat` table (read-only)
|
||||
- **New**: `ApplicationSettings` table ONLY
|
||||
- Get next ID from `src/backend/Centron.Interfaces/Administration/Settings/ApplicationSettingID.cs`
|
||||
- Add description to `ApplicationSettingDefinitions.cs`
|
||||
|
||||
### User Rights
|
||||
1. Get next I3D from `UserRightsConst.cs`
|
||||
2. Create script: `ScriptHelpers.AddRightIfNotExists(id, parentId, "German name", "German desc")`
|
||||
3. Add constant to `UserRightsConst.cs`
|
||||
#### Application Settings
|
||||
- **Legacy settings**: Stored in `Stammdat` table (read-only, no new additions)
|
||||
- **New settings**: Use `ApplicationSettings` table exclusively
|
||||
- **Setting IDs**: Get next available ID from comment in `src/backend/Centron.Interfaces/Administration/Settings/ApplicationSettingID.cs`
|
||||
- **Descriptions**: Add to `ApplicationSettingDefinitions.cs`
|
||||
|
||||
### Web Service (Full Stack)
|
||||
1. **BL**: `{Entity}BL.cs` returning `Result<T>`
|
||||
2. **WebServiceBL**: `{Entity}WebServiceBL.cs` with DTO↔Entity conversion
|
||||
3. **RestService**: Add to `CentronRestService.cs` (`Request<T>` → `Response<T>`)
|
||||
4. **Interface**: `ICentronRestService.cs` with `[OperationContract]`, `[WebInvoke(Method="POST", UriTemplate="...")]`, `[Authenticate]`
|
||||
5. **Logic**: `I{Entity}Logic`, `BL{Entity}Logic`, `WS{Entity}Logic`
|
||||
#### Adding New Settings
|
||||
1. Check next available ID in `ApplicationSettingID.cs`
|
||||
2. Add enum value with new ID
|
||||
3. Update "Next Centron Settings ID" comment
|
||||
4. Add description in `ApplicationSettingDefinitions.cs`
|
||||
5. Create group setting classes for accessing settings
|
||||
6. Use `AppSettingsBL.GetSettings()` and `GetSettingsForUpdate()`
|
||||
|
||||
### WPF Module
|
||||
1. **Controller**: Implement `ICentronAppModuleController`
|
||||
2. **View**: `UserControl` inheriting `BaseModule`
|
||||
3. **ViewModel**: Inherit `BindableBase`
|
||||
4. **Ribbon**: Implement `IRibbonControlModule` variations
|
||||
5. **Registration**: Add to `ModuleRegistration.cs` with rights checks
|
||||
6. **Theme**: Prefer DevExpress controls over WPF standard
|
||||
### User Rights Management
|
||||
|
||||
## Agent Usage (MANDATORY)
|
||||
#### Adding New Rights
|
||||
1. **Open** `UserRightsConst.cs` to get next I3D
|
||||
2. **Create script** using `ScriptHelpers.AddRightIfNotExists()`:
|
||||
```csharp
|
||||
yield return ScriptHelpers.AddRightIfNotExists(
|
||||
UserRightsConst.Sales.Customer.Helpdesk.SHOW_HOURLYSURCHARGERATES,
|
||||
UserRightsConst.Sales.Customer.Helpdesk.ID,
|
||||
"German display name",
|
||||
"German description");
|
||||
```
|
||||
3. **Add constant** to `UserRightsConst.cs`
|
||||
|
||||
### Project Agents (.claude/agents/)
|
||||
- **primary-development**: ALL development tasks (orchestrator)
|
||||
- **database-script-creator**: Database schema changes → generates ScriptMethod*.cs
|
||||
- **webservice-developer**: Full-stack web service implementation
|
||||
- **ui-module-creator**: WPF modules with MVVM + DevExpress
|
||||
- **centron-nexus-developer**: Blazor Server, Razor components, SignalR, DevExpress Blazor
|
||||
- **external-api-integrator**: Third-party API integrations (FinAPI, GLS, Shipcloud, etc.)
|
||||
- **edi-specialist**: EDI processing (OpenTrans, EDIFACT, supplier integrations)
|
||||
- **nhibernate-query-reviewer**: Query optimization, N+1 detection
|
||||
- **localization-checker**: German/English verification
|
||||
- **bookkeeping-export-expert**: DATEV, Abacus, SAP exports
|
||||
- **test-engineer**: Test generation
|
||||
- **code-reviewer**: Code quality/security
|
||||
- **refactoring-specialist**: Code cleanup
|
||||
- **debugger**: Bug diagnosis
|
||||
- **architect**: System design
|
||||
- **documentation-writer**: Docs
|
||||
- **security-analyst**: Security reviews
|
||||
### Web Service Development
|
||||
|
||||
### MANDATORY Agent Usage
|
||||
- New features → **primary-development**
|
||||
- DB schema → **database-script-creator**
|
||||
- Web service → **webservice-developer**
|
||||
- WPF module → **ui-module-creator**
|
||||
- CentronNexus/Blazor → **centron-nexus-developer**
|
||||
- External API → **external-api-integrator**
|
||||
- EDI integration → **edi-specialist**
|
||||
- Complex queries → **nhibernate-query-reviewer**
|
||||
- UI text → **localization-checker**
|
||||
#### Creating Web Service Methods (Full Stack)
|
||||
1. **BL Layer**: Create method in `{Entity}BL.cs` returning `Result<T>`
|
||||
2. **WebServiceBL**: Create `{Entity}WebServiceBL.cs` with DTO↔Entity conversion
|
||||
3. **RestService**: Add method to `CentronRestService.cs` accepting `Request<T>` and returning `Response<T>`
|
||||
4. **Interface**: Add method signature to `ICentronRestService.cs` with attributes:
|
||||
```csharp
|
||||
[OperationContract]
|
||||
[WebInvoke(Method = "POST", UriTemplate = "MethodName")]
|
||||
[Authenticate]
|
||||
```
|
||||
5. **Logic Interfaces**: Create `I{Entity}Logic`, `BL{Entity}Logic`, `WS{Entity}Logic`
|
||||
|
||||
## Commands
|
||||
```bash
|
||||
dotnet build Centron.sln # Build
|
||||
dotnet test Centron.sln # Test all
|
||||
cd scripts/Centron.Scripts && dotnet run # Build orchestration
|
||||
#### Request Classes
|
||||
- Place in `Centron.WebServices.Core/RestRequests/`
|
||||
- Decorate with `[DataContract]` and `[DataMember]` attributes
|
||||
- Use for complex parameters instead of multiple individual parameters
|
||||
|
||||
### UI Development
|
||||
|
||||
#### Creating WPF Modules
|
||||
1. **AppModuleController**: Implement `ICentronAppModuleController`
|
||||
2. **View**: Create `UserControl` inheriting from `BaseModule`
|
||||
3. **ViewModel**: Inherit from `BindableBase`
|
||||
4. **Ribbon**: Implement `IRibbonControlModule` interface variations
|
||||
5. **Registration**: Add to `ModuleRegistration.cs` with rights and feature checks
|
||||
|
||||
#### Localization Requirements
|
||||
- **Resource Files**:
|
||||
- German (default): `LocalizedStrings.resx`
|
||||
- English: `LocalizedStrings.en.resx`
|
||||
- **XAML Usage**: `{x:Static properties:LocalizedStrings.KeyName}`
|
||||
- **Code Usage**: Direct access via `LocalizedStrings.KeyName`
|
||||
- **Key Format**: `{ClassName}_{MethodName}_{Description}`
|
||||
- **Tool**: Use ResXManager Visual Studio extension
|
||||
|
||||
### Accessing Data in Client Code
|
||||
|
||||
#### Single Use
|
||||
```csharp
|
||||
var result = await ClassContainer.Instance
|
||||
.WithInstance((IEntityLogic logic) => logic.GetEntity(id))
|
||||
.ThrowIfError();
|
||||
```
|
||||
|
||||
**Targets**: clean, setup-versioning, build-web-service, build-centron-net, run-tests, create-installers
|
||||
#### Multiple Uses (with proper disposal)
|
||||
```csharp
|
||||
public class ViewModel : IDisposable
|
||||
{
|
||||
private readonly IEntityLogic _logic;
|
||||
|
||||
## Slash Commands
|
||||
`/test`, `/review`, `/optimize`, `/implement`, `/explain`, `/analyze`, `/adr`, `/scaffold`
|
||||
public ViewModel()
|
||||
{
|
||||
_logic = ClassContainer.Instance.GetInstance<IEntityLogic>();
|
||||
}
|
||||
|
||||
## MCP Servers
|
||||
**serena**: Semantic search, symbol manipulation | **context7**: Library docs | **fetch**: Web content | **sequential-thinking**: Problem decomposition | **memory**: Knowledge graph | **playwright**: Browser automation | **windows-mcp**: Windows interaction
|
||||
|
||||
## Claude Instructions
|
||||
|
||||
### Tooling Decision (REQUIRED at task start)
|
||||
```
|
||||
🎯 Tooling Strategy Decision
|
||||
|
||||
Task Analysis: [Brief description]
|
||||
|
||||
Tooling Decisions:
|
||||
- Agents: [name] / Not using - Reason: [justification]
|
||||
- Slash Commands: [/command] / Not using - Reason: [justification]
|
||||
- MCP Servers: [server:tool] / Not using - Reason: [justification]
|
||||
- Approach: [strategy]
|
||||
public void Dispose()
|
||||
{
|
||||
ClassContainer.Instance.ReleaseInstance(_logic);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**When NOT to use agents**: Single file read, simple edit, 1-2 tool calls
|
||||
## Documentation
|
||||
|
||||
### Task Summary (REQUIRED at end)
|
||||
```
|
||||
📊 Task Completion Summary
|
||||
### Creating Documentation
|
||||
When adding new documentation to the project:
|
||||
|
||||
What Was Done: [description]
|
||||
1. **Choose the right location** within the existing `docs/` structure:
|
||||
- `docs/getting-started/` - Beginner guides and introductory material
|
||||
- `docs/guides/development/` - Development task guides
|
||||
- `docs/guides/database/` - Database-related guides
|
||||
- `docs/guides/ui/` - UI development guides
|
||||
- `docs/guides/services/` - Web services guides
|
||||
- `docs/reference/architecture/` - Architecture specifications
|
||||
- `docs/reference/database/` - Database reference documentation
|
||||
- `docs/reference/receipts/` - Receipts system documentation
|
||||
- `docs/reference/security/` - Security documentation
|
||||
- `docs/operations/` - Operational procedures
|
||||
|
||||
Features Involved:
|
||||
- Agents: [list or None - justification]
|
||||
- Slash Commands: [list or None - justification]
|
||||
- MCP Servers: [list or None - justification]
|
||||
- Core Tools: [Read, Write, Edit, Glob, Grep, Bash, etc.]
|
||||
- Files Modified: [list or None]
|
||||
- Performance: [Parallel ops, extended thinking, or N/A]
|
||||
2. **Name the file appropriately** using kebab-case (e.g., `actionprice-system.md`)
|
||||
|
||||
Efficiency Notes: [observations]
|
||||
```
|
||||
3. **Create the file** with UTF-8 with BOM encoding, using proper Markdown format
|
||||
|
||||
### Checklist
|
||||
✅ Provide tooling decisions at task start
|
||||
✅ Use `Result<T>` pattern
|
||||
✅ Follow ILogic interface pattern
|
||||
✅ German localization for UI text
|
||||
✅ UTF-8 with BOM for C#/XAML
|
||||
✅ DB conventions (I3D, FK, tracking columns)
|
||||
✅ Run tests before commits
|
||||
✅ Reference ticket numbers
|
||||
✅ Use parallel tool calls
|
||||
✅ Leverage agents/slash commands/MCP servers
|
||||
4. **Update navigation** in `docs/README.md`:
|
||||
- Add a new entry with a link to your documentation file
|
||||
- Follow the existing pattern and place in appropriate section
|
||||
|
||||
## Common Tasks
|
||||
1. **DB Table**: database-script-creator → ScriptMethod*.cs with conventions
|
||||
2. **Web Service**: webservice-developer → BL → WebServiceBL → REST → Logic
|
||||
3. **WPF Module**: ui-module-creator → View, ViewModel, Controller, Ribbon, Localization
|
||||
4. **Query Optimization**: nhibernate-query-reviewer → N+1, indexes, soft delete
|
||||
5. **Update the Solution File** (`Centron.sln`):
|
||||
- Find the appropriate solution folder for your documentation directory
|
||||
- Add your file to the `ProjectSection(SolutionItems)` section
|
||||
- Use the pattern: `docs\path\to\your-file.md = docs\path\to\your-file.md`
|
||||
|
||||
## Critical Files
|
||||
- `src/centron/Centron.WPF.UI/App.xaml.cs` - WPF entry
|
||||
- `src/backend/Centron.BL/` - Business logic
|
||||
- `src/backend/Centron.DAO/` - Data access
|
||||
- `src/webservice/Centron.WebServices.Core/RestService/CentronRestService.cs` - REST API
|
||||
- `src/backend/Centron.Interfaces/` - Service interfaces
|
||||
|
||||
## Git
|
||||
**Branch**: `master` (main) | **Types**: `feature/*`, `bugfix/*`, `hotfix/*`
|
||||
**Commits**: `feat(module):`, `fix(module):`, `refactor(module):`, `docs:` + optional `(Ticket #12345)`
|
||||
### Documentation Standards
|
||||
- Use UTF-8 with BOM encoding for all documentation files
|
||||
- Start with a `#` heading that clearly describes the content
|
||||
- Use proper Markdown formatting for headings, lists, code blocks, etc.
|
||||
- Include links to related documentation when appropriate
|
||||
- For internal links, use relative paths to other documentation files
|
||||
|
||||
## Important Notes
|
||||
- Project uses custom versioning via Nerdbank.GitVersioning
|
||||
- Build artifacts placed in `/artifacts` directory
|
||||
- Integration with Azure DevOps for CI/CD
|
||||
- Automatic ticket integration with c-entron ticket system
|
||||
- Supports both standalone and web service deployment modes
|
||||
- Always test database scripts before committing
|
||||
- Use German for all user-facing text with English translations
|
||||
- Follow dual implementation pattern (BL + WS) for all data access
|
||||
- When creating a script, do not override ApplicationVersion, MethodKind, or ScriptCollection. These are legacy properties.
|
||||
- When creating a linq query for database access, beware of the limitations and capabilities of NHibernate (it is our OR-Mapper).
|
||||
@@ -1,45 +1,60 @@
|
||||
# Versuch 02 - Kurzuebersicht
|
||||
|
||||
## Inhalt
|
||||
Fokus auf Use-Case- und Modulanalyse (ERP-Dokumentation), inkl. Gap-Analyse zwischen dokumentierter und tatsaechlich entdeckter Funktionalitaet. Der Versuch liefert vor allem Umfangs-, Coverage- und Discovery-Kennzahlen statt klassischer StRS/SyRS/SwRS-Requirements.
|
||||
Fokus auf konsolidierte End-to-End-Requirements-Spezifikation (StRS, SyRS, SwRS) mit hoher ISO-29148-Reife, Qualitaetsmetriken und separaten Traceability-Artefakten (CSV). Gegenueber Versuch 01 ist die Struktur noch staerker in Teilartefakte fuer Stakeholder/System/Software zerlegt.
|
||||
|
||||
## Kennzahlen (einheitliches Vergleichsformat)
|
||||
| Kennzahl | Wert |
|
||||
| --- | --- |
|
||||
| Ergebnisdateien gesamt | 30 |
|
||||
| Ergebnisdateitypen (MD/PDF/CSV/SQL/YAML/JSON/TXT) | 24 / 4 / 0 / 2 / 0 / 0 / 0 |
|
||||
| Markdown-Zeilen gesamt | 21.882 |
|
||||
| Anforderungen/Features gesamt (konsolidiert) | 1.720 (siehe `Requirements.md`) |
|
||||
| Formale Anforderungen gesamt (StRS+SyRS+SwRS) | 0 |
|
||||
| Stakeholder-Anforderungen (StRS) | 0 |
|
||||
| System-Anforderungen (SyRS) | 0 |
|
||||
| Software-Anforderungen (SwRS) | 0 |
|
||||
| Use Cases gesamt (explizit) | 1.720 |
|
||||
| Dokumentierte Use Cases | 509 |
|
||||
| Undokumentierte Use Cases | 1.211 (71% Gap) |
|
||||
| Ueberlappung Use Cases <-> Anforderungen (abgezogen) | 0 (bereits dedupliziert) |
|
||||
| ISO-29148-Compliance | n.v. |
|
||||
| Traceability-Abdeckung | n.v. (kein StRS->SyRS->SwRS-Nachweis) |
|
||||
| Code Coverage | n.v. |
|
||||
| Test Coverage | n.v. |
|
||||
| Analysierte Quellartefakte | 150.000+ LoC analysiert; 3.412 potenzielle Use Cases |
|
||||
| Separate Traceability-CSV (Dateien / Zeilen) | 0 / 0 |
|
||||
|
||||
## Evaluation-Hinweis
|
||||
Sehr stark fuer Funktions-/Use-Case-Discovery und Doku-Gap-Analyse; konsolidierte Zaehlung erfolgt in `Requirements.md`.
|
||||
| Ergebnisdateien gesamt | 37 |
|
||||
| Ergebnisdateitypen (MD/PDF/CSV/SQL/YAML/JSON/TXT) | 26 / 1 / 5 / 0 / 1 / 3 / 1 |
|
||||
| Markdown-Zeilen gesamt | 15.625 |
|
||||
| Anforderungen/Features gesamt (konsolidiert) | 220 (siehe `Requirements.md`) |
|
||||
| Formale Anforderungen gesamt (StRS+SyRS+SwRS) | 220 |
|
||||
| Stakeholder-Anforderungen (StRS) | 84 |
|
||||
| System-Anforderungen (SyRS) | 53 |
|
||||
| Software-Anforderungen (SwRS) | 83 |
|
||||
| Use Cases gesamt (explizit) | 46 |
|
||||
| Dokumentierte Use Cases | 46 |
|
||||
| Undokumentierte Use Cases | n.v. |
|
||||
| Ueberlappung Use Cases <-> Anforderungen (abgezogen) | 46 (konservativ) |
|
||||
| ISO-29148-Compliance | 96,1% (100% mandatory) |
|
||||
| Traceability-Abdeckung | 100% bidirektional |
|
||||
| Code Coverage | 87,3% (laut Doku) |
|
||||
| Test Coverage | 87,3% (laut Doku) |
|
||||
| Analysierte Quellartefakte | 14.940 Dateien (13.717 C#, 1.189 XAML, 34 Projekte) |
|
||||
| Separate Traceability-CSV (Dateien / Zeilen) | 4 / 327 |
|
||||
|
||||
## Vorgehen
|
||||
- Erweiterter Prompt zu Claude Code
|
||||
- Verwendung spezialisierter generischer Agenten für Claude Code.
|
||||
- Verwendung von MCP Servern zur Verbesserung der LLM Performance
|
||||
- Serena MCP zum Speichern von Memories
|
||||
- Windows-MCP (Basierend auf AutoiT) um Auch das laufende Frontend mit in die Analyse Einzubeziehen
|
||||
- MSSQL MCP mit Anbindung an die Datenbank um auch das DB Schema mit in die Analyse einzubinden
|
||||
|
||||
- Erweiterter Prompt zu Claude Code
|
||||
- Verwendung spezialisierter ISO-29148-Agents
|
||||
- Kein MCP-Fokus (ISO-Konsolidierung vor Discovery-Erweiterung)
|
||||
|
||||
## Prompt
|
||||
"Please analyze this software project and write a reuqirements specification according to modern standards.
|
||||
Use Agents and MCP servers wherever possible.
|
||||
Keep superflous texts to a minimum and concentrate on actual requirements.
|
||||
"
|
||||
## Verwendeter Prompt
|
||||
```text
|
||||
Please analyze this software project and write a ISO 29148 compliant reuqirements specification.
|
||||
Use Agents wherever possible.
|
||||
```
|
||||
|
||||
## Agenten (Beispiele)
|
||||
- `Tools/agents/iso29148-master-orchestrator-agent.md`
|
||||
- Orchestrierung der Meilensteine und Integration der Teilartefakte
|
||||
- `Tools/agents/iso29148-system-requirements-agent.md`
|
||||
- Systemanforderungen (SyRS), Architektur- und Schnittstellenfokus
|
||||
- `Tools/agents/iso29148-stakeholder-agent.md`
|
||||
- Stakeholder-Anforderungen (StRS) und fachliche Perspektive
|
||||
- `Tools/agents/iso29148-software-requirements-agent`
|
||||
- Softwareanforderungen (SwRS) und Umsetzungsbezug
|
||||
|
||||
## Ergebnisbeispiele aus `Ergenisse`
|
||||
- `Ergenisse/master/ISO29148_Executive_Summary.md`
|
||||
- 14.940 analysierte Dateien und 220+ Requirements (Executive-Ebene)
|
||||
- `Ergenisse/master/ISO29148_Quality_Report.md`
|
||||
- Gesamtscore 92,4%, Traceability 100%, ISO-29148 konforme Qualitaetsbewertung
|
||||
- `Ergenisse/master/ISO29148_Traceability_Master.csv`
|
||||
- Konsolidierte Nachverfolgbarkeit zwischen Requirement-Ebenen
|
||||
- `Ergenisse/stakeholder/StRS_Complete.md`, `Ergenisse/system/SyRS_Complete.md`, `Ergenisse/software/SwRS_Complete.md`
|
||||
- Vollstaendige Dreiebenen-Spezifikation
|
||||
|
||||
## Evaluation-Hinweis
|
||||
Sehr gut geeignet fuer vergleichende ISO-29148-Evaluation mit quantifizierter Qualitaets- und Traceability-Sicht; konsolidierte Zaehlung erfolgt in `Requirements.md`.
|
||||
|
||||
@@ -1,23 +1,20 @@
|
||||
# Versuch 03 - Requirements (konsolidiert)
|
||||
|
||||
## Konsolidierungsentscheidung
|
||||
Use Cases und Anforderungen werden als gleiches Zielobjekt betrachtet. In Versuch 03 sind Use Cases in den Stakeholder-Diagrammen dokumentiert, aber inhaltlich mit den formalen Anforderungen verknuepft (Traceability auf StR-IDs). Daher erfolgt eine deduplizierte Konsolidierung.
|
||||
Use Cases und Anforderungen werden als gleiches Zielobjekt betrachtet. In Versuch 03 liegen die Features/Faehigkeiten ueberwiegend als Use Cases vor (keine vollstaendige StRS/SyRS/SwRS-Gliederung).
|
||||
|
||||
## Cluster-Liste
|
||||
| Cluster | Anzahl |
|
||||
| --- | ---: |
|
||||
| Stakeholder-Anforderungen (StRS) | 84 |
|
||||
| System-Anforderungen (SyRS) | 53 |
|
||||
| Software-Anforderungen (SwRS) | 83 |
|
||||
| Explizite Use Cases (Diagramme) | 46 |
|
||||
| Ueberlappung Use Cases <-> Anforderungen (konservativ abgezogen) | 46 |
|
||||
| Formale Anforderungen (StRS+SyRS+SwRS) | 0 |
|
||||
| Dokumentierte Use Cases | 509 |
|
||||
| Neu entdeckte (vormals undokumentierte) Use Cases | 1211 |
|
||||
| Ueberlappung Use Cases <-> Anforderungen (abgezogen) | 0 |
|
||||
|
||||
## Summen
|
||||
- Rohsumme (`Requirements + Use Cases`): **266**
|
||||
- **Konsolidierte Requirements/Faehigkeiten gesamt: 220**
|
||||
- Rohsumme (`Requirements + Use Cases`): **1720**
|
||||
- **Konsolidierte Requirements/Faehigkeiten gesamt: 1720**
|
||||
|
||||
## Use-Case-Cluster (Nachweis)
|
||||
- Sales Management: 13
|
||||
- Helpdesk Management: 17
|
||||
- Financial Management: 16
|
||||
- Summe explizite Use Cases: 46
|
||||
## Hinweis
|
||||
- Die Zahl `1720` ist bereits dedupliziert als "Total System Functionality".
|
||||
- Potenzialmetriken pro Extraktionsmethode wurden nicht addiert, um Doppelzaehlungen zu vermeiden.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# AGENTS.md
|
||||
# AGENTS.md
|
||||
|
||||
This file provides guidance to Codex when working with code in this repository.
|
||||
|
||||
@@ -31,6 +31,14 @@ Available targets:
|
||||
- `run-tests` - Execute all test suites
|
||||
- `create-installers` - Build MSI installers
|
||||
|
||||
## Agent Notes
|
||||
|
||||
- Default shell is PowerShell (`pwsh`). Prefer PowerShell-native commands like `Get-Content`, `Set-Content -Encoding UTF8`, and here-strings (`@'...'@`) instead of Unix tools (`sed`, `nl`, etc.).
|
||||
- Use `rg`/`rg --files` for fast searches—they are available by default.
|
||||
- Repository expects UTF-8 with BOM for C# and XAML; `Set-Content -Encoding UTF8` satisfies this.
|
||||
- Long replacements can rely on PowerShell string operations or single-line `python -c` scripts (heredocs are unavailable in `pwsh`).
|
||||
- `dotnet build Centron.sln` may warn about `libfintx.FinTSConfig`; this is expected and can be ignored for success checks.
|
||||
|
||||
### Publishing
|
||||
- **Publish WPF UI**: `dotnet publish src/centron/Centron.WPF.UI/Centron.WPF.UI.csproj -c Release -r win-x64 --self-contained`
|
||||
- **Publish Web Service**: `dotnet publish src/webservice/Centron.Host.WindowsService/Centron.Host.WindowsService.csproj -c Release -r win-x64 --self-contained`
|
||||
@@ -284,4 +292,4 @@ When adding new documentation to the project:
|
||||
- Supports both standalone and web service deployment modes
|
||||
- Always test database scripts before committing
|
||||
- Use German for all user-facing text with English translations
|
||||
- Follow dual implementation pattern (BL + WS) for all data access
|
||||
- Follow dual implementation pattern (BL + WS) for all data access
|
||||
|
||||
@@ -1,316 +1,248 @@
|
||||
# CLAUDE.md
|
||||
# c-entron.NET
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
> ⚠️ **FOR CLAUDE AI - NOT FOR DEVELOPERS**
|
||||
>
|
||||
> This file contains project conventions and patterns that Claude AI uses to generate correct code.
|
||||
> **Developers**: See [.claude/README.md](.claude/README.md) for user documentation.
|
||||
|
||||
## Development Commands
|
||||
> **v2.1.0** | 2025-01-20 | ERP for German SMBs | C# .NET 8 | WPF + REST API
|
||||
|
||||
### Building
|
||||
- **Build entire solution**: `dotnet build Centron.sln`
|
||||
- **Build specific project**: `dotnet build src/centron/Centron.WPF.UI/Centron.WPF.UI.csproj`
|
||||
- **Build for Release**: `dotnet build Centron.sln -c Release`
|
||||
|
||||
### Testing
|
||||
- **Run all tests**: `dotnet test Centron.sln`
|
||||
- **Run specific test project**: `dotnet test tests/backend/Centron.Tests.BL/Centron.Tests.BL.csproj`
|
||||
- **Run integration tests**: `dotnet test tests/Centron.Tests.Integration/Centron.Tests.Integration.csproj`
|
||||
- **Run end-to-end tests**: `dotnet test tests/Centron.Tests.EndToEnd/Centron.Tests.EndToEnd.csproj`
|
||||
|
||||
### Using Centron.Scripts Build System
|
||||
The project uses a custom build system via Centron.Scripts for complete builds:
|
||||
|
||||
```bash
|
||||
cd scripts/Centron.Scripts
|
||||
dotnet run -- <target>
|
||||
```
|
||||
|
||||
Available targets:
|
||||
- `clean` - Clean artifacts and bin/obj directories
|
||||
- `setup-versioning` - Set up version information
|
||||
- `build-web-service` - Build the web service components
|
||||
- `build-centron-net` - Build the WPF client application
|
||||
- `run-tests` - Execute all test suites
|
||||
- `create-installers` - Build MSI installers
|
||||
|
||||
### Publishing
|
||||
- **Publish WPF UI**: `dotnet publish src/centron/Centron.WPF.UI/Centron.WPF.UI.csproj -c Release -r win-x64 --self-contained`
|
||||
- **Publish Web Service**: `dotnet publish src/webservice/Centron.Host.WindowsService/Centron.Host.WindowsService.csproj -c Release -r win-x64 --self-contained`
|
||||
|
||||
## Project Architecture
|
||||
|
||||
### High-Level Structure
|
||||
This is a .NET 8 enterprise application with a multi-layered architecture:
|
||||
## Stack
|
||||
**Core**: C# 12, .NET 8 | **Frontend**: WPF + Blazor Server, DevExpress 24.2.7 (WPF & Blazor), MVVM | **Backend**: ASP.NET Core 8, SQL Server 2019+, NHibernate 5.x, JWT auth | **Real-Time**: SignalR | **Build**: Azure DevOps, Centron.Scripts, WiX MSI | **Test**: NUnit
|
||||
|
||||
## Structure
|
||||
```
|
||||
src/
|
||||
├── apis/ - External API integrations (FinAPI, GLS, Shipcloud, etc.)
|
||||
├── backend/ - Core business logic layer
|
||||
│ ├── Centron.BL/ - Business Logic layer
|
||||
│ ├── Centron.Common/ - Common utilities and helpers
|
||||
│ ├── Centron.DAO/ - Data Access Objects (NHibernate)
|
||||
│ ├── Centron.Entities/ - Domain entities
|
||||
│ ├── Centron.Gateway/ - External service gateways
|
||||
│ └── Centron.Interfaces/ - Service interfaces
|
||||
├── centron/ - WPF client application
|
||||
│ ├── Centron.WPF.UI/ - Main WPF application
|
||||
│ └── Centron.WPF.UI.Extension/ - UI extensions
|
||||
├── shared/ - Shared components and controls
|
||||
│ ├── Centron.Core/ - Core shared functionality
|
||||
│ ├── Centron.Controls/ - Custom UI controls
|
||||
│ └── Centron.Controls.Preview/ - Preview controls
|
||||
└── webservice/ - Web service components
|
||||
├── Centron.Host/ - Web service host
|
||||
├── Centron.Host.Console/ - Console host
|
||||
├── Centron.Host.WindowsService/ - Windows service host
|
||||
├── Centron.WebServices.Core/ - Web service core
|
||||
└── c-entron.misc.ConnectionManager/ - Connection management
|
||||
├── apis/ - External integrations (FinAPI, GLS, Shipcloud, ITscope, etc.)
|
||||
├── backend/ - BL, DAO, Entities, Interfaces, EDI
|
||||
├── centron/ - WPF UI (Desktop)
|
||||
├── CentronNexus/ - Blazor Server (Web Portal)
|
||||
├── shared/ - Core, Controls
|
||||
└── webservice/ - REST API, Hosts
|
||||
tests/ - BL, DAO, Integration, E2E
|
||||
.claude/ - agents/, commands/, hooks/, settings.json
|
||||
```
|
||||
|
||||
### Data Access Pattern
|
||||
The application uses a dual data access pattern supporting both direct database access and web service communication:
|
||||
**Key Files**: `src/centron/Centron.WPF.UI/App.xaml.cs` (WPF), `src/webservice/Centron.Host.WindowsService/Program.cs` (Service), `Centron.sln`, `version.json`
|
||||
|
||||
#### WPF UI Architecture (3-layer pattern | ILogic Interface Pattern)
|
||||
All data operations in the UI must use the ILogic interface accessed through ClassContainer:
|
||||
- WPF UI modules use a 3-part data access pattern:
|
||||
- I{Module}Logic interface - Defines the contract
|
||||
- BL{Module}Logic (NHibernate/SQL Server) - Direct database access via NHibernate
|
||||
- WS{Module}Logic (REST API) - Web service access via REST API
|
||||
- Access via ClassContainer.Instance.WithInstance((ILogic logic) => ...).ThrowIfError();
|
||||
- Connection types controlled by AppModuleController:
|
||||
- CentronConnectionType.CentronWebServices ➜ WSLogic
|
||||
- CentronConnectionType.SqlServer ➜ BLLogic
|
||||
## Naming
|
||||
- **C# Classes**: `PascalCase`, Interfaces: `IPascalCase`, Methods: `PascalCase`, Private: `_camelCase`, Local: `camelCase`
|
||||
- **DB Tables**: `PascalCase` English (new), Keep German (legacy), PK: `I3D` (int IDENTITY), FK: `{Table}I3D`
|
||||
- **Standard Columns**: `CreatedByI3D`, `CreatedDate`, `ChangedByI3D`, `ChangedDate`, `IsDeleted`, `DeletedByI3D`, `DeletedDate`
|
||||
- **BL Pattern**: `I{Module}Logic`, `BL{Module}Logic`, `WS{Module}Logic`, `{Entity}BL`, `{Entity}WebServiceBL`
|
||||
|
||||
## Critical Patterns
|
||||
|
||||
### Result Pattern (MANDATORY)
|
||||
```csharp
|
||||
var result = await ClassContainer
|
||||
.Instance
|
||||
.WithInstance((IAccountContractsLogic logic) => logic.GetAccountContracts(filter))
|
||||
.ThrowIfError();
|
||||
```
|
||||
|
||||
#### Backend Architecture (2-layer pattern)
|
||||
- Backend uses a 2-layer BL approach for web service implementation:
|
||||
- Base BL class (e.g., AccountDeviceBL) - contains core business logic and database access via DAO
|
||||
- WebService BL class (e.g., AccountDeviceWebServiceBL) - handles DTO conversion and calls base BL
|
||||
- WebService BL pattern:
|
||||
- Inherits from BaseBL and creates instance of corresponding base BL class
|
||||
- Converts DTOs to entities using conversion methods (ConvertAccountDeviceDTOToAccountDevice)
|
||||
- Uses ObjectMapper for entity-to-DTO conversion
|
||||
- Ensures DTO entities are not connected to NHibernate database context for API security
|
||||
- API implementation in ICentronRestService and CentronRestService:
|
||||
- API methods call WebService BL classes
|
||||
- All API operations use DTO entities for data transfer
|
||||
- Example: SaveAccountDevice API method → AccountDeviceWebServiceBL.SaveAccountDevice → AccountDeviceBL.SaveAccountDevice
|
||||
|
||||
### Technology Stack
|
||||
- **.NET 8** - Primary framework
|
||||
- **WPF** - Desktop UI framework
|
||||
- **NHibernate** with **FluentNHibernate** - ORM for database access
|
||||
- **DevExpress 24.2.7** - UI controls and components
|
||||
- **Bullseye** - Build orchestration
|
||||
- **Entity Framework** - Some components use EF alongside NHibernate
|
||||
|
||||
### Connection Types
|
||||
Modules support different connection types declared in AppModuleController:
|
||||
- `CentronConnectionType.CentronWebServices` - Uses WSLogic implementation
|
||||
- `CentronConnectionType.SqlServer` - Uses BLLogic implementation
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Code Style and Standards
|
||||
- KISS
|
||||
- DRY
|
||||
- SOLID
|
||||
- Clean Architecture
|
||||
|
||||
### General Rules
|
||||
- Write self-explanatory code and only comment when absolutely necessary
|
||||
- When updating code, always update DocStrings
|
||||
|
||||
### Language Requirements
|
||||
- All user-facing content must be in German (primary market)
|
||||
- Support for English through localization files
|
||||
- Use German resource files (LocalizedStrings.resx) and English (LocalizedStrings.en.resx)
|
||||
|
||||
### File Encoding
|
||||
- All C# source files (*.cs) must use UTF-8 with BOM
|
||||
- All XAML files (*.xaml) must use UTF-8 with BOM
|
||||
|
||||
### Naming Conventions
|
||||
- ILogic interfaces: `I{Module}Logic`
|
||||
- BL implementations: `BL{Module}Logic`
|
||||
- WS implementations: `WS{Module}Logic`
|
||||
- All methods return `Result<T>` or `Task<Result<T>>`
|
||||
|
||||
### Code Signing (Optional)
|
||||
Set environment variables for code signing:
|
||||
- `CENTRON_BUILD_CODE_SIGNING_CERTIFICATE` - Path to certificate
|
||||
- `CENTRON_BUILD_CODE_SIGNING_CERTIFICATE_PASSWORD` - Certificate password
|
||||
|
||||
## Database
|
||||
- Uses NHibernate ORM with SQL Server
|
||||
- Configuration files generated during build process
|
||||
- Test databases required for end-to-end testing
|
||||
|
||||
## Development Processes
|
||||
|
||||
### Database Schema Changes
|
||||
|
||||
#### Creating Database Scripts
|
||||
1. **Reserve script number** in Teams `c-entron Entwickler` group → Files → `Datenbankupdate 2 1.xlsx`
|
||||
2. **Create script class** at `src/backend/Centron.BL/Administration/Scripts/ScriptMethods/Scripts/ScriptMethod{number}.cs`
|
||||
3. **Implement BaseScriptMethod** with `ApplicationVersion` and `GetSqlQueries()` method
|
||||
4. **Use ScriptHelpers** when possible (preferred over raw SQL):
|
||||
- `ScriptHelpers.AddColumnIfNotExists()`
|
||||
- `ScriptHelpers.AddTableIfNotExists()`
|
||||
- `ScriptHelpers.AddRightIfNotExists()`
|
||||
- `ScriptHelpers.AddIndexIfNotExists()`
|
||||
- `ScriptHelpers.AddForeignKeyIfNotExists()`
|
||||
|
||||
#### Database Conventions
|
||||
- **Primary Key**: Every table must have `I3D` [int] IDENTITY(1,1) NOT NULL
|
||||
- **Foreign Keys**: Must end with `I3D` suffix (e.g., `AccountI3D`)
|
||||
- **Standard Columns**: Include `CreatedByI3D`, `CreatedDate`, `ChangedByI3D`, `ChangedDate`, `IsDeleted`, `DeletedByI3D`, `DeletedDate`
|
||||
- **Data Types**: Use `nvarchar` over `varchar`, `datetime2(2)` for timestamps, `bit` for booleans
|
||||
- **Naming**: New tables/columns use English names (historical German names remain unchanged)
|
||||
|
||||
### Settings Management
|
||||
|
||||
#### Application Settings
|
||||
- **Legacy settings**: Stored in `Stammdat` table (read-only, no new additions)
|
||||
- **New settings**: Use `ApplicationSettings` table exclusively
|
||||
- **Setting IDs**: Get next available ID from comment in `src/backend/Centron.Interfaces/Administration/Settings/ApplicationSettingID.cs`
|
||||
- **Descriptions**: Add to `ApplicationSettingDefinitions.cs`
|
||||
|
||||
#### Adding New Settings
|
||||
1. Check next available ID in `ApplicationSettingID.cs`
|
||||
2. Add enum value with new ID
|
||||
3. Update "Next Centron Settings ID" comment
|
||||
4. Add description in `ApplicationSettingDefinitions.cs`
|
||||
5. Create group setting classes for accessing settings
|
||||
6. Use `AppSettingsBL.GetSettings()` and `GetSettingsForUpdate()`
|
||||
|
||||
### User Rights Management
|
||||
|
||||
#### Adding New Rights
|
||||
1. **Open** `UserRightsConst.cs` to get next I3D
|
||||
2. **Create script** using `ScriptHelpers.AddRightIfNotExists()`:
|
||||
```csharp
|
||||
yield return ScriptHelpers.AddRightIfNotExists(
|
||||
UserRightsConst.Sales.Customer.Helpdesk.SHOW_HOURLYSURCHARGERATES,
|
||||
UserRightsConst.Sales.Customer.Helpdesk.ID,
|
||||
"German display name",
|
||||
"German description");
|
||||
```
|
||||
3. **Add constant** to `UserRightsConst.cs`
|
||||
|
||||
### Web Service Development
|
||||
|
||||
#### Creating Web Service Methods (Full Stack)
|
||||
1. **BL Layer**: Create method in `{Entity}BL.cs` returning `Result<T>`
|
||||
2. **WebServiceBL**: Create `{Entity}WebServiceBL.cs` with DTO↔Entity conversion
|
||||
3. **RestService**: Add method to `CentronRestService.cs` accepting `Request<T>` and returning `Response<T>`
|
||||
4. **Interface**: Add method signature to `ICentronRestService.cs` with attributes:
|
||||
```csharp
|
||||
[OperationContract]
|
||||
[WebInvoke(Method = "POST", UriTemplate = "MethodName")]
|
||||
[Authenticate]
|
||||
```
|
||||
5. **Logic Interfaces**: Create `I{Entity}Logic`, `BL{Entity}Logic`, `WS{Entity}Logic`
|
||||
|
||||
#### Request Classes
|
||||
- Place in `Centron.WebServices.Core/RestRequests/`
|
||||
- Decorate with `[DataContract]` and `[DataMember]` attributes
|
||||
- Use for complex parameters instead of multiple individual parameters
|
||||
|
||||
### UI Development
|
||||
|
||||
#### Creating WPF Modules
|
||||
1. **AppModuleController**: Implement `ICentronAppModuleController`
|
||||
2. **View**: Create `UserControl` inheriting from `BaseModule`
|
||||
3. **ViewModel**: Inherit from `BindableBase`
|
||||
4. **Ribbon**: Implement `IRibbonControlModule` interface variations
|
||||
5. **Registration**: Add to `ModuleRegistration.cs` with rights and feature checks
|
||||
|
||||
#### Localization Requirements
|
||||
- **Resource Files**:
|
||||
- German (default): `LocalizedStrings.resx`
|
||||
- English: `LocalizedStrings.en.resx`
|
||||
- **XAML Usage**: `{x:Static properties:LocalizedStrings.KeyName}`
|
||||
- **Code Usage**: Direct access via `LocalizedStrings.KeyName`
|
||||
- **Key Format**: `{ClassName}_{MethodName}_{Description}`
|
||||
- **Tool**: Use ResXManager Visual Studio extension
|
||||
|
||||
### Accessing Data in Client Code
|
||||
|
||||
#### Single Use
|
||||
```csharp
|
||||
var result = await ClassContainer.Instance
|
||||
.WithInstance((IEntityLogic logic) => logic.GetEntity(id))
|
||||
.ThrowIfError();
|
||||
```
|
||||
|
||||
#### Multiple Uses (with proper disposal)
|
||||
```csharp
|
||||
public class ViewModel : IDisposable
|
||||
{
|
||||
private readonly IEntityLogic _logic;
|
||||
|
||||
public ViewModel()
|
||||
{
|
||||
_logic = ClassContainer.Instance.GetInstance<IEntityLogic>();
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
ClassContainer.Instance.ReleaseInstance(_logic);
|
||||
}
|
||||
public Result<T> Method() {
|
||||
try {
|
||||
var data = _dao.Get<T>(id);
|
||||
return data == null ? Result.Error<T>("Not found") : Result.Success(data);
|
||||
} catch (Exception ex) { return Result.Error<T>(ex); }
|
||||
}
|
||||
```
|
||||
|
||||
## Documentation
|
||||
### UI Data Access (MANDATORY)
|
||||
```csharp
|
||||
// Single use
|
||||
var result = await ClassContainer.Instance
|
||||
.WithInstance((IEntityLogic logic) => logic.GetEntity(id))
|
||||
.ThrowIfError();
|
||||
|
||||
### Creating Documentation
|
||||
When adding new documentation to the project:
|
||||
// Multiple uses (IDisposable)
|
||||
private readonly IEntityLogic _logic;
|
||||
public ViewModel() { _logic = ClassContainer.Instance.GetInstance<IEntityLogic>(); }
|
||||
public void Dispose() { ClassContainer.Instance.ReleaseInstance(_logic); }
|
||||
```
|
||||
|
||||
1. **Choose the right location** within the existing `docs/` structure:
|
||||
- `docs/getting-started/` - Beginner guides and introductory material
|
||||
- `docs/guides/development/` - Development task guides
|
||||
- `docs/guides/database/` - Database-related guides
|
||||
- `docs/guides/ui/` - UI development guides
|
||||
- `docs/guides/services/` - Web services guides
|
||||
- `docs/reference/architecture/` - Architecture specifications
|
||||
- `docs/reference/database/` - Database reference documentation
|
||||
- `docs/reference/receipts/` - Receipts system documentation
|
||||
- `docs/reference/security/` - Security documentation
|
||||
- `docs/operations/` - Operational procedures
|
||||
### Architecture
|
||||
**WPF UI** → `I{Module}Logic` (ClassContainer) → `BL{Module}Logic` (SQL) OR `WS{Module}Logic` (REST)
|
||||
**REST API** → `CentronRestService` → `{Entity}WebServiceBL` (DTO conversion) → `{Entity}BL` (Business Logic) → DAO → NHibernate → SQL Server
|
||||
|
||||
2. **Name the file appropriately** using kebab-case (e.g., `actionprice-system.md`)
|
||||
Connection types: `CentronConnectionType.SqlServer` (BLLogic) | `CentronConnectionType.CentronWebServices` (WSLogic)
|
||||
|
||||
3. **Create the file** with UTF-8 with BOM encoding, using proper Markdown format
|
||||
## Database Conventions (MUST FOLLOW)
|
||||
- **PK**: `I3D` [int] IDENTITY(1,1) NOT NULL (auto-created by `ScriptHelpers.AddTableIfNotExists()`)
|
||||
- **FK**: End with `I3D` suffix (e.g., `AccountI3D`)
|
||||
- **Standard Columns**: CreatedByI3D, CreatedDate, ChangedByI3D, ChangedDate, IsDeleted, DeletedByI3D, DeletedDate (all REQUIRED)
|
||||
- **Types**: `nvarchar` (NOT varchar), `datetime2(2)`, `bit`, `decimal(18,2)` for currency
|
||||
- **Naming**: English PascalCase (new), Keep German (legacy), `dbo` schema
|
||||
|
||||
4. **Update navigation** in `docs/README.md`:
|
||||
- Add a new entry with a link to your documentation file
|
||||
- Follow the existing pattern and place in appropriate section
|
||||
### Creating Database Scripts
|
||||
1. Reserve number in Teams: `c-entron Entwickler` → Files → `Datenbankupdate 2 1.xlsx`
|
||||
2. Create: `src/backend/Centron.BL/Administration/Scripts/ScriptMethods/Scripts/ScriptMethod{number}.cs`
|
||||
3. Implement `BaseScriptMethod` with `GetSqlQueries()`
|
||||
4. Use `ScriptHelpers.*` (AddTableIfNotExists, AddColumnIfNotExists, AddRightIfNotExists, etc.)
|
||||
5. **Convert to UTF-8 with BOM** (C# files require BOM)
|
||||
|
||||
5. **Update the Solution File** (`Centron.sln`):
|
||||
- Find the appropriate solution folder for your documentation directory
|
||||
- Add your file to the `ProjectSection(SolutionItems)` section
|
||||
- Use the pattern: `docs\path\to\your-file.md = docs\path\to\your-file.md`
|
||||
## Localization (REQUIRED)
|
||||
- **Primary**: German (`LocalizedStrings.resx`) | **Secondary**: English (`LocalizedStrings.en.resx`)
|
||||
- **Code**: `LocalizedStrings.KeyName` | **XAML**: `{x:Static properties:LocalizedStrings.KeyName}`
|
||||
- **Key Format**: `{ClassName}_{Method}_{Description}`
|
||||
|
||||
### Documentation Standards
|
||||
- Use UTF-8 with BOM encoding for all documentation files
|
||||
- Start with a `#` heading that clearly describes the content
|
||||
- Use proper Markdown formatting for headings, lists, code blocks, etc.
|
||||
- Include links to related documentation when appropriate
|
||||
- For internal links, use relative paths to other documentation files
|
||||
## File Encoding (CRITICAL)
|
||||
- **UTF-8 WITH BOM**: `*.cs`, `*.xaml` (MANDATORY)
|
||||
- **UTF-8 NO BOM**: `*.md`, `*.json`, `*.xml`, `*.config`
|
||||
|
||||
**PowerShell Conversion**:
|
||||
```powershell
|
||||
$file = 'path\to\file.cs'
|
||||
$content = [System.IO.File]::ReadAllText($file)
|
||||
$utf8BOM = New-Object System.Text.UTF8Encoding($true)
|
||||
[System.IO.File]::WriteAllText($file, $content, $utf8BOM)
|
||||
```
|
||||
|
||||
## NHibernate Performance
|
||||
- Use `.Fetch()` for eager loading (prevent N+1)
|
||||
- Always filter: `.Where(x => !x.IsDeleted)`
|
||||
- Use `Future()` for multiple collections
|
||||
- Avoid lazy loading in loops
|
||||
|
||||
```csharp
|
||||
// Good
|
||||
var accounts = session.Query<Account>()
|
||||
.Where(x => !x.IsDeleted)
|
||||
.Fetch(x => x.AccountType)
|
||||
.Fetch(x => x.PriceList)
|
||||
.ToList();
|
||||
```
|
||||
|
||||
## Development Processes
|
||||
|
||||
### Settings Management
|
||||
- **Legacy**: `Stammdat` table (read-only)
|
||||
- **New**: `ApplicationSettings` table ONLY
|
||||
- Get next ID from `src/backend/Centron.Interfaces/Administration/Settings/ApplicationSettingID.cs`
|
||||
- Add description to `ApplicationSettingDefinitions.cs`
|
||||
|
||||
### User Rights
|
||||
1. Get next I3D from `UserRightsConst.cs`
|
||||
2. Create script: `ScriptHelpers.AddRightIfNotExists(id, parentId, "German name", "German desc")`
|
||||
3. Add constant to `UserRightsConst.cs`
|
||||
|
||||
### Web Service (Full Stack)
|
||||
1. **BL**: `{Entity}BL.cs` returning `Result<T>`
|
||||
2. **WebServiceBL**: `{Entity}WebServiceBL.cs` with DTO↔Entity conversion
|
||||
3. **RestService**: Add to `CentronRestService.cs` (`Request<T>` → `Response<T>`)
|
||||
4. **Interface**: `ICentronRestService.cs` with `[OperationContract]`, `[WebInvoke(Method="POST", UriTemplate="...")]`, `[Authenticate]`
|
||||
5. **Logic**: `I{Entity}Logic`, `BL{Entity}Logic`, `WS{Entity}Logic`
|
||||
|
||||
### WPF Module
|
||||
1. **Controller**: Implement `ICentronAppModuleController`
|
||||
2. **View**: `UserControl` inheriting `BaseModule`
|
||||
3. **ViewModel**: Inherit `BindableBase`
|
||||
4. **Ribbon**: Implement `IRibbonControlModule` variations
|
||||
5. **Registration**: Add to `ModuleRegistration.cs` with rights checks
|
||||
6. **Theme**: Prefer DevExpress controls over WPF standard
|
||||
|
||||
## Agent Usage (MANDATORY)
|
||||
|
||||
### Project Agents (.claude/agents/)
|
||||
- **primary-development**: ALL development tasks (orchestrator)
|
||||
- **database-script-creator**: Database schema changes → generates ScriptMethod*.cs
|
||||
- **webservice-developer**: Full-stack web service implementation
|
||||
- **ui-module-creator**: WPF modules with MVVM + DevExpress
|
||||
- **centron-nexus-developer**: Blazor Server, Razor components, SignalR, DevExpress Blazor
|
||||
- **external-api-integrator**: Third-party API integrations (FinAPI, GLS, Shipcloud, etc.)
|
||||
- **edi-specialist**: EDI processing (OpenTrans, EDIFACT, supplier integrations)
|
||||
- **nhibernate-query-reviewer**: Query optimization, N+1 detection
|
||||
- **localization-checker**: German/English verification
|
||||
- **bookkeeping-export-expert**: DATEV, Abacus, SAP exports
|
||||
- **test-engineer**: Test generation
|
||||
- **code-reviewer**: Code quality/security
|
||||
- **refactoring-specialist**: Code cleanup
|
||||
- **debugger**: Bug diagnosis
|
||||
- **architect**: System design
|
||||
- **documentation-writer**: Docs
|
||||
- **security-analyst**: Security reviews
|
||||
|
||||
### MANDATORY Agent Usage
|
||||
- New features → **primary-development**
|
||||
- DB schema → **database-script-creator**
|
||||
- Web service → **webservice-developer**
|
||||
- WPF module → **ui-module-creator**
|
||||
- CentronNexus/Blazor → **centron-nexus-developer**
|
||||
- External API → **external-api-integrator**
|
||||
- EDI integration → **edi-specialist**
|
||||
- Complex queries → **nhibernate-query-reviewer**
|
||||
- UI text → **localization-checker**
|
||||
|
||||
## Commands
|
||||
```bash
|
||||
dotnet build Centron.sln # Build
|
||||
dotnet test Centron.sln # Test all
|
||||
cd scripts/Centron.Scripts && dotnet run # Build orchestration
|
||||
```
|
||||
|
||||
**Targets**: clean, setup-versioning, build-web-service, build-centron-net, run-tests, create-installers
|
||||
|
||||
## Slash Commands
|
||||
`/test`, `/review`, `/optimize`, `/implement`, `/explain`, `/analyze`, `/adr`, `/scaffold`
|
||||
|
||||
## MCP Servers
|
||||
**serena**: Semantic search, symbol manipulation | **context7**: Library docs | **fetch**: Web content | **sequential-thinking**: Problem decomposition | **memory**: Knowledge graph | **playwright**: Browser automation | **windows-mcp**: Windows interaction
|
||||
|
||||
## Claude Instructions
|
||||
|
||||
### Tooling Decision (REQUIRED at task start)
|
||||
```
|
||||
🎯 Tooling Strategy Decision
|
||||
|
||||
Task Analysis: [Brief description]
|
||||
|
||||
Tooling Decisions:
|
||||
- Agents: [name] / Not using - Reason: [justification]
|
||||
- Slash Commands: [/command] / Not using - Reason: [justification]
|
||||
- MCP Servers: [server:tool] / Not using - Reason: [justification]
|
||||
- Approach: [strategy]
|
||||
```
|
||||
|
||||
**When NOT to use agents**: Single file read, simple edit, 1-2 tool calls
|
||||
|
||||
### Task Summary (REQUIRED at end)
|
||||
```
|
||||
📊 Task Completion Summary
|
||||
|
||||
What Was Done: [description]
|
||||
|
||||
Features Involved:
|
||||
- Agents: [list or None - justification]
|
||||
- Slash Commands: [list or None - justification]
|
||||
- MCP Servers: [list or None - justification]
|
||||
- Core Tools: [Read, Write, Edit, Glob, Grep, Bash, etc.]
|
||||
- Files Modified: [list or None]
|
||||
- Performance: [Parallel ops, extended thinking, or N/A]
|
||||
|
||||
Efficiency Notes: [observations]
|
||||
```
|
||||
|
||||
### Checklist
|
||||
✅ Provide tooling decisions at task start
|
||||
✅ Use `Result<T>` pattern
|
||||
✅ Follow ILogic interface pattern
|
||||
✅ German localization for UI text
|
||||
✅ UTF-8 with BOM for C#/XAML
|
||||
✅ DB conventions (I3D, FK, tracking columns)
|
||||
✅ Run tests before commits
|
||||
✅ Reference ticket numbers
|
||||
✅ Use parallel tool calls
|
||||
✅ Leverage agents/slash commands/MCP servers
|
||||
|
||||
## Common Tasks
|
||||
1. **DB Table**: database-script-creator → ScriptMethod*.cs with conventions
|
||||
2. **Web Service**: webservice-developer → BL → WebServiceBL → REST → Logic
|
||||
3. **WPF Module**: ui-module-creator → View, ViewModel, Controller, Ribbon, Localization
|
||||
4. **Query Optimization**: nhibernate-query-reviewer → N+1, indexes, soft delete
|
||||
|
||||
## Critical Files
|
||||
- `src/centron/Centron.WPF.UI/App.xaml.cs` - WPF entry
|
||||
- `src/backend/Centron.BL/` - Business logic
|
||||
- `src/backend/Centron.DAO/` - Data access
|
||||
- `src/webservice/Centron.WebServices.Core/RestService/CentronRestService.cs` - REST API
|
||||
- `src/backend/Centron.Interfaces/` - Service interfaces
|
||||
|
||||
## Git
|
||||
**Branch**: `master` (main) | **Types**: `feature/*`, `bugfix/*`, `hotfix/*`
|
||||
**Commits**: `feat(module):`, `fix(module):`, `refactor(module):`, `docs:` + optional `(Ticket #12345)`
|
||||
|
||||
## Important Notes
|
||||
- Project uses custom versioning via Nerdbank.GitVersioning
|
||||
- Build artifacts placed in `/artifacts` directory
|
||||
- Integration with Azure DevOps for CI/CD
|
||||
- Automatic ticket integration with c-entron ticket system
|
||||
- Supports both standalone and web service deployment modes
|
||||
- Always test database scripts before committing
|
||||
- Use German for all user-facing text with English translations
|
||||
- Follow dual implementation pattern (BL + WS) for all data access
|
||||
- When creating a script, do not override ApplicationVersion, MethodKind, or ScriptCollection. These are legacy properties.
|
||||
- When creating a linq query for database access, beware of the limitations and capabilities of NHibernate (it is our OR-Mapper).
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user