FruitBankHybridApp/.github/copilot-instructions.md

FruitBankHybridApp — Domain Rules

@repo { type = "product" layer = 2 own-dep-repos = ["AyCode.Core", "AyCode.Blazor", "Mango.Nop 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)

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.