1760 lines
53 KiB
Markdown
1760 lines
53 KiB
Markdown
# System Interface Specifications
|
|
## Centron Enterprise Application - Interface Documentation
|
|
|
|
### Document Information
|
|
- **Document ID**: SyRS-INT-CENTRON-2024-001
|
|
- **Version**: 1.0
|
|
- **Date**: September 30, 2024
|
|
- **Related Documents**: SyRS_Complete.md, SyRS_Architecture.md, SyRS_API_Specification.yaml
|
|
- **Project**: UseCaseAnalyse (Centron Enterprise Application)
|
|
|
|
---
|
|
|
|
## 1. Interface Overview
|
|
|
|
### 1.1 Interface Classification
|
|
|
|
The Centron Enterprise Application implements a comprehensive interface architecture supporting multiple interaction patterns:
|
|
|
|
#### **Internal Interfaces**
|
|
- **Layer Interfaces**: Communication between architectural layers
|
|
- **Component Interfaces**: Inter-component communication within layers
|
|
- **Module Interfaces**: Plugin and extension points
|
|
- **Service Interfaces**: Cross-cutting service contracts
|
|
|
|
#### **External Interfaces**
|
|
- **Database Interfaces**: Data persistence and retrieval
|
|
- **Web Service Interfaces**: REST API for external access
|
|
- **Integration Interfaces**: External system connectivity
|
|
- **User Interfaces**: Human-computer interaction
|
|
|
|
### 1.2 Interface Design Principles
|
|
|
|
- **Contract-First Design**: Interfaces defined before implementations
|
|
- **Backward Compatibility**: Version management and compatibility preservation
|
|
- **Error Handling**: Consistent error response patterns
|
|
- **Security**: Authentication and authorization integration
|
|
- **Performance**: Optimized for high-throughput scenarios
|
|
|
|
---
|
|
|
|
## 2. Internal System Interfaces
|
|
|
|
### 2.1 Business Logic Interfaces (ILogic Pattern)
|
|
|
|
#### **2.1.1 Core ILogic Interface Pattern**
|
|
|
|
**Base ILogic Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.BL
|
|
{
|
|
/// <summary>
|
|
/// Base interface for all business logic services implementing the dual-access pattern
|
|
/// </summary>
|
|
public interface ILogic : IDisposable
|
|
{
|
|
/// <summary>
|
|
/// Gets the current connection type (SqlServer or CentronWebServices)
|
|
/// </summary>
|
|
CentronConnectionType ConnectionType { get; }
|
|
|
|
/// <summary>
|
|
/// Gets a value indicating whether the service is initialized
|
|
/// </summary>
|
|
bool IsInitialized { get; }
|
|
|
|
/// <summary>
|
|
/// Initializes the service with the specified connection context
|
|
/// </summary>
|
|
Task<Result> InitializeAsync(IServiceContext context);
|
|
}
|
|
}
|
|
```
|
|
|
|
**Result Pattern Implementation**
|
|
```csharp
|
|
namespace Centron.Interfaces.Results
|
|
{
|
|
/// <summary>
|
|
/// Standardized result pattern for all service operations
|
|
/// </summary>
|
|
public class Result<T>
|
|
{
|
|
public bool IsSuccess { get; set; }
|
|
public T Data { get; set; }
|
|
public string ErrorMessage { get; set; }
|
|
public Exception Exception { get; set; }
|
|
public ResultStatus Status { get; set; }
|
|
public string[] ValidationErrors { get; set; }
|
|
public Dictionary<string, object> Metadata { get; set; }
|
|
|
|
public static Result<T> AsSuccess(T data, string message = null)
|
|
{
|
|
return new Result<T>
|
|
{
|
|
IsSuccess = true,
|
|
Data = data,
|
|
Status = ResultStatus.Success,
|
|
Metadata = new Dictionary<string, object>()
|
|
};
|
|
}
|
|
|
|
public static Result<T> AsError(string errorMessage, Exception exception = null)
|
|
{
|
|
return new Result<T>
|
|
{
|
|
IsSuccess = false,
|
|
ErrorMessage = errorMessage,
|
|
Exception = exception,
|
|
Status = ResultStatus.Error,
|
|
Metadata = new Dictionary<string, object>()
|
|
};
|
|
}
|
|
}
|
|
|
|
public enum ResultStatus
|
|
{
|
|
Success,
|
|
Warning,
|
|
Error,
|
|
ValidationError,
|
|
NotFound,
|
|
Unauthorized,
|
|
Forbidden
|
|
}
|
|
}
|
|
```
|
|
|
|
#### **2.1.2 Customer Management Interfaces**
|
|
|
|
**Customer Logic Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.Sales.Customers
|
|
{
|
|
/// <summary>
|
|
/// Customer management business logic interface
|
|
/// Supports both direct database (BL) and web service (WS) implementations
|
|
/// </summary>
|
|
public interface ICustomerLogic : ILogic
|
|
{
|
|
/// <summary>
|
|
/// Retrieves customers based on filter criteria
|
|
/// </summary>
|
|
/// <param name="filter">Customer filter criteria</param>
|
|
/// <returns>Array of customer entities matching the criteria</returns>
|
|
Task<Result<Customer[]>> GetCustomersAsync(CustomerFilter filter);
|
|
|
|
/// <summary>
|
|
/// Retrieves a single customer by ID
|
|
/// </summary>
|
|
/// <param name="customerId">Unique customer identifier</param>
|
|
/// <returns>Customer entity or null if not found</returns>
|
|
Task<Result<Customer>> GetCustomerByIdAsync(int customerId);
|
|
|
|
/// <summary>
|
|
/// Saves customer information (create or update)
|
|
/// </summary>
|
|
/// <param name="customer">Customer entity to save</param>
|
|
/// <returns>Saved customer with updated metadata</returns>
|
|
Task<Result<Customer>> SaveCustomerAsync(Customer customer);
|
|
|
|
/// <summary>
|
|
/// Deletes a customer with validation
|
|
/// </summary>
|
|
/// <param name="customerId">Customer ID to delete</param>
|
|
/// <param name="reason">Deletion reason for audit trail</param>
|
|
/// <returns>Operation result</returns>
|
|
Task<Result> DeleteCustomerAsync(int customerId, string reason);
|
|
|
|
/// <summary>
|
|
/// Validates customer data for business rules
|
|
/// </summary>
|
|
/// <param name="customer">Customer to validate</param>
|
|
/// <returns>Validation results with error details</returns>
|
|
Task<Result<ValidationResult>> ValidateCustomerAsync(Customer customer);
|
|
|
|
/// <summary>
|
|
/// Searches customers using full-text search
|
|
/// </summary>
|
|
/// <param name="searchTerm">Search term</param>
|
|
/// <param name="maxResults">Maximum results to return</param>
|
|
/// <returns>Array of matching customers</returns>
|
|
Task<Result<Customer[]>> SearchCustomersAsync(string searchTerm, int maxResults = 100);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Customer filter criteria
|
|
/// </summary>
|
|
public class CustomerFilter
|
|
{
|
|
public string SearchText { get; set; }
|
|
public string CustomerNumber { get; set; }
|
|
public string CompanyName { get; set; }
|
|
public string City { get; set; }
|
|
public string Country { get; set; }
|
|
public CustomerStatus? Status { get; set; }
|
|
public DateTime? CreatedAfter { get; set; }
|
|
public DateTime? CreatedBefore { get; set; }
|
|
public int PageSize { get; set; } = 100;
|
|
public int PageNumber { get; set; } = 1;
|
|
public string[] SortFields { get; set; }
|
|
public SortDirection SortDirection { get; set; } = SortDirection.Ascending;
|
|
}
|
|
|
|
public enum CustomerStatus
|
|
{
|
|
Active = 1,
|
|
Inactive = 2,
|
|
Suspended = 3,
|
|
Archived = 4
|
|
}
|
|
}
|
|
```
|
|
|
|
#### **2.1.3 Financial Management Interfaces**
|
|
|
|
**Financial Logic Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.Finances
|
|
{
|
|
/// <summary>
|
|
/// Financial management business logic interface
|
|
/// Handles payments, invoicing, and financial reporting
|
|
/// </summary>
|
|
public interface IFinancialLogic : ILogic
|
|
{
|
|
/// <summary>
|
|
/// Processes incoming payments with validation and reconciliation
|
|
/// </summary>
|
|
Task<Result<IncomingPayment>> ProcessIncomingPaymentAsync(IncomingPayment payment);
|
|
|
|
/// <summary>
|
|
/// Processes outgoing payments with approval workflow
|
|
/// </summary>
|
|
Task<Result<OutgoingPayment>> ProcessOutgoingPaymentAsync(OutgoingPayment payment);
|
|
|
|
/// <summary>
|
|
/// Generates invoices based on orders or contracts
|
|
/// </summary>
|
|
Task<Result<Invoice>> GenerateInvoiceAsync(InvoiceGenerationRequest request);
|
|
|
|
/// <summary>
|
|
/// Performs automated bank reconciliation
|
|
/// </summary>
|
|
Task<Result<ReconciliationResult>> ReconcileBankTransactionsAsync(BankReconciliationRequest request);
|
|
|
|
/// <summary>
|
|
/// Retrieves financial reports with customizable parameters
|
|
/// </summary>
|
|
Task<Result<FinancialReport>> GenerateFinancialReportAsync(FinancialReportRequest request);
|
|
|
|
/// <summary>
|
|
/// Validates German tax compliance for financial transactions
|
|
/// </summary>
|
|
Task<Result<TaxValidationResult>> ValidateGermanTaxComplianceAsync(FinancialTransaction transaction);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Bank reconciliation request parameters
|
|
/// </summary>
|
|
public class BankReconciliationRequest
|
|
{
|
|
public int AccountId { get; set; }
|
|
public DateTime FromDate { get; set; }
|
|
public DateTime ToDate { get; set; }
|
|
public BankTransactionImport[] ImportedTransactions { get; set; }
|
|
public ReconciliationRules Rules { get; set; }
|
|
public bool AutoApprove { get; set; }
|
|
}
|
|
}
|
|
```
|
|
|
|
#### **2.1.4 Helpdesk Management Interfaces**
|
|
|
|
**Helpdesk Logic Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.Sales.Support
|
|
{
|
|
/// <summary>
|
|
/// Helpdesk and support management business logic interface
|
|
/// Handles ticket lifecycle, escalation, and knowledge management
|
|
/// </summary>
|
|
public interface IHelpdeskLogic : ILogic
|
|
{
|
|
/// <summary>
|
|
/// Creates a new support ticket with automated classification
|
|
/// </summary>
|
|
Task<Result<Ticket>> CreateTicketAsync(TicketCreationRequest request);
|
|
|
|
/// <summary>
|
|
/// Updates ticket status with audit trail and notification
|
|
/// </summary>
|
|
Task<Result<Ticket>> UpdateTicketStatusAsync(int ticketId, TicketStatus newStatus, string comment);
|
|
|
|
/// <summary>
|
|
/// Assigns ticket to a support agent with workload balancing
|
|
/// </summary>
|
|
Task<Result<Ticket>> AssignTicketAsync(int ticketId, int assigneeId, string reason);
|
|
|
|
/// <summary>
|
|
/// Processes ticket escalation based on SLA rules
|
|
/// </summary>
|
|
Task<Result<EscalationResult>> EscalateTicketAsync(int ticketId, EscalationReason reason);
|
|
|
|
/// <summary>
|
|
/// Retrieves tickets based on filter criteria with pagination
|
|
/// </summary>
|
|
Task<Result<TicketSearchResult>> GetTicketsAsync(TicketFilter filter);
|
|
|
|
/// <summary>
|
|
/// Adds comment or update to existing ticket
|
|
/// </summary>
|
|
Task<Result<TicketComment>> AddTicketCommentAsync(int ticketId, TicketComment comment);
|
|
|
|
/// <summary>
|
|
/// Searches knowledge base for relevant articles
|
|
/// </summary>
|
|
Task<Result<KnowledgeArticle[]>> SearchKnowledgeBaseAsync(string query, int maxResults);
|
|
|
|
/// <summary>
|
|
/// Calculates SLA compliance metrics for tickets
|
|
/// </summary>
|
|
Task<Result<SLAMetrics>> CalculateSLAMetricsAsync(SLAMetricsRequest request);
|
|
}
|
|
|
|
public enum TicketStatus
|
|
{
|
|
Open = 1,
|
|
InProgress = 2,
|
|
Pending = 3,
|
|
Resolved = 4,
|
|
Closed = 5,
|
|
Cancelled = 6
|
|
}
|
|
|
|
public enum TicketPriority
|
|
{
|
|
Low = 1,
|
|
Normal = 2,
|
|
High = 3,
|
|
Urgent = 4,
|
|
Critical = 5
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.2 Data Access Interfaces
|
|
|
|
#### **2.2.1 Repository Pattern Interfaces**
|
|
|
|
**Generic Repository Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.DAO
|
|
{
|
|
/// <summary>
|
|
/// Generic repository interface for entity data access
|
|
/// Provides standard CRUD operations with async support
|
|
/// </summary>
|
|
/// <typeparam name="TEntity">Entity type</typeparam>
|
|
/// <typeparam name="TKey">Primary key type</typeparam>
|
|
public interface IRepository<TEntity, TKey> : IDisposable
|
|
where TEntity : class, IEntity<TKey>
|
|
{
|
|
/// <summary>
|
|
/// Retrieves entity by primary key
|
|
/// </summary>
|
|
Task<TEntity> GetByIdAsync(TKey id);
|
|
|
|
/// <summary>
|
|
/// Retrieves all entities with optional filtering
|
|
/// </summary>
|
|
Task<IEnumerable<TEntity>> GetAllAsync(Expression<Func<TEntity, bool>> predicate = null);
|
|
|
|
/// <summary>
|
|
/// Finds entities matching the specified criteria
|
|
/// </summary>
|
|
Task<IEnumerable<TEntity>> FindAsync(Expression<Func<TEntity, bool>> predicate);
|
|
|
|
/// <summary>
|
|
/// Finds a single entity matching the criteria
|
|
/// </summary>
|
|
Task<TEntity> FindSingleAsync(Expression<Func<TEntity, bool>> predicate);
|
|
|
|
/// <summary>
|
|
/// Adds new entity to the repository
|
|
/// </summary>
|
|
Task<TEntity> AddAsync(TEntity entity);
|
|
|
|
/// <summary>
|
|
/// Updates existing entity
|
|
/// </summary>
|
|
Task<TEntity> UpdateAsync(TEntity entity);
|
|
|
|
/// <summary>
|
|
/// Removes entity from the repository
|
|
/// </summary>
|
|
Task DeleteAsync(TKey id);
|
|
|
|
/// <summary>
|
|
/// Removes entity by reference
|
|
/// </summary>
|
|
Task DeleteAsync(TEntity entity);
|
|
|
|
/// <summary>
|
|
/// Counts entities matching the criteria
|
|
/// </summary>
|
|
Task<int> CountAsync(Expression<Func<TEntity, bool>> predicate = null);
|
|
|
|
/// <summary>
|
|
/// Checks if any entities match the criteria
|
|
/// </summary>
|
|
Task<bool> AnyAsync(Expression<Func<TEntity, bool>> predicate = null);
|
|
|
|
/// <summary>
|
|
/// Executes custom query with parameters
|
|
/// </summary>
|
|
Task<IEnumerable<TResult>> ExecuteQueryAsync<TResult>(string query, object parameters = null);
|
|
|
|
/// <summary>
|
|
/// Begins a new transaction scope
|
|
/// </summary>
|
|
Task<IDbTransaction> BeginTransactionAsync();
|
|
}
|
|
}
|
|
```
|
|
|
|
**Customer Repository Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.DAO.Sales
|
|
{
|
|
/// <summary>
|
|
/// Specialized repository interface for customer entities
|
|
/// Extends generic repository with customer-specific operations
|
|
/// </summary>
|
|
public interface ICustomerRepository : IRepository<Customer, int>
|
|
{
|
|
/// <summary>
|
|
/// Finds customers by company name with fuzzy matching
|
|
/// </summary>
|
|
Task<Customer[]> FindByCompanyNameAsync(string companyName, bool exactMatch = false);
|
|
|
|
/// <summary>
|
|
/// Finds customers by email address
|
|
/// </summary>
|
|
Task<Customer> FindByEmailAsync(string email);
|
|
|
|
/// <summary>
|
|
/// Retrieves customers with their related entities (addresses, contacts, orders)
|
|
/// </summary>
|
|
Task<Customer[]> GetCustomersWithRelatedDataAsync(CustomerFilter filter);
|
|
|
|
/// <summary>
|
|
/// Performs full-text search across customer data
|
|
/// </summary>
|
|
Task<CustomerSearchResult> FullTextSearchAsync(string searchTerm, int maxResults, int offset);
|
|
|
|
/// <summary>
|
|
/// Gets customer statistics for dashboard display
|
|
/// </summary>
|
|
Task<CustomerStatistics> GetCustomerStatisticsAsync(DateTime? fromDate = null);
|
|
|
|
/// <summary>
|
|
/// Validates customer uniqueness constraints
|
|
/// </summary>
|
|
Task<ValidationResult> ValidateCustomerUniquenessAsync(Customer customer);
|
|
|
|
/// <summary>
|
|
/// Archives inactive customers based on criteria
|
|
/// </summary>
|
|
Task<ArchiveResult> ArchiveInactiveCustomersAsync(CustomerArchiveFilter filter);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Customer search result with metadata
|
|
/// </summary>
|
|
public class CustomerSearchResult
|
|
{
|
|
public Customer[] Customers { get; set; }
|
|
public int TotalCount { get; set; }
|
|
public int PageSize { get; set; }
|
|
public int PageNumber { get; set; }
|
|
public string[] SearchTerms { get; set; }
|
|
public TimeSpan SearchDuration { get; set; }
|
|
}
|
|
}
|
|
```
|
|
|
|
#### **2.2.2 Database Context Interfaces**
|
|
|
|
**NHibernate Session Management**
|
|
```csharp
|
|
namespace Centron.Interfaces.DAO
|
|
{
|
|
/// <summary>
|
|
/// NHibernate session factory interface for database connectivity
|
|
/// Manages database sessions and transactions
|
|
/// </summary>
|
|
public interface INHibernateSessionFactory
|
|
{
|
|
/// <summary>
|
|
/// Creates a new database session
|
|
/// </summary>
|
|
ISession OpenSession();
|
|
|
|
/// <summary>
|
|
/// Creates a new database session asynchronously
|
|
/// </summary>
|
|
Task<ISession> OpenSessionAsync();
|
|
|
|
/// <summary>
|
|
/// Creates a stateless session for bulk operations
|
|
/// </summary>
|
|
IStatelessSession OpenStatelessSession();
|
|
|
|
/// <summary>
|
|
/// Gets current session if available
|
|
/// </summary>
|
|
ISession GetCurrentSession();
|
|
|
|
/// <summary>
|
|
/// Validates database schema compatibility
|
|
/// </summary>
|
|
Task<SchemaValidationResult> ValidateSchemaAsync();
|
|
|
|
/// <summary>
|
|
/// Closes the session factory and releases resources
|
|
/// </summary>
|
|
void Close();
|
|
}
|
|
|
|
/// <summary>
|
|
/// Database connection configuration interface
|
|
/// </summary>
|
|
public interface IDatabaseConfiguration
|
|
{
|
|
string ConnectionString { get; }
|
|
string DatabaseProvider { get; }
|
|
bool ShowSql { get; }
|
|
bool FormatSql { get; }
|
|
string HbmMappingAssembly { get; }
|
|
CacheConfiguration CacheConfiguration { get; }
|
|
|
|
/// <summary>
|
|
/// Builds NHibernate configuration
|
|
/// </summary>
|
|
Configuration BuildConfiguration();
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.3 Module System Interfaces
|
|
|
|
#### **2.3.1 Module Controller Interface**
|
|
|
|
**App Module Controller Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.Modules
|
|
{
|
|
/// <summary>
|
|
/// Interface for application module controllers
|
|
/// Defines module lifecycle and integration points
|
|
/// </summary>
|
|
public interface ICentronAppModuleController : IDisposable
|
|
{
|
|
/// <summary>
|
|
/// Unique module identifier
|
|
/// </summary>
|
|
string ModuleId { get; }
|
|
|
|
/// <summary>
|
|
/// Human-readable module name
|
|
/// </summary>
|
|
string ModuleName { get; }
|
|
|
|
/// <summary>
|
|
/// Module description for documentation
|
|
/// </summary>
|
|
string Description { get; }
|
|
|
|
/// <summary>
|
|
/// Module version information
|
|
/// </summary>
|
|
Version Version { get; }
|
|
|
|
/// <summary>
|
|
/// Required user rights for module access
|
|
/// </summary>
|
|
UserRight[] RequiredRights { get; }
|
|
|
|
/// <summary>
|
|
/// Module dependencies
|
|
/// </summary>
|
|
string[] Dependencies { get; }
|
|
|
|
/// <summary>
|
|
/// Module initialization priority (lower values load first)
|
|
/// </summary>
|
|
int LoadPriority { get; }
|
|
|
|
/// <summary>
|
|
/// Indicates if module is currently loaded
|
|
/// </summary>
|
|
bool IsLoaded { get; }
|
|
|
|
/// <summary>
|
|
/// Determines if module can be loaded in current context
|
|
/// </summary>
|
|
bool CanLoad(IModuleContext context);
|
|
|
|
/// <summary>
|
|
/// Initializes and loads the module
|
|
/// </summary>
|
|
Task<ModuleLoadResult> LoadAsync(IModuleContext context);
|
|
|
|
/// <summary>
|
|
/// Unloads the module and releases resources
|
|
/// </summary>
|
|
Task<ModuleUnloadResult> UnloadAsync();
|
|
|
|
/// <summary>
|
|
/// Refreshes module state and configuration
|
|
/// </summary>
|
|
Task RefreshAsync();
|
|
|
|
/// <summary>
|
|
/// Gets module configuration settings
|
|
/// </summary>
|
|
IModuleConfiguration GetConfiguration();
|
|
|
|
/// <summary>
|
|
/// Validates module integrity and dependencies
|
|
/// </summary>
|
|
Task<ModuleValidationResult> ValidateAsync();
|
|
}
|
|
|
|
/// <summary>
|
|
/// Module execution context
|
|
/// </summary>
|
|
public interface IModuleContext
|
|
{
|
|
IServiceProvider ServiceProvider { get; }
|
|
ILogger Logger { get; }
|
|
IUserContext UserContext { get; }
|
|
IApplicationContext ApplicationContext { get; }
|
|
IDictionary<string, object> Properties { get; }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Module load result with status and metadata
|
|
/// </summary>
|
|
public class ModuleLoadResult
|
|
{
|
|
public bool Success { get; set; }
|
|
public string Message { get; set; }
|
|
public TimeSpan LoadDuration { get; set; }
|
|
public string[] LoadedComponents { get; set; }
|
|
public Exception Exception { get; set; }
|
|
}
|
|
}
|
|
```
|
|
|
|
#### **2.3.2 Ribbon Integration Interface**
|
|
|
|
**Ribbon Control Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.UI
|
|
{
|
|
/// <summary>
|
|
/// Interface for modules that integrate with the application ribbon
|
|
/// Provides ribbon customization and command handling
|
|
/// </summary>
|
|
public interface IRibbonControlModule
|
|
{
|
|
/// <summary>
|
|
/// Creates ribbon pages for the module
|
|
/// </summary>
|
|
RibbonPage[] CreateRibbonPages();
|
|
|
|
/// <summary>
|
|
/// Creates context-sensitive ribbon tabs
|
|
/// </summary>
|
|
RibbonPageCategory[] CreateContextualTabs();
|
|
|
|
/// <summary>
|
|
/// Registers ribbon commands with the command manager
|
|
/// </summary>
|
|
void RegisterRibbonCommands(ICommandManager commandManager);
|
|
|
|
/// <summary>
|
|
/// Updates ribbon state based on current selection/context
|
|
/// </summary>
|
|
void UpdateRibbonState(IRibbonUpdateContext context);
|
|
|
|
/// <summary>
|
|
/// Handles ribbon command execution
|
|
/// </summary>
|
|
Task<CommandResult> ExecuteRibbonCommandAsync(string commandId, object parameter);
|
|
|
|
/// <summary>
|
|
/// Determines if ribbon command can execute in current context
|
|
/// </summary>
|
|
bool CanExecuteRibbonCommand(string commandId, object parameter);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Ribbon update context for state management
|
|
/// </summary>
|
|
public interface IRibbonUpdateContext
|
|
{
|
|
object SelectedItem { get; }
|
|
object[] SelectedItems { get; }
|
|
string CurrentView { get; }
|
|
IUserContext UserContext { get; }
|
|
IDictionary<string, object> ContextData { get; }
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. External System Interfaces
|
|
|
|
### 3.1 Web Service Interfaces
|
|
|
|
#### **3.1.1 REST Service Interface**
|
|
|
|
**Main REST Service Interface**
|
|
```csharp
|
|
namespace Centron.Host.Services
|
|
{
|
|
/// <summary>
|
|
/// Main REST service interface for external API access
|
|
/// Implements comprehensive business functionality via HTTP endpoints
|
|
/// </summary>
|
|
[ServiceContract]
|
|
public partial interface ICentronRestService
|
|
{
|
|
// Authentication and Session Management
|
|
[OperationContract]
|
|
[WebInvoke(Method = "POST", UriTemplate = "Authenticate")]
|
|
Response<AuthenticationResult> Authenticate(Request<AuthenticationRequest> request);
|
|
|
|
[OperationContract]
|
|
[WebInvoke(Method = "POST", UriTemplate = "RefreshToken")]
|
|
Response<TokenRefreshResult> RefreshToken(Request<TokenRefreshRequest> request);
|
|
|
|
[OperationContract]
|
|
[WebInvoke(Method = "POST", UriTemplate = "Logout")]
|
|
Response Logout(Request<LogoutRequest> request);
|
|
|
|
// User and Rights Management
|
|
[OperationContract]
|
|
[WebInvoke(Method = "POST", UriTemplate = "GetUserRights")]
|
|
[Authenticate]
|
|
Response<UserRightsDTO> GetUserRights(Request<UserRightsFilter> request);
|
|
|
|
[OperationContract]
|
|
[WebInvoke(Method = "POST", UriTemplate = "UpdateUserRights")]
|
|
[Authenticate]
|
|
[RequireRight(UserRightsConst.Administration.Users.EDIT_USER_RIGHTS)]
|
|
Response UpdateUserRights(Request<UpdateUserRightsRequest> request);
|
|
|
|
// System Health and Monitoring
|
|
[OperationContract]
|
|
[WebInvoke(Method = "GET", UriTemplate = "Health")]
|
|
Response<SystemHealthStatus> GetSystemHealth();
|
|
|
|
[OperationContract]
|
|
[WebInvoke(Method = "GET", UriTemplate = "Version")]
|
|
Response<SystemVersionInfo> GetSystemVersion();
|
|
}
|
|
|
|
/// <summary>
|
|
/// Authentication attribute for securing endpoints
|
|
/// </summary>
|
|
[AttributeUsage(AttributeTargets.Method)]
|
|
public class AuthenticateAttribute : Attribute
|
|
{
|
|
public bool RequireActiveSession { get; set; } = true;
|
|
public string[] AllowedRoles { get; set; }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Authorization attribute for role-based access control
|
|
/// </summary>
|
|
[AttributeUsage(AttributeTargets.Method)]
|
|
public class RequireRightAttribute : Attribute
|
|
{
|
|
public int RequiredRightId { get; }
|
|
|
|
public RequireRightAttribute(int rightId)
|
|
{
|
|
RequiredRightId = rightId;
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### **3.1.2 Request/Response Patterns**
|
|
|
|
**Standard Request/Response DTOs**
|
|
```csharp
|
|
namespace Centron.Host.Messages
|
|
{
|
|
/// <summary>
|
|
/// Generic request wrapper for all API operations
|
|
/// Provides standardized request metadata and context
|
|
/// </summary>
|
|
/// <typeparam name="T">Request data type</typeparam>
|
|
[DataContract]
|
|
public class Request<T>
|
|
{
|
|
[DataMember]
|
|
public Guid RequestId { get; set; } = Guid.NewGuid();
|
|
|
|
[DataMember]
|
|
public DateTime Timestamp { get; set; } = DateTime.UtcNow;
|
|
|
|
[DataMember]
|
|
public string ClientVersion { get; set; }
|
|
|
|
[DataMember]
|
|
public string UserAgent { get; set; }
|
|
|
|
[DataMember]
|
|
public string CorrelationId { get; set; }
|
|
|
|
[DataMember]
|
|
public T Data { get; set; }
|
|
|
|
[DataMember]
|
|
public Dictionary<string, string> Headers { get; set; } = new();
|
|
|
|
[DataMember]
|
|
public RequestContext Context { get; set; }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Generic response wrapper for all API operations
|
|
/// Provides standardized response metadata and error handling
|
|
/// </summary>
|
|
/// <typeparam name="T">Response data type</typeparam>
|
|
[DataContract]
|
|
public class Response<T> : Response
|
|
{
|
|
[DataMember]
|
|
public T Data { get; set; }
|
|
|
|
public static Response<T> Success(T data, string message = null)
|
|
{
|
|
return new Response<T>
|
|
{
|
|
Success = true,
|
|
Data = data,
|
|
Message = message,
|
|
Timestamp = DateTime.UtcNow
|
|
};
|
|
}
|
|
}
|
|
|
|
/// <summary>
|
|
/// Base response class with common properties
|
|
/// </summary>
|
|
[DataContract]
|
|
public class Response
|
|
{
|
|
[DataMember]
|
|
public bool Success { get; set; }
|
|
|
|
[DataMember]
|
|
public string Message { get; set; }
|
|
|
|
[DataMember]
|
|
public DateTime Timestamp { get; set; }
|
|
|
|
[DataMember]
|
|
public Guid RequestId { get; set; }
|
|
|
|
[DataMember]
|
|
public ErrorDetail[] Errors { get; set; }
|
|
|
|
[DataMember]
|
|
public Dictionary<string, object> Metadata { get; set; } = new();
|
|
|
|
public static Response Error(string message, params ErrorDetail[] errors)
|
|
{
|
|
return new Response
|
|
{
|
|
Success = false,
|
|
Message = message,
|
|
Errors = errors,
|
|
Timestamp = DateTime.UtcNow
|
|
};
|
|
}
|
|
}
|
|
|
|
/// <summary>
|
|
/// Detailed error information for API responses
|
|
/// </summary>
|
|
[DataContract]
|
|
public class ErrorDetail
|
|
{
|
|
[DataMember]
|
|
public string Code { get; set; }
|
|
|
|
[DataMember]
|
|
public string Message { get; set; }
|
|
|
|
[DataMember]
|
|
public string Field { get; set; }
|
|
|
|
[DataMember]
|
|
public ErrorSeverity Severity { get; set; }
|
|
|
|
[DataMember]
|
|
public Dictionary<string, object> AdditionalData { get; set; }
|
|
}
|
|
|
|
public enum ErrorSeverity
|
|
{
|
|
Info = 1,
|
|
Warning = 2,
|
|
Error = 3,
|
|
Critical = 4
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3.2 Database Interfaces
|
|
|
|
#### **3.2.1 Connection Management Interface**
|
|
|
|
**Database Connection Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.DAO
|
|
{
|
|
/// <summary>
|
|
/// Database connection management interface
|
|
/// Handles multiple connection types and contexts
|
|
/// </summary>
|
|
public interface IDatabaseConnectionManager : IDisposable
|
|
{
|
|
/// <summary>
|
|
/// Current connection type
|
|
/// </summary>
|
|
CentronConnectionType ConnectionType { get; }
|
|
|
|
/// <summary>
|
|
/// Connection string for current context
|
|
/// </summary>
|
|
string ConnectionString { get; }
|
|
|
|
/// <summary>
|
|
/// Indicates if connection is currently active
|
|
/// </summary>
|
|
bool IsConnected { get; }
|
|
|
|
/// <summary>
|
|
/// Opens database connection
|
|
/// </summary>
|
|
Task<ConnectionResult> OpenConnectionAsync();
|
|
|
|
/// <summary>
|
|
/// Closes database connection
|
|
/// </summary>
|
|
Task CloseConnectionAsync();
|
|
|
|
/// <summary>
|
|
/// Tests connection validity
|
|
/// </summary>
|
|
Task<ConnectionHealthResult> TestConnectionAsync();
|
|
|
|
/// <summary>
|
|
/// Switches connection context
|
|
/// </summary>
|
|
Task<ConnectionResult> SwitchConnectionAsync(CentronConnectionType newConnectionType);
|
|
|
|
/// <summary>
|
|
/// Gets connection statistics
|
|
/// </summary>
|
|
Task<ConnectionStatistics> GetConnectionStatisticsAsync();
|
|
|
|
/// <summary>
|
|
/// Event fired when connection state changes
|
|
/// </summary>
|
|
event EventHandler<ConnectionStateChangedEventArgs> ConnectionStateChanged;
|
|
}
|
|
|
|
public enum CentronConnectionType
|
|
{
|
|
SqlServer = 1,
|
|
CentronWebServices = 2
|
|
}
|
|
|
|
/// <summary>
|
|
/// Connection operation result
|
|
/// </summary>
|
|
public class ConnectionResult
|
|
{
|
|
public bool Success { get; set; }
|
|
public string Message { get; set; }
|
|
public TimeSpan Duration { get; set; }
|
|
public Exception Exception { get; set; }
|
|
public CentronConnectionType ConnectionType { get; set; }
|
|
}
|
|
}
|
|
```
|
|
|
|
#### **3.2.2 Schema Management Interface**
|
|
|
|
**Database Schema Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.DAO
|
|
{
|
|
/// <summary>
|
|
/// Database schema management interface
|
|
/// Handles schema validation, migration, and versioning
|
|
/// </summary>
|
|
public interface IDatabaseSchemaManager
|
|
{
|
|
/// <summary>
|
|
/// Gets current database schema version
|
|
/// </summary>
|
|
Task<SchemaVersion> GetCurrentSchemaVersionAsync();
|
|
|
|
/// <summary>
|
|
/// Gets target schema version for application
|
|
/// </summary>
|
|
SchemaVersion GetTargetSchemaVersion();
|
|
|
|
/// <summary>
|
|
/// Validates database schema against expected structure
|
|
/// </summary>
|
|
Task<SchemaValidationResult> ValidateSchemaAsync();
|
|
|
|
/// <summary>
|
|
/// Migrates database schema to target version
|
|
/// </summary>
|
|
Task<SchemaMigrationResult> MigrateSchemaAsync(SchemaMigrationOptions options);
|
|
|
|
/// <summary>
|
|
/// Generates database schema script
|
|
/// </summary>
|
|
Task<string> GenerateSchemaScriptAsync(SchemaScriptOptions options);
|
|
|
|
/// <summary>
|
|
/// Gets available migration scripts
|
|
/// </summary>
|
|
Task<MigrationScript[]> GetAvailableMigrationScriptsAsync();
|
|
|
|
/// <summary>
|
|
/// Executes specific migration script
|
|
/// </summary>
|
|
Task<ScriptExecutionResult> ExecuteMigrationScriptAsync(int scriptNumber);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Schema version information
|
|
/// </summary>
|
|
public class SchemaVersion
|
|
{
|
|
public int Major { get; set; }
|
|
public int Minor { get; set; }
|
|
public int Patch { get; set; }
|
|
public int Build { get; set; }
|
|
public DateTime CreatedDate { get; set; }
|
|
public string Description { get; set; }
|
|
|
|
public override string ToString() => $"{Major}.{Minor}.{Patch}.{Build}";
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3.3 External API Interfaces
|
|
|
|
#### **3.3.1 Financial API Interface (FinAPI)**
|
|
|
|
**FinAPI Client Interface**
|
|
```csharp
|
|
namespace Centron.APIs.FinAPI
|
|
{
|
|
/// <summary>
|
|
/// FinAPI client interface for German banking integration
|
|
/// Provides comprehensive banking and financial services
|
|
/// </summary>
|
|
public interface IFinApiClient : IDisposable
|
|
{
|
|
/// <summary>
|
|
/// Indicates if client is properly initialized
|
|
/// </summary>
|
|
bool IsInitialized { get; }
|
|
|
|
/// <summary>
|
|
/// Indicates if client is authenticated with FinAPI
|
|
/// </summary>
|
|
bool IsAuthenticated { get; }
|
|
|
|
/// <summary>
|
|
/// Current REST API endpoint address
|
|
/// </summary>
|
|
string RestApiAddress { get; }
|
|
|
|
/// <summary>
|
|
/// Configures client for sandbox mode
|
|
/// </summary>
|
|
void SetSandBoxMode(bool sandBoxMode);
|
|
|
|
/// <summary>
|
|
/// Updates REST API endpoint address
|
|
/// </summary>
|
|
void SetNewRestApiAddress(string restApiAddress);
|
|
|
|
/// <summary>
|
|
/// Sets client credentials for API authentication
|
|
/// </summary>
|
|
void SetNewClientCredentials(string clientId, string clientSecret, string dataEncryptionKey);
|
|
|
|
/// <summary>
|
|
/// Sets dialog handler for user interactions
|
|
/// </summary>
|
|
void SetConnectionDialogHandler(IOnlineBankingConnectionDialog dialogHandler);
|
|
|
|
/// <summary>
|
|
/// Authenticates user and obtains access token
|
|
/// </summary>
|
|
Task<Result> LoginAndGetAccessToken(string username, string userpassword);
|
|
|
|
/// <summary>
|
|
/// Retrieves current user account information
|
|
/// </summary>
|
|
Task<Result<User>> GetUserAccount();
|
|
|
|
/// <summary>
|
|
/// Creates new user account
|
|
/// </summary>
|
|
Task<Result> CreateUserAccount(CreateUserAccountRequest createRequest);
|
|
|
|
/// <summary>
|
|
/// Updates existing user account
|
|
/// </summary>
|
|
Task<Result<User>> UpdateUserAccount(UpdateUserAccountRequest updateRequest);
|
|
|
|
/// <summary>
|
|
/// Changes user account password
|
|
/// </summary>
|
|
Task<Result> ChangeUserAccountPassword(ChangeUserAccountPasswordRequest changePasswordRequest);
|
|
|
|
/// <summary>
|
|
/// Imports new bank connection for user
|
|
/// </summary>
|
|
Task<Result<string>> ImportNewBankConnection(ImportNewBankConnectionRequest importRequest);
|
|
|
|
/// <summary>
|
|
/// Deletes existing bank connection
|
|
/// </summary>
|
|
Task<Result> DeleteBankConnection(long bankConnectionId);
|
|
|
|
/// <summary>
|
|
/// Removes specific account from bank connection
|
|
/// </summary>
|
|
Task<Result> RemoveAccountFromBankConnection(long bankAccountId);
|
|
|
|
/// <summary>
|
|
/// Loads all bank connections for user
|
|
/// </summary>
|
|
Task<Result<BankConnectionList>> LoadBankConnections();
|
|
|
|
/// <summary>
|
|
/// Loads bank accounts with optional filtering
|
|
/// </summary>
|
|
Task<Result<AccountList>> LoadBankAccounts(long? bankConnectionId = null);
|
|
|
|
/// <summary>
|
|
/// Retrieves account transactions with filtering
|
|
/// </summary>
|
|
Task<Result<List<IOnlineBankingAccountTransaction>>> GetAccountTransactions(IGetAccountTransactionsFilter filter);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Online banking connection dialog interface
|
|
/// </summary>
|
|
public interface IOnlineBankingConnectionDialog
|
|
{
|
|
Task<BankingCredentials> RequestCredentialsAsync(string bankName, string[] requiredFields);
|
|
Task<string> RequestTanAsync(TanRequest tanRequest);
|
|
Task NotifyConnectionStatusAsync(string status, bool isError = false);
|
|
}
|
|
}
|
|
```
|
|
|
|
#### **3.3.2 Shipping API Interfaces**
|
|
|
|
**GLS Shipping Interface**
|
|
```csharp
|
|
namespace Centron.Api.Gls
|
|
{
|
|
/// <summary>
|
|
/// GLS shipping service interface
|
|
/// Provides German shipping and logistics services
|
|
/// </summary>
|
|
public interface IGlsShippingClient : IDisposable
|
|
{
|
|
/// <summary>
|
|
/// Creates new shipment with GLS
|
|
/// </summary>
|
|
Task<Result<GlsShipment>> CreateShipmentAsync(GlsShipmentRequest request);
|
|
|
|
/// <summary>
|
|
/// Retrieves shipment tracking information
|
|
/// </summary>
|
|
Task<Result<GlsTrackingInfo>> GetTrackingInfoAsync(string trackingNumber);
|
|
|
|
/// <summary>
|
|
/// Cancels existing shipment
|
|
/// </summary>
|
|
Task<Result> CancelShipmentAsync(string shipmentId, string reason);
|
|
|
|
/// <summary>
|
|
/// Calculates shipping costs
|
|
/// </summary>
|
|
Task<Result<GlsShippingCost>> CalculateShippingCostAsync(GlsShippingCostRequest request);
|
|
|
|
/// <summary>
|
|
/// Retrieves available delivery options
|
|
/// </summary>
|
|
Task<Result<GlsDeliveryOption[]>> GetDeliveryOptionsAsync(string postalCode, string countryCode);
|
|
|
|
/// <summary>
|
|
/// Generates shipping label
|
|
/// </summary>
|
|
Task<Result<byte[]>> GenerateShippingLabelAsync(string shipmentId, LabelFormat format);
|
|
}
|
|
|
|
public enum LabelFormat
|
|
{
|
|
PDF,
|
|
PNG,
|
|
ZPL, // Zebra Programming Language
|
|
EPL // Eltron Programming Language
|
|
}
|
|
}
|
|
|
|
namespace Centron.Api.Shipcloud
|
|
{
|
|
/// <summary>
|
|
/// Shipcloud multi-carrier shipping interface
|
|
/// Provides access to multiple shipping providers
|
|
/// </summary>
|
|
public interface IShipcloudClient : IDisposable
|
|
{
|
|
/// <summary>
|
|
/// Gets available carriers and their services
|
|
/// </summary>
|
|
Task<Result<CarrierService[]>> GetAvailableCarriersAsync(string countryCode = "DE");
|
|
|
|
/// <summary>
|
|
/// Calculates shipping quotes from multiple carriers
|
|
/// </summary>
|
|
Task<Result<ShippingQuote[]>> GetShippingQuotesAsync(ShippingQuoteRequest request);
|
|
|
|
/// <summary>
|
|
/// Creates shipment with selected carrier
|
|
/// </summary>
|
|
Task<Result<ShipcloudShipment>> CreateShipmentAsync(ShipcloudShipmentRequest request);
|
|
|
|
/// <summary>
|
|
/// Retrieves comprehensive tracking information
|
|
/// </summary>
|
|
Task<Result<ShipcloudTrackingInfo>> GetTrackingInfoAsync(string shipmentId);
|
|
|
|
/// <summary>
|
|
/// Updates shipment information
|
|
/// </summary>
|
|
Task<Result<ShipcloudShipment>> UpdateShipmentAsync(string shipmentId, ShipmentUpdateRequest request);
|
|
}
|
|
}
|
|
```
|
|
|
|
#### **3.3.3 Product Data API Interfaces**
|
|
|
|
**ITscope Product Data Interface**
|
|
```csharp
|
|
namespace Centron.APIs.ITscopeDataAccess
|
|
{
|
|
/// <summary>
|
|
/// ITscope product database interface
|
|
/// Provides comprehensive IT product information and pricing
|
|
/// </summary>
|
|
public interface IITscopeDataClient : IDisposable
|
|
{
|
|
/// <summary>
|
|
/// Searches products by various criteria
|
|
/// </summary>
|
|
Task<Result<ITscopeProduct[]>> SearchProductsAsync(ITscopeSearchRequest request);
|
|
|
|
/// <summary>
|
|
/// Retrieves detailed product information
|
|
/// </summary>
|
|
Task<Result<ITscopeProductDetail>> GetProductDetailAsync(string productId);
|
|
|
|
/// <summary>
|
|
/// Gets current product pricing information
|
|
/// </summary>
|
|
Task<Result<ITscopePrice[]>> GetProductPricingAsync(string productId, string countryCode = "DE");
|
|
|
|
/// <summary>
|
|
/// Retrieves product availability information
|
|
/// </summary>
|
|
Task<Result<ITscopeAvailability[]>> GetProductAvailabilityAsync(string productId);
|
|
|
|
/// <summary>
|
|
/// Gets product categories and classification
|
|
/// </summary>
|
|
Task<Result<ITscopeCategory[]>> GetProductCategoriesAsync();
|
|
|
|
/// <summary>
|
|
/// Synchronizes product data with local database
|
|
/// </summary>
|
|
Task<Result<SynchronizationResult>> SynchronizeProductDataAsync(SynchronizationRequest request);
|
|
}
|
|
|
|
/// <summary>
|
|
/// ITscope product search criteria
|
|
/// </summary>
|
|
public class ITscopeSearchRequest
|
|
{
|
|
public string SearchTerm { get; set; }
|
|
public string[] Categories { get; set; }
|
|
public string Manufacturer { get; set; }
|
|
public decimal? MinPrice { get; set; }
|
|
public decimal? MaxPrice { get; set; }
|
|
public bool InStockOnly { get; set; }
|
|
public string CountryCode { get; set; } = "DE";
|
|
public int MaxResults { get; set; } = 100;
|
|
public SortOptions SortBy { get; set; }
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Interface Integration Patterns
|
|
|
|
### 4.1 Service Integration Pattern
|
|
|
|
#### **4.1.1 ClassContainer Integration**
|
|
|
|
**Service Resolution Pattern**
|
|
```csharp
|
|
namespace CentronSoftware.Centron.WPF.UI.Services.Container
|
|
{
|
|
/// <summary>
|
|
/// Centralized service container managing dual implementation pattern
|
|
/// Provides unified access to both BL and WS implementations
|
|
/// </summary>
|
|
public class ClassContainer
|
|
{
|
|
/// <summary>
|
|
/// Resolves service instance based on current connection type
|
|
/// </summary>
|
|
public T GetInstance<T>(object[] paramObjects = null)
|
|
{
|
|
this.InitializeAsync().Wait();
|
|
|
|
WindsorContainer container = this._currentContainer ?? this._rootContainer;
|
|
|
|
if (paramObjects != null)
|
|
{
|
|
var arguments = Arguments.FromTyped(paramObjects);
|
|
return container.Resolve<T>(arguments);
|
|
}
|
|
|
|
return container.Resolve<T>();
|
|
}
|
|
|
|
/// <summary>
|
|
/// Executes operation with automatic service resolution and disposal
|
|
/// </summary>
|
|
public async Task<Result<T>> WithInstance<T>(Func<T, Task<Result<T>>> operation)
|
|
{
|
|
var instance = GetInstance<T>();
|
|
try
|
|
{
|
|
return await operation(instance);
|
|
}
|
|
finally
|
|
{
|
|
ReleaseInstance(instance);
|
|
}
|
|
}
|
|
|
|
/// <summary>
|
|
/// Extension method for error handling
|
|
/// </summary>
|
|
public static class ResultExtensions
|
|
{
|
|
public static T ThrowIfError<T>(this Task<Result<T>> resultTask)
|
|
{
|
|
var result = resultTask.Result;
|
|
if (result.HasError)
|
|
{
|
|
throw new BusinessLogicException(result.ErrorMessage, result.Exception);
|
|
}
|
|
return result.Data;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// Usage Example
|
|
var customers = await ClassContainer.Instance
|
|
.WithInstance((ICustomerLogic logic) => logic.GetCustomersAsync(filter))
|
|
.ThrowIfError();
|
|
```
|
|
|
|
#### **4.1.2 Async Operation Pattern**
|
|
|
|
**Async Interface Implementation**
|
|
```csharp
|
|
/// <summary>
|
|
/// Standardized async operation pattern for all interfaces
|
|
/// Ensures consistent behavior across BL and WS implementations
|
|
/// </summary>
|
|
public abstract class AsyncOperationBase<T>
|
|
{
|
|
protected readonly ILogger _logger;
|
|
protected readonly CancellationToken _cancellationToken;
|
|
|
|
protected async Task<Result<TResult>> ExecuteAsync<TResult>(
|
|
Func<Task<TResult>> operation,
|
|
string operationName = null)
|
|
{
|
|
var stopwatch = Stopwatch.StartNew();
|
|
try
|
|
{
|
|
_logger?.LogDebug($"Starting operation: {operationName}");
|
|
|
|
var result = await operation();
|
|
|
|
stopwatch.Stop();
|
|
_logger?.LogDebug($"Operation {operationName} completed in {stopwatch.ElapsedMilliseconds}ms");
|
|
|
|
return Result<TResult>.AsSuccess(result);
|
|
}
|
|
catch (Exception ex)
|
|
{
|
|
stopwatch.Stop();
|
|
_logger?.LogError(ex, $"Operation {operationName} failed after {stopwatch.ElapsedMilliseconds}ms");
|
|
|
|
return Result<TResult>.AsError(ex.Message, ex);
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.2 Error Handling Patterns
|
|
|
|
#### **4.2.1 Standardized Error Handling**
|
|
|
|
**Global Error Handling Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.Common
|
|
{
|
|
/// <summary>
|
|
/// Global error handling interface for consistent error management
|
|
/// </summary>
|
|
public interface IErrorHandler
|
|
{
|
|
/// <summary>
|
|
/// Handles business logic errors
|
|
/// </summary>
|
|
Task<ErrorHandlingResult> HandleBusinessErrorAsync(Exception exception, IOperationContext context);
|
|
|
|
/// <summary>
|
|
/// Handles validation errors
|
|
/// </summary>
|
|
Task<ErrorHandlingResult> HandleValidationErrorAsync(ValidationException exception, IOperationContext context);
|
|
|
|
/// <summary>
|
|
/// Handles system errors
|
|
/// </summary>
|
|
Task<ErrorHandlingResult> HandleSystemErrorAsync(SystemException exception, IOperationContext context);
|
|
|
|
/// <summary>
|
|
/// Handles external API errors
|
|
/// </summary>
|
|
Task<ErrorHandlingResult> HandleExternalApiErrorAsync(ExternalApiException exception, IOperationContext context);
|
|
|
|
/// <summary>
|
|
/// Transforms exceptions to user-friendly messages
|
|
/// </summary>
|
|
string GetUserFriendlyMessage(Exception exception, CultureInfo culture);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Error handling result with recommended action
|
|
/// </summary>
|
|
public class ErrorHandlingResult
|
|
{
|
|
public ErrorHandlingAction RecommendedAction { get; set; }
|
|
public string UserMessage { get; set; }
|
|
public string LogMessage { get; set; }
|
|
public bool ShouldRetry { get; set; }
|
|
public TimeSpan RetryDelay { get; set; }
|
|
public int MaxRetryAttempts { get; set; }
|
|
public Dictionary<string, object> Context { get; set; }
|
|
}
|
|
|
|
public enum ErrorHandlingAction
|
|
{
|
|
DisplayError,
|
|
LogAndContinue,
|
|
RetryOperation,
|
|
EscalateToSupport,
|
|
GracefulDegradation,
|
|
TerminateOperation
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Interface Versioning and Evolution
|
|
|
|
### 5.1 Version Management Strategy
|
|
|
|
#### **5.1.1 Interface Versioning**
|
|
|
|
**Versioned Interface Pattern**
|
|
```csharp
|
|
namespace Centron.Interfaces.Versioning
|
|
{
|
|
/// <summary>
|
|
/// Interface versioning support for backward compatibility
|
|
/// </summary>
|
|
public interface IVersionedInterface
|
|
{
|
|
/// <summary>
|
|
/// Interface version information
|
|
/// </summary>
|
|
InterfaceVersion Version { get; }
|
|
|
|
/// <summary>
|
|
/// Supported interface versions
|
|
/// </summary>
|
|
InterfaceVersion[] SupportedVersions { get; }
|
|
|
|
/// <summary>
|
|
/// Checks if specific version is supported
|
|
/// </summary>
|
|
bool IsVersionSupported(InterfaceVersion version);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Interface version information
|
|
/// </summary>
|
|
public class InterfaceVersion : IComparable<InterfaceVersion>
|
|
{
|
|
public int Major { get; set; }
|
|
public int Minor { get; set; }
|
|
public int Patch { get; set; }
|
|
public string PreRelease { get; set; }
|
|
|
|
public bool IsCompatibleWith(InterfaceVersion other)
|
|
{
|
|
return Major == other.Major && Minor >= other.Minor;
|
|
}
|
|
|
|
public int CompareTo(InterfaceVersion other)
|
|
{
|
|
// Standard semantic versioning comparison
|
|
var majorComparison = Major.CompareTo(other.Major);
|
|
if (majorComparison != 0) return majorComparison;
|
|
|
|
var minorComparison = Minor.CompareTo(other.Minor);
|
|
if (minorComparison != 0) return minorComparison;
|
|
|
|
return Patch.CompareTo(other.Patch);
|
|
}
|
|
|
|
public override string ToString() => $"{Major}.{Minor}.{Patch}" +
|
|
(!string.IsNullOrEmpty(PreRelease) ? $"-{PreRelease}" : "");
|
|
}
|
|
}
|
|
```
|
|
|
|
### 5.2 Interface Evolution Guidelines
|
|
|
|
#### **5.2.1 Breaking Change Management**
|
|
|
|
**Interface Evolution Rules**
|
|
1. **Additive Changes** (Non-breaking):
|
|
- Adding new methods to interfaces (with default implementations)
|
|
- Adding new optional parameters to existing methods
|
|
- Adding new properties to DTOs
|
|
- Adding new enum values (when used as flags)
|
|
|
|
2. **Modify Changes** (Potentially breaking):
|
|
- Changing method signatures
|
|
- Modifying return types
|
|
- Changing exception types
|
|
- Renaming members
|
|
|
|
3. **Removal Changes** (Breaking):
|
|
- Removing methods or properties
|
|
- Removing enum values
|
|
- Removing entire interfaces
|
|
|
|
**Migration Support Interface**
|
|
```csharp
|
|
namespace Centron.Interfaces.Migration
|
|
{
|
|
/// <summary>
|
|
/// Interface migration support for managing breaking changes
|
|
/// </summary>
|
|
public interface IInterfaceMigrationSupport<TOld, TNew>
|
|
{
|
|
/// <summary>
|
|
/// Migrates from old interface version to new version
|
|
/// </summary>
|
|
TNew MigrateToNewVersion(TOld oldVersion);
|
|
|
|
/// <summary>
|
|
/// Provides backward compatibility adapter
|
|
/// </summary>
|
|
TOld CreateBackwardCompatibilityAdapter(TNew newVersion);
|
|
|
|
/// <summary>
|
|
/// Validates migration compatibility
|
|
/// </summary>
|
|
MigrationValidationResult ValidateMigration(TOld oldVersion);
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Interface Documentation Standards
|
|
|
|
### 6.1 Documentation Requirements
|
|
|
|
#### **6.1.1 Interface Documentation Template**
|
|
|
|
```csharp
|
|
namespace Centron.Interfaces.Example
|
|
{
|
|
/// <summary>
|
|
/// [Brief description of the interface purpose and scope]
|
|
///
|
|
/// This interface provides [detailed description of functionality].
|
|
/// It supports [key capabilities and features].
|
|
///
|
|
/// Implementation Notes:
|
|
/// - [Important implementation considerations]
|
|
/// - [Performance characteristics]
|
|
/// - [Thread safety information]
|
|
/// - [Error handling behavior]
|
|
///
|
|
/// Usage Examples:
|
|
/// <code>
|
|
/// // Basic usage example
|
|
/// var service = container.GetInstance<IExampleService>();
|
|
/// var result = await service.PerformOperationAsync(parameters);
|
|
/// </code>
|
|
///
|
|
/// Version History:
|
|
/// - 1.0.0: Initial version
|
|
/// - 1.1.0: Added support for [new feature]
|
|
/// - 2.0.0: Breaking change - [description of change]
|
|
///
|
|
/// Related Interfaces:
|
|
/// <see cref="IRelatedInterface"/>
|
|
/// <see cref="IAnotherInterface"/>
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Special considerations:
|
|
/// - [Security implications]
|
|
/// - [Performance recommendations]
|
|
/// - [Configuration requirements]
|
|
/// </remarks>
|
|
public interface IExampleService : IDisposable
|
|
{
|
|
/// <summary>
|
|
/// [Brief description of method purpose]
|
|
///
|
|
/// Detailed description of what this method does, including:
|
|
/// - Business logic performed
|
|
/// - Side effects or state changes
|
|
/// - Prerequisites or preconditions
|
|
/// - Post-conditions or guarantees
|
|
/// </summary>
|
|
/// <param name="parameter">[Parameter description with valid values, constraints, and defaults]</param>
|
|
/// <returns>
|
|
/// [Description of return value including:
|
|
/// - Success case return values
|
|
/// - Error conditions and return values
|
|
/// - Null return conditions]
|
|
/// </returns>
|
|
/// <exception cref="ArgumentNullException">Thrown when [specific condition]</exception>
|
|
/// <exception cref="InvalidOperationException">Thrown when [specific condition]</exception>
|
|
/// <example>
|
|
/// <code>
|
|
/// // Example usage
|
|
/// var result = await service.ExampleMethodAsync("validInput");
|
|
/// if (result.IsSuccess)
|
|
/// {
|
|
/// // Handle success
|
|
/// ProcessResult(result.Data);
|
|
/// }
|
|
/// else
|
|
/// {
|
|
/// // Handle error
|
|
/// LogError(result.ErrorMessage);
|
|
/// }
|
|
/// </code>
|
|
/// </example>
|
|
/// <seealso cref="RelatedMethod"/>
|
|
Task<Result<ReturnType>> ExampleMethodAsync(string parameter);
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Conclusion
|
|
|
|
### 7.1 Interface Architecture Summary
|
|
|
|
The Centron Enterprise Application implements a comprehensive interface architecture that provides:
|
|
|
|
1. **Standardization**: Consistent patterns across all system interfaces
|
|
2. **Flexibility**: Dual implementation support (BL/WS) through ILogic pattern
|
|
3. **Extensibility**: Plugin-based module system with well-defined contracts
|
|
4. **Maintainability**: Clear separation of concerns and dependency inversion
|
|
5. **Reliability**: Robust error handling and validation throughout
|
|
|
|
### 7.2 Key Interface Patterns
|
|
|
|
- **ILogic Pattern**: Dual implementation support for both direct database and web service access
|
|
- **Repository Pattern**: Standardized data access with generic and specialized implementations
|
|
- **Request/Response Pattern**: Consistent API communication with metadata and error handling
|
|
- **Module Interface Pattern**: Extensible plugin architecture with lifecycle management
|
|
- **Service Integration Pattern**: ClassContainer-based dependency injection and service resolution
|
|
|
|
### 7.3 Interface Evolution Strategy
|
|
|
|
The interface architecture is designed to evolve gracefully:
|
|
- Version management supports backward compatibility
|
|
- Interface migration tools handle breaking changes
|
|
- Comprehensive documentation ensures proper usage
|
|
- Standardized patterns facilitate maintenance and extension
|
|
|
|
This interface specification provides the foundation for all system interactions, ensuring consistency, reliability, and maintainability across the entire Centron Enterprise Application.
|
|
|
|
---
|
|
|
|
**Document Control**
|
|
- **Review Authority**: System Architecture Review Board
|
|
- **Next Review**: December 30, 2024
|
|
- **Distribution**: Development teams, integration partners, technical stakeholders
|
|
- **Related Documents**: SyRS_Complete.md, SyRS_Architecture.md, SyRS_API_Specification.yaml, SyRS_Traceability.csv |