Clarify docs: conventions, layering, timestamp interface
Updated documentation to clarify .md file update scope and add rules for documentation layering. Replaced inline dependency graph in README.md with a reference to ARCHITECTURE.md. Corrected timestamp interface references from ITimeStampUpdated to ITimeStampModified for consistency. Clarified nopCommerce dependency boundaries.
This commit is contained in:
parent
f47701af59
commit
2303e99f95
|
|
@ -23,8 +23,9 @@
|
|||
## 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.
|
||||
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.
|
||||
|
|
|
|||
12
README.md
12
README.md
|
|
@ -15,15 +15,9 @@ Shared nopCommerce extension libraries providing domain entities, DTOs, data acc
|
|||
|
||||
## 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
|
||||
```
|
||||
See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for full dependency graph and project roles.
|
||||
|
||||
`Mango.Nop.Core` has zero nopCommerce runtime dependency (uses mirror copies in `NopDependencies/`). `Mango.Nop.Data` and `.Services` depend on nopCommerce.
|
||||
|
||||
## Reference Modes
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ Zero nopCommerce runtime dependency. Contains:
|
|||
|
||||
### 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
|
||||
- **`MgDbTableBase<TEntity>`** — extends nopCommerce `EntityRepository<TEntity>`, adds `GetAll()`, timestamp handling (`ITimeStampCreated`, `ITimeStampModified`), event publishing
|
||||
- **`MgDtoDbTableBase`** — DTO-aware repository with entity ↔ DTO mapping
|
||||
- **`MgDbContextBase`** — EF Core context base for custom tables
|
||||
- **`MgDalBase`** — Data Access Layer orchestrator
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
- **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`.
|
||||
- **Timestamp interfaces** — entities implementing `ITimeStampCreated` / `ITimeStampModified` get automatic timestamp management in `MgDbTableBase`.
|
||||
|
||||
## Project Boundaries
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue