From c0073815ae2660cfaf435aa2bf4bd9ea7946ed95 Mon Sep 17 00:00:00 2001 From: Loretta Date: Thu, 15 Jan 2026 11:34:06 +0100 Subject: [PATCH] Add ToonDescription attributes to core entities and DTOs Introduced ToonDescription annotations across DTO and entity classes to provide metadata, business rules, and documentation for classes and properties. Updated usings to include AyCode.Core.Serializers.Toons where needed. These changes improve code clarity and support tooling for documentation and code generation. --- Mango.Nop.Core/Dtos/CustomerDto.cs | 1 + Mango.Nop.Core/Dtos/MgOrderDto.cs | 5 +++++ Mango.Nop.Core/Dtos/MgOrderItemDto.cs | 3 +++ Mango.Nop.Core/Dtos/MgProductDto.cs | 2 ++ Mango.Nop.Core/Dtos/MgStockQuantityHistoryDto.cs | 2 ++ Mango.Nop.Core/Entities/MgEntityBase.cs | 2 ++ Mango.Nop.Core/Entities/MgStockTaking.cs | 2 ++ Mango.Nop.Core/Entities/MgStockTakingItem.cs | 2 ++ Mango.Nop.Core/NopDependencies/BaseEntity.cs | 2 ++ Mango.Nop.Core/NopDependencies/Catalogs/Customer.cs | 4 +++- Mango.Nop.Core/NopDependencies/Catalogs/GenericAttribute.cs | 2 ++ Mango.Nop.Core/NopDependencies/Catalogs/Order.cs | 6 ++++++ Mango.Nop.Core/NopDependencies/Catalogs/OrderItem.cs | 3 +++ Mango.Nop.Core/NopDependencies/Catalogs/OrderNote.cs | 1 + .../NopDependencies/Catalogs/StockQuantityHistory.cs | 6 +++++- 15 files changed, 41 insertions(+), 2 deletions(-) diff --git a/Mango.Nop.Core/Dtos/CustomerDto.cs b/Mango.Nop.Core/Dtos/CustomerDto.cs index bc9df76..28b7866 100644 --- a/Mango.Nop.Core/Dtos/CustomerDto.cs +++ b/Mango.Nop.Core/Dtos/CustomerDto.cs @@ -15,6 +15,7 @@ public class CustomerDto : ModelDtoBase, ISoftDeletedEntity public string FirstName { get; set; } public string LastName { get; set; } + [ToonDescription(BusinessRule = "get => $\"{LastName} {FirstName}\"")] public string FullName => $"{LastName} {FirstName}"; public int RegisteredInStoreId { get; set; } diff --git a/Mango.Nop.Core/Dtos/MgOrderDto.cs b/Mango.Nop.Core/Dtos/MgOrderDto.cs index 3a5dd4a..aa09a74 100644 --- a/Mango.Nop.Core/Dtos/MgOrderDto.cs +++ b/Mango.Nop.Core/Dtos/MgOrderDto.cs @@ -1,4 +1,5 @@ using AyCode.Core.Extensions; +using AyCode.Core.Serializers.Toons; using AyCode.Core.Helpers; using LinqToDB.Mapping; using Mango.Nop.Core.Entities; @@ -14,6 +15,7 @@ using System.Linq.Expressions; namespace Mango.Nop.Core.Dtos; +[ToonDescription("Base DTO for orders with items, customer and status tracking")] public abstract class MgOrderDto : MgEntityBase, IModelDtoBase, IMgOrderDto where TOrderItemDto : IMgOrderItemDto where TProductDto : IMgProductDto { public Guid OrderGuid { get; set; } @@ -40,16 +42,19 @@ public abstract class MgOrderDto : MgEntityBase, IMo [Association(ThisKey = nameof(Id), OtherKey = nameof(OrderNote.OrderId), CanBeNull = true)] public List OrderNotes { get; set; } + [ToonDescription(Purpose = "Enum wrapper", BusinessRule = "get, set => OrderStatusId")] public OrderStatus OrderStatus { get => (OrderStatus)OrderStatusId; set => OrderStatusId = (int)value; } + [ToonDescription(Purpose = "Enum wrapper", BusinessRule = "get, set => ShippingStatusId")] public ShippingStatus ShippingStatus { get => (ShippingStatus)ShippingStatusId; set => ShippingStatusId = (int)value; } + [ToonDescription(Purpose = "Enum wrapper", BusinessRule = "get, set => PaymentStatusId")] public PaymentStatus PaymentStatus { get => (PaymentStatus)PaymentStatusId; diff --git a/Mango.Nop.Core/Dtos/MgOrderItemDto.cs b/Mango.Nop.Core/Dtos/MgOrderItemDto.cs index c22a64c..7d4a658 100644 --- a/Mango.Nop.Core/Dtos/MgOrderItemDto.cs +++ b/Mango.Nop.Core/Dtos/MgOrderItemDto.cs @@ -1,4 +1,5 @@ using AyCode.Core.Extensions; +using AyCode.Core.Serializers.Toons; using AyCode.Core.Helpers; using LinqToDB.Mapping; using Mango.Nop.Core.Entities; @@ -8,6 +9,7 @@ using Nop.Core.Domain.Orders; namespace Mango.Nop.Core.Dtos; +[ToonDescription("Base DTO for order items with product association")] public abstract class MgOrderItemDto : MgEntityBase, IModelDtoBase, IMgOrderItemDto where TProductDto : IMgProductDto { public Guid OrderItemGuid { get; set; } @@ -24,6 +26,7 @@ public abstract class MgOrderItemDto : MgEntityBase, IModelDtoBase< public string AttributesXml { get; set; } public decimal? ItemWeight { get; set; } + [ToonDescription(BusinessRule = "get => ProductDto?.Name ?? 'ProductDto is null!!!'")] public string ProductName => ProductDto?.Name ?? "ProductDto is null!!!"; [Association(ThisKey = nameof(ProductId), OtherKey = nameof(BaseEntity.Id), CanBeNull = true)] diff --git a/Mango.Nop.Core/Dtos/MgProductDto.cs b/Mango.Nop.Core/Dtos/MgProductDto.cs index 520ea5c..ed97a36 100644 --- a/Mango.Nop.Core/Dtos/MgProductDto.cs +++ b/Mango.Nop.Core/Dtos/MgProductDto.cs @@ -1,10 +1,12 @@ using AyCode.Interfaces.Entities; +using AyCode.Core.Serializers.Toons; using Mango.Nop.Core.Entities; using Mango.Nop.Core.Interfaces; //using Nop.Core.Domain.Catalog; namespace Mango.Nop.Core.Dtos; +[ToonDescription("Base DTO for products with warehouse and pricing")] public abstract class MgProductDto : MgEntityBase, /*Product,*/ IMgProductDto//IModelDtoBase//, IDiscountSupported { //public int Id { get; set; } diff --git a/Mango.Nop.Core/Dtos/MgStockQuantityHistoryDto.cs b/Mango.Nop.Core/Dtos/MgStockQuantityHistoryDto.cs index 6d3cc1d..33f6953 100644 --- a/Mango.Nop.Core/Dtos/MgStockQuantityHistoryDto.cs +++ b/Mango.Nop.Core/Dtos/MgStockQuantityHistoryDto.cs @@ -1,4 +1,5 @@ using AyCode.Interfaces.Entities; +using AyCode.Core.Serializers.Toons; using LinqToDB.Mapping; using Mango.Nop.Core.Entities; using Mango.Nop.Core.Interfaces; @@ -18,6 +19,7 @@ namespace Mango.Nop.Core.Dtos public TProductDto ProductDto { get; set; } } + [ToonDescription("Base DTO for stock quantity history with product")] public abstract class MgStockQuantityHistoryDto : MgEntityBase, IModelDtoBase, IMgTStockQuantityHistoryDto where TProductDto : IMgProductDto { diff --git a/Mango.Nop.Core/Entities/MgEntityBase.cs b/Mango.Nop.Core/Entities/MgEntityBase.cs index edac1b6..c796294 100644 --- a/Mango.Nop.Core/Entities/MgEntityBase.cs +++ b/Mango.Nop.Core/Entities/MgEntityBase.cs @@ -1,8 +1,10 @@ using AyCode.Interfaces.Entities; +using AyCode.Core.Serializers.Toons; using Nop.Core; namespace Mango.Nop.Core.Entities; +[ToonDescription("Base entity class with Id property and ToString override")] public abstract class MgEntityBase : BaseEntity, IEntityInt { public override string ToString() diff --git a/Mango.Nop.Core/Entities/MgStockTaking.cs b/Mango.Nop.Core/Entities/MgStockTaking.cs index dce99f7..7e90b37 100644 --- a/Mango.Nop.Core/Entities/MgStockTaking.cs +++ b/Mango.Nop.Core/Entities/MgStockTaking.cs @@ -1,4 +1,5 @@ using System.ComponentModel.Design; +using AyCode.Core.Serializers.Toons; using AyCode.Interfaces.Entities; using AyCode.Interfaces.TimeStampInfo; using LinqToDB.Mapping; @@ -13,6 +14,7 @@ public interface IMgStockTaking : IEntityInt, ITimeStampInfo public bool IsReadyForClose(); } +[ToonDescription("Base entity for stock taking sessions with items")] public abstract class MgStockTaking : MgEntityBase, IMgStockTaking where TStockTakingItem : class, IMgStockTakingItem { public DateTime StartDateTime { get; set; } diff --git a/Mango.Nop.Core/Entities/MgStockTakingItem.cs b/Mango.Nop.Core/Entities/MgStockTakingItem.cs index 9c297bb..ec673ab 100644 --- a/Mango.Nop.Core/Entities/MgStockTakingItem.cs +++ b/Mango.Nop.Core/Entities/MgStockTakingItem.cs @@ -1,4 +1,5 @@ using AyCode.Interfaces.Entities; +using AyCode.Core.Serializers.Toons; using AyCode.Interfaces.TimeStampInfo; using LinqToDB; using LinqToDB.Mapping; @@ -18,6 +19,7 @@ public interface IMgStockTakingItem : IEntityInt, ITimeStampInfo public int MeasuredStockQuantity { get; set; } } +[ToonDescription("Base entity for stock taking items with product association")] public abstract class MgStockTakingItem : MgEntityBase, IMgStockTakingItem where TStockTaking : class, IMgStockTaking where TProduct : class, IMgProductDto { diff --git a/Mango.Nop.Core/NopDependencies/BaseEntity.cs b/Mango.Nop.Core/NopDependencies/BaseEntity.cs index 643d8d9..6ade8ce 100644 --- a/Mango.Nop.Core/NopDependencies/BaseEntity.cs +++ b/Mango.Nop.Core/NopDependencies/BaseEntity.cs @@ -1,4 +1,6 @@ //namespace Nop.Core.Domain.Common; +using AyCode.Core.Serializers.Toons; + using AyCode.Interfaces.Entities; diff --git a/Mango.Nop.Core/NopDependencies/Catalogs/Customer.cs b/Mango.Nop.Core/NopDependencies/Catalogs/Customer.cs index 90cfa3a..605c350 100644 --- a/Mango.Nop.Core/NopDependencies/Catalogs/Customer.cs +++ b/Mango.Nop.Core/NopDependencies/Catalogs/Customer.cs @@ -1,4 +1,5 @@ -using Nop.Core.Domain.Common; +using AyCode.Core.Serializers.Toons; +using Nop.Core.Domain.Common; using Nop.Core.Domain.Tax; namespace Nop.Core.Domain.Customers; @@ -6,6 +7,7 @@ namespace Nop.Core.Domain.Customers; /// /// Represents a customer /// +[ToonDescription("NopCommerce customer entity")] public partial class Customer : BaseEntity, ISoftDeletedEntity { public Customer() diff --git a/Mango.Nop.Core/NopDependencies/Catalogs/GenericAttribute.cs b/Mango.Nop.Core/NopDependencies/Catalogs/GenericAttribute.cs index 48368ca..d3159bd 100644 --- a/Mango.Nop.Core/NopDependencies/Catalogs/GenericAttribute.cs +++ b/Mango.Nop.Core/NopDependencies/Catalogs/GenericAttribute.cs @@ -5,6 +5,7 @@ namespace Nop.Core.Domain.Common; /// /// Represents a generic attribute /// +[ToonDescription("NopCommerce generic attribute for key-value storage", Purpose = "A flexible key-value store used to extend entities with custom business logic data without changing the database schema")] public partial class GenericAttribute : BaseEntity { /// @@ -27,6 +28,7 @@ public partial class GenericAttribute : BaseEntity /// /// Gets or sets the value /// + [ToonDescription(Purpose = "Raw string representation of the Key's value")] public string Value { get; set; } /// diff --git a/Mango.Nop.Core/NopDependencies/Catalogs/Order.cs b/Mango.Nop.Core/NopDependencies/Catalogs/Order.cs index 713b9ad..bb0fce1 100644 --- a/Mango.Nop.Core/NopDependencies/Catalogs/Order.cs +++ b/Mango.Nop.Core/NopDependencies/Catalogs/Order.cs @@ -1,4 +1,6 @@ using Nop.Core.Domain.Common; +using AyCode.Core.Serializers.Toons; + using Nop.Core.Domain.Payments; using Nop.Core.Domain.Shipping; using Nop.Core.Domain.Tax; @@ -8,6 +10,7 @@ namespace Nop.Core.Domain.Orders; /// /// Represents an order /// +[ToonDescription("NopCommerce order entity with payment and shipping")] public partial class Order : BaseEntity, ISoftDeletedEntity { #region Properties @@ -309,6 +312,7 @@ public partial class Order : BaseEntity, ISoftDeletedEntity /// /// Gets or sets the payment status /// + [ToonDescription(Purpose = "Enum wrapper", BusinessRule = "get, set => PaymentStatusId")] public PaymentStatus PaymentStatus { get => (PaymentStatus)PaymentStatusId; @@ -318,6 +322,7 @@ public partial class Order : BaseEntity, ISoftDeletedEntity /// /// Gets or sets the shipping status /// + [ToonDescription(Purpose = "Enum wrapper", BusinessRule = "get, set => ShippingStatusId")] public ShippingStatus ShippingStatus { get => (ShippingStatus)ShippingStatusId; @@ -327,6 +332,7 @@ public partial class Order : BaseEntity, ISoftDeletedEntity /// /// Gets or sets the customer tax display type /// + [ToonDescription(Purpose = "Enum wrapper", BusinessRule = "get, set => CustomerTaxDisplayTypeId")] public TaxDisplayType CustomerTaxDisplayType { get => (TaxDisplayType)CustomerTaxDisplayTypeId; diff --git a/Mango.Nop.Core/NopDependencies/Catalogs/OrderItem.cs b/Mango.Nop.Core/NopDependencies/Catalogs/OrderItem.cs index d3824b7..2138f47 100644 --- a/Mango.Nop.Core/NopDependencies/Catalogs/OrderItem.cs +++ b/Mango.Nop.Core/NopDependencies/Catalogs/OrderItem.cs @@ -1,8 +1,11 @@ namespace Nop.Core.Domain.Orders; +using AyCode.Core.Serializers.Toons; + /// /// Represents an order item /// +[ToonDescription("NopCommerce order item entity")] public partial class OrderItem : BaseEntity { /// diff --git a/Mango.Nop.Core/NopDependencies/Catalogs/OrderNote.cs b/Mango.Nop.Core/NopDependencies/Catalogs/OrderNote.cs index eb1a8e4..e922796 100644 --- a/Mango.Nop.Core/NopDependencies/Catalogs/OrderNote.cs +++ b/Mango.Nop.Core/NopDependencies/Catalogs/OrderNote.cs @@ -5,6 +5,7 @@ namespace Nop.Core.Domain.Orders; /// /// Represents an order note /// +[ToonDescription("NopCommerce order note entity")] public partial class OrderNote : BaseEntity { /// diff --git a/Mango.Nop.Core/NopDependencies/Catalogs/StockQuantityHistory.cs b/Mango.Nop.Core/NopDependencies/Catalogs/StockQuantityHistory.cs index 7b4890b..1e1bbc4 100644 --- a/Mango.Nop.Core/NopDependencies/Catalogs/StockQuantityHistory.cs +++ b/Mango.Nop.Core/NopDependencies/Catalogs/StockQuantityHistory.cs @@ -1,4 +1,6 @@ -using AyCode.Interfaces.Entities; +using AyCode.Core.Serializers.Toons; +using AyCode.Interfaces.Entities; +using LinqToDB.Mapping; using Mango.Nop.Core.Interfaces; namespace Nop.Core.Domain.Catalog; @@ -17,6 +19,8 @@ public interface IMgStockQuantityHistory /// /// Represents a stock quantity change entry /// +[Table(Name = nameof(StockQuantityHistory))] +[ToonDescription("NopCommerce stock movement log", Purpose = "Audit trail for physical and logical stock movements")] public partial class StockQuantityHistory : BaseEntity, IMgStockQuantityHistory { ///