# 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.