Refactor docs: topic folders, navigation, protocol sync

- Restructured documentation: added `docs/README.md` to each sub-project, moved LOGGING and SIGNALR docs into dedicated subfolders with their own `README.md`. - Updated all cross-references to use new topic folder paths and canonical AyCode.Core doc locations. - Updated `.csproj` files to auto-include all Markdown docs and project-level `README.md` files. - Removed obsolete single-file docs, replaced with structured content in topic folders. - Enforced AI Agent Protocol: session setup, output prefix, no-re-read, and mandatory `docs-check` skill after code changes. - Added domain-critical reminders and navigation guidance to relevant `README.md` files.
2026-04-25 07:24:39 +02:00 · 2026-04-25 07:24:39 +02:00 · 599f8a6787
parent 25e5ded777
commit 599f8a6787
17 changed files with 167 additions and 32 deletions
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
--- a/Mango.Nop.Core/.github/copilot-instructions.md
+++ b/Mango.Nop.Core/.github/copilot-instructions.md
--- a/Mango.Nop.Core/Mango.Nop.Core.csproj
+++ b/Mango.Nop.Core/Mango.Nop.Core.csproj
@ -52,8 +52,8 @@
 	</ItemGroup>

 	<ItemGroup>
-		<None Include="docs\DTOS.md" />
-		<None Include="docs\NOP_DEPENDENCIES.md" />
+		<None Include="docs\**\*.md" />
+		<None Include="**\README.md" Exclude="$(DefaultItemExcludes);docs\**" />
 	</ItemGroup>

 </Project>
--- a/Mango.Nop.Core/README.md
+++ b/Mango.Nop.Core/README.md
@ -61,7 +61,7 @@ Nop.Core.BaseEntity (NopDependencies/, implements IBaseEntity)

 ### Loggers

-Extends AyCode logging infrastructure — for base types see `AyCode.Core/docs/LOGGING.md`.
+Extends AyCode logging infrastructure — for base types see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md`.

 | Type | Inherits | Purpose |
 |---|---|---|
@ -88,7 +88,7 @@ Extends AyCode logging infrastructure — for base types see `AyCode.Core/docs/L

 - `linq2db` — data access, `[Association]` / `[Table]` attributes
 - `Microsoft.AspNetCore.Mvc.NewtonsoftJson` — JSON serialization
- Binary serialization: `AcBinarySerializer` (see `AyCode.Core/docs/BINARY_FORMAT.md`). SignalR transport: `AcSignalR` (see `AyCode.Core/AyCode.Services/docs/SIGNALR.md`).
+- Binary serialization: `AcBinarySerializer` (see `AyCode.Core/AyCode.Core/docs/BINARY/BINARY_FORMAT.md`). SignalR transport: `AcSignalR` (see `AyCode.Core/AyCode.Services/docs/SIGNALR/README.md`).
 - `AyCode.Core.Serializers.SourceGenerator` (ProjectReference, `OutputItemType="Analyzer"`) — compile-time binary serializer. See [`AyCode.Core/docs/BINARY_SOURCE_GEN.md`](../../../../../../Aycode/Source/AyCode.Core/AyCode.Core/docs/BINARY_SOURCE_GEN.md)
 - AyCode DLL references: `AyCode.Interfaces`, `AyCode.Core`, `AyCode.Utils`, `AyCode.Entities` (types only, no runtime nopCommerce dependency)

