πŸ“± MobileDevicesController.md

Welcome to the comprehensive documentation for the MobileDevicesController in the IrbyImaging solution. This controller manages CRUD operations, listing, filtering, and history tracking of mobile devices in the system.


πŸ“‹ Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Architecture & Key Components
  4. API Endpoints Overview
  5. Helper Methods & Utilities
  6. Error Handling & Return Types
  7. Models & ViewModels
  8. Usage Examples
  9. UML Class Diagram
  10. Conclusion

1. Overview & Purpose

The MobileDevicesController is an ASP.NET Core MVC controller that:

  • πŸ“Š Lists all mobile devices (Index, Telogis).
  • πŸ” Filters by search terms and asset status (persisted in session).
  • πŸ“‹ Creates new mobile devices (GET/POST).
  • πŸ–ŠοΈ Edits existing devices (GET/POST).
  • πŸ“œ Displays history of changes for a given device.
  • πŸ” Intended for internal use by Mobile Admin or Admin roles (via BaseController).

This controller orchestrates calls between:

  • Business Logic (IAssetManager)
  • Mapping Layer (IMobileDeviceMapper)
  • Data Context (IrbyContext)
  • Session & Configuration (IConfiguration, HttpContext.Session)

2. Dependencies & Technologies

Category Library / Technology Purpose
Framework ASP.NET Core MVC Web application framework
Dependency Injection Microsoft.Extensions DI container for controllers & services
Data Access Entity Framework Core ORM via IrbyContext
Business Logic IAssetManager Asset retrieval, creation, updates & history
Mapping IMobileDeviceMapper Converts Domain ↔ ViewModels
Configuration IConfiguration App settings, connection strings, app policies
Utilities System.Text Session key encoding/decoding
Authorization Microsoft.AspNetCore.Authorization Restricts endpoints to admins (commented)

3. Architecture & Key Components

BaseController
   └── MobileDevicesController
          β”œβ”€β”€ IAssetManager (_manager)
          β”œβ”€β”€ IMobileDeviceMapper (_mapper)
          β”œβ”€β”€ IrbyContext (_context)
          └── IConfiguration (_configuration)
  • BaseController
    Contains common functionality (session, user context, error handling).
  • IAssetManager
    • Retrieves and manages assets (mobile devices & Telogis devices).
    • Methods: GetMobileDevices_Async, GetMobileDeviceById_Async, AddNewAssetWithHistory_Async, etc.
  • IMobileDeviceMapper
    • Maps domain MobileDevice to/from various ViewModels (List, Detail, Create, Edit, History).
  • IrbyContext
    • EF Core DbContext for database operations.
  • IConfiguration
    • Provides access to configuration values (e.g., session keys, policies).

4. API Endpoints Overview

Method Signature HTTP Verb Route Description
Index(string search, AssetStatus? status = null) GET /MobileDevices List all devices, optional search & status filter.
Telogis(string search, AssetStatus status) GET /MobileDevices/Telogis List Telogis devices by search & status.
Details(Guid? id) GET /MobileDevices/Details/{id} Show details view for a single device.
Create(DeviceType deviceType) GET /MobileDevices/Create Render form to create a new device of given type.
Create(MobileDeviceCreateViewModel viewModel) POST /MobileDevices/Create Process creation form, validate, save, redirect.
Edit(Guid? id) GET /MobileDevices/Edit/{id} Render form to edit an existing device.
Edit(Guid id, MobileDeviceEditViewModel viewModel) POST /MobileDevices/Edit/{id} Process edit form, validate, update, redirect.
History(Guid? id) GET /MobileDevices/History/{id} Display change history for a device.

4.1 Index Action

public async Task<IActionResult> Index(string search, AssetStatus? status = null)
  • πŸ” Parameters
    • search : free-text filter
    • status : optional enum (Active, Retired, All, etc.)
  • βš™οΈ Workflow
    1. Determine effective status (query string β†’ session β†’ default All).
    2. Fetch devices via _manager.GetMobileDevices_Async(search).
    3. Map to MobileDeviceListViewModel.
    4. Store chosen status in session for persistence.
    5. Return the Index view.

5. Helper Methods & Utilities

