Masterarbeit/QuellCode/CentronERP/docs/reference/receipts/actionprice-system.md

# ActionPrice System Documentation

## Overview
The ActionPrice (Aktionspreis) system in c-entron manages time-limited promotional pricing from distributors and manufacturers. It integrates seamlessly with the price matrix (Preismatrix) to provide users with current action prices alongside other pricing sources.

## Table of Contents
- [Database Structure](#database-structure)
- [Architecture & Components](#architecture--components)
- [Data Flow](#data-flow)
- [Data Sources](#data-sources)
- [UI Access](#ui-access)
- [Integration with Price Matrix](#integration-with-price-matrix)
- [API Reference](#api-reference)
- [Business Rules](#business-rules)

## Database Structure

### Table: `HerstellerArtikAktionspreis`
**Location**: SQL Server database
**Mapped by**: `ActionPriceMaps.cs`

| Column | Data Type | Description |
|--------|-----------|-------------|
| `I3D` | int IDENTITY(1,1) | Primary key |
| `ArtikelI3D` | int | Foreign key to Article table |
| `Artikelcode` | nvarchar(60) | Article code |
| `Preis` | decimal | Action price |
| `Distributor` | nvarchar(100) | Distributor name |
| `GueltigAb` | datetime2(2) | Effective from date |
| `GueltigBis` | datetime2(2) | Effective until date |
| `Text` | nvarchar(500) | Description/notes |
| `Hersteller` | nvarchar(60) | Manufacturer |
| `BearbeiterI3D` | int | Editor user ID |
| `EDI_I3D` | int | EDI integration ID (reserved) |
| `Verfuegbarkeit` | nvarchar(50) | Availability |
| `VK` | decimal | Selling price |
| `Kreditorcode` | nvarchar(50) | Creditor code |
| `Status` | int | Status flag |
| `DistID` | nvarchar(50) | Distributor product ID |

## Architecture & Components

### Core Components

#### 1. Entity Layer
- **File**: `Centron.Entities/Warehousing/ActionPrice.cs`
- **Purpose**: Domain entity representing action price data
- **Properties**: Maps 1:1 with database columns

#### 2. Data Access Layer (DAO)
- **File**: `Centron.DAO/Mappings/Warehousing/ActionPriceMaps.cs`
- **Purpose**: NHibernate mapping for ActionPrice entity
- **Technology**: FluentNHibernate

#### 3. Business Logic Layer (BL)
- **File**: `Centron.BL/Warehousing/ActionPriceBL.cs`
- **Methods**:
  - `GetActionPrice(int actionPriceI3D)`
  - `GetActionPricesByArticleI3D(int articleI3D)`
  - `SaveOrUpdateActionPrice(ActionPrice actionPrice)`
  - `DeleteActionPrice(ActionPrice actionPrice)`

#### 4. Web Service Layer
- **File**: `Centron.BL/WebServices/Warehousing/ActionPriceWebServiceBL.cs`
- **Purpose**: DTO conversion and web service operations
- **Features**: Entity ↔ DTO mapping using ObjectMapper

#### 5. REST API
- **File**: `CentronRestService.cs`
- **Endpoints**:
  - `POST /GetActionPrice`
  - `POST /GetActionPricesByArticleI3D`
  - `POST /SaveOrUpdateActionPrice`
  - `POST /DeleteActionPrice`

### Dual Implementation Pattern

Following c-entron's standard pattern, ActionPrice supports both connection types:

#### BL Logic (Direct Database)
- **File**: `BLActionPriceLogic.cs`
- **Connection**: `CentronConnectionType.SqlServer`
- **Access**: Direct database via NHibernate

#### WS Logic (Web Service)
- **File**: `WSActionPriceLogic.cs`
- **Connection**: `CentronConnectionType.CentronWebServices`
- **Access**: REST API calls

## Data Flow

### Reading ActionPrices
```
1. Price Matrix Request
   ↓
2. Article Lookup (by ManufacturerCode or EAN)
   ↓
3. IActionPriceLogic.GetActionPricesByArticleI3D()
   ↓
4. Filter by Date Range (current valid prices only)
   ↓
5. Convert to PriceItemViewModel
   ↓
6. Display in Price Matrix Grid
```

### Creating ActionPrices
```
1. User Right-clicks Price Matrix Grid
   ↓
2. Select "Aktionspreis hinzufügen"
   ↓
3. AddActionPriceViewModel Dialog Opens
   ↓
4. User Enters Data (Distributor, Price, Dates)
   ↓
5. Validation (Distributor required, valid date range)
   ↓
6. IActionPriceLogic.SaveOrUpdateActionPrice()
   ↓
7. Data Saved to Database
   ↓
8. Price Matrix Refreshed
```

## Data Sources

### Current Active Sources

#### 1. Manual Entry (Primary)
- **Location**: Article Management → Additional Info → Preisspiegel Tab
- **Method**: Right-click context menu → "Aktionspreis hinzufügen"
- **Validation**:
  - Distributor name required
  - EffectiveFrom ≤ EffectiveUntil
- **User Tracking**: EditorI3D field tracks creator

### Potential Sources (Infrastructure Exists)

#### 1. EDI Integration
- **Evidence**: `EDI_I3D` field in database
- **Status**: Infrastructure exists but no active implementation found
- **Purpose**: Automated import from supplier EDI systems

#### 2. Bulk Import
- **Evidence**: Standard c-entron import patterns
- **Status**: No specific ActionPrice import modules identified
- **Potential**: Could be implemented for supplier data feeds

## UI Access

### Step-by-Step Navigation

1. **Open Article Management**
   - Navigate: Warehousing → Article Management

2. **Select Article**
   - Search for and open an existing article

3. **Access Additional Info**
   - Navigate to "Zusatzinfo" (Additional Info) section

4. **Open Preisspiegel Tab**
   - Click on "Preisspiegel" tab
   - This displays the price matrix grid

5. **Access ActionPrice Functions**
   - **Right-click** on the price matrix grid
   - Context menu appears with options:
     - "Preisspiegel aktualisieren" (Refresh)
     - "Aktionspreis hinzufügen" (Add ActionPrice)
     - "Aktionspreis bearbeiten" (Edit ActionPrice)
     - "Aktionspreis löschen" (Delete ActionPrice)

### UI Components
- **View**: `ArticleAdditionalInfoView.xaml`
- **ViewModel**: `ArticleAdditionalInfoViewModel.cs`
- **Grid**: `PriceWatchGridControl` (line 68)
- **Tab**: "Preisspiegel" (line 64)
- **Context Menu**: Lines 123-141

## Integration with Price Matrix

### Price Matrix Sources
ActionPrice is one of 7 parallel price sources in the matrix:

1. **ITscope** - External API
2. **Article Import** - Imported price data
3. **COP** - External API
4. **NEOS** - External API
5. **TradersGuide** - External API
6. **EGIS** - External API
7. **Aktionspreise** - Internal action prices ←

### Display Logic
- **File**: `PriceMatrixViewModel.cs`
- **Method**: `GetPriceItemsFromArticleActionPrices()` (lines 416-459)
- **Filtering**: Only shows prices where current date is within EffectiveFrom/EffectiveUntil range
- **Service Label**: Displays as "Aktionspreise" in Service column
- **Description Format**: "Aktionspreis vom {EffectiveFrom:d} bis {EffectiveUntil:d}. {Text}"

### Price Item Properties
```csharp
// ActionPrice in Price Matrix
Service = "Aktionspreise"
Supplier = actionPrice.Distributor
PurchasePrice = actionPrice.Price
RawPurchasePrice = actionPrice.Price
Date = actionPrice.EffectiveFrom
Stock = null // Always visible
ArticleDescription = "Aktionspreis vom ... bis ... {Text}"
```

## API Reference

### REST Endpoints

#### Get Single ActionPrice
```http
POST /GetActionPrice
Content-Type: application/json

{
  "Data": 123 // ActionPrice I3D
}
```

#### Get ActionPrices by Article
```http
POST /GetActionPricesByArticleI3D
Content-Type: application/json

{
  "Data": 456 // Article I3D
}
```

#### Save or Update ActionPrice
```http
POST /SaveOrUpdateActionPrice
Content-Type: application/json

{
  "Data": {
    "I3D": 0, // 0 for new, >0 for update
    "ArticleI3D": 456,
    "ArticleCode": "ART001",
    "Price": 99.99,
    "Distributor": "Supplier Name",
    "EffectiveFrom": "2024-01-01T00:00:00",
    "EffectiveUntil": "2024-12-31T23:59:59",
    "Text": "Special promotion",
    "Manufacturer": "Brand Name"
  }
}
```

#### Delete ActionPrice
```http
POST /DeleteActionPrice
Content-Type: application/json

{
  "Data": {
    "I3D": 123,
    // ... other properties
  }
}
```

### Code Usage

#### Get ActionPrices for Article
```csharp
var actionPrices = await ClassContainer.Instance
    .WithInstance((IActionPriceLogic logic) =>
        logic.GetActionPricesByArticleI3D(articleI3D))
    .ThrowIfError();
```

#### Save New ActionPrice
```csharp
var actionPriceDTO = new ActionPriceDTO
{
    ArticleI3D = articleI3D,
    Distributor = "Supplier Name",
    Price = 99.99,
    EffectiveFrom = DateTime.Now,
    EffectiveUntil = DateTime.Now.AddMonths(3),
    Text = "Special promotion"
};

await ClassContainer.Instance
    .WithInstance((IActionPriceLogic logic) =>
        logic.SaveOrUpdateActionPrice(actionPriceDTO))
    .ThrowIfError();
```

## Business Rules

### Validation Rules

1. **Required Fields**
   - `Distributor` - Must not be empty or whitespace

2. **Date Validation**
   - `EffectiveFrom` must be ≤ `EffectiveUntil`
   - Both dates are required

3. **Display Rules**
   - Only ActionPrices with current date within effective range show in Price Matrix
   - Filter: `EffectiveFrom.StartOfDay() <= DateTime.Now && EffectiveUntil >= DateTime.Now`

### Data Integrity

1. **Article Linking**
   - ActionPrices are linked to articles via `ArticleI3D`
   - Article must exist in system

2. **User Tracking**
   - `EditorI3D` tracks who created/modified the record
   - Automatically set during save operations

3. **Status Management**
   - `Status` field available for workflow management
   - Currently not actively used in UI

### Price Matrix Integration

1. **Loading Priority**
   - ActionPrices loaded in parallel with other price sources
   - No specific priority ordering

2. **Cache Behavior**
   - Price matrix results are cached by ManufacturerCode + EANCode
   - Cache invalidated when ActionPrices are modified

3. **Display Formatting**
   - ActionPrices always show Stock as null (always visible)
   - Service column shows "Aktionspreise"
   - Description includes date range and text

## Troubleshooting

### Common Issues

1. **ActionPrice Not Visible in Price Matrix**
   - Check if current date is within EffectiveFrom/EffectiveUntil range
   - Verify article linking via ArticleI3D
   - Ensure Price Matrix cache is refreshed

2. **Context Menu Not Appearing**
   - Ensure right-clicking directly on the Price Matrix grid
   - Check if article is properly selected
   - Verify user is in "Preisspiegel" tab

3. **Save Validation Errors**
   - Verify Distributor field is not empty
   - Check date range: EffectiveFrom ≤ EffectiveUntil
   - Ensure all required fields are populated

### Debug Information

- **Price Matrix Loading**: Check `PriceMatrixViewModel.GetPriceItemsFromArticleActionPrices()`
- **Article Lookup**: Verify article found by ManufacturerCode or EANCode
- **Date Filtering**: Current ActionPrice validation logic
- **UI Binding**: Check `ArticleAdditionalInfoViewModel.ActionPrices` collection

## Development Notes

### Future Enhancements

1. **EDI Integration**
   - `EDI_I3D` field suggests planned EDI integration
   - Could automate ActionPrice imports from suppliers

2. **Bulk Import**
   - Standard c-entron import patterns could be applied
   - Excel/CSV import functionality possible

3. **Workflow Management**
   - `Status` field could support approval workflows
   - Multi-step ActionPrice approval process

4. **Advanced Filtering**
   - Additional filter options in Price Matrix
   - ActionPrice-specific search capabilities

### Code Maintenance

- **Entity Changes**: Update both `ActionPrice` entity and `ActionPriceDTO`
- **Database Changes**: Update `ActionPriceMaps` NHibernate mapping
- **API Changes**: Update both BL and WS logic implementations
- **UI Changes**: Update both View and ViewModel files

---

*This documentation covers the complete ActionPrice system as implemented in c-entron. For questions or updates, refer to the source code files referenced throughout this document.*