Add EKÁER topic docs, schema update, and issue tracking
- 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.
This commit is contained in:
parent
727b237253
commit
d6c828262d
|
|
@ -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/` |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,26 @@
|
|||
# EKÁER — Known Issues
|
||||
|
||||
> Companion to [`README.md`](README.md). Topic `EKAER`, prefix `MGFBANKPLUG` → entry IDs `MGFBANKPLUG-EKAER-I-<RAND>` (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
|
||||
|
|
@ -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-<RAND>`.
|
||||
> 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`
|
||||
|
|
@ -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-<RAND>` (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<INavCredentials>(/* NAV-fiók: User/Password/SigningKey/TaxNumber/BaseUrl */);
|
||||
services.AddHttpClient<EkaerManageService>(/* NAV TLS 1.2 */);
|
||||
services.AddScoped<IEkaerTradeCardValidator, EkaerTradeCardValidator>();
|
||||
services.AddScoped<IEkaerSubmitService, EkaerSubmitService>();
|
||||
services.AddScoped<IShippingToEkaerMapper, ShippingToEkaerMapper>();
|
||||
services.AddSingleton(/* EkaerMappingOptions: destination + saját raktár */);
|
||||
services.AddScoped<IFruitBankEkaerService, FruitBankEkaerService>();
|
||||
```
|
||||
|
|
@ -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<GenericAttributeDto>
|
||||
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<int>('IncomingQuantity')"
|
||||
constraints: "not-mapped"
|
||||
|
|
@ -854,4 +849,4 @@
|
|||
Id: int
|
||||
purpose: "Primary key / unique identification"
|
||||
primary-key: true
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue