# 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

```powershell
# 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

```powershell
# 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
```csharp
// 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
```csharp
// 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
```csharp
// 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
```csharp
// 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
```csharp
// 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
```csharp
// 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
```powershell
.\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
```powershell
.\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
```powershell
.\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
```powershell
.\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
```powershell
.\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
```powershell
.\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)
```markdown
## 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)
```markdown
## 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:**
```powershell
.\Analyze-UseCases.ps1
# Open report, ignore obsolete rights section
```

**Analyze specific module:**
```powershell
.\Analyze-UseCases-DeepDive.ps1 -AnalysisType Rights
# Open Rights-ByModule.md, find your module
```

### Batch Processing

**Generate all reports at once:**
```powershell
# 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:**
```powershell
# 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:**
```powershell
# 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"**
```powershell
# Check policy
Get-ExecutionPolicy

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

### No Results Found

**Check paths:**
```powershell
# 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:**
```powershell
# Edit Analyze-UseCases-DeepDive.ps1
# Find: $modulePatterns = @{ ... }
# Add your custom module detection patterns
```

### Export to Other Formats

**Convert Markdown to HTML/PDF:**
```powershell
# Using Pandoc (if installed)
pandoc UseCaseAnalysisReport.md -o UseCaseAnalysisReport.html
pandoc UseCaseAnalysisReport.md -o UseCaseAnalysisReport.pdf
```

### Integration with CI/CD

**Azure DevOps Pipeline:**
```yaml
- 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.