--- a/Mango.Nop.Core/docs/README.md
+++ b/Mango.Nop.Core/docs/README.md
@ -0,0 +1,19 @@
+# Mango.Nop.Core documentation
+
+Topic documentation for the `Mango.Nop.Core` project (Layer 2 framework — NopCommerce-adjacent base types).
+
+## Reference docs (flat)
+
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — Project architecture
+- [`CONVENTIONS.md`](CONVENTIONS.md) — Project-specific conventions
+- [`DTOS.md`](DTOS.md) — DTO system, mapping strategies
+- [`NOP_DEPENDENCIES.md`](NOP_DEPENDENCIES.md) — NopCommerce entity mirror pattern
+
+## Navigation
+
+Per the AI Agent Core Protocol (folder navigation rule), start from this README when browsing `docs/`. All docs at this level are single-file reference; topic folders (e.g., LOGGING/) exist only at sub-projects that host a variant (see `../Mango.Nop.Services/docs/LOGGING/`).
+
+## See also
+
+- **Repo-level conventions**: `../../docs/CONVENTIONS.md`
+- **Base framework**: `../../../../../Aycode/Source/AyCode.Core/` docs
--- a/Mango.Nop.Data/Mango.Nop.Data.csproj
+++ b/Mango.Nop.Data/Mango.Nop.Data.csproj
@ -46,8 +46,8 @@
 	</ItemGroup>

 	<ItemGroup>
-		<None Include="docs\REPOSITORIES.md" />
-		<None Include="docs\TRANSACTIONS.md" />
+		<None Include="docs\**\*.md" />
+		<None Include="**\README.md" Exclude="$(DefaultItemExcludes);docs\**" />
 	</ItemGroup>

 </Project>
--- a/Mango.Nop.Data/docs/README.md
+++ b/Mango.Nop.Data/docs/README.md
@ -0,0 +1,17 @@
+# Mango.Nop.Data documentation
+
+Topic documentation for the `Mango.Nop.Data` project (Layer 2, data access layer).
+
+## Reference docs (flat)
+
+- [`REPOSITORIES.md`](REPOSITORIES.md) — Repository pattern usage
+- [`TRANSACTIONS.md`](TRANSACTIONS.md) — Transaction pattern usage
+
+## Navigation
+
+Per the AI Agent Core Protocol (folder navigation rule), start from this README when browsing `docs/`. All docs at this level are single-file reference.
+
+## See also
+
+- **Repo-level conventions**: `../../docs/CONVENTIONS.md`
+- **Core DTOs**: `../Mango.Nop.Core/docs/DTOS.md`
--- a/Mango.Nop.Services/Mango.Nop.Services.csproj
+++ b/Mango.Nop.Services/Mango.Nop.Services.csproj
@ -49,8 +49,8 @@


 	<ItemGroup>
-		<None Include="docs\SERVICES.md" />
-		<None Include="docs\LOGGING_BRIDGE.md" />
+		<None Include="docs\**\*.md" />
+		<None Include="**\README.md" Exclude="$(DefaultItemExcludes);docs\**" />
 	</ItemGroup>

 </Project>
--- a/Mango.Nop.Services/README.md
+++ b/Mango.Nop.Services/README.md
@ -14,7 +14,7 @@ Service base classes for nopCommerce plugin development — background tasks, se
 | Document | Topic |
 |---|---|
 | `SERVICES.md` | MgBackgroundServiceBase, MgSessionServiceBase, MgEventConsumerBase, MgLockServiceBase |
-| `LOGGING_BRIDGE.md` | NopLogWriter — AyCode-to-nopCommerce log bridge, TransactionScope(Suppress) |
+| `LOGGING/README.md` | NopLogWriter — AyCode-to-nopCommerce log bridge, TransactionScope(Suppress) |

 ## Folder Structure

--- a/Mango.Nop.Services/docs/LOGGING/README.md
+++ b/Mango.Nop.Services/docs/LOGGING/README.md
@ -1,7 +1,7 @@
 # NopLogWriter — Logging Bridge

 > Part of `Mango.Nop.Services`. See `Mango.Nop.Services/README.md` for project overview.
