Masterarbeit/QuellCode/CentronERP/docs/reference/receipts/contracts-backend.md

Contracts Backend Architecture

This document describes the specific backend implementation for contracts within the c-entron.NET receipts system. Contracts extend the generic receipt architecture with specialized functionality for recurring billing, service agreements, and customer asset management.

Overview

Contracts in c-entron.NET are specialized receipts that handle ongoing service agreements, maintenance contracts, and recurring billing scenarios. They extend the base receipt functionality with contract-specific features like billing intervals, contingent management, device tracking, and automated invoice generation.

Entity Architecture

ReceiptContract Entity

Location: src/backend/Centron.Entities/Entities/Sales/Receipts/ContractLists/ReceiptContract.cs

The ReceiptContract class extends ReceiptBase and implements IReceiptContract. It represents the main contract entity with comprehensive contract-specific properties.

Core Contract Properties

Customer and Project Information:

• CustomerI3D: Primary customer reference
• ProjectNumber: Project identifier for the contract
• PurchaseOrderNumber: Customer's purchase order reference
• AdditionalText: Supplementary contract description

Personnel Assignment:

• SalesRepresentativeI3D: Assigned sales representative
• OfficeStaffI3D: Internal staff responsible for contract management

Delivery and Billing Addresses:

• DeliveryAddress, DeliveryAddressCustomerI3D: Service delivery location
• InvoiceAddress, InvoiceAddressCustomerI3D: Billing address information
• LicenseeAddress, LicenseeAddressCustomerI3D: Software licensing address

Contract Lifecycle:

• DeliveryDate: Contract start or service delivery date
• ContractEnd: Contract termination date
• ContractTermination: Actual termination date
• FirstPaidDate: Date of first payment received
• ReminderDate: Follow-up reminder date
• PreparationDate: Contract preparation date
• FinishDate: Contract completion date

Billing Configuration

Billing Intervals:

• BillingIntervalKind: Type of billing cycle (Daily, Monthly, Quarterly, Yearly)
• BillingIntervalDuration: Number of intervals (e.g., 3 for quarterly when kind is Monthly)
• BillingKind: Billing methodology (enum BillingKinds)
• AutomatedBilling: Boolean flag for automatic invoice generation

Contract Calculation:

• CalculationKind: How contract values are calculated (enum ContractCalculationKind)
• CalcNeedKind: Calculation requirements (enum ContractNeedCalcKind)
• IsNormalize: Whether to normalize billing amounts
• IsFullNormalizeAmount: Full normalization flag

Payment and Collection:

• PaymentConditionI3D: Reference to payment terms
• PaymentConditionText: Custom payment terms description
• CollectInvoice: Collection settings
• MandatI3D: SEPA mandate reference

Advanced Contract Features

Contingent Management:

• ContingentUsedHours: Hours consumed from contract contingent
• ContingentUsedAmount: Monetary amount consumed
• ContingentBalanceUsedHours: Balance hours utilized
• ContingentBalanceUsedAmount: Balance amount utilized
• ContingentBalanceArticleI3D: Article used for contingent balancing
• UseContingentBalanceArticle: Flag to enable balance article usage
• ContingentResidualValueStart: Starting residual value
• ContingentResidualValueStartDate: Start date for residual calculation

Contingent Limits and Monitoring:

• IsContingentLimitBilling: Enable contingent limit billing
• ContingentLimitValue: Limit threshold value
• ContingentLimitKind: Type of limit (enum ContingentLimitKinds)
• IsMonitoring: Enable contract monitoring
• MonitoringValue: Monitoring threshold

Device and Asset Management:

• Contract-specific device relationships through master data lists
• Serial number tracking and device lifecycle management
• Click counter management for printer/copier contracts

Contract Automation

Prolongation and Renewals:

• AutomatedProlongation: Automatic contract renewal flag
• LastSubsequentBillingDate: Date of last follow-up billing

Web Integration:

• IsDisplayedOnWeb: Web portal visibility flag
• WebReportI3D: Associated web report

Database Schema

Contract Database Architecture

Contracts follow the dual-layer database architecture used throughout the receipts system, consisting of legacy German-named tables and modern English-named views.

Legacy Contract Tables

VertragKopf Table (Contract Headers)

Physical Table: dbo.VertragKopf
Entity Class: Centron.DAO.TemporaryEntities.VertragKopf
Mapping: Centron.DAO.Mappings.TemporaryEntities.VertragKopfMaps

The VertragKopf table inherits from ReceiptTable and contains contract header information.

Key Columns:

• I3D - Primary key (identity)
• Nummer - Contract number
• KundenI3D - Customer reference
• Datum - Contract date
• Status - Contract state
• Berechnungsart - Calculation method
• AutoVerlaengerung - Auto-renewal flag
• AbrechnungsIntervallArt - Billing interval type
• AbrechnungsIntervallDauer - Billing interval duration
• VertragsBeginn - Contract start date
• VertragsEnde - Contract end date
• KuendigungsDatum - Termination date
• ErsteBezahlung - First payment date
• KontingentWert - Contingent value
• KontingentArt - Contingent type
• Automatische Abrechnung - Automated billing flag

