60 lines
3.9 KiB
Markdown
60 lines
3.9 KiB
Markdown
# 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>();
|
|
```
|