-> For AyCode base logging types (`AcLogItemWriterBase`, `AcLogItem`, log levels) see `AyCode.Core/docs/LOGGING.md`.
+> For AyCode base logging types (`AcLogItemWriterBase`, `AcLogItem`, log levels) see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md`.

 ## Overview

--- a/Mango.Nop.Services/docs/README.md
+++ b/Mango.Nop.Services/docs/README.md
@ -0,0 +1,21 @@
+# Mango.Nop.Services documentation
+
+Topic documentation for the `Mango.Nop.Services` project (Layer 2, service patterns).
+
+## Reference docs (flat)
+
+- [`SERVICES.md`](SERVICES.md) — Service pattern usage
+
+## Topic folders
+
+- [`LOGGING/`](LOGGING/README.md) — Logger bridge between NopCommerce's logger and AyCode.Core's logger (project-specific variant)
+
+## Navigation
+
+Per the AI Agent Core Protocol (folder navigation rule), start from this README when browsing `docs/`. Single-file reference docs remain flat; project-specific variants of framework topics (like LOGGING) live in named subfolders.
+
+## See also
+
+- **Base logger** (framework): `../../../../../Aycode/Source/AyCode.Core/AyCode.Core/docs/LOGGING/README.md`
+- **Remote logger variant**: `../../../../../Aycode/Source/AyCode.Core/AyCode.Services/docs/LOGGING/README.md`
+- **Server-side logger variant**: `../../../../../Aycode/Source/AyCode.Core/AyCode.Core.Server/docs/LOGGING/README.md`
--- a/Mango.Nop.Services/docs/SERVICES.md
+++ b/Mango.Nop.Services/docs/SERVICES.md
@ -1,7 +1,7 @@
 # Service Base Classes

 > Part of `Mango.Nop.Services`. See `Mango.Nop.Services/README.md` for project overview.
-> For logging bridge see `docs/LOGGING_BRIDGE.md`.
+> For logging bridge see `docs/LOGGING/README.md`.

 ## MgBackgroundServiceBase

--- a/README.md
+++ b/README.md
@ -48,4 +48,4 @@ Mango.Nop.Services (net9.0) → Nop.Core, Nop.Data, Nop.Services, Nop.Web.Framew
 | `Mango.Nop.Data/docs/TRANSACTIONS.md` | MgDbContextBase — 4 transaction methods, lock strategy, callback contract |
 | `Mango.Nop.Services/README.md` | Services project overview |
 | `Mango.Nop.Services/docs/SERVICES.md` | MgBackgroundServiceBase, MgSessionServiceBase, MgEventConsumerBase, MgLockServiceBase |
-| `Mango.Nop.Services/docs/LOGGING_BRIDGE.md` | NopLogWriter — AyCode-to-nopCommerce log bridge |
+| `Mango.Nop.Services/docs/LOGGING/README.md` | NopLogWriter — AyCode-to-nopCommerce log bridge |
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@ -107,7 +107,7 @@ BaseEntity → MgEntityBase → MgProductDto : IMgProductDto

 ## Logging Architecture

-Base logging infrastructure (`IAcLoggerBase`, `IAcLogWriterBase`, `AcLoggerBase`, `AcLogItemWriterBase`, `AcLogItem`) is defined in AyCode.Core — see `AyCode.Core/docs/LOGGING.md` for base types, log levels, and writer contracts.
+Base logging infrastructure (`IAcLoggerBase`, `IAcLogWriterBase`, `AcLoggerBase`, `AcLogItemWriterBase`, `AcLogItem`) is defined in AyCode.Core — see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md` for base types, log levels, and writer contracts.

 This layer provides the nopCommerce-specific bridge:

@ -115,7 +115,7 @@ This layer provides the nopCommerce-specific bridge:
 Application code → Mango.Nop.Core.Loggers.ILogger (extends IAcLoggerBase)
                    → Logger<TCategory> (extends AcLoggerBase, delegates to IAcLogWriterBase[])
                        → NopLogWriter (in Services, extends AcLogItemWriterBase<AcLogItem>) → Nop Log table (direct SQL insert)
