# EDI Architecture Documentation

This document provides a comprehensive overview of the Electronic Data Interchange (EDI) architecture in the c-entron.NET system, focusing on the supplier EDI integration patterns and implementation.

## Table of Contents

- [Overview](#overview)
- [Core Architecture](#core-architecture)
- [EDI Data Flow](#edi-data-flow)
- [Supplier Integration Patterns](#supplier-integration-patterns)
- [Partial Class Architecture](#partial-class-architecture)
- [EDI Data Types](#edi-data-types)
- [Document Processing Workflow](#document-processing-workflow)
- [Error Handling and Logging](#error-handling-and-logging)
- [Configuration Management](#configuration-management)
- [Extension Points](#extension-points)

## Overview

The EDI system in c-entron.NET facilitates automated business document exchange between c-entron and various suppliers. The architecture supports multiple EDI standards and supplier-specific formats, processing orders, order responses, deliveries, and invoices through a unified interface.

### Key Components

- **SupplierEdiBL**: Main business logic class handling EDI operations
- **EDICommonBL**: Shared utilities for data parsing and formatting
- **EDILogBL**: Logging and audit trail management
- **ClientConnectBL**: Connection management for external EDI services
- **Partial Classes**: Supplier-specific implementations for different EDI formats

## Core Architecture

### Class Hierarchy

```
SupplierEdiBL (main class)
├── SupplierEdiBL.AlsoCH.cs      - ALSO Switzerland specific implementation
├── SupplierEdiBL.Also.cs        - ALSO generic implementation
├── SupplierEdiBL.Alltron.cs     - Alltron supplier integration
├── SupplierEdiBL.Herweck.cs     - Herweck supplier integration
├── SupplierEdiBL.Komsa.cs       - Komsa supplier integration
└── SupplierEdiBL.Opentrans.cs   - OpenTrans 2.1 standard implementation
```

### Dependencies

The EDI system relies on several core components:

- **Gateway Libraries**: Supplier-specific EDI parsing libraries
  - `Centron.Gateway.EDI_Also`
  - `Centron.Gateway.EDI_AlsoCH`
  - `Centron.Gateway.EDI_Alltron`
  - `Centron.Gateway.EDI_Herweck`
  - `Centron.Gateway.OpenTrans`

- **External APIs**:
  - ITScope API for product data synchronization
  - EGIS integration for electronic invoicing
  - ZUGFeRD for structured invoice data

## EDI Data Flow

### High-Level Process Flow

```
1. Configuration Setup
   ├── Supplier EDI configurations defined
   ├── Connection parameters configured
   └── Data type mappings established

2. Document Download
   ├── FTP/SFTP file retrieval
   ├── File decompression (ZIP support)
   └── Document validation

3. Data Processing
   ├── Format detection (EdiDataType)
   ├── Supplier-specific parsing
   └── c-entron object creation

4. Integration
   ├── Order matching and validation
   ├── Business rule application
   └── Database persistence

5. Logging and Audit
   ├── Processing status tracking
   ├── Error logging
   └── User notification
```

### Core Processing Method: `ApplyDistriToCentron`

The `ApplyDistriToCentron` method serves as the central dispatch mechanism for processing EDI files:

```csharp
public async Task<bool> ApplyDistriToCentron(
    List<EDIDistriFile> xmlData, 
    SupplierEdiConfigurations config, 
    OrderInfo deal)
```

**Key Responsibilities:**
- Routes processing based on `EdiDataType` and `ObjectKind`
- Delegates to supplier-specific parsing methods
- Handles file cleanup after successful processing
- Returns success/failure status for downstream processing

## Supplier Integration Patterns

### Document Types Supported

Each supplier integration supports different combinations of document types:

| Supplier | Order Response | Delivery | Invoice | Notes |
|----------|---------------|----------|---------|--------|
| OpenTrans 2.1 | ✓ | ✓ | ✓ | Industry standard |
| ALSO | ✓ | ✓ | ✓ | Generic ALSO format |
| ALSO CH | ✓ | ✓ | ✓ | Switzerland-specific |
| Herweck | ✓ | ✓ | ✓ | Dual structure support |
| Komsa | ✓ | ✓ | ✗ | No invoice integration |
| Alltron | ✓ | ✓ | ✓ | Full document support |
| ZUGFeRD | ✗ | ✗ | ✓ | Invoice-only standard |

## Partial Class Architecture

### Design Pattern

The EDI system uses partial classes to organize supplier-specific logic while maintaining a unified interface. Each partial class handles:

1. **Document Parsing**: XML deserialization using supplier-specific schemas
2. **Data Mapping**: Conversion from supplier format to c-entron entities
3. **Business Logic**: Supplier-specific validation and processing rules
4. **Error Handling**: Format-specific error recovery and logging

### Example: ALSO CH Implementation

```csharp
public partial class SupplierEdiBL
{
    public bool ReadAlsoCHResponse(List<EDIDistriFile> distriFiles, SupplierEdiConfigurations config)
    {
        // Parse ALSO CH specific XML format
        var serializer = new XmlSerializer(typeof(orderresponse));
        var response = (orderresponse)serializer.Deserialize(distriFile.XmlDatei);
        
        // Map to c-entron entities
        EDIOrderResponseHead head = new EDIOrderResponseHead();
        // ... mapping logic
        
        // Process and validate
        return ApplyEDIReceiptToCentronOrder(lstHead, lstItems, lstData, objectKind);
    }
}
```

### Supplier-Specific Features

#### ALSO CH (AlsoCH.cs)
- **Special Handling**: Swiss banking integration (ESR codes)
- **Additional Costs**: Handling of various Swiss fees (G1-G8 codes)
- **Localization**: Swiss address format and currency handling

#### Herweck (Herweck.cs)  
- **Dual Structure**: Supports both legacy and new XML structures
- **Fallback Logic**: Automatic retry with alternative parsing method
- **Advanced Mapping**: Complex article code resolution

#### Alltron (Alltron.cs)
- **Serial Number Tracking**: Enhanced barcode and serial number management
- **Delivery Integration**: Detailed delivery note processing
- **Swiss Market**: Optimized for Swiss IT distribution

## EDI Data Types

### Supported Formats

```csharp
public enum EdiDataType
{
    OpenTrans21 = 1,    // Industry standard OpenTrans 2.1
    Also = 2,           // ALSO generic format
    AlsoCH = 3,         // ALSO Switzerland
    Herweck = 4,        // Herweck proprietary format
    Komsa = 5,          // Komsa format
    Alltron = 6,        // Alltron format
    Zugferd = 7         // ZUGFeRD standard
}
```

### Object Kinds

```csharp
public enum EDIConnectionObjectKind
{
    Order = 1,          // Purchase orders (outbound)
    OrderResponse = 2,  // Order confirmations (inbound)
    Delivery = 3,       // Delivery notifications (inbound)
    Invoice = 4         // Electronic invoices (inbound)
}
```

## Document Processing Workflow

### Order Response Processing

1. **Document Reception**: Download from supplier FTP/SFTP
2. **Format Detection**: Identify EDI format and supplier
3. **Header Processing**:
   - Extract order reference information
   - Validate buyer/supplier party IDs
   - Map delivery addresses
4. **Line Item Processing**:
   - Parse product codes (supplier, manufacturer, EAN)
   - Extract quantities and pricing
   - Handle delivery dates and availability
5. **Integration**:
   - Match with existing c-entron orders
   - Update order status and quantities
   - Generate user notifications for discrepancies

### Delivery Note Processing

1. **Shipment Information**: Extract tracking and delivery details
2. **Serial Number Handling**: Process individual item serial numbers
3. **Quantity Validation**: Verify shipped quantities against orders
4. **Barcode Processing**: Handle product identification codes
5. **Receipt Generation**: Create delivery receipts in c-entron

### Invoice Processing

1. **Financial Data**: Extract pricing, VAT, and currency information
2. **Reference Matching**: Link invoices to deliveries and orders
3. **Tax Calculation**: Validate VAT amounts and rates
4. **Payment Terms**: Process payment conditions and bank details
5. **Accounting Integration**: Create accounting entries

## Error Handling and Logging

### Logging Framework

The EDI system uses structured logging through `EDILogBL`:

```csharp
public enum EDILogState
{
    DownloadOK,         // Successful processing
    DownloadError,      // Processing errors
    DownloadTest,       // Test mode operations
    Exception,          // System exceptions
    TestException       // Test mode exceptions
}
```

### Error Recovery Strategies

1. **Format Fallbacks**: Multiple parsing attempts for flexible formats
2. **Partial Processing**: Continue processing valid records despite individual failures
3. **User Notifications**: Alert users to validation issues requiring manual intervention
4. **Retry Logic**: Automatic retry for transient connection issues

### Audit Trail

- Complete processing history for each document
- User actions and validations tracked
- Error details and resolution steps logged
- Performance metrics and processing times recorded

## Configuration Management

### Supplier Configuration

Each supplier integration requires configuration through `SupplierEdiConfigurations`:

```csharp
public class SupplierEdiConfigurations
{
    public int SupplierI3D { get; set; }           // Supplier identifier
    public string SupplierCustomerNumber { get; set; } // Customer number at supplier
    public int EdiDataType { get; set; }           // Format type
    public int ObjectKind { get; set; }            // Document type
    public string ConnectionString { get; set; }   // FTP/API connection details
    // ... additional configuration properties
}
```

### Branch-Specific Handling

- Multi-branch deployments supported
- Branch-specific supplier configurations
- Centralized vs. distributed processing options

## Extension Points

### Adding New Suppliers

To integrate a new supplier:

1. **Create Partial Class**: `SupplierEdiBL.NewSupplier.cs`
2. **Implement Reading Methods**:
   ```csharp
   private bool ReadNewSupplierResponse(List<EDIDistriFile> files, SupplierEdiConfigurations config)
   private bool ReadNewSupplierDelivery(List<EDIDistriFile> files, SupplierEdiConfigurations config)
   private bool ReadNewSupplierInvoice(List<EDIDistriFile> files, SupplierEdiConfigurations config)
   ```
3. **Update ApplyDistriToCentron**: Add new case for supplier format
4. **Add Gateway Library**: Create parsing library if needed
5. **Configure Mappings**: Set up data type and configuration entries

### Custom Business Logic

- Override validation rules in supplier-specific partials
- Implement custom data transformations
- Add supplier-specific error handling
- Extend logging and audit capabilities

### API Integration

- ITScope API integration for real-time product data
- EGIS electronic invoicing support
- ZUGFeRD structured invoice processing
- Custom API endpoints for supplier-specific requirements

## Best Practices

### Performance Considerations

- Batch processing for large document volumes
- Async processing for I/O operations
- Memory-efficient XML parsing for large files
- Connection pooling for FTP/API operations

### Security

- Secure credential storage for supplier connections
- Encrypted data transmission (SFTP/HTTPS)
- Audit logging for compliance requirements
- Access control for EDI operations

### Maintainability

- Consistent error handling patterns across suppliers
- Comprehensive unit testing for each supplier integration
- Clear separation of concerns between parsing and business logic
- Documentation of supplier-specific requirements and limitations

---

**Related Documentation:**
- [Database Schema Reference](../database/README.md)
- [Security Architecture](../security/README.md)
- [Receipt Processing Guide](../receipts/README.md)