feat: Implement Category, Item, UOM, Vendor, and Warehouse services with CRUD operations

- Added CategoryService for managing categories with listing, tree structure, and creation functionalities. - Introduced ItemService for item management, including listing, detail retrieval, creation, updating, and status management. - Created UomService for handling unit of measure operations, including listing and creation. - Developed VendorService for vendor management, supporting listing, detail retrieval, creation, updating, and status management. - Implemented WarehouseService for warehouse and bin management, including listing warehouses, creating warehouses, and managing bins within warehouses. - Added interfaces for each service to define the contract for service implementations. - Generated Entity Framework Core model snapshot for database migrations.
2026-07-10 10:44:30 +05:30
parent ec94bac410
commit 057dd5aedc
54 changed files with 3437 additions and 18 deletions
@@ -0,0 +1,28 @@
+using ERPCore.Common.Http;
+using ERPCore.System.Errors;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ERPCore.Controllers;
+
+/// <summary>
+/// Base for the v1 API controllers. Centralises ETag / If-Match handling
+/// (docs/11-BACKEND-PHASE1.md §1.6) so concurrency behaviour is uniform.
+/// Each controller declares its own explicit lowercase <c>[Route]</c> to match
+/// the API contract paths (docs/11 §1.1).
+/// </summary>
+[ApiController]
+[Produces("application/json")]
+public abstract class ApiControllerBase : ControllerBase
+{
+    /// <summary>Parse a mandatory <c>If-Match</c> header, or 428 if absent/malformed.</summary>
+    protected uint RequireIfMatch()
+    {
+        var header = Request.Headers.IfMatch.ToString();
+        if (!ETag.TryParse(header, out var rowVersion))
+            throw new DomainException("PRECONDITION_REQUIRED", "A valid If-Match header is required for this update.", 428);
+        return rowVersion;
+    }
+
+    /// <summary>Emit the strong <c>ETag</c> response header for a row-version token.</summary>
+    protected void SetETag(uint rowVersion) => Response.Headers.ETag = ETag.From(rowVersion);
+}
@@ -0,0 +1,31 @@
+using ERPCore.Dtos.Categories;
+using ERPCore.Dtos.Common;
+using ERPCore.Services.Interfaces;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ERPCore.Controllers;
+
+/// <summary>Category endpoints (docs/11-BACKEND-PHASE1.md §2.3).</summary>
+[Route("api/v1/categories")]
+public sealed class CategoriesController : ApiControllerBase
+{
+    private readonly ICategoryService _categories;
+
+    public CategoriesController(ICategoryService categories) => _categories = categories;
+
+    /// <summary>Flat paged list, or a nested tree when <c>tree=true</c>.</summary>
+    [HttpGet]
+    [ProducesResponseType(typeof(PagedResponse<CategoryDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(IReadOnlyList<CategoryTreeDto>), StatusCodes.Status200OK)]
+    public async Task<IActionResult> List([FromQuery] PageQuery query, [FromQuery] bool tree, CancellationToken ct)
+        => tree ? Ok(await _categories.GetTreeAsync(ct)) : Ok(await _categories.ListAsync(query, ct));
+
+    [HttpPost]
+    [ProducesResponseType(typeof(CategoryDto), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
+    public async Task<ActionResult<CategoryDto>> Create([FromBody] CreateCategoryRequest request, CancellationToken ct)
+    {
+        var dto = await _categories.CreateAsync(request, ct);
+        return Created($"/api/v1/categories/{dto.CategoryId}", dto);
+    }
+}
@@ -0,0 +1,89 @@
+using ERPCore.Domain.Enums;
+using ERPCore.Dtos.Common;
+using ERPCore.Dtos.Items;
+using ERPCore.Services.Interfaces;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ERPCore.Controllers;
+
+/// <summary>Item master endpoints (docs/11-BACKEND-PHASE1.md §2.1–2.2).</summary>
+[Route("api/v1/items")]
+public sealed class ItemsController : ApiControllerBase
+{
+    private readonly IItemService _items;
+
+    public ItemsController(IItemService items) => _items = items;
+
+    /// <summary>List items with optional filters and paging.</summary>
+    [HttpGet]
+    [ProducesResponseType(typeof(PagedResponse<ItemListItemDto>), StatusCodes.Status200OK)]
+    public async Task<ActionResult<PagedResponse<ItemListItemDto>>> List(
+        [FromQuery] PageQuery query,
+        [FromQuery] EntityStatus? status,
+        [FromQuery] long? categoryId,
+        [FromQuery] TrackingMode? trackingMode,
+        CancellationToken ct)
+        => Ok(await _items.ListAsync(query, status, categoryId, trackingMode, ct));
+
+    /// <summary>Get a single item; returns an <c>ETag</c> for optimistic concurrency.</summary>
+    [HttpGet("{itemId:long}")]
+    [ProducesResponseType(typeof(ItemDetailDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<ActionResult<ItemDetailDto>> GetById(long itemId, CancellationToken ct)
+    {
+        var result = await _items.GetAsync(itemId, ct);
+        if (result is null) return NotFound();
+
+        SetETag(result.RowVersion);
+        return Ok(result.Value);
+    }
+
+    /// <summary>Create an item (SKU unique). Server sets status and timestamps.</summary>
+    [HttpPost]
+    [ProducesResponseType(typeof(ItemDetailDto), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
+    public async Task<ActionResult<ItemDetailDto>> Create([FromBody] CreateItemRequest request, CancellationToken ct)
+    {
+        var result = await _items.CreateAsync(request, ct);
+        SetETag(result.RowVersion);
+        return Created($"/api/v1/items/{result.Value.ItemId}", result.Value);
+    }
+
+    /// <summary>Full update; requires <c>If-Match</c> (412 on stale ETag).</summary>
+    [HttpPut("{itemId:long}")]
+    [ProducesResponseType(typeof(ItemDetailDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status412PreconditionFailed)]
+    public async Task<ActionResult<ItemDetailDto>> Update(long itemId, [FromBody] UpdateItemRequest request, CancellationToken ct)
+    {
+        var expected = RequireIfMatch();
+        var result = await _items.UpdateAsync(itemId, request, expected, ct);
+        SetETag(result.RowVersion);
+        return Ok(result.Value);
+    }
+
+    /// <summary>Activate / deactivate the item (FR-MD-08 — deactivate, not delete).</summary>
+    [HttpPatch("{itemId:long}/status")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> SetStatus(long itemId, [FromBody] UpdateItemStatusRequest request, CancellationToken ct)
+    {
+        await _items.SetStatusAsync(itemId, request.Status, ct);
+        return NoContent();
+    }
+
+    /// <summary>Replace the item's per-warehouse reorder settings (FR-MD-05).</summary>
+    [HttpPut("{itemId:long}/reorder")]
+    [ProducesResponseType(typeof(ItemReorderSettingsDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<ActionResult<ItemReorderSettingsDto>> UpdateReorder(long itemId, [FromBody] UpdateReorderRequest request, CancellationToken ct)
+        => Ok(await _items.UpdateReorderAsync(itemId, request, ct));
+
+    /// <summary>Replace the item's UOM conversions (FR-MD-02).</summary>
+    [HttpPut("{itemId:long}/uom-conversions")]
+    [ProducesResponseType(typeof(ItemUomConversionsDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<ActionResult<ItemUomConversionsDto>> UpdateUomConversions(long itemId, [FromBody] UpdateUomConversionsRequest request, CancellationToken ct)
+        => Ok(await _items.UpdateUomConversionsAsync(itemId, request, ct));
+}
@@ -0,0 +1,29 @@
+using ERPCore.Dtos.Common;
+using ERPCore.Dtos.Uoms;
+using ERPCore.Services.Interfaces;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ERPCore.Controllers;
+
+/// <summary>Unit-of-measure endpoints (docs/11-BACKEND-PHASE1.md §2.2).</summary>
+[Route("api/v1/uoms")]
+public sealed class UomsController : ApiControllerBase
+{
+    private readonly IUomService _uoms;
+
+    public UomsController(IUomService uoms) => _uoms = uoms;
+
+    [HttpGet]
+    [ProducesResponseType(typeof(PagedResponse<UomDto>), StatusCodes.Status200OK)]
+    public async Task<ActionResult<PagedResponse<UomDto>>> List([FromQuery] PageQuery query, CancellationToken ct)
+        => Ok(await _uoms.ListAsync(query, ct));
+
+    [HttpPost]
+    [ProducesResponseType(typeof(UomDto), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status409Conflict)]
+    public async Task<ActionResult<UomDto>> Create([FromBody] CreateUomRequest request, CancellationToken ct)
+    {
+        var dto = await _uoms.CreateAsync(request, ct);
+        return Created($"/api/v1/uoms/{dto.UomId}", dto);
+    }
+}
@@ -0,0 +1,65 @@
+using ERPCore.Domain.Enums;
+using ERPCore.Dtos.Common;
+using ERPCore.Dtos.Vendors;
+using ERPCore.Services.Interfaces;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ERPCore.Controllers;
+
+/// <summary>Vendor master endpoints (docs/11-BACKEND-PHASE1.md §2.4).</summary>
+[Route("api/v1/vendors")]
+public sealed class VendorsController : ApiControllerBase
+{
+    private readonly IVendorService _vendors;
+
+    public VendorsController(IVendorService vendors) => _vendors = vendors;
+
+    [HttpGet]
+    [ProducesResponseType(typeof(PagedResponse<VendorDto>), StatusCodes.Status200OK)]
+    public async Task<ActionResult<PagedResponse<VendorDto>>> List(
+        [FromQuery] PageQuery query, [FromQuery] EntityStatus? status, CancellationToken ct)
+        => Ok(await _vendors.ListAsync(query, status, ct));
+
+    [HttpGet("{vendorId:long}")]
+    [ProducesResponseType(typeof(VendorDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<ActionResult<VendorDto>> GetById(long vendorId, CancellationToken ct)
+    {
+        var result = await _vendors.GetAsync(vendorId, ct);
+        if (result is null) return NotFound();
+
+        SetETag(result.RowVersion);
+        return Ok(result.Value);
+    }
+
+    [HttpPost]
+    [ProducesResponseType(typeof(VendorDto), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status409Conflict)]
+    public async Task<ActionResult<VendorDto>> Create([FromBody] CreateVendorRequest request, CancellationToken ct)
+    {
+        var result = await _vendors.CreateAsync(request, ct);
+        SetETag(result.RowVersion);
+        return Created($"/api/v1/vendors/{result.Value.VendorId}", result.Value);
+    }
+
+    [HttpPut("{vendorId:long}")]
+    [ProducesResponseType(typeof(VendorDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status412PreconditionFailed)]
+    public async Task<ActionResult<VendorDto>> Update(long vendorId, [FromBody] UpdateVendorRequest request, CancellationToken ct)
+    {
+        var expected = RequireIfMatch();
+        var result = await _vendors.UpdateAsync(vendorId, request, expected, ct);
+        SetETag(result.RowVersion);
+        return Ok(result.Value);
+    }
+
+    [HttpPatch("{vendorId:long}/status")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> SetStatus(long vendorId, [FromBody] UpdateVendorStatusRequest request, CancellationToken ct)
+    {
+        await _vendors.SetStatusAsync(vendorId, request.Status, ct);
+        return NoContent();
+    }
+}
@@ -0,0 +1,54 @@
+using ERPCore.Dtos.Common;
+using ERPCore.Dtos.Warehouses;
+using ERPCore.Services.Interfaces;
+using Microsoft.AspNetCore.Mvc;
+
+namespace ERPCore.Controllers;
+
+/// <summary>Warehouse &amp; bin endpoints (docs/11-BACKEND-PHASE1.md §2.5).</summary>
+[Route("api/v1/warehouses")]
+public sealed class WarehousesController : ApiControllerBase
+{
+    private readonly IWarehouseService _warehouses;
+
+    public WarehousesController(IWarehouseService warehouses) => _warehouses = warehouses;
+
+    [HttpGet]
+    [ProducesResponseType(typeof(PagedResponse<WarehouseDto>), StatusCodes.Status200OK)]
+    public async Task<ActionResult<PagedResponse<WarehouseDto>>> List([FromQuery] PageQuery query, CancellationToken ct)
+        => Ok(await _warehouses.ListAsync(query, ct));
+
+    [HttpGet("{warehouseId:long}")]
+    [ProducesResponseType(typeof(WarehouseDto), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<ActionResult<WarehouseDto>> GetById(long warehouseId, CancellationToken ct)
+    {
+        var dto = await _warehouses.GetAsync(warehouseId, ct);
+        return dto is null ? NotFound() : Ok(dto);
+    }
+
+    [HttpPost]
+    [ProducesResponseType(typeof(WarehouseDto), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status409Conflict)]
+    public async Task<ActionResult<WarehouseDto>> Create([FromBody] CreateWarehouseRequest request, CancellationToken ct)
+    {
+        var dto = await _warehouses.CreateAsync(request, ct);
+        return Created($"/api/v1/warehouses/{dto.WarehouseId}", dto);
+    }
+
+    [HttpGet("{warehouseId:long}/bins")]
+    [ProducesResponseType(typeof(IReadOnlyList<BinDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<ActionResult<IReadOnlyList<BinDto>>> ListBins(long warehouseId, CancellationToken ct)
+        => Ok(await _warehouses.ListBinsAsync(warehouseId, ct));
+
+    [HttpPost("{warehouseId:long}/bins")]
+    [ProducesResponseType(typeof(BinDto), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status409Conflict)]
+    public async Task<ActionResult<BinDto>> CreateBin(long warehouseId, [FromBody] CreateBinRequest request, CancellationToken ct)
+    {
+        var dto = await _warehouses.CreateBinAsync(warehouseId, request, ct);
+        return Created($"/api/v1/warehouses/{warehouseId}/bins/{dto.BinId}", dto);
+    }
+}