# Mango.Nop.Core — Domain Rules

## Workspace Dependencies

@repo {
  name = "Mango.Nop.Core"
  type = "framework"
  layer = 2
  own-dep-repos = ["AyCode.Core: ../../../../../../Aycode/Source/AyCode.Core"]
}

> Domain framework for NopCommerce plugins. Built on Layer 0 (AyCode.Core), consumed by Layer 3 (specific plugin apps, plural and unknown).

> **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).

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

**Before writing code, ask:**
1. Generic (reusable across any NopCommerce plugin)? → belongs HERE
2. Plugin-specific (business logic, specific entities, plugin names)? → NOT HERE
3. Same pattern in 2+ plugins? → promote to framework

**Hard rules:**
- ❌ No plugin names or business-specific terms in code, identifiers, namespaces, or docs
- ❌ No framework → plugin references
- ✅ Abstract/virtual base classes — plugins derive/override
- ✅ Generic DTOs / extensions / interfaces for cross-plugin reuse
- ✅ Mirror NopCommerce entities without a hard runtime dependency on Nop

**Nop-plugin-framework-specific emphasis:**
- `NopDependencies/` mirrors NopCommerce entity classes (same namespace as originals) — stays generic, no plugin-specific logic
- DTOs use type parameters for consumer entity types (e.g. `MgOrderDto<TOrderItemDto, TProductDto>`) — never hardcode concrete plugin types
- Zero runtime NopCommerce dependency — plugin apps bring their own Nop runtime
- Any plugin-specific logic (domain rules, business-specific entities) stays in the plugin, not here

Framework design = **"write the base first, derive the specific later"**.

Full doctrine: AyCode.Core's `.github/copilot-instructions.md#framework-first-design-principle` and `docs/ARCHITECTURE.md#framework-vs-consumer-boundary`.

## Shared Agent Skills

Skills defined in other repos that can be referenced from here:

- **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)
  **Invoke proactively** before any domain-related coding task (see "Documentation-first coding" below). Honours the active repo's **no-re-read** rule.

- **protocol-audit** — Cross-repo consistency audit for `.github/copilot-instructions.md` across all repos.
  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.

## Protocol History

Cumulative log of LLM-protocol decisions (rule changes, new skills, structural shifts):

- `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md`

Read this file when you need to understand **why** a rule is the way it is, or before proposing a protocol change — it may save a debate about something already resolved.

## Documentation-first coding

Before running any source-code `Grep` / `get_file` / `code_search` in response to a domain-related request, invoke the **`docs-discovery`** skill (path above). Scans `docs/` folders in THIS repo AND in referenced repos (via `own-dep-repos`) via Glob, loads paired .md sets as a unit. Rule-number-agnostic — refers to rule NAMES (no-re-read, folder-navigation, explicit-consent) which are stable across repos.

## Related Documentation

| Document | Topic |
|---|---|
| `docs/ARCHITECTURE.md` | Layer position, Nop-framework-specific architecture notes |
| `docs/CONVENTIONS.md` | Framework-first placement + Nop-specific naming |
| `docs/DTOS.md` | DTO system — two mapping strategies, all DTO types |
| `docs/NOP_DEPENDENCIES.md` | Mirror pattern for NopCommerce entities |
| `README.md` | Folder structure, entity hierarchy, key types index |

## Related Solutions

Types referenced here but not defined may live in AyCode.Core or AyCode.Blazor (see @repo path above for AyCode.Core; AyCode.Blazor is at sibling path).