FruitBank/.github/copilot-instructions.md

FruitBank nopCommerce Server — Domain Rules

own-dep-repos: "name: path" — paths are relative to this repo root (.github/..)

@repo { name = "FruitBank" type = "product" layer = 2 own-dep-repos = [ "AyCode.Core: ../../../Aycode/Source/AyCode.Core", "Mango.Nop Libraries: ../NopCommerce.Common/4.70/Libraries" ] }

This is the single source of truth for the nopCommerce server workspace. Do not duplicate these elsewhere. For Mango.Nop library rules see: .github/copilot-instructions.md (in Mango.Nop Libraries repo) For core framework rules see: .github/copilot-instructions.md (in AyCode.Core repo) On first use, read ../NopCommerce.Common/4.70/Plugins/Nop.Plugin.Misc.AIPlugin/docs/SCHEMA.md — full TOON domain model (rule 19 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. 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 workspace likely live in AyCode.Core.
16. Mango.Nop Libraries (../NopCommerce.Common/4.70/Libraries/) — independent shared library. Contains DTOs, entities, data access, and service base classes. DTO or entity base classes not found in plugins likely live in Libraries.
17. FruitBank nopCommerce Plugin (../NopCommerce.Common/4.70/Plugins/Nop.Plugin.Misc.AIPlugin/) is the main FruitBank plugin. Contains SignalR hubs/endpoints, measurement services, data access (DbTable classes), admin controllers, and AI services. For plugin docs see: ../NopCommerce.Common/4.70/Plugins/Nop.Plugin.Misc.AIPlugin/docs/.
18. Documentation layering — write .md documentation at the defining layer (where the code lives). Higher-layer .md files reference the base docs (e.g. ../../../Aycode/Source/AyCode.Core/{Project}/docs/FILENAME.md) and document only project-specific overrides or extensions. Never duplicate base-layer descriptions in consumer-level docs.
19. 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.