Ergebnisse 1-3 + Typs Debug
This commit is contained in:
549
Ergebnisse/Ergebnisse 03/USE_CASE_ANALYSIS_README.md
Normal file
549
Ergebnisse/Ergebnisse 03/USE_CASE_ANALYSIS_README.md
Normal file
@@ -0,0 +1,549 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user