From d6c828262d8046e62c806077764a0489dea16e80 Mon Sep 17 00:00:00 2001 From: Loretta Date: Tue, 2 Jun 2026 15:23:48 +0200 Subject: [PATCH] =?UTF-8?q?Add=20EK=C3=81ER=20topic=20docs,=20schema=20upd?= =?UTF-8?q?ate,=20and=20issue=20tracking?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Registered `EKAER` topic code and docs location in the per-repo registry. - Added `Gtin` property to schema for EKÁER VTSZ (customs tariff) mapping. - Created EKÁER README detailing server-side NAV reporting logic and mapping. - Added EKÁER issues and TODO docs to track known problems and open mapping decisions. - Improved cross-references for EKÁER documentation discoverability. --- .../.github/TOPIC_CODES.md | 7 ++- .../docs/EKAER/EKAER_ISSUES.md | 26 ++++++++ .../docs/EKAER/EKAER_TODO.md | 33 +++++++++++ Nop.Plugin.Misc.AIPlugin/docs/EKAER/README.md | 59 +++++++++++++++++++ Nop.Plugin.Misc.AIPlugin/docs/SCHEMA.md | 11 +--- 5 files changed, 125 insertions(+), 11 deletions(-) create mode 100644 Nop.Plugin.Misc.AIPlugin/docs/EKAER/EKAER_ISSUES.md create mode 100644 Nop.Plugin.Misc.AIPlugin/docs/EKAER/EKAER_TODO.md create mode 100644 Nop.Plugin.Misc.AIPlugin/docs/EKAER/README.md diff --git a/Nop.Plugin.Misc.AIPlugin/.github/TOPIC_CODES.md b/Nop.Plugin.Misc.AIPlugin/.github/TOPIC_CODES.md index 3e019ca..615b498 100644 --- a/Nop.Plugin.Misc.AIPlugin/.github/TOPIC_CODES.md +++ b/Nop.Plugin.Misc.AIPlugin/.github/TOPIC_CODES.md @@ -8,6 +8,7 @@ Per-repo topic registry for this plugin, per the **per-repo extension convention ## This repo's own topic codes -| Code | Topic | Scope | Docs location | -|--------|-----------|------------------------------------------------------------------------------------------------|------------------| -| `PREO` | PRE-ORDER | Customer advance orders placed before stock arrives, and their conversion into real nopCommerce orders when an inbound shipping document confirms incoming stock. | `docs/PREORDER/` | +| Code | Topic | Scope | Docs location | +|---------|-----------|------------------------------------------------------------------------------------------------|------------------| +| `PREO` | PRE-ORDER | Customer advance orders placed before stock arrives, and their conversion into real nopCommerce orders when an inbound shipping document confirms incoming stock. | `docs/PREORDER/` | +| `EKAER` | EKÁER | Server-side / nopCommerce-specific aspects of NAV EKÁER reporting: VTSZ source from `Product`, `Shipping`→`tradeCard` data needs, serving the NAV call. The protocol/base layer lives in AyCode.Core (`AyCode.Services/Nav/`). | `docs/EKAER/` | diff --git a/Nop.Plugin.Misc.AIPlugin/docs/EKAER/EKAER_ISSUES.md b/Nop.Plugin.Misc.AIPlugin/docs/EKAER/EKAER_ISSUES.md new file mode 100644 index 0000000..8ac88ef --- /dev/null +++ b/Nop.Plugin.Misc.AIPlugin/docs/EKAER/EKAER_ISSUES.md @@ -0,0 +1,26 @@ +# EKÁER — Known Issues + +> Companion to [`README.md`](README.md). Topic `EKAER`, prefix `MGFBANKPLUG` → entry IDs `MGFBANKPLUG-EKAER-I-` (issue) / `-B-` (confirmed bug). +> ID format, Status vocabulary, type codes and archival → `../../.github/TOPIC_CODES.md` (→ framework registry). + +Scope: a FruitBank EKÁER-bejelentés szerver-oldali / nopCommerce-integrációs problémái — VTSZ-forrás, adatmodell-megfeleltetések, NAV-hívás kiszolgálása. + +## Active entries + +## MGFBANKPLUG-EKAER-I-T3X8: A `Product.Gtin` átmenetileg a VTSZ-t tárolja — szétválasztandó + +**Status:** Open · **Priority:** P3 · **Type:** I (adatmodell / átmeneti megoldás) + +Az EKÁER `tradeCardItem.productVtsz` (kötelező, 8 jegyű vámtarifaszám) forrása jelenleg a nopCommerce **`Product.Gtin`** oszlop (a `ProductDto.Gtin`-en keresztül). A GTIN és a VTSZ **fogalmilag különböző**: +- **GTIN** — globális kereskedelmi cikkszám (vonalkód-azonosító, EAN/UPC). +- **VTSZ** — vámtarifaszám (a termék vám-/statisztikai besorolása). + +Egy termékhez a kettő nem azonos; a `Gtin` oszlop VTSZ-ként való használata **átmeneti** megoldás az EKÁER-integráció beindításához. + +**Hatás:** jelenleg nincs üzemszerű gond (a `Gtin` mező szabad, és a VTSZ-t tölthetjük bele). Hosszú távon viszont, ha a valódi GTIN-re is szükség lesz, a kettő ütközik. + +**Javítási irány (hosszú táv):** külön `Vtsz` mező/`GenericAttribute` a `Product`-on, és a `ShippingToEkaerMapper` onnan olvasson — a `Gtin` maradjon a valódi GTIN. + +**Affected:** +- `FruitBank.Common/Dtos/ProductDto.cs` → `Gtin` property (a `[Column(nameof(Product.Gtin))]` jelöléssel, summary-ban megjelölve) +- jövőbeli: `ShippingToEkaerMapper` (`FruitBank.Common/Services/Ekaer/`) — a `productVtsz`-t a külön `Vtsz` mezőből olvassa diff --git a/Nop.Plugin.Misc.AIPlugin/docs/EKAER/EKAER_TODO.md b/Nop.Plugin.Misc.AIPlugin/docs/EKAER/EKAER_TODO.md new file mode 100644 index 0000000..e78a6ca --- /dev/null +++ b/Nop.Plugin.Misc.AIPlugin/docs/EKAER/EKAER_TODO.md @@ -0,0 +1,33 @@ +# EKÁER — TODO / nyitott döntések + +> Companion to [`README.md`](README.md). Topic `EKAER`, prefix `MGFBANKPLUG` → entry IDs `MGFBANKPLUG-EKAER-T-`. +> ID format, Status vocabulary, type codes, archival → `../../.github/TOPIC_CODES.md` (→ framework registry). + +Scope: a `Shipping` / `ShippingDocument` → NAV `tradeCard` leképezés (`ShippingToEkaerMapper`, `FruitBank.Common/Services/Ekaer/`) nyitott üzleti/technikai döntései. A **tisztázott** megfeleltetést lásd [`README.md`](README.md). + +## Active entries + +## MGFBANKPLUG-EKAER-T-K7Q2: Shipping → tradeCard mapping — nyitott döntések + +**Status:** Open · **Priority:** P2 · **Type:** T (mapping-tervezés) + +A `ShippingToEkaerMapper` megírása előtt tisztázandó pontok. Minden sor a jelenlegi (alapértelmezett) feltételezést és a nyitott kérdést rögzíti. + +| # | Téma | Jelenlegi feltételezés | Nyitott kérdés | +|---|------|------------------------|----------------| +| 1 | `tradeType` (E/I/D irány) | Bejövő = beszerzés. HU feladó → **D** (belföldi), egyébként → **I** (import). A feladó országát a `ShippingDocument.Partner` / `Country` adja. | Automatikusan az országból dőljön el, vagy kézzel (UI) állítható? A kimenő (**E**, export) egyelőre hatókörön kívül (lásd #7). | +| 2 | Célhely (destination) | Hardcode-olt FruitBank-telephely (cím). | Ne hardcode legyen — konfigból/beállításból jöjjön. Honnan (plugin settings / nopCommerce warehouse)? | +| 3 | Érték (`value`, HUF) | `UnitPriceOnDocument × MeasuredQuantity`. | A bejövő tételek tipikusan **EUR**-ban — deviza + árfolyam (FX) konverzió kell HUF-ra. Árfolyam forrása/időpontja? Vevőnként egyeztetni. | +| 4 | Tömeg (`weight`) | `ShippingItem.MeasuredGrossWeight` (bruttó). | Az EKÁER **bruttó** tömeget vár — megerősíteni, hogy ez bruttó és nem nettó. | +| 5 | Granularitás | 1 `ShippingDocument` → 1 `tradeCard`; 1 `Shipping` → több művelet (több dokumentum). | Megerősíteni: tényleg dokumentumonként egy tradeCard? | +| 6 | Eladó (`seller*`) mezők | `ShippingDocument.Partner`-ből: `Name`, `TaxId` (első 8 jegy = adószám-törzs), `CountryCode`, `City`, `Street`, `PostalCode`. | A `Partner` (`PartnerBase`) pontos mezőnevei/forrásai — megerősíteni. | +| 7 | Kimenő irány (`Order` → EKÁER) | Egyelőre nincs. A vevő gyakran maga viszi el (saját fuvar) → nem mi jelentünk. | Mikor kell mégis nekünk export/kimenő (E) tradeCard-ot küldeni? | +| 8 | `productVtsz` forrás | `ProductDto.Gtin` (átmeneti). | GTIN ≠ VTSZ — lásd [`MGFBANKPLUG-EKAER-I-T3X8`](EKAER_ISSUES.md). Hosszú távon külön `Vtsz` mező. | +| 9 | tétel `tradeReason` | `A` (beszerzés) — a mapper ezt használja bejövő árura. | Korábban tévesen `S`-nek feltételezve; az enum valójában `S`=értékesítés, `A`=beszerzés. Üzletileg megerősítendő. | +| 10 | `value` mező | Egyelőre **üresen hagyva** (opcionális mező) a deviza tisztázásáig (#3). | Megerősíteni, hogy a NAV elfogadja érték nélkül bejövő relációban, vagy kötelező-e. | + +**Affected:** +- `ShippingToEkaerMapper` (`FruitBank.Common/Services/Ekaer/`) — a leképezés +- `EkaerTradeCardValidator` / `EkaerSubmitService` / `EkaerManageService` (`AyCode.Services/Nav/Ekaer/`) — validáció + beküldés + HTTP (általános NAV-réteg) +- `FruitBankEkaerService` (`FruitBank.Common.Server/Services/Ekaer/`) — a szerver-oldali fogyasztó (map → submit) +- Forrás-entitások (`FruitBank.Common`): `Shipping`, `ShippingDocument`, `ShippingItem`, `ProductDto.Gtin` diff --git a/Nop.Plugin.Misc.AIPlugin/docs/EKAER/README.md b/Nop.Plugin.Misc.AIPlugin/docs/EKAER/README.md new file mode 100644 index 0000000..4f8b81b --- /dev/null +++ b/Nop.Plugin.Misc.AIPlugin/docs/EKAER/README.md @@ -0,0 +1,59 @@ +# EKÁER — NAV közúti áruforgalom-bejelentés (FruitBank áttekintő) + +Topic `EKAER`, prefix `MGFBANKPLUG` → entry ID-k `MGFBANKPLUG-EKAER-I-` (issue) / `-T-` (TODO) / `-B-` (bug). + +A FruitBank EKÁER-bejelentés **szerver-oldali** (a kliens már standalone WASM, böngészőből CORS miatt nem hívhat NAV-ot — a kliens SignalR-en triggerel). A tényleges logika viszont **rétegekre bontva** él, nem ebben a pluginban; ez a folder a **belépő/áttekintő** + a FruitBank-/nopCommerce-specifikus nyitott döntések. + +> A NAV-protokoll részletei (transport, auth, üzenet-szerkezet) az `AyCode.Core` repóban: `AyCode.Services/Nav/docs/EKAER_*.md`. Itt **nem** ismételjük. + +## A teljes EKÁER-kép (4 réteg) + +| Réteg | Hol | Mit ad | +|---|---|---| +| **NAV/EKÁER framework** | `AyCode.Services/Nav/` + `Nav/Ekaer/` (AyCode.Core) | transport, auth (SHA-512), generált modellek, **`EkaerTradeCardValidator`** (NAV-séma + üzleti szabályok), **`EkaerSubmitService`** (validate→send), `EkaerManageService` (HTTP). Általános — **nem** FruitBank-specifikus. | +| **FruitBank leképezés** | `FruitBank.Common/Services/Ekaer/` | **`ShippingToEkaerMapper`** — `Shipping` → `tradeCard` ops (tiszta leképező, nem validál) | +| **FruitBank fogyasztó** | `FruitBank.Common.Server/Services/Ekaer/` | **`FruitBankEkaerService`** — szerver-oldali orchestráció: credentials/options + map → submit | +| **nopCommerce-integráció (ez a plugin)** | ez a folder + a plugin kód | DI-bekötés, NAV-fiók settings, a VTSZ-forrás (`Product.Gtin`), SignalR-trigger a kliens felől, és ez a doksi | + +## A beküldési lánc + +``` +FruitBankEkaerService.SubmitShippingAsync(shipping) // FruitBank.Common.Server + → ShippingToEkaerMapper.MapShipping(...) // FruitBank.Common (map) + → EkaerSubmitService.SubmitAsync(ops) // AyCode.Services (validate → send) + → EkaerTradeCardValidator.Validate(ops) // hibalista → ha nem üres: NEM küld + → EkaerManageService.ManageAsync(request) // auth + HTTP POST a NAV-nak +``` +Validációs hiba → **hibalista** (`EkaerSubmitResult.Invalid`), nem megy ki kérés. NAV-oldali hiba → `NavReportException` propagál. + +## Companion fájlok + +- [`EKAER_ISSUES.md`](EKAER_ISSUES.md) — ismert problémák (pl. `MGFBANKPLUG-EKAER-I-T3X8`: GTIN≠VTSZ). +- [`EKAER_TODO.md`](EKAER_TODO.md) — a `Shipping → tradeCard` mapping nyitott üzleti döntései. + +## A leképezés (tisztázott pontok) + +| EKÁER | FruitBank forrás | +|---|---| +| `seller*` (feladó) | `ShippingDocument.Partner` (a beszállító) | +| `carrierText` (fuvarozó, szöveges) | `Shipping.CargoPartner.Name` | +| `vehicle` / `vehicle2` | `Shipping.CargoTruck` / `CargoTrailer` (`LicencePlate` + `CountryCode`, normalizálva) | +| tétel `productVtsz` | `ShippingItem.ProductDto.Gtin` (átmenetileg — lásd `EKAER_ISSUES.md`) | +| tétel `productName` | `ShippingItem.ProductName` | +| tétel `weight` | `ShippingItem.MeasuredGrossWeight` (bruttó) | +| tétel `tradeReason` | `A` (beszerzés — bejövő áru). ⚠️ Az enum: `S`=értékesítés, `A`=beszerzés, `W`=bérmunka, `O`=egyéb. | + +A nyitott pontok (tradeType, destination, value/deviza, granularitás, kimenő irány): [`EKAER_TODO.md`](EKAER_TODO.md). + +## Bekötés a szerveren (DI) + +A plugin (vagy a szerver-startup) köti be a láncot — a NAV-fiók titkos adatai a szerver config/secret store-jából: +```csharp +services.AddSingleton(/* NAV-fiók: User/Password/SigningKey/TaxNumber/BaseUrl */); +services.AddHttpClient(/* NAV TLS 1.2 */); +services.AddScoped(); +services.AddScoped(); +services.AddScoped(); +services.AddSingleton(/* EkaerMappingOptions: destination + saját raktár */); +services.AddScoped(); +``` diff --git a/Nop.Plugin.Misc.AIPlugin/docs/SCHEMA.md b/Nop.Plugin.Misc.AIPlugin/docs/SCHEMA.md index f6179a5..699b2c1 100644 --- a/Nop.Plugin.Misc.AIPlugin/docs/SCHEMA.md +++ b/Nop.Plugin.Misc.AIPlugin/docs/SCHEMA.md @@ -1,10 +1,3 @@ -# Domain Model Schema (Toon Format) - -> Part of `Nop.Plugin.Misc.FruitBankPlugin`. See `README.md` for project overview. -> Full domain model in Toon (Token-Oriented Object Notation) format — see `AyCode.Core/Serializers/Toons/README.md` (in AyCode.Core solution). -> This is the authoritative schema for entities, DTOs, and enums in the FruitBank domain. -> For behavioral documentation (workflows, lifecycles, event cascades) see `docs/DOMAIN_MODEL.md`. - @meta { version = "1.0" format = "toon" @@ -165,6 +158,8 @@ constraints: "readonly, not-mapped" GenericAttributes: List navigation: "one-to-many" + Gtin: string + purpose: "nopCommerce Gtin column — holds the EKÁER VTSZ (customs tariff number) used as the trade-card item productVtsz in NAV road-freight reporting." IncomingQuantity: int business-logic: "get => GenericAttributes.GetValueOrDefault('IncomingQuantity')" constraints: "not-mapped" @@ -854,4 +849,4 @@ Id: int purpose: "Primary key / unique identification" primary-key: true -} +} \ No newline at end of file