Mango.Nop.Libraries/.github/copilot-instructions.md

Mango.Nop Libraries — Domain Rules

This is the single source of truth for Mango.Nop library rules. Do not duplicate these elsewhere. For detailed docs see: README.md → docs/ For core framework rules see: ../../../../../../Aycode/Source/AyCode.Core/.github/copilot-instructions.md

nopCommerce Compatibility

1. All three libraries target net9.0 — required by nopCommerce 4.80.9. Do NOT change TFM.
2. NopDependencies folder in Mango.Nop.Core contains mirror copies of nopCommerce entity classes (BaseEntity, Customer, Order, Product, GenericAttribute, etc.) so that Mango.Nop.Core can be referenced without the full nopCommerce dependency chain.
3. Do NOT modify files in NopDependencies/ unless the nopCommerce version changes.

Entity & DTO Patterns

4. BaseEntity (NopDependencies) = root entity base with int Id. All nopCommerce entities inherit from this.
5. MgEntityBase = custom entity base that inherits BaseEntity and implements IEntityInt (from AyCode.Interfaces). Used for domain-specific entities.
6. ModelDtoBase<TMainEntity> = DTO base with two-way mapping: CopyEntityValuesToDto() and CreateMainEntity(). All DTOs inherit from this.
7. GenericAttribute = polymorphic key-value store. KeyGroup = owner type name, EntityId = owner ID. Extension methods in GenericAttributeExtensions provide typed access.

Data Access Patterns

8. MgDbTableBase<TEntity> = repository base wrapping nopCommerce EntityRepository<TEntity>. Adds GetAll(), timestamp handling, and event publishing.
9. MgDtoDbTableBase = DTO-aware repository — handles DTO ↔ entity mapping on top of MgDbTableBase.
10. MgDbContextBase = EF Core context base for custom tables.

Conventions

11. Mg prefix for all custom types: MgEntityBase, MgOrderDto, MgDbTableBase, etc.
12. No redundant code — before writing new logic, search for existing methods. Reuse or extract shared logic.
13. Keep all .md files in sync — when you modify code, update any affected .md file.
14. All AyCode references are via DLL (not ProjectReference) — this is intentional. When a type is referenced but not defined in this library (e.g. IEntityInt, IId<T>, AcConst, ToonDescription), look it up in ../../../../../../Aycode/Source/AyCode.Core/ source and docs.

Reference Modes

• Full stack (ProjectReference, all 3 libraries) — for nopCommerce plugins needing entity access, data layer, and services.
• Types only (DLL reference, Mango.Nop.Core only) — for projects that only need DTOs, entities, and interfaces without the nopCommerce runtime dependency.