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 in the same area. If you already read an .md file during your work and notice it contradicts the current code, fix the discrepancy — but do NOT proactively scan or open .md files just to check for issues.
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.
15. Documentation layering — write .md documentation at the defining layer (where the code lives). Higher-layer .md files reference the base docs (e.g. see AyCode.Core/docs/SIGNALR.md) and document only project-specific overrides or extensions. Never duplicate base-layer descriptions in consumer-level 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.