VertragPos Table (Contract Items)

Physical Table: dbo.VertragPos
Entity Class: Centron.DAO.TemporaryEntities.VertragPos
Mapping: Centron.DAO.Mappings.TemporaryEntities.VertragPosMaps

The VertragPos table contains contract line items and positions.

Key Columns:

• I3D - Primary key (identity)
• VertragKopfI3D - Foreign key to contract header
• Pos - Position number for ordering
• ArtikelI3D - Article/product reference
• Text - Item description
• Stk - Quantity
• VKKalk - Sales price calculation
• EK - Purchase price
• MwstI3D - VAT rate reference
• VertragI3D - Contract reference for recurring items
• Lieferdatum - Delivery date
• Benachrichtigungsdatum - Notification date

Contract Version Tables

Version History Tables:

• VertragKopfVersions - Contract header version history
• VertragPosVersions - Contract items version history

Critical Architecture Detail: Version tables are exact 1:1 copies of their corresponding original tables (VertragKopf and VertragPos). This means:

• Every column that exists in VertragKopf must also exist in VertragKopfVersions with identical data types
• Every column that exists in VertragPos must also exist in VertragPosVersions with identical data types
• The only exceptions are system columns (I3D, OriginalI3D) which are handled specially
• Additional versioning columns are added: OriginalI3D (references original record) and KopfVersionsI3D (for position tables)

Contract Version Creation Process: When a contract version is saved (using AssetHeadDAO.SaveAssetVersion mechanism):

-- Save contract header version
INSERT INTO VertragKopfVersions (all_columns_except_I3D, OriginalI3D)
SELECT all_columns_except_I3D, I3D AS OriginalI3D
FROM VertragKopf
WHERE I3D = @contractId

-- Save contract items version
INSERT INTO VertragPosVersions (all_columns_except_I3D, OriginalI3D, KopfVersionsI3D)
SELECT all_columns_except_I3D, I3D AS OriginalI3D, @headerVersionId AS KopfVersionsI3D
FROM VertragPos
WHERE VertragKopfI3D = @contractId

This enables complete audit trails of all contract modifications, rollback capability, and change tracking functionality.

⚠️ Schema Maintenance Warning: When adding new columns to VertragKopf or VertragPos, the identical columns must also be added to their corresponding version tables (VertragKopfVersions and VertragPosVersions). Failure to maintain this 1:1 correspondence will cause runtime errors during version saving operations.

Modern Contract Views

Contracts View (Contract Headers)

Database View: dbo.Contracts
Purpose: Clean, English-named view of VertragKopf for C# application use

Benefits:

• Consistent English naming convention
• Cleaner column structure
• Type safety improvements
• Better integration with ORM mapping

ContractItems View (Contract Items)

Database View: dbo.ContractItems
Purpose: Clean, English-named view of VertragPos for C# application use

Contract Version Views

Version Views:

• ContractVersions - Clean view of VertragKopfVersions
• ContractItemVersions - Clean view of VertragPosVersions

Contract Logging Integration

AnlageLog Integration

Contracts integrate with the centralized AnlageLog table for audit logging:

Contract Log Entries:

• AnlageArt = 22 (Contract identifier)
• AnlageI3D - References contract I3D from VertragKopf
• Log entries for contract creation, modifications, billing events, renewals, and terminations

Typical Log Events:

• Contract creation and approval
• Billing interval changes
• Contingent modifications
• Device associations/removals
• Automated billing execution
• Contract renewals and terminations

Business Logic Architecture

ReceiptContractBL

Location: src/backend/Centron.BL/Sales/Receipts/ContractLists/ReceiptContractBL.cs

The ReceiptContractBL class provides contract-specific business logic extending the base receipt functionality.

Key Responsibilities

Contract Invoice Management:

• DeactivateContractInvoice(): Deactivate invoices generated from contracts
• GetContractInfosFromInvoices(): Extract contract information from invoices
• ExistsInvoiceForContract(): Check if invoices exist for a contract

Device and Counter Management:

• ResetDeviceClickCounter(): Reset click counters for printer/copier contracts
• UpdateDeviceToContract(): Associate devices with contracts
• CheckCounterHistory(): Validate counter readings history

Contingent and Billing:

• ContractContingentBalanceCalculation(): Calculate contingent balances
• CalculateContingentWithRecalculationArticle(): Handle contingent recalculations
• UpdateContractContingentBalanceCalculationForReceiptChange(): Adjust balances when receipts change
• UpdateTakeRestAndOverBooking(): Handle remainder and overbooking scenarios

Master Data List Management:

• AddMasteDateListsToContract(): Associate master data lists with contracts
• CreateMasterDataListsForNewMspArticles(): Create lists for new MSP articles
• RemoveMasterDataList(): Remove master data list associations
• CheckRemovedMasterDataList(): Validate removed associations

Contract-Specific Item Processing:

• GetContractRelevantItems(): Retrieve items relevant for contract billing
• UpdatePriceForContractRelevantItem(): Update pricing for contract items
• SaveContractPositionCounter(): Persist counter readings
• SaveContractFreeCopies(): Handle free copy allowances

