From debad7f7452ba67e48cc29ee5801c14a92723776 Mon Sep 17 00:00:00 2001 From: Loretta Date: Tue, 31 Mar 2026 16:15:03 +0200 Subject: [PATCH] Add LLM instruction files for cross-repo navigation - CLAUDE.md: single-line pointer to copilot-instructions.md - copilot-instructions.md: added @repo name field, relative paths in own-dep-repos, SCHEMA.md first-use read, "do not re-read .md files" rule, and explicit permission to navigate external repos Co-Authored-By: Claude Opus 4.6 --- .github/copilot-instructions.md | 48 +++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 49 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 CLAUDE.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..1c5f5deb --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,48 @@ +# 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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..66676773 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +Always read `.github/copilot-instructions.md` first — it is the single source of truth for this repo.