Method Description
GetStatusFromSession() : AssetStatus? Decode SelectedStatus from session into AssetStatus enum.
StoreStatusInSession(AssetStatus status) Encode AssetStatus as UTF8 bytes & store in session.
private AssetStatus? GetStatusFromSession()
{
    if (HttpContext.Session.TryGetValue(SelectedStatusKey, out var statusBytes))
    {
        var statusString = Encoding.UTF8.GetString(statusBytes);
        if (Enum.TryParse<AssetStatus>(statusString, out AssetStatus tempStatus))
            return tempStatus;
    }
    return null;
}

6. Error Handling & Return Types

  • Try/Catch blocks in Index to gracefully handle exceptions.
  • ModelState.IsValid checks in POST actions to re-display form with validation errors πŸ₯.
  • Response Tuples (response, message) from _manager calls for domain-level success/failure.
  • HTTP 404 (NotFound()) used when id == null or entity not found.
  • RedirectToAction(nameof(Index)) on successful Create/Edit.
  • View("Error") fallback for unhandled exceptions.

7. Models & ViewModels

7.1 Domain Model: MobileDevice

Property Type Description
Id Guid Primary key
Name string Device name
Serial string Serial number
Status AssetStatus Current asset status
Type DeviceType e.g., Phone, Tablet
… … Additional metadata

7.2 ViewModels

ViewModel Purpose
MobileDeviceListViewModel Data for Index & Telogis list views
MobileDeviceDetailViewModel Data for single device details view
MobileDeviceCreateViewModel Fields + validation for Create form
MobileDeviceEditViewModel Fields + validation for Edit form
MobileDeviceHistoryListViewModel History entries for device transactions

8. Usage Examples

8.1 Listing Devices

GET /MobileDevices?search=iPhone&status=Active
  • Returns a view listing all active devices whose name or serial contains β€œiPhone”.

8.2 Creating a New Device

// GET: Render form
GET /MobileDevices/Create?deviceType=Phone

// POST: Submit form
POST /MobileDevices/Create
Content-Type: application/x-www-form-urlencoded

Name=John's%20iPhone&Serial=XYZ123&Type=Phone&Status=Active
  • On validation success, adds device & history, then redirects to Index.

8.3 Editing a Device

GET /MobileDevices/Edit/3f2e1a7f-2b9d-4c42-a4c0-4d2b4d38e5ad

POST /MobileDevices/Edit/3f2e1a7f-2b9d-4c42-a4c0-4d2b4d38e5ad
Reason=Updated%20status&Status=Retired&… 
  • Validates mismatch id, ModelState, then calls _manager.UpdateAssetAndHistory_Async.

9. UML Class Diagram

@startuml
class BaseController {
  +constructor(IrbyContext, IConfiguration)
  +HttpContext : HttpContext
}

class MobileDevicesController {
  - _manager : IAssetManager
  - _mapper : IMobileDeviceMapper
  - _context : IrbyContext
  - _configuration : IConfiguration
  + Index(search:String, status:AssetStatus?)
  + Telogis(search:String, status:AssetStatus)
  + Details(id:Guid?)
  + Create(type:DeviceType)
  + Create(viewModel:MobileDeviceCreateViewModel)
  + Edit(id:Guid?)
  + Edit(id:Guid, viewModel:MobileDeviceEditViewModel)
  + History(id:Guid?)
  - GetStatusFromSession() : AssetStatus?
  - StoreStatusInSession(status:AssetStatus)
}

MobileDevicesController --|> BaseController
MobileDevicesController --> IAssetManager
MobileDevicesController --> IMobileDeviceMapper
MobileDevicesController --> IrbyContext
MobileDevicesController --> IConfiguration
@enduml

Use PlantUML to render the diagram.


10. Conclusion

βœ… MobileDevicesController provides a cohesive, session-aware interface for managing mobile device assets.
πŸ› οΈ It delegates to business and mapping services, focusing purely on HTTP concerns and view orchestration.
πŸš€ With detailed error-handling, validation, and history-tracking, it ensures both robustness and traceability.

Feel free to extend this controller by:

  • Adding AJAX endpoints for dynamic filtering.
  • Introducing role-based segmentation for read/write.
  • Implementing bulk import/export features for large device inventories.

Happy coding! πŸŽ‰