diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 9995ce6..822c5f4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -4,17 +4,25 @@ You are operating in a multi-repo, documentation-first architecture. You MUST STRICTLY follow this protocol for every response. Failure to do so will break the workspace rules. 1. **MANDATORY OUTPUT PREFIX:** Your response MUST begin on the very first line with this format: - `[LOADED_DOCS: N files (+K this turn: )]` + `[LOADED_DOCS: N files (+K this turn: )]` - `N` = total count of `.md` files currently in your context (across all loaded docs in this conversation) - `K` = count of `.md` files newly loaded during THIS response (may be 0) - - If `K > 0`: list the newly loaded **basenames only** (no paths) after `:` + - If `K > 0`: list the newly loaded files as **shortest unique short names** (see naming rule below) - If `K = 0`: write `[LOADED_DOCS: N files, no new loads]` - If `N = 0`: write `[LOADED_DOCS: NONE]` + **Short-name rule (for each loaded `.md` file):** + - **Default:** use the basename only. Works for all topic-prefixed companions (`LOGGING_ISSUES.md`, `BINARY_FEATURES.md`) and flat single-file topics (`ARCHITECTURE.md`, `GLOSSARY.md`, `CONVENTIONS.md`) — these are already unique. + - **For `README.md` files:** always include the immediate parent folder as prefix → `TOPIC/README.md` (e.g., `LOGGING/README.md`, `BINARY/README.md`). Never write a bare `README.md` in the prefix because multiple folders have one. + - **Cross-project disambiguation:** if two files share the same short name (rare — e.g., `docs/README.md` from two different projects), extend the prefix one more level: `PROJECT/docs/README.md`. Always use the shortest unique form. + - **Never use absolute paths.** Never include the `.github/` prefix for `copilot-instructions.md` — the `.github/` location is implicit. When multiple are loaded simultaneously (typical in `protocol-audit`), apply the cross-project disambiguation above: `AyCode.Core/copilot-instructions.md`, `FruitBankHybridApp/copilot-instructions.md`, etc. + **Examples:** - `[LOADED_DOCS: NONE]` — nothing loaded yet - `[LOADED_DOCS: 1 files, no new loads]` — only `copilot-instructions.md` loaded earlier, nothing new this turn - - `[LOADED_DOCS: 4 files (+3 this turn: LOGGING.md, LOGGING_ISSUES.md, LOGGING_TODO.md)]` — 3 new this turn + - `[LOADED_DOCS: 4 files (+3 this turn: LOGGING/README.md, LOGGING_ISSUES.md, LOGGING_TODO.md)]` — logger topic folder loaded + - `[LOADED_DOCS: 7 files (+3 this turn: SIGNALR/README.md, SIGNALR_ISSUES.md, SIGNALR_TODO.md)]` — SignalR topic loaded (LOGGING was already in context) + - `[LOADED_DOCS: 5 files (+2 this turn: ARCHITECTURE.md, GLOSSARY.md)]` — top-level reference docs loaded (flat, no folder prefix needed) This prefix is MANDATORY on **EVERY** response (not just the first, not just when loading happens). It serves two purposes: **(a)** user-visible compliance signal, and **(b)** self-commitment for the no-re-read rule — in subsequent turns you read your own prior prefix from the conversation to enforce Rule #3. Dropping the prefix breaks both. @@ -50,6 +58,23 @@ You are operating in a multi-repo, documentation-first architecture. You MUST ST 5. **EXPLICIT CONSENT FOR MODIFICATIONS:** NEVER rewrite, create, or delete any file (code, documentation, configuration, memory, or otherwise) without the user's explicit permission. If the user does not specifically request a code modification (e.g., using phrases like "we are just thinking," "what do you think," "let's plan"), you MUST ONLY provide text-based analysis and planning. You are FORBIDDEN from using file-modifying tools (`replace_string_in_file`, `edit_file`, `create_file`, etc.) until the user explicitly says "ok", "go ahead", "implement", or a similar unambiguous approval. +## Session Setup + +**Mandatory reads at session start** — in addition to this `copilot-instructions.md`, the agent MUST load the four workspace skills' `SKILL.md` files: + +- `docs-discovery/SKILL.md` — **reactive** (triggers on any domain question — must be ready BEFORE the first domain query arrives) +- `docs-check/SKILL.md` — **reactive** (triggers at the end of every code-modifying response) +- `protocol-audit/SKILL.md` — **on-demand** (triggers on explicit "audit protocol" command) +- `adr-author/SKILL.md` — **on-demand + LLM-suggested** (triggers on explicit planning/design requests, or when the LLM flags an ADR-worthy conversation and the user confirms) + +**Path resolution**: if this repo is the canonical protocol host (see `@repo` block below — typically AyCode.Core), the paths are local: `.github/skills//SKILL.md`. Otherwise, prefix with this repo's `own-dep-repos` AyCode.Core path (see the `## Shared Agent Skills` section below for explicit paths). + +**Why mandatory**: workspace skills are NOT in Claude Code's native skill-registry / system-reminder. Without pre-loading their `SKILL.md` content, the agent cannot reliably recognize implicit triggers (e.g., "domain question → invoke docs-discovery" at the moment the question arrives, not retroactively). Pre-loading is a **one-time cost** per session (~10-13K tokens); Rule #3 (no-re-read) prevents repeated reads; re-read only if Rule #4 (Context Recovery) fires. + +**Amortization — critical, do NOT re-evaluate per-turn**: the Session Setup cost is measured over the ENTIRE session, not per single turn. A typical session has many turns; the first domain question alone already recoups the investment (alternative — repeated source-code `Grep`/`Read` per turn — costs 10-20K tokens *per turn* with lower output quality). Do NOT flag pre-loaded content as "wasteful" for turns that don't invoke it — the design depends on cross-turn amortization + Rule #3 (no-re-read) + on-demand specificity of Rule #4 (Context Recovery). This amortization is the **central token-economics principle** of the entire protocol stack. + +The first response's `[LOADED_DOCS: ...]` prefix must reflect **5 files** (this `copilot-instructions.md` + 4 SKILL.md). + ## Workspace Dependencies # own-dep-repos: "name: path" — paths are relative to this repo root (.github/..) @repo { @@ -66,7 +91,7 @@ You are operating in a multi-repo, documentation-first architecture. You MUST ST ## Shared Agent Skills -Skills defined in other repos that can be referenced from here: +Skills defined in other repos. **All four are pre-loaded at session start per the `## Session Setup` section above** (mandatory — ensures implicit triggers fire reliably): - **protocol-audit** — Cross-repo consistency audit for `.github/copilot-instructions.md` across all 5 repos. Location: `AyCode.Core/.github/skills/protocol-audit/SKILL.md` @@ -76,6 +101,14 @@ Skills defined in other repos that can be referenced from here: Location: `AyCode.Core/.github/skills/docs-discovery/SKILL.md` (see `own-dep-repos` above for the relative path to AyCode.Core) **Invoke proactively** before any domain-related coding task (see "Documentation-first coding" below). Honours the active repo's **no-re-read** rule. +- **docs-check** — Evaluate loaded `.md` files at the end of every code-modifying response: drift vs code, missing topic coverage, csproj-glob registration gaps for new `.md` files, and new issue/TODO candidates. Emits the `[DOCUMENTATION CHECK]` section. + Location: `AyCode.Core/.github/skills/docs-check/SKILL.md` + **Invoke at the end of every code-modifying response.** Read-only on loaded docs; all patches surface as proposals (Rule #5 approval required). + +- **adr-author** — Create Architecture Decision Records (ADRs) for architecturally significant design decisions. Structured interview (context → alternatives → trade-offs → decision → consequences) producing a durable `docs/adr/NNNN-.md` file (product decisions) or a new `LLMP-DEC-N` row in the protocol decision log (meta-protocol decisions). + Location: `AyCode.Core/.github/skills/adr-author/SKILL.md` + **Invoke on explicit user request** ("let's plan X", "decide Y vs Z", "design the W module") **or proactively flag** when the conversation looks ADR-worthy (user must confirm — never auto-invoke). + ## Protocol History Cumulative log of LLM-protocol decisions (rule changes, new skills, structural shifts): @@ -114,10 +147,7 @@ Before running any source-code `Grep` / `get_file` / `code_search` in response t ## Conventions 14. **`Mg` prefix** for all custom types: `MgEntityBase`, `MgOrderDto`, `MgDbTableBase`, etc. 15. **No redundant code** — before writing new logic, check whether similar methods already exist in the current context. Reuse or extract shared logic. -16. **Keep all .md documentation in sync (PASSIVE DETECTION & ASK FIRST)** — If you notice *any contradiction, error, or missing information* between the code and your currently loaded `.md` files, **briefly notify the user and ask for permission before making changes**. Do NOT automatically update `.md` files or trigger new searches yet. Once the user approves, you may actively search, read, and update the necessary docs in the correct layer. -**Identify missing documentation:** If you notice during your task that a frequently used pattern, underlying logic, or important behavior is missing from the docs, **and adding it would improve future LLM context-efficiency (saving searches/tokens)**, briefly notify the user to get approval. -**Topic-based separation:** When creating or expanding documentation, keep logically distinct features or domains in separate `.md` files (e.g., architecture, data model, billing) and only reference them in the main/index documents. Do not cram everything into a single monolithic file. Keep in mind: these `.md` files are primarily for LLM grounding and context providing. Keep them concise, structured, and focused on rules/patterns rather than human-readable prose. -**ENFORCEMENT:** At the end of EVERY code-modifying response, append a **`[DOCUMENTATION CHECK]`** section. Evaluate ONLY the `.md` files *already in your context*. State in 1-2 sentences if you found discrepancies or missing concepts, and ask if they should be documented. **DO NOT trigger searches or tool calls for this initial check**. +16. **Keep all .md documentation in sync** — at the end of EVERY code-modifying response, invoke the **`docs-check`** skill (`AyCode.Core/.github/skills/docs-check/SKILL.md`). It evaluates loaded `.md` files for drift vs code, missing topic coverage, csproj-glob registration gaps for new `.md` files, and new issue/TODO candidates — then emits the `[DOCUMENTATION CHECK]` section per its procedure (or `[DOCUMENTATION CHECK] None.` single-line when nothing to report). The skill encapsulates the full calibration (4 prerequisites, 3-item volume cap, no-ID rule, status-update-on-fix clause) and empty-state handling. Passive detection + ASK FIRST; all patches require user approval (Rule #5). Do NOT trigger new searches for this check. 17. All AyCode references are via **DLL** (not ProjectReference) — this is intentional. **AyCode.Core** solution (`../../../../../Aycode/Source/AyCode.Core/`) contains all core framework code: interfaces, serialization, binary protocol, SignalR base classes, data sources, logging. Types not defined in this library (e.g. `IEntityInt`, `IId`, `AcConst`, `ToonDescription`) likely live in AyCode.Core. 18. **Do not re-read .md files** already in your context window. They only change if you modify them yourself (new content is already in context) or if the developer tells you they changed — in that case re-read them once. 19. **Folder navigation** — start from the root `README.md` for solution-level navigation. When you need to understand a folder's contents or find a type/class, read the `README.md` in that folder first — it indexes the local files and sub-folders. Follow this before grepping or reading source files. diff --git a/Mango.Nop.Core/.github/copilot-instructions.md b/Mango.Nop.Core/.github/copilot-instructions.md index 91f783c..ab073c8 100644 --- a/Mango.Nop.Core/.github/copilot-instructions.md +++ b/Mango.Nop.Core/.github/copilot-instructions.md @@ -13,6 +13,23 @@ > **AI Agent Protocol:** This repo follows the AI Agent Core Protocol defined in AyCode.Core. Same rules apply: `[LOADED_DOCS]` prefix, docs-before-code, no-re-read policy, context recovery on compaction, explicit consent for modifications. Full protocol: AyCode.Core's `.github/copilot-instructions.md` (see @repo path above). +## Session Setup + +**Mandatory reads at session start** — in addition to this `copilot-instructions.md`, the agent MUST also load: + +1. **Canonical AI Agent Core Protocol** — AyCode.Core's `copilot-instructions.md` (for the full numbered Rules #1-5 that this inherit file references but does NOT duplicate). Path via the `own-dep-repos` AyCode.Core entry above. +2. **The four workspace skills** (see `## Shared Agent Skills` section below for paths): + - `docs-discovery/SKILL.md` — **reactive** (triggers on domain questions) + - `docs-check/SKILL.md` — **reactive** (triggers at end of code-modifying responses) + - `protocol-audit/SKILL.md` — **on-demand** (triggers on explicit "audit protocol" command) + - `adr-author/SKILL.md` — **on-demand + LLM-suggested** (triggers on explicit planning/design requests, or LLM flag + user confirmation) + +The first response's `[LOADED_DOCS: ...]` prefix must reflect **6 files** (this file + AyCode.Core's `copilot-instructions.md` + 4 SKILL.md files). + +**Why mandatory**: workspace skills are NOT in Claude Code's native skill-registry / system-reminder — without pre-loading, implicit triggers (e.g., "domain question → invoke docs-discovery" at the moment of the question) may be missed. This file inherits rules from AyCode.Core, so the canonical protocol file must be loaded alongside. One-time cost per session; Rule #3 (no-re-read) prevents repeated reads; re-read only if Rule #4 (Context Recovery) fires. + +**Amortization — critical, do NOT re-evaluate per-turn**: the Session Setup cost is measured over the ENTIRE session, not per single turn. A typical session has many turns; the first domain question alone already recoups the investment (alternative — repeated source-code `Grep`/`Read` per turn — costs 10-20K tokens *per turn* with lower output quality). Do NOT flag pre-loaded content as "wasteful" for turns that don't invoke it — the design depends on cross-turn amortization + Rule #3 (no-re-read) + on-demand specificity of Rule #4 (Context Recovery). This amortization is the **central token-economics principle** of the entire protocol stack. + ## Framework-First Design Principle 🛑 **This repo is framework (Layer 2 — Domain framework), not a consumer application.** Provides base types for NopCommerce plugin development. Consumers = specific plugin projects (plural, unknown). @@ -41,7 +58,7 @@ Full doctrine: AyCode.Core's `.github/copilot-instructions.md#framework-first-de ## Shared Agent Skills -Skills defined in other repos that can be referenced from here: +Skills defined in other repos. **All four are pre-loaded at session start per the `## Session Setup` section above** (mandatory — ensures implicit triggers fire reliably): - **docs-discovery** — Load relevant `.md` documentation (main + `_ISSUES` + `_TODO` paired sets) BEFORE source-code search or modifications. Saves tokens vs. grep-based rediscovery. Location: `AyCode.Core/.github/skills/docs-discovery/SKILL.md` (see `own-dep-repos` above for the relative path to AyCode.Core) @@ -51,6 +68,14 @@ Skills defined in other repos that can be referenced from here: Location: `AyCode.Core/.github/skills/protocol-audit/SKILL.md` Activate from an AyCode.Core session, or read the SKILL.md directly and follow its steps. +- **docs-check** — Evaluate loaded `.md` files at the end of every code-modifying response: drift vs code, missing topic coverage, csproj-glob registration gaps for new `.md` files, and new issue/TODO candidates. Emits the `[DOCUMENTATION CHECK]` section. + Location: `AyCode.Core/.github/skills/docs-check/SKILL.md` + **Invoke at the end of every code-modifying response.** Read-only on loaded docs; all patches surface as proposals (Rule #5 approval required). + +- **adr-author** — Create Architecture Decision Records (ADRs) for architecturally significant design decisions. Structured interview (context → alternatives → trade-offs → decision → consequences) producing a durable `docs/adr/NNNN-.md` file (product decisions) or a new `LLMP-DEC-N` row in the protocol decision log (meta-protocol decisions). + Location: `AyCode.Core/.github/skills/adr-author/SKILL.md` + **Invoke on explicit user request** ("let's plan X", "decide Y vs Z", "design the W module") **or proactively flag** when the conversation looks ADR-worthy (user must confirm — never auto-invoke). + ## Protocol History Cumulative log of LLM-protocol decisions (rule changes, new skills, structural shifts): diff --git a/Mango.Nop.Core/Mango.Nop.Core.csproj b/Mango.Nop.Core/Mango.Nop.Core.csproj index 9a7b7b8..d4e6715 100644 --- a/Mango.Nop.Core/Mango.Nop.Core.csproj +++ b/Mango.Nop.Core/Mango.Nop.Core.csproj @@ -52,8 +52,8 @@ - - + + diff --git a/Mango.Nop.Core/README.md b/Mango.Nop.Core/README.md index 77c1b55..710c499 100644 --- 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) diff --git a/Mango.Nop.Core/docs/README.md b/Mango.Nop.Core/docs/README.md new file mode 100644 index 0000000..e602ea6 --- /dev/null +++ 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 diff --git a/Mango.Nop.Data/Mango.Nop.Data.csproj b/Mango.Nop.Data/Mango.Nop.Data.csproj index 7faccd2..5460ead 100644 --- a/Mango.Nop.Data/Mango.Nop.Data.csproj +++ b/Mango.Nop.Data/Mango.Nop.Data.csproj @@ -46,8 +46,8 @@ - - + + diff --git a/Mango.Nop.Data/docs/README.md b/Mango.Nop.Data/docs/README.md new file mode 100644 index 0000000..8f4910e --- /dev/null +++ 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` diff --git a/Mango.Nop.Services/Mango.Nop.Services.csproj b/Mango.Nop.Services/Mango.Nop.Services.csproj index 08ae823..17c5a50 100644 --- a/Mango.Nop.Services/Mango.Nop.Services.csproj +++ b/Mango.Nop.Services/Mango.Nop.Services.csproj @@ -49,8 +49,8 @@ - - + + diff --git a/Mango.Nop.Services/README.md b/Mango.Nop.Services/README.md index 263cdc9..a63b8d6 100644 --- 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 diff --git a/Mango.Nop.Services/docs/LOGGING_BRIDGE.md b/Mango.Nop.Services/docs/LOGGING/README.md similarity index 96% rename from Mango.Nop.Services/docs/LOGGING_BRIDGE.md rename to Mango.Nop.Services/docs/LOGGING/README.md index 8932b99..334aac3 100644 --- a/Mango.Nop.Services/docs/LOGGING_BRIDGE.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 diff --git a/Mango.Nop.Services/docs/README.md b/Mango.Nop.Services/docs/README.md new file mode 100644 index 0000000..14332ab --- /dev/null +++ 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` diff --git a/Mango.Nop.Services/docs/SERVICES.md b/Mango.Nop.Services/docs/SERVICES.md index f4123d1..895474f 100644 --- 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 diff --git a/README.md b/README.md index 86caa85..20addeb 100644 --- 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 | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index a06ca16..b40ce7a 100644 --- 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 (extends AcLoggerBase, delegates to IAcLogWriterBase[]) → NopLogWriter (in Services, extends AcLogItemWriterBase) → 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`. diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md index d23381a..527bf5a 100644 --- 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(logWriters.ToArray())` in constructor. - `logWriters` injected as `IEnumerable` — 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` — FK marker interfaces diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index 7d71ed9..5f86faa 100644 --- 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`, `EntityInsertedEvent`, `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()` / `InsertLogItemAsync()` 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\** | 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\** | 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 | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8c93666 --- /dev/null +++ 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).