📚 DocksController Documentation


📑 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. API Endpoints Overview
  5. View Models & Data Models
  6. Helper Methods & Utilities
  7. Error Handling & Return Types
  8. UML & Sequence Diagrams
  9. Sample Usage & Code Snippets
  10. Conclusion

🔍 Overview & Purpose

The DocksController is part of the IrbyImaging.UI ASP.NET Core MVC application. It manages CRUD operations and history tracking for Dock assets. This controller:

  • Lists docks (Index)
  • Displays details (Details)
  • Creates new docks (Create)
  • Edits existing docks (Edit)
  • Shows change history (History)

It leverages the IAssetManager service for business logic, IDockMapper for view-model translations, and inherits from BaseController for shared context/configuration.


🔗 Dependencies & Technologies

Layer Technology / Service
Framework ASP.NET Core MVC (Controllers, Routing, Views)
DI / Configuration Microsoft.Extensions.DependencyInjection
Authorization Microsoft.AspNetCore.Authorization (Policies)
Data Access Entity Framework Core (IrbyContext)
Business Logic IAssetManager
Mapping IDockMapper
Utility Shared Utility classes (Responses enum, etc.)
// Constructor injection in Startup.cs
services.AddScoped<IAssetManager, AssetManager>();
services.AddScoped<IDockMapper, DockMapper>();
services.AddDbContext<IrbyContext>(options => /* ... */);

🏷️ Key Functional Areas

  1. Index: Search & list docks
  2. Details: Show single-dock details
  3. Create (GET/POST): Form to create a dock
  4. Edit (GET/POST): Form to update a dock
  5. History: Show asset history

Each action returns an IActionResult (View or Redirect).


🌐 API Endpoints Overview

Although this is an MVC controller (views, not pure JSON APIs), the routes map as follows:

HTTP Verb Route Action Purpose
GET /Docks Index List/Search docks
GET /Docks/Details/{id} Details View details of a single dock
GET /Docks/Create Create Display create-dock form
POST /Docks/Create Create Submit new-dock data
GET /Docks/Edit/{id} Edit Display edit-dock form
POST /Docks/Edit/{id} Edit Submit updated-dock data
GET /Docks/History/{id} History Display change history for a dock

🗂️ View Models & Data Models

ViewModel Purpose
DockListViewModel Data for Index view
DockDetailViewModel Data for Details view
DockCreateViewModel Fields for creating a dock
DockEditViewModel Fields for editing a dock
DockHistoryListViewModel History entries & dock summary
public class DockCreateViewModel
{
    public string Name { get; set; }
    public string Location { get; set; }
    // ... validation attributes
    public string ErrorMessage { get; set; }
}

🛠️ Helper Methods & Utilities

  • _manager (IAssetManager):

    • GetDocks_Async(string search)
    • GetDockById_Async(Guid? id)
    • AddNewAssetWithHistory_Async(...)
    • UpdateAssetAndHistory_Async(...)
    • GetHistoryByAssetId_Async(Guid? id)
  • _mapper (IDockMapper):

    • GenerateDockListViewModel(...)
    • GenerateDockDetailViewModel(...)
    • GenerateDockCreateViewModel()
    • CreateViewModelToDock(...)
    • DockToEditViewModel(...)
    • EditViewModelToDock(...)
    • GenerateDockHistoryListViewModel(...)

These abstract away mapping and business logic, keeping the controller slim.


⚠️ Error Handling & Return Types

Condition Response
id == null NotFound()
Asset not found in DB NotFound()
ModelState.IsValid == false Return current View with ViewModel
Manager returns Failure Show error message in view
Success (Create/Edit) RedirectToAction(nameof(Index))
if (!ModelState.IsValid)
    return View(viewModel);

(var response, var message) = await _manager.AddNewAssetWithHistory_Async(...);
if (response == Responses.Failure)
{
    viewModel.ErrorMessage = message;
    return View(viewModel);
}

📈 UML & Sequence Diagrams

1. Class Diagram (Mermaid)

classDiagram
    class DocksController {
        -IAssetManager _manager
        -IDockMapper _mapper
        -IrbyContext _context
        -IConfiguration _configuration
        +Index(string search, AssetStatus status) : IActionResult
        +Details(Guid? id) : IActionResult
        +Create() : IActionResult
        +Create(DockCreateViewModel vm) : IActionResult
        +Edit(Guid? id) : IActionResult
        +Edit(Guid id, DockEditViewModel vm) : IActionResult
        +History(Guid? id) : IActionResult
    }

    DocksController --> IAssetManager
    DocksController --> IDockMapper
    DocksController --> IrbyContext
    DocksController --> IConfiguration
    DocksController --|> BaseController

2. Sequence Diagram for Create (POST)

sequenceDiagram
    participant User
    participant Controller as DocksController
    participant Mapper as IDockMapper
    participant Manager as IAssetManager
    participant DB as IrbyContext

    User->>Controller: POST /Docks/Create (DockCreateViewModel)
    Controller->>Mapper: CreateViewModelToDock(vm)
    Mapper-->>Controller: Dock entity
    Controller->>Manager: AddNewAssetWithHistory_Async(dock, username)
    Manager->>DB: Insert Dock + History
    DB-->>Manager: Success
    Manager-->>Controller: (Responses.Success, "")
    Controller->>User: Redirect to /Docks

💡 Sample Usage & Code Snippets

1. Invoking Index from Razor

<form asp-action="Index" method="get">
    <input type="text" name="search" placeholder="Search docks..." />
    <select name="status">
        <option value="Active">Active</option>
        <option value="Inactive">Inactive</option>
    </select>
    <button type="submit">🔍 Search</button>
</form>

<table>
    @foreach(var dock in Model.Docks)
    {
        <tr>
            <td>@dock.Name</td>
            <td>@dock.Status</td>
            <td>
                <a asp-action="Details" asp-route-id="@dock.Id">Details</a>
            </td>
        </tr>
    }
</table>

2. Creating a New Dock (Controller Test)

[Fact]
public async Task Create_Post_ReturnsRedirectOnSuccess()
{
    // Arrange
    var mockMgr = new Mock<IAssetManager>();
    mockMgr.Setup(m => m.AddNewAssetWithHistory_Async(It.IsAny<Dock>(), It.IsAny<string>()))
           .ReturnsAsync((Responses.Success, string.Empty));
    var controller = new DocksController(mockMgr.Object, mockMapper, dbContext, config);

    var vm = new DockCreateViewModel { Name="Dock1", Location="A1" };

    // Act
    var result = await controller.Create(vm);

    // Assert
    var redirect = Assert.IsType<RedirectToActionResult>(result);
    Assert.Equal("Index", redirect.ActionName);
}

🏁 Conclusion

The DocksController orchestrates all Dock-related user interactions:

  • Delegates mapping to IDockMapper
  • Delegates business logic to IAssetManager
  • Maintains clean MVC patterns with clear error handling
  • Enables audit/history tracking

With this documentation, developers should be able to:

  • Understand each endpoint & its flow
  • Extend or update view models and business logic
  • Write unit/integration tests against controller actions

Happy coding! 🚢