550 lines
14 KiB
Markdown
550 lines
14 KiB
Markdown
# 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.
|