ContractSpecificLogic

Location: src/backend/Centron.BL/Sales/Receipts/ContractLists/ContractSpecificLogic.cs

This class implements contract-specific operations that are called by the main ReceiptBL through the SpecificLogics pattern.

Related Business Logic Classes

ContractBL

Location: src/backend/Centron.BL/Sales/CustomerAssets/Contracts/ContractBL.cs

Handles broader contract asset management beyond the receipt functionality:

• Contract lifecycle management
• Device associations and management
• Contract analysis and reporting
• Integration with customer asset management

AutomaticFacturaBL.Contracts

Location: src/backend/Centron.BL/Sales/CustomerAssets/AutomaticFactura/AutomaticFacturaBL.Contracts.cs

Manages automated billing for contracts:

• Automatic invoice generation based on billing intervals
• RMM (Remote Monitoring and Management) integration
• Billing parameter calculation
• Multi-interval billing support

Contract Workflows

Contract Creation Process

1. Initialize Contract

   var contract = new ReceiptContract
   {
       CustomerI3D = customerId,
       Date = DateTime.Now,
       BillingIntervalKind = BillingIntervalKinds.Monthly,
       BillingIntervalDuration = 1,
       AutomatedBilling = true
   };
   

2. Configure Billing Parameters

   • Set billing intervals and calculation methods
   • Define payment conditions and terms
   • Configure contingent limits if applicable

3. Add Contract Items

   • Products and services to be provided
   • Pricing and quantity information
   • Device associations for maintenance contracts

4. Set Up Automation

   • Enable automated billing if required
   • Configure renewal settings
   • Set up monitoring and alerts

Automated Billing Process

The automated billing system (AutomaticFacturaBL) processes contracts based on their billing intervals:

1. Contract Evaluation

   • Check contracts due for billing
   • Validate billing parameters and dates
   • Verify customer and contract status

2. Invoice Generation

   • Create invoice based on contract items
   • Apply pricing rules and calculations
   • Handle contingent deductions

3. Post-Processing

   • Update contract billing dates
   • Generate documents and notifications
   • Update contingent balances

Device Management Integration

For maintenance and service contracts:

1. Device Association

   • Link devices to contracts through master data lists
   • Track serial numbers and device information
   • Monitor device status and warranty information

2. Counter Reading Management

   • Collect meter readings for copiers/printers
   • Calculate usage-based billing amounts
   • Handle free copy allowances and overages

3. Service Integration

   • Connect with RMM systems for automated data collection
   • Process device monitoring data
   • Generate alerts for maintenance requirements

Configuration Options

Billing Interval Configuration

BillingIntervalKind Options:

• Daily: Daily billing cycles
• Monthly: Monthly billing cycles
• Quarterly: Quarterly billing cycles
• Yearly: Annual billing cycles

BillingIntervalDuration:

• Number of intervals (e.g., 3 months for quarterly when kind is Monthly)
• Supports flexible billing periods

Calculation Methods

ContractCalculationKind Options:

• Standard calculation methods for different contract types
• Custom calculation logic for specialized scenarios

ContractNeedCalcKind:

• Defines calculation requirements and triggers
• Controls when recalculations are needed

Integration Points

Customer Asset Management

• Integration with device and asset tracking systems
• Warranty and maintenance schedule management
• Service history and documentation

Accounting System

• Automated journal entry generation for contract billing
• Revenue recognition for service contracts
• Contingent liability tracking

External Systems

• RMM Integration: Remote monitoring and management systems
• Device APIs: Direct device communication for counter readings
• Customer Portals: Web-based contract management interfaces

Performance Considerations

Billing Performance

• Batch Processing: Large contract sets processed in batches
• Parallel Processing: Multiple contracts processed simultaneously where possible
• Caching: Frequently accessed contract data cached for performance

Database Optimization

• Indexed Relationships: Foreign keys properly indexed
• Partitioning: Large contract tables partitioned by date ranges
• Archive Strategy: Old contract data archived for performance

Security and Compliance

Access Control

• Role-Based Permissions: Different access levels for contract operations
• Branch Isolation: Contracts accessible only to authorized branches
• Customer Isolation: Cross-customer data protection

Audit Requirements

• Change Tracking: Complete audit trail for all contract modifications
• Billing History: Detailed logging of all billing operations
• Compliance Reporting: Support for regulatory reporting requirements

Best Practices

Contract Design

• Clear Billing Intervals: Use consistent and predictable billing cycles
• Contingent Management: Monitor contingent usage to prevent overruns
• Device Integration: Properly associate devices for accurate billing

Development Guidelines

• Use ContractBL: Leverage existing contract business logic
• Handle Contingents: Always consider contingent impacts in calculations
• Validate Intervals: Ensure billing interval consistency
• Test Automation: Thoroughly test automated billing scenarios

Troubleshooting

• Billing Issues: Check interval configuration and calculation settings
• Device Problems: Verify master data list associations
• Performance Issues: Review indexing and query optimization
• Integration Failures: Validate external system connections and data formats