Add architecture docs for Mango.Nop & update dev DB config
Added detailed documentation: ARCHITECTURE.md, CONVENTIONS.md, GLOSSARY.md, and copilot-instructions.md for Mango.Nop.Core, Data, and Services. Updated/added README.md files for all Mango.Nop libraries and the FruitBank nopCommerce plugin, clarifying structure, key types, and usage. Switched appsettings.json connection string from production to development database. These changes improve developer onboarding and enforce architectural consistency.
This commit is contained in:
parent
1a9e0dcf0b
commit
f47701af59
|
|
@ -0,0 +1,31 @@
|
||||||
|
# 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.
|
||||||
|
|
@ -0,0 +1,41 @@
|
||||||
|
# Mango.Nop.Core
|
||||||
|
|
||||||
|
Shared domain library containing entities, DTOs, interfaces, and nopCommerce entity mirrors. **net9.0**.
|
||||||
|
|
||||||
|
## Folder Structure
|
||||||
|
|
||||||
|
| Folder | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `Dtos/` | DTO classes shared across consumers: `MgOrderDto`, `MgOrderItemDto`, `MgProductDto`, `MgGenericAttributeDto`, `MgStockQuantityHistoryDto`, `CustomerDto`, `ModelDtoBase` |
|
||||||
|
| `Entities/` | Custom entities: `MgEntityBase`, `MgStockTaking`, `MgStockTakingItem` |
|
||||||
|
| `Extensions/` | Extension methods for nopCommerce `BaseEntity` collections and `GenericAttribute` |
|
||||||
|
| `Interfaces/` | DTO interfaces (`IMgOrderDto`, `IMgProductDto`, etc.), soft-delete interfaces, foreign key markers |
|
||||||
|
| `Loggers/` | `ILogger` / `Logger` — logging abstraction |
|
||||||
|
| `Models/` | Login request/response models (`MgLoginModelRequest`, `MgLoginModelResponse`) |
|
||||||
|
| `NopDependencies/` | Mirror copies of nopCommerce entity classes — `BaseEntity`, `Customer`, `Order`, `OrderItem`, `Product`, `GenericAttribute`, enums (`OrderStatus`, `PaymentStatus`, etc.) |
|
||||||
|
| `Services/` | `IMgLockService` interface |
|
||||||
|
| `Utils/` | `CommonHelper2` — utility methods |
|
||||||
|
|
||||||
|
## Key Types
|
||||||
|
|
||||||
|
### DTOs (Dtos/)
|
||||||
|
- **`MgOrderDto`** — Order DTO used across SignalR communication
|
||||||
|
- **`MgOrderItemDto`** — Order item DTO
|
||||||
|
- **`MgProductDto`** — Product DTO with GenericAttribute-based properties
|
||||||
|
- **`MgGenericAttributeDto`** — GenericAttribute DTO
|
||||||
|
- **`ModelDtoBase`** / `IModelDtoBase` — base class for all DTOs
|
||||||
|
|
||||||
|
### nopCommerce Mirrors (NopDependencies/)
|
||||||
|
Mirror copies of nopCommerce entities so that `Mango.Nop.Core` can be referenced without pulling in the full nopCommerce dependency chain. Includes:
|
||||||
|
- `BaseEntity` — root entity base
|
||||||
|
- `Customer`, `CustomerRole`, `Order`, `OrderItem`, `Product`, `GenericAttribute`, `StockQuantityHistory`
|
||||||
|
- Enums: `OrderStatus`, `PaymentStatus`, `ShippingStatus`, `ProductType`, etc.
|
||||||
|
|
||||||
|
### Entities (Entities/)
|
||||||
|
- **`MgEntityBase`** — base for all custom Mango entities
|
||||||
|
- **`MgStockTaking`**, **`MgStockTakingItem`** — stocktaking entities
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
- `linq2db` — data access
|
||||||
|
- `MessagePack` — binary serialization
|
||||||
|
- `Microsoft.AspNetCore.Mvc.NewtonsoftJson` — JSON serialization
|
||||||
|
|
@ -0,0 +1,23 @@
|
||||||
|
# Mango.Nop.Data
|
||||||
|
|
||||||
|
Data access layer with repository base classes and DB context abstractions. **net9.0**.
|
||||||
|
|
||||||
|
## Folder Structure
|
||||||
|
|
||||||
|
| Folder | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `Interfaces/` | Repository interfaces: `IMgDalBase`, `IMgDbContextBase`, `IMgDbTableBase` |
|
||||||
|
| `Repositories/` | Repository base implementations: `MgDalBase`, `MgDbContextBase`, `MgDbTableBase`, `MgDtoDbTableBase` |
|
||||||
|
|
||||||
|
## Key Types
|
||||||
|
|
||||||
|
- **`MgDalBase`** — Data Access Layer base class
|
||||||
|
- **`MgDbContextBase`** — Database context base for nopCommerce integration
|
||||||
|
- **`MgDbTableBase`** — Table-level repository base (entity → DB operations)
|
||||||
|
- **`MgDtoDbTableBase`** — DTO-aware table base — handles DTO ↔ entity mapping
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
- `Mango.Nop.Core` (ProjectReference)
|
||||||
|
- `Nop.Core`, `Nop.Data` (nopCommerce ProjectReferences)
|
||||||
|
- `MessagePack`, `Microsoft.AspNetCore.Mvc.NewtonsoftJson`
|
||||||
|
|
@ -0,0 +1,19 @@
|
||||||
|
# Mango.Nop.Services
|
||||||
|
|
||||||
|
Service base classes for nopCommerce plugin development — background tasks, session management, events, locking. **net9.0**.
|
||||||
|
|
||||||
|
## Key Types
|
||||||
|
|
||||||
|
| Type | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `MgBackgroundServiceBase` / `IMgBackgroundService` | Base for hosted background services in nopCommerce |
|
||||||
|
| `MgSessionServiceBase` / `IMgSessionService` | Session management base — user session state |
|
||||||
|
| `MgSessionItemBase` / `IMgSessionItem` | Individual session item base |
|
||||||
|
| `MgEventConsumerBase` | Base for nopCommerce event consumers (entity insert/update/delete) |
|
||||||
|
| `MgLockServiceBase` | Distributed lock service base |
|
||||||
|
| `NopLogWriter` | Logging bridge — writes to nopCommerce log system |
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
- `Mango.Nop.Core`, `Mango.Nop.Data` (ProjectReferences)
|
||||||
|
- `Nop.Core`, `Nop.Data`, `Nop.Services`, `Nop.Web.Framework` (nopCommerce ProjectReferences)
|
||||||
|
|
@ -0,0 +1,31 @@
|
||||||
|
# Mango.Nop Libraries
|
||||||
|
|
||||||
|
> For library domain rules see: `.github/copilot-instructions.md`
|
||||||
|
> For detailed docs see: `docs/`
|
||||||
|
|
||||||
|
Shared nopCommerce extension libraries providing domain entities, DTOs, data access, and service base classes. All target **net9.0** (nopCommerce 4.80.9 requirement).
|
||||||
|
|
||||||
|
## Projects
|
||||||
|
|
||||||
|
| Project | Purpose | Key Types |
|
||||||
|
|---|---|---|
|
||||||
|
| [Mango.Nop.Core](Mango.Nop.Core/README.md) | Domain entities, DTOs, interfaces, nopCommerce entity mirrors | `MgOrderDto`, `MgProductDto`, `MgEntityBase`, `GenericAttribute`, `BaseEntity` |
|
||||||
|
| [Mango.Nop.Data](Mango.Nop.Data/README.md) | Data access layer — repository base classes, DB context | `MgDalBase`, `MgDbContextBase`, `MgDbTableBase`, `MgDtoDbTableBase` |
|
||||||
|
| [Mango.Nop.Services](Mango.Nop.Services/README.md) | Service base classes — background services, session, events, locking | `MgBackgroundServiceBase`, `MgSessionServiceBase`, `MgEventConsumerBase`, `NopLogWriter` |
|
||||||
|
|
||||||
|
## Dependency Graph
|
||||||
|
|
||||||
|
```
|
||||||
|
AyCode.Core (net9.0, DLL references: AyCode.Interfaces, AyCode.Entities, AyCode.Core, AyCode.Utils, + .Server variants)
|
||||||
|
↑
|
||||||
|
Mango.Nop.Core (net9.0, no nopCommerce dependency)
|
||||||
|
↑
|
||||||
|
Mango.Nop.Data (net9.0) → references Nop.Core, Nop.Data
|
||||||
|
↑
|
||||||
|
Mango.Nop.Services (net9.0) → references Nop.Core, Nop.Data, Nop.Services, Nop.Web.Framework
|
||||||
|
```
|
||||||
|
|
||||||
|
## Reference Modes
|
||||||
|
|
||||||
|
- **Full stack** (ProjectReference, all 3 libraries) — for nopCommerce plugins that need 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.
|
||||||
|
|
@ -0,0 +1,73 @@
|
||||||
|
# Architecture
|
||||||
|
|
||||||
|
## Dependency Graph
|
||||||
|
|
||||||
|
```
|
||||||
|
AyCode.Core (net9.0, DLL refs: AyCode.Interfaces, .Entities, .Core, .Utils, + .Server variants)
|
||||||
|
↑
|
||||||
|
Mango.Nop.Core (net9.0, no nopCommerce runtime dependency)
|
||||||
|
↑
|
||||||
|
Mango.Nop.Data (net9.0) → Nop.Core, Nop.Data
|
||||||
|
↑
|
||||||
|
Mango.Nop.Services (net9.0) → Nop.Core, Nop.Data, Nop.Services, Nop.Web.Framework
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rule:** Dependencies flow upward only. `Mango.Nop.Core` has zero nopCommerce runtime dependency — it uses mirror copies in `NopDependencies/`.
|
||||||
|
|
||||||
|
## Project Roles
|
||||||
|
|
||||||
|
### Mango.Nop.Core — Domain Layer
|
||||||
|
Zero nopCommerce runtime dependency. Contains:
|
||||||
|
- **DTOs** (`Dtos/`) — `ModelDtoBase<TMainEntity>` with bidirectional entity mapping (`CopyEntityValuesToDto`, `CreateMainEntity`)
|
||||||
|
- **Entities** (`Entities/`) — `MgEntityBase` (inherits `BaseEntity`, implements `IEntityInt`)
|
||||||
|
- **NopDependencies** (`NopDependencies/`) — mirror copies of nopCommerce entities (`BaseEntity`, `Customer`, `Order`, `Product`, `GenericAttribute`, enums). Allows referencing without full nopCommerce dependency chain.
|
||||||
|
- **Extensions** (`Extensions/`) — `GenericAttributeExtensions` for typed attribute access, `CollectionExtensionsNopBaseEntity` for collection operations
|
||||||
|
- **Interfaces** (`Interfaces/`) — DTO interfaces, soft-delete, foreign key markers
|
||||||
|
- **Models** (`Models/`) — Login request/response
|
||||||
|
- **Loggers** (`Loggers/`) — `ILogger` abstraction
|
||||||
|
|
||||||
|
### Mango.Nop.Data — Data Access Layer
|
||||||
|
Wraps nopCommerce data infrastructure with custom base classes:
|
||||||
|
- **`MgDbTableBase<TEntity>`** — extends nopCommerce `EntityRepository<TEntity>`, adds `GetAll()`, timestamp handling (`ITimeStampCreated`, `ITimeStampUpdated`), event publishing
|
||||||
|
- **`MgDtoDbTableBase`** — DTO-aware repository with entity ↔ DTO mapping
|
||||||
|
- **`MgDbContextBase`** — EF Core context base for custom tables
|
||||||
|
- **`MgDalBase`** — Data Access Layer orchestrator
|
||||||
|
|
||||||
|
### Mango.Nop.Services — Service Layer
|
||||||
|
Service base classes for nopCommerce plugin development:
|
||||||
|
- **`MgBackgroundServiceBase`** — hosted background task base
|
||||||
|
- **`MgSessionServiceBase`** / `MgSessionItemBase` — session management
|
||||||
|
- **`MgEventConsumerBase`** — nopCommerce entity event handler base
|
||||||
|
- **`MgLockServiceBase`** — distributed locking
|
||||||
|
- **`NopLogWriter`** — logging bridge to nopCommerce log system
|
||||||
|
|
||||||
|
## NopDependencies Pattern
|
||||||
|
|
||||||
|
`Mango.Nop.Core/NopDependencies/` contains mirror copies of nopCommerce entity classes with the **same namespace** as the original nopCommerce types:
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// In NopDependencies/BaseEntity.cs — same namespace as nopCommerce
|
||||||
|
namespace Nop.Core;
|
||||||
|
public abstract partial class BaseEntity : IBaseEntity
|
||||||
|
{
|
||||||
|
public int Id { get; set; }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This allows `Mango.Nop.Core` to be referenced by projects that don't have a direct nopCommerce dependency (e.g., Blazor/MAUI clients), while maintaining type compatibility with the real nopCommerce entities at the server level.
|
||||||
|
|
||||||
|
## Reference Modes
|
||||||
|
|
||||||
|
```
|
||||||
|
Mango.Nop Libraries
|
||||||
|
┌──────────────────────┐
|
||||||
|
│ Core Data Services │
|
||||||
|
└──┬──────┬──────┬─────┘
|
||||||
|
│ │ │
|
||||||
|
┌───────────────┤ │ │
|
||||||
|
│ (DLL, Core │ │ │
|
||||||
|
│ only) │ │ │
|
||||||
|
▼ ▼ ▼ ▼
|
||||||
|
Types-only clients Full-stack nopCommerce
|
||||||
|
(Blazor/MAUI/etc.) plugins (server-side)
|
||||||
|
```
|
||||||
|
|
@ -0,0 +1,23 @@
|
||||||
|
# Conventions
|
||||||
|
|
||||||
|
## Naming
|
||||||
|
|
||||||
|
- **`Mg` prefix** for all custom types: `MgEntityBase`, `MgOrderDto`, `MgDbTableBase`, `MgDalBase`, etc.
|
||||||
|
- **`I` + name** for interfaces: `IMgDalBase`, `IMgDbTableBase`, `IMgOrderDto`, `IMgLockService`.
|
||||||
|
- **`Dto` suffix** for DTOs wrapping nopCommerce entities: `MgOrderDto`, `MgProductDto`, `MgOrderItemDto`.
|
||||||
|
- **`DbTable` suffix** for repository classes: `MgDbTableBase`, `MgDtoDbTableBase`.
|
||||||
|
- **`Base` suffix** for abstract base classes: `MgEntityBase`, `ModelDtoBase`, `MgBackgroundServiceBase`.
|
||||||
|
|
||||||
|
## Patterns
|
||||||
|
|
||||||
|
- **DTO bidirectional mapping** — `ModelDtoBase<TMainEntity>` provides `CopyEntityValuesToDto(entity)` and `CreateMainEntity()`. Override both in concrete DTOs.
|
||||||
|
- **NopDependencies mirror** — entity classes in `NopDependencies/` use the **same namespace** as the original nopCommerce types. Do not change namespaces.
|
||||||
|
- **GenericAttribute typed access** — use `GenericAttributeExtensions.GetValueOrDefault<T>()` / `GetValueOrNull<T>()` instead of raw string parsing.
|
||||||
|
- **Repository base chain** — `MgDbTableBase<TEntity>` → `EntityRepository<TEntity>` (nopCommerce). Override virtual methods, don't replace the chain.
|
||||||
|
- **Timestamp interfaces** — entities implementing `ITimeStampCreated` / `ITimeStampUpdated` get automatic timestamp management in `MgDbTableBase`.
|
||||||
|
|
||||||
|
## Project Boundaries
|
||||||
|
|
||||||
|
- `Mango.Nop.Core` — NO nopCommerce runtime dependency. Only NopDependencies mirrors.
|
||||||
|
- `Mango.Nop.Data` — depends on nopCommerce data layer (`Nop.Core`, `Nop.Data`).
|
||||||
|
- `Mango.Nop.Services` — depends on full nopCommerce stack (includes `Nop.Services`, `Nop.Web.Framework`).
|
||||||
|
|
@ -0,0 +1,32 @@
|
||||||
|
# Glossary
|
||||||
|
|
||||||
|
Terminology for the Mango.Nop Libraries. Read this before working on unfamiliar areas.
|
||||||
|
|
||||||
|
## Entity & DTO System
|
||||||
|
|
||||||
|
| Term | Definition |
|
||||||
|
|---|---|
|
||||||
|
| **BaseEntity** | nopCommerce root entity base with `int Id`. Mirror copy in `NopDependencies/`. |
|
||||||
|
| **MgEntityBase** | Custom entity base — inherits `BaseEntity`, implements `IEntityInt` (AyCode). Used for domain-specific entities (e.g., `MgStockTaking`). |
|
||||||
|
| **ModelDtoBase\<T\>** | Abstract DTO base with bidirectional mapping: `CopyEntityValuesToDto()` reads from entity, `CreateMainEntity()` creates entity from DTO. |
|
||||||
|
| **NopDependencies** | Mirror copies of nopCommerce entity classes in `Mango.Nop.Core`. Same namespaces as originals. Eliminates full nopCommerce dependency for consumers that only need types. |
|
||||||
|
| **GenericAttribute** | nopCommerce polymorphic key-value store. `KeyGroup` = owner type name, `EntityId` = owner ID, `Key` = attribute name, `Value` = string value. |
|
||||||
|
|
||||||
|
## Data Access
|
||||||
|
|
||||||
|
| Term | Definition |
|
||||||
|
|---|---|
|
||||||
|
| **MgDbTableBase\<T\>** | Repository base wrapping nopCommerce `EntityRepository<T>`. Adds `GetAll()`, automatic timestamp management, event publishing. |
|
||||||
|
| **MgDtoDbTableBase** | DTO-aware repository — handles DTO ↔ entity mapping on top of `MgDbTableBase`. |
|
||||||
|
| **MgDbContextBase** | EF Core `DbContext` base for custom (non-nopCommerce) tables. |
|
||||||
|
| **MgDalBase** | Data Access Layer orchestrator — coordinates multiple repositories. |
|
||||||
|
|
||||||
|
## Services
|
||||||
|
|
||||||
|
| Term | Definition |
|
||||||
|
|---|---|
|
||||||
|
| **MgBackgroundServiceBase** | Base for hosted background services within nopCommerce. |
|
||||||
|
| **MgSessionServiceBase** | Session state management — tracks user sessions. |
|
||||||
|
| **MgEventConsumerBase** | Base for nopCommerce entity event consumers (insert/update/delete notifications). |
|
||||||
|
| **MgLockServiceBase** | Distributed lock service — prevents concurrent operations on shared resources. |
|
||||||
|
| **NopLogWriter** | Logging bridge — writes to nopCommerce's built-in log system. |
|
||||||
Loading…
Reference in New Issue