-                        → [Other AyCode log writers: console, file, SignalR, etc. — see AyCode.Core/docs/LOGGING.md]
+                        → [Other AyCode log writers: console, file, SignalR, etc. — see AyCode.Core/AyCode.Core/docs/LOGGING/README.md]
 ```

 **Important:** `MgBackgroundServiceBase` uses nopCommerce's `Nop.Services.Logging.ILogger` directly (not the Mango wrapper). Other services use `Mango.Nop.Core.Loggers.ILogger`.
--- a/docs/CONVENTIONS.md
+++ b/docs/CONVENTIONS.md
@ -53,14 +53,14 @@
 - Session items track `SessionId`, `SignaRConnectionId`, `RequestCount`.

 ### Logging
- Base logging infrastructure (`IAcLoggerBase`, `IAcLogWriterBase`, `AcLoggerBase`, `AcLogItemWriterBase`) — see `AyCode.Core/docs/LOGGING.md`.
+- Base logging infrastructure (`IAcLoggerBase`, `IAcLogWriterBase`, `AcLoggerBase`, `AcLogItemWriterBase`) — see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md`.
 - Services create loggers via `new Logger<TCategory>(logWriters.ToArray())` in constructor.
 - `logWriters` injected as `IEnumerable<IAcLogWriterBase>` — typically contains `NopLogWriter` + other writers.
 - **Exception:** `MgBackgroundServiceBase` uses `Nop.Services.Logging.ILogger` directly (nopCommerce logger), not the Mango wrapper.

 ### Serialization Attributes
 - `[ToonDescription(...)]` — AyCode metadata for AI/doc tooling. `Purpose`, `BusinessRule`, `TypeRelation`, `RelatedTypes` properties.
- `[AcBinarySerializable(false, true, false, true)]` — AcBinarySerializer config (see `AyCode.Core/docs/BINARY_FORMAT.md`). Parameters control serialization behavior for AcSignalR transport (see `AyCode.Core/AyCode.Services/docs/SIGNALR.md`).
+- `[AcBinarySerializable(false, true, false, true)]` — AcBinarySerializer config (see `AyCode.Core/AyCode.Core/docs/BINARY/BINARY_FORMAT.md`). Parameters control serialization behavior for AcSignalR transport (see `AyCode.Core/AyCode.Services/docs/SIGNALR/README.md`).
 - LinqToDB `[Table(Name = "...")]` and `[Association(...)]` — DB mapping.

 ## Project Boundaries
@ -74,7 +74,7 @@
 Key AyCode types used across these libraries:
 - `IEntityInt` (AyCode.Interfaces.Entities) — `int Id` entity contract
 - `IBaseEntity` — defined locally in NopDependencies, mirrors AyCode's concept
- `IAcLoggerBase`, `IAcLogWriterBase`, `AcLoggerBase`, `AcLogItemWriterBase` — logging infrastructure (see `AyCode.Core/docs/LOGGING.md`)
+- `IAcLoggerBase`, `IAcLogWriterBase`, `AcLoggerBase`, `AcLogItemWriterBase` — logging infrastructure (see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md`)
 - `IAcModelDtoBaseEmpty` — DTO marker interface
 - `IAcSoftRemoveEntity`, `IAcSoftRemoveEntityInt` — soft-delete contracts
 - `IForeignKey`, `IForeignCollection<T>` — FK marker interfaces
--- a/docs/GLOSSARY.md
+++ b/docs/GLOSSARY.md
@ -17,7 +17,7 @@ Terminology for the Mango.Nop Libraries. Read this before working on unfamiliar
 | **GenericAttribute** | nopCommerce polymorphic key-value store. `KeyGroup` = owner type name, `EntityId` = owner ID, `Key` = attribute name, `Value` = string value. `CreatedOrUpdatedDateUTC` tracks last change. |
 | **PropertyHelper.CopyPublicValueTypeProperties** | AyCode utility — reflection-based copy of all public value-type properties between two objects. Used by complex DTOs (`MgOrderDto`, `MgOrderItemDto`). |
 | **ToonDescription** | AyCode metadata attribute for AI/doc tooling. Properties: `Purpose`, `BusinessRule`, `TypeRelation`, `RelatedTypes`. |
-| **AcBinarySerializable** | AyCode binary serialization attribute (AcBinarySerializer, see `AyCode.Core/docs/BINARY_FORMAT.md`). Configures how a type is serialized for AcSignalR transport (see `AyCode.Core/AyCode.Services/docs/SIGNALR.md`). |
+| **AcBinarySerializable** | AyCode binary serialization attribute (AcBinarySerializer, see `AyCode.Core/AyCode.Core/docs/BINARY/BINARY_FORMAT.md`). Configures how a type is serialized for AcSignalR transport (see `AyCode.Core/AyCode.Services/docs/SIGNALR/README.md`). |

 ## Data Access

@ -40,7 +40,7 @@ Terminology for the Mango.Nop Libraries. Read this before working on unfamiliar
 | **MgSessionItemBase** | Session item with `SessionId`, `SignaRConnectionId`, `RequestCount`. Primary constructor: `(string sessionKey)`. |
 | **MgEventConsumerBase** | nopCommerce event consumer base. Subscribes to: `EntityUpdatedEvent<Product>`, `EntityInsertedEvent<Product>`, `CustomerRegisteredEvent`, `OrderPlacedEvent`, `PageRenderingEvent`, `ProductSearchEvent`. All handlers virtual with empty default. |
 | **MgLockServiceBase** | `SemaphoreSlim(1)` wrapper. Implements `IMgLockService`. Used by `MgDbContextBase.TransactionSafe*`. |
-| **NopLogWriter** | Bridges AyCode logging (see `AyCode.Core/docs/LOGGING.md`) to nopCommerce `Log` table.
+| **NopLogWriter** | Bridges AyCode logging (see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md`) to nopCommerce `Log` table.
 | **NopLoggerMsSqlNopDataProvider** | Extends `MsSqlNopDataProvider`. Provides `InsertLogItem<T>()` / `InsertLogItemAsync<T>()` with own `TransactionScope(Suppress, ReadUncommitted)` to avoid transaction nesting. |

 ## AyCode Types (external, from DLL references)
