📱 DeskPhonesController Documentation


Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. API Endpoints Overview
  5. Routing & Authorization
  6. View Models & Data Models
  7. Helper Methods & Utilities
  8. Error Handling & Return Types
  9. Third-Party Integrations
  10. Class Diagram (UML)
  11. Usage Examples
  12. Conclusion

Overview & Purpose

DeskPhonesController is an ASP.NET Core MVC controller within the IrbyImaging.UI assembly that manages CRUD (Create, Read, Update, History) operations for Desk Phone assets. It interacts with:

  • IAssetManager for business logic and data retrieval/updating.
  • IDeskPhoneMapper to translate between domain models and view models.
  • IrbyContext for EF Core context (via BaseController).
  • IConfiguration for app settings.

🎯 Primary Goals

  • Present paginated/searchable lists of desk phones
  • Display details for a single desk phone
  • Enable authorized users to create new desk phone records
  • Allow editing of existing desk phones with audit history
  • Show asset history (change log)

Dependencies & Technologies

Technology Version / Detail
ASP.NET Core MVC Controllers, Views, Routing
Entity Framework Core IrbyContext
Dependency Injection Built-in DI container
Configuration IConfiguration
Custom Business Logic IAssetManager
AutoMapper-style Mapper IDeskPhoneMapper
C# / .NET 6+ (assumed) Async/await, Task-based programming

Key Functional Areas

1. Index (List View)

  • Purpose: Show a searchable list of desk phones, optionally filtered by asset status.
  • Signature:
    public async Task<IActionResult> Index(string search, AssetStatus status)
    
  • Workflow:
    1. Calls _manager.GetDeskPhones_Async(search) to retrieve matching desk phones.
    2. Uses _mapper.GenerateDeskPhoneListViewModel(...) to produce a DeskPhoneListViewModel.
    3. Returns the View(viewModel) for rendering.

2. Details View

  • Purpose: Display all details of a single desk phone.
  • Signature:
    public async Task<IActionResult> Details(Guid? id)
    
  • Workflow:
    1. Validates id != null; returns NotFound() if missing.
    2. Calls _manager.GetDeskPhoneById_Async(id); returns NotFound() if not found.
    3. Maps to DeskPhoneDetailViewModel and returns the view.

3. Create Desk Phone

  • GET

    public IActionResult Create()
    
    • Returns a fresh DeskPhoneCreateViewModel for user input.
  • POST

    [HttpPost]
    [ValidateAntiForgeryToken]
    public async Task<IActionResult> Create(DeskPhoneCreateViewModel viewModel)
    
    • Validates ModelState.
    • Converts view model to domain model via _mapper.CreateViewModelToDeskPhone(viewModel).
    • Invokes _manager.AddNewAssetWithHistory_Async(...).
    • On failure, redisplay form with ErrorMessage.
    • On success, redirects to Index.

4. Edit Desk Phone

  • GET

    public async Task<IActionResult> Edit(Guid? id)
    
    • Loads existing desk phone, maps to DeskPhoneEditViewModel.
  • POST

    [HttpPost]
    [ValidateAntiForgeryToken]
    public async Task<IActionResult> Edit(Guid id, DeskPhoneEditViewModel viewModel)
    
    • Checks route/data id match.
    • Validates ModelState.
    • Maps back to domain model and calls _manager.UpdateAssetAndHistory_Async(...).
    • On failure, repopulates form with error.
    • On success, redirects to Index.

5. History View

  • Purpose: Show audit/log history for a desk phone.
  • Signature:
    public async Task<IActionResult> History(Guid? id)
    
  • Workflow:
    1. Validate id.
    2. Retrieve list of history events (_manager.GetHistoryByAssetId_Async).
    3. Map to DeskPhoneHistoryListViewModel and include current detail view.
    4. Return view.

API Endpoints Overview

HTTP Verb Route Action Description
GET /DeskPhones Index List & search desk phones
GET /DeskPhones/Details/{id} Details View a specific desk phone
GET /DeskPhones/Create Create (form) Show create form
POST /DeskPhones/Create Create (submit) Process new desk phone creation
GET /DeskPhones/Edit/{id} Edit (form) Show edit form
POST /DeskPhones/Edit/{id} Edit (submit) Process desk phone updates
GET /DeskPhones/History/{id} History Display change history

Routing & Authorization

  • Base Controller: Inherits from BaseController, which provides:
    • Access to IrbyContext
    • Common functionality (e.g., user info, config)
  • [Authorize] Attributes (commented out in code, but expected in production):
    • Class-Level: ReadOnlyOrAdminPolicy
    • Create/Edit: AdminPolicy

🔒 Apply appropriate policies to ensure data protection.


View Models & Data Models

Domain Model (Simplified)

public class DeskPhone {
  public Guid Id { get; set; }
  public string Manufacturer { get; set; }
  public string Model { get; set; }
  public AssetStatus Status { get; set; }
  // ...other common asset properties...
}

View Models

ViewModel Purpose
DeskPhoneListViewModel Presentation model for the Index page
DeskPhoneDetailViewModel Detailed properties for a single asset
DeskPhoneCreateViewModel Fields + validation for creating asset
DeskPhoneEditViewModel Fields + validation for editing asset
DeskPhoneHistoryListViewModel List of history entries + current detail

Helper Methods & Utilities

All mapping between domain models and view models is encapsulated in IDeskPhoneMapper.
Business rules & data persistence live in IAssetManager.

Examples

// Creating a new ViewModel for the Create page
var viewModel = _mapper.GenerateDeskPhoneCreateViewModel();

// Mapping back to domain model
var deskPhone = _mapper.EditViewModelToDeskPhone(viewModel);

Error Handling & Return Types

  • Null Checks
    • id == null or returned entity null → return NotFound();
  • ModelState Validation
    • Invalid input returns original View(viewModel).
  • Business Failures
    • Manager returns (Responses.Failure, message).
    • Controller displays ErrorMessage on a fresh view model.
  • Success
    • Redirect to Index via RedirectToAction(nameof(Index)).

Third-Party Integrations

  • Entity Framework Core (IrbyContext)
  • ASP.NET Core MVC (Views, Controllers, DI, Configuration)

Class Diagram (UML)

classDiagram
    class DeskPhonesController {
        - IAssetManager _manager
        - IDeskPhoneMapper _mapper
        - IrbyContext _context
        - IConfiguration _configuration
        + Task<IActionResult> Index(string search, AssetStatus status)
        + Task<IActionResult> Details(Guid? id)
        + IActionResult Create()
        + Task<IActionResult> Create(DeskPhoneCreateViewModel vm)
        + Task<IActionResult> Edit(Guid? id)
        + Task<IActionResult> Edit(Guid id, DeskPhoneEditViewModel vm)
        + Task<IActionResult> History(Guid? id)
    }
    DeskPhonesController --> IAssetManager
    DeskPhonesController --> IDeskPhoneMapper
    DeskPhonesController --> IrbyContext
    DeskPhonesController --> IConfiguration

Usage Examples

🔍 Search & Filter

GET /DeskPhones?search=Cisco&status=Active

📝 Create New Desk Phone (cURL)

curl -X POST https://yourapp/DeskPhones/Create \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "Manufacturer=Yealink&Model=T46S&Status=Available&SerialNumber=12345"

🚧 Edit / Update

GET /DeskPhones/Edit/3f5a9b20-8c3a-4ef7-8b9c-ff1a2bc3d9e0
POST /DeskPhones/Edit/3f5a9b20-8c3a-4ef7-8b9c-ff1a2bc3d9e0

📜 View History

GET /DeskPhones/History/3f5a9b20-8c3a-4ef7-8b9c-ff1a2bc3d9e0

Conclusion

The DeskPhonesController orchestrates all user interactions for desk phone asset management within IrbyImaging.UI. It cleanly separates concerns:

  • Controller: HTTP request handling, routing, input validation.
  • Manager: Business logic & data operations.
  • Mapper: Translation between domain entities and UI models.

🎉 By following this pattern, the controller remains thin and testable, while the IAssetManager and IDeskPhoneMapper can be independently unit-tested and maintained. Enjoy building and extending your desk phone management features!