FruitBankHybridApp/.github/copilot-instructions.md

# FruitBankHybridApp — Domain Rules

# own-dep-repos: "name: path" — paths are relative to this repo root (.github/..)
@repo {
  name = "FruitBankHybridApp"
  type = "product"
  layer = 2
  own-dep-repos = [
    "AyCode.Core: ../../../Aycode/Source/AyCode.Core",
    "AyCode.Blazor: ../../../Aycode/Source/AyCode.Blazor",
    "Mango.Nop Libraries: ../NopCommerce.Common/4.70/Libraries"
  ]
}

> This is the **single source of truth** for domain rules. Do not duplicate these elsewhere.
> For detailed docs see: `README.md` → `docs/`
> For core framework rules see: `.github/copilot-instructions.md` (in AyCode.Core repo)
> For UI framework rules see: `.github/copilot-instructions.md` (in AyCode.Blazor repo)
> For nopCommerce library rules see: `.github/copilot-instructions.md` (in Mango.Nop Libraries repo)
> For nopCommerce plugin (server side) rules see: `../NopCommerce.Common/4.70/Plugins/Nop.Plugin.Misc.AIPlugin/README.md` (in Mango.Nop Plugins repo)
> On first use, read `../NopCommerce.Common/4.70/Plugins/Nop.Plugin.Misc.AIPlugin/docs/SCHEMA.md` — full TOON domain model (rule 21 prevents re-reading)
> External repos in `own-dep-repos` are fully accessible — read their source code, docs, and `.github/copilot-instructions.md` freely when you need type definitions, base classes, or context. Do not limit yourself to the current workspace.

## Business Domain
1. **FruitBank** = fruit & vegetable wholesaler. The server side runs as a **nopCommerce plugin** — Customer, Order, Product, GenericAttribute are nopCommerce entities.
2. **Shipping** = INBOUND delivery (supplier → warehouse). **Order** = OUTBOUND delivery (warehouse → customer). Never confuse the two directions.
3. **"Pallet"** (`XxxItemPallet`) = a **measurement record**, NOT a physical pallet. Always created for every item, even non-measurable ones.

## Measurement Logic
4. **IsMeasurable=false** → weights are 0.0, only `TrayQuantity` is recorded. A Pallet record is still created.
5. **NetWeight = GrossWeight − PalletWeight − (TrayQuantity × TareWeight)** — this formula is universal across ShippingItemPallet, OrderItemPallet, and StockTakingItemPallet.
6. **MeasuringStatus.Finnished** — intentional legacy typo with double-n. Do NOT fix the spelling.
7. **MeasuringStatus** progression: NotStarted(0) → Started(10) → Finnished(20) → Audited(30). OrderItemPallet adds Audited when RevisorId > 0.

## Data Model
8. **GenericAttribute** = polymorphic key-value store. `KeyGroup` = owner type name, `EntityId` = owner ID. ProductDto reads IsMeasurable, Tare, AverageWeight, IncomingQuantity, NetWeight from GenericAttributes.
9. **Three parallel measurement hierarchies** share the same base (`MeasuringItemPalletBase`):
   - Shipping: ShippingItem → ShippingItemPallet
   - Order: OrderItemDto → OrderItemPallet (adds RevisorId for audit)
   - StockTaking: StockTakingItem → StockTakingItemPallet

## Technical
10. SignalR uses **AcBinaryHubProtocol** (custom binary), not default JSON.
11. Do not suggest removal/rollback as a solution — find a fix for the problem.
12. All AyCode references are via **DLL** (not ProjectReference) — this is intentional. nopCommerce 4.80.9 requirement.
13. **No redundant code** — before writing new logic, check whether similar methods already exist in the current context. Reuse or extract shared logic into smaller methods rather than duplicating.
14. **Keep all .md files in sync** — when you modify code and you know which .md file documents it, update that .md file too. If you notice a contradiction between code and an .md file, automatically update the .md to match the code (code is the source of truth). When fixing a reference, check other .md files that may share the same broken reference. If the root cause is at a lower layer, fix it there first. During code review, if you find useful behavior or conventions not yet documented, briefly suggest what to document and where — but do not add new content without approval.
15. **MgGridBase** (AyCode.Blazor) is the canonical grid base for all data screens. New grids inherit `FruitBankGridBase<TEntity>`, set CRUD tags in the constructor, and use `MgGridWithInfoPanel` for layout. See `AyCode.Blazor.Components/docs/MGGRID.md` (in AyCode.Blazor repo) for the full technical reference. Do NOT create parallel grid base classes.
16. **AyCode.Core** solution (`../../../Aycode/Source/AyCode.Core/`) contains all core framework code: SignalR base classes, serialization, binary protocol, data sources, logging. Types not defined in this solution likely live in AyCode.Core.
17. **AyCode.Blazor** solution (`../../../Aycode/Source/AyCode.Blazor/`) contains all UI framework code: MgGridBase, MgGridWithInfoPanel, toolbar, layout persistence, Blazor component infrastructure. UI base classes or components not found here likely live in AyCode.Blazor.
18. **Mango.Nop Libraries** (`../NopCommerce.Common/4.70/Libraries/`) — independent shared library with its own `.github/copilot-instructions.md` and `docs/`. Contains DTOs, entities, data access, and service base classes. DTO or entity base classes not found in this solution likely live in Libraries.
19. **FruitBank nopCommerce Plugin** (`../NopCommerce.Common/4.70/Plugins/Nop.Plugin.Misc.AIPlugin/`) is the server-side plugin running inside nopCommerce 4.80.9. Contains SignalR hubs/endpoints, measurement services, data access (DbTable classes), admin controllers, and AI services. Server-side endpoints and services are defined here.
20. **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.
21. **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.