@ -48,10 +48,10 @@ Terminology for the Mango.Nop Libraries. Read this before working on unfamiliar
 | Term | Definition |
 |---|---|
 | **IEntityInt** | `int Id` entity contract (AyCode.Interfaces.Entities) |
-| **IAcLoggerBase** | Logger interface — see `AyCode.Core/docs/LOGGING.md` (`AyCode.Core.Loggers`) |
-| **IAcLogWriterBase** | Log writer interface — pluggable output sink (see `AyCode.Core/docs/LOGGING.md`) |
-| **AcLoggerBase** | Logger base class with category name and writer array (see `AyCode.Core/docs/LOGGING.md`) |
-| **AcLogItemWriterBase\<T\>** | Log writer base for structured log items (see `AyCode.Core/docs/LOGGING.md`) |
+| **IAcLoggerBase** | Logger interface — see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md` (`AyCode.Core.Loggers`) |
+| **IAcLogWriterBase** | Log writer interface — pluggable output sink (see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md`) |
+| **AcLoggerBase** | Logger base class with category name and writer array (see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md`) |
+| **AcLogItemWriterBase\<T\>** | Log writer base for structured log items (see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md`) |
 | **IAcModelDtoBaseEmpty** | Empty DTO marker interface |
 | **IAcSoftRemoveEntity** | Soft-delete contract (AyCode) |
 | **IForeignKey** | FK marker interface |
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,23 @@
+# Mango.Nop Libraries documentation
+
+Top-level documentation for the Mango.Nop shared libraries (Layer 2 — shared NopCommerce plugin framework).
+
+## Reference docs (flat)
+
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — Repo architecture overview
+- [`CONVENTIONS.md`](CONVENTIONS.md) — Coding conventions
+- [`GLOSSARY.md`](GLOSSARY.md) — Domain glossary
+
+## Sub-projects with docs
+
+- `Mango.Nop.Core/docs/` — Core entity mirrors, DTOs, architecture
+- `Mango.Nop.Data/docs/` — Repository and transaction patterns
+- `Mango.Nop.Services/docs/` — Service patterns, logger bridge
+
+## Navigation
+
+Per the AI Agent Core Protocol (folder navigation rule), start from this README when browsing `docs/`. Single-file reference docs remain flat at this level; multi-file topics live in named subfolders at the sub-project level.
+
+## See also
+
+- **Base framework**: `../../../../Aycode/Source/AyCode.Core/` (see each project's `docs/` folder).