Masterarbeit/Versuche/Versuch 03/ERP_DOCUMENTATION/USE_CASE_ANALYSIS_README.md

Use Case Analysis Tools - c-entron.NET

Comprehensive PowerShell scripts for extracting and analyzing use cases from the c-entron.NET codebase.

Overview

These tools analyze the codebase to discover documented and undocumented use cases by examining:

1. User Rights - All rights defined in UserRightsConst.cs
2. REST API Endpoints - All endpoints in ICentronRestService.cs
3. Wizard Pages - All wizard implementations with IWizardPage
4. Command Definitions - Commands in ViewModels (DelegateCommand, ICommand)
5. State/Status Enums - State transitions in Entity enums
6. Validation Rules - Business logic validation patterns

Scripts

1. Analyze-UseCases.ps1

Primary analysis tool that generates a comprehensive overview report.

Usage

# Basic usage - generates UseCaseAnalysisReport.md
.\Analyze-UseCases.ps1

# Custom output file
.\Analyze-UseCases.ps1 -OutputFile "reports\use-cases-2025-01.md"

# Show progress during analysis
.\Analyze-UseCases.ps1 -ShowProgress

Output

Generates a Markdown report with:

• Executive summary table
• Rights analysis (active vs obsolete)
• REST endpoints grouped by module
• Wizard pages by wizard name
• Command definitions by ViewModel
• State enums with transition counts
• Validation rule statistics
• Gap analysis (documented vs potential use cases)

Sample Output Structure:

## Use Case Discovery Report

### Executive Summary
| Category | Count | Notes |
|----------|-------|-------|
| User Rights | 450 | 35 obsolete, 485 total |
| REST Endpoints | 387 | Across 42 modules |
| Wizard Pages | 156 | In 28 wizards |
...

### 1. Rights Analysis
Total Rights: 485
Active: 450
Documented Use Cases: 509
Undocumented Potential: 0 (rights < documented cases)

### 2. REST API Endpoints
Total: 387
- Sales: 89 endpoints
- Administration: 67 endpoints
...

---

2. Analyze-UseCases-DeepDive.ps1

Detailed analysis tool for specific aspects with module grouping and cross-referencing.

Usage

# Analyze all aspects (generates multiple reports)
.\Analyze-UseCases-DeepDive.ps1 -AnalysisType All

# Analyze specific aspect
.\Analyze-UseCases-DeepDive.ps1 -AnalysisType Rights
.\Analyze-UseCases-DeepDive.ps1 -AnalysisType Endpoints
.\Analyze-UseCases-DeepDive.ps1 -AnalysisType Wizards
.\Analyze-UseCases-DeepDive.ps1 -AnalysisType Commands
.\Analyze-UseCases-DeepDive.ps1 -AnalysisType States

# Custom output directory
.\Analyze-UseCases-DeepDive.ps1 -AnalysisType All -OutputDirectory "reports\deep-dive-2025-01"

Output Files

Creates separate reports in UseCaseAnalysis/ directory:

1. Rights-ByModule.md

   • Rights grouped by module (Sales, Purchasing, Warehouse, etc.)
   • Includes descriptions from XML comments
   • Module categorization based on right names and descriptions

2. Endpoints-ToBusinessLogic.md

   • REST endpoints mapped to corresponding BL classes
   • Grouped by module/URI prefix
   • Shows HTTP method, URI template, method name, response type, and BL class

3. Wizards-FlowAnalysis.md

   • Wizard pages, commands, and validation methods
   • Flow visualization potential
   • Step-by-step wizard structure

4. Commands-PatternAnalysis.md

   • Commands categorized by pattern (CRUD, Navigation, Search, Export, Validation)
   • Grouped by ViewModel
   • Pattern detection for common command types

5. States-StateMachineAnalysis.md

   • State enums with all possible values
   • Mermaid state diagrams showing transitions
   • Sorted by complexity (state count)

---

Analysis Details

What Gets Analyzed

User Rights

// From: src/webservice/Centron.WebServices.Core/EntitiesWrongPlace/Administration/Rights/UserRightsConst.cs
/// <summary>
/// Text of the Right: Artikelverwaltung
/// </summary>
public const int RIGHT_ARTIKELSTAMM = 10220;

• Counts all public const int declarations
• Identifies obsolete rights via [Obsolete] attribute
• Extracts descriptions from XML comments

REST API Endpoints

// From: src/webservice/Centron.Host/Services/ICentronRestService.cs
[OperationContract]
[WebInvoke(Method = "POST", UriTemplate = "sales/customers")]
[Authenticate]
Task<Response<CustomerDTO>> GetCustomers(Request<CustomerSearchDTO> request);

• Finds all [OperationContract] methods
• Extracts HTTP method, URI template, response type
• Groups by module (URI prefix)

Wizard Pages

// Searches for: IWizardPage implementations
public class CustomerWizardPage1 : UserControl, IWizardPage
{
    // Page implementation
}

• Finds all classes implementing IWizardPage
• Groups pages by wizard name (from namespace or path)
• Counts pages per wizard

Command Definitions

// From: ViewModels in src/centron/Centron.WPF.UI/Modules/
public DelegateCommand SaveCommand { get; }
public ICommand DeleteCommand { get; }
private DelegateCommand _searchCommand;

• Finds DelegateCommand, RelayCommand, ICommand declarations
• Extracts command names
• Groups by ViewModel
• Categorizes by pattern (CRUD, Navigation, etc.)

State Enums

// From: src/backend/Centron.Entities/
public enum InvoiceStatus
{
    Draft = 0,
    Pending = 1,
    Approved = 2,
    Paid = 3
}

• Finds enums with "Status" or "State" in name
• Extracts all enum values
• Counts possible state transitions
• Creates state flow diagrams

Validation Rules

// From: src/backend/Centron.BL/
if (string.IsNullOrEmpty(customer.Name))
    return Result.Error("Name required");

if (amount < 0)
    throw new ValidationException("Amount must be positive");

• Finds validation patterns (null checks, range checks, exceptions)
• Counts validation rules per BL class
• Identifies high-impact validation files (>10 rules)

---

Interpreting Results

Understanding the Gap

Documented Use Cases: 509 (from existing documentation)

Potential Use Cases: Sum of:

• Active Rights (typically 400-500)
• REST Endpoints (typically 300-400)
• Wizard Pages (typically 100-200)
• Commands (typically 500-1000)
• State Transitions (typically 50-150)
• Validation Rules (typically 1000-2000)

Total Potential: Usually 2000-4000

Gap: Total Potential - 509 = Undocumented Use Cases

Why the Gap Exists

1. Multiple representations of same use case

   • One feature might have: 1 right + 2 endpoints + 5 commands + 1 wizard + 3 states
   • These represent 12 "findings" but only 1 use case

2. Internal/Technical use cases

   • Many commands are technical (Refresh, Close, Cancel)
   • Some validations are low-level checks, not user-facing features

3. Composite use cases

   • Complex features combine multiple rights, endpoints, wizards

Recommended Interpretation

Rights Count ≈ High-level feature count (most reliable)

• Each right typically represents a distinct user-facing feature
• Compare this number to documented use cases first

Endpoints Count = API surface area

• Good for API documentation
• Not 1:1 with use cases (often multiple endpoints per feature)

Commands Count = User actions

• Very detailed, includes many micro-interactions
• Useful for UI/UX documentation

Wizards Count = Complex workflows

• Each wizard = major multi-step use case
• High value for documentation

States Count = Business process complexity

• Shows lifecycle/workflow complexity
• Good for state machine documentation

---

Workflow Recommendations

Step 1: Initial Overview

.\Analyze-UseCases.ps1 -ShowProgress
# Review: UseCaseAnalysisReport.md

Action: Compare active rights (450) with documented use cases (509)

• If rights > documented: Missing documentation
• If documented > rights: Some features may not have rights (unusual)

Step 2: Module Deep Dive

.\Analyze-UseCases-DeepDive.ps1 -AnalysisType Rights
# Review: UseCaseAnalysis/Rights-ByModule.md

Action: Identify modules with many rights but sparse documentation

• Focus on top 3-5 modules with highest right counts
• Cross-reference with existing documentation

Step 3: API Documentation

.\Analyze-UseCases-DeepDive.ps1 -AnalysisType Endpoints
# Review: UseCaseAnalysis/Endpoints-ToBusinessLogic.md

Action: Verify REST API coverage

• Document undocumented endpoints
• Create API reference documentation
• Map endpoints to user features

Step 4: Wizard Documentation

.\Analyze-UseCases-DeepDive.ps1 -AnalysisType Wizards
# Review: UseCaseAnalysis/Wizards-FlowAnalysis.md

Action: Document complex workflows

• Create step-by-step wizard guides
• Add screenshots for each wizard page
• Document validation rules per page

Step 5: State Machine Documentation

.\Analyze-UseCases-DeepDive.ps1 -AnalysisType States
# Review: UseCaseAnalysis/States-StateMachineAnalysis.md

Action: Create state transition documentation

• Use generated Mermaid diagrams
• Document business rules for each transition
• Identify who can trigger each transition (rights)

Step 6: Full Deep Dive

.\Analyze-UseCases-DeepDive.ps1 -AnalysisType All
# Review all reports in: UseCaseAnalysis/

Action: Comprehensive documentation update

• Cross-reference all findings
• Identify patterns and commonalities
• Create master documentation index

---

Example Output Snippets

Executive Summary (Analyze-UseCases.ps1)

========================================
USE CASE ANALYSIS COMPLETE
========================================
Active User Rights:      450
REST Endpoints:          387
Wizard Pages:            156
Commands:                789
State Transitions:       87
Validation Rules:        1543
----------------------------------------
TOTAL POTENTIAL:         3412
Documented Use Cases:    509
UNDOCUMENTED GAP:        2903
========================================

Rights by Module (Analyze-UseCases-DeepDive.ps1)

## Sales (89 rights)

| Constant Name | Value | Description |
|---------------|-------|-------------|
| `RIGHT_KUNDENSTAMM` | 10310 | Kunden |
| `RIGHT_ANGEBOT` | 40000 | Angebot |
| `RIGHT_RECHNUNG` | 40100 | Rechnung |
...

Endpoints to BL Mapping (Analyze-UseCases-DeepDive.ps1)

## sales (89 endpoints)

| Method | URI | Method Name | Response Type | Business Logic |
|--------|-----|-------------|---------------|----------------|
| POST | `sales/customers` | `GetCustomers` | `CustomerDTO` | `CustomerWebServiceBL` |
| POST | `sales/invoices` | `GetInvoices` | `InvoiceDTO` | `InvoiceWebServiceBL` |
...

---

Tips & Tricks

Filtering Output

Focus on active rights only:

.\Analyze-UseCases.ps1
# Open report, ignore obsolete rights section

Analyze specific module:

.\Analyze-UseCases-DeepDive.ps1 -AnalysisType Rights
# Open Rights-ByModule.md, find your module

Batch Processing

Generate all reports at once:

# Create timestamped directory
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
$reportDir = "use-case-analysis-$timestamp"

# Run both scripts
.\Analyze-UseCases.ps1 -OutputFile "$reportDir\overview.md"
.\Analyze-UseCases-DeepDive.ps1 -AnalysisType All -OutputDirectory $reportDir

# Results in: use-case-analysis-20250120-143022/

Comparing Over Time

Track changes between versions:

# Generate baseline
.\Analyze-UseCases.ps1 -OutputFile "baseline-v2.1.0.md"

# After development
.\Analyze-UseCases.ps1 -OutputFile "current-v2.2.0.md"

# Compare
code --diff baseline-v2.1.0.md current-v2.2.0.md

Integration with Documentation

Use as input for documentation:

# Generate reports
.\Analyze-UseCases-DeepDive.ps1 -AnalysisType All

# Copy relevant sections into documentation
# Example: Copy Rights-ByModule.md sections into user manual
# Example: Copy States diagrams into design documentation

---

Troubleshooting

Script Not Running

Error: "Execution Policy"

# Check policy
Get-ExecutionPolicy

# Allow scripts (run as Admin)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

No Results Found

Check paths:

# Verify you're in project root
cd C:\DEV\C-entron.net\c-entron.NET

# Check required files exist
Test-Path "src\webservice\Centron.WebServices.Core\EntitiesWrongPlace\Administration\Rights\UserRightsConst.cs"
Test-Path "src\webservice\Centron.Host\Services\ICentronRestService.cs"

Incomplete Results

Large codebase timeout:

• Deep dive analysis can take 5-10 minutes on large codebases
• Run individual analyses instead of "All"
• Use -AnalysisType parameter to focus

Encoding Issues

Special characters in output:

• Reports use UTF-8 encoding
• Open in VS Code or editor with UTF-8 support
• Avoid Notepad (use Notepad++ or VS Code)

---

Advanced Usage

Custom Analysis

Modify patterns in scripts:

# Edit Analyze-UseCases-DeepDive.ps1
# Find: $modulePatterns = @{ ... }
# Add your custom module detection patterns

Export to Other Formats

Convert Markdown to HTML/PDF:

# Using Pandoc (if installed)
pandoc UseCaseAnalysisReport.md -o UseCaseAnalysisReport.html
pandoc UseCaseAnalysisReport.md -o UseCaseAnalysisReport.pdf

Integration with CI/CD

Azure DevOps Pipeline:

- task: PowerShell@2
  displayName: 'Analyze Use Cases'
  inputs:
    targetType: 'filePath'
    filePath: '$(Build.SourcesDirectory)/Analyze-UseCases.ps1'
    arguments: '-OutputFile "$(Build.ArtifactStagingDirectory)/use-cases.md"'

- task: PublishPipelineArtifact@1
  inputs:
    targetPath: '$(Build.ArtifactStagingDirectory)'
    artifact: 'use-case-reports'

---

Files Generated

Analyze-UseCases.ps1

• UseCaseAnalysisReport.md (or custom path via -OutputFile)

Analyze-UseCases-DeepDive.ps1

• UseCaseAnalysis/Rights-ByModule.md
• UseCaseAnalysis/Endpoints-ToBusinessLogic.md
• UseCaseAnalysis/Wizards-FlowAnalysis.md
• UseCaseAnalysis/Commands-PatternAnalysis.md
• UseCaseAnalysis/States-StateMachineAnalysis.md

---

Version History

v1.0.0 (2025-01-20)

• Initial release
• Support for Rights, Endpoints, Wizards, Commands, States, Validations
• Two-tier analysis (overview + deep dive)
• Markdown output with tables and diagrams

---

Support

For issues or questions:

1. Check existing documentation in .claude/ directory
2. Review CLAUDE.md for project conventions
3. Consult development team

---

Note: These scripts are read-only analysis tools. They do not modify any source code or project files.