seb/dashback
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

services

Browse Source
This commit is contained in:
seb
2026-06-24 09:50:08 +02:00
parent 185b68fe52
commit 9b11a8a24c
18 changed files with 716 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/api/README.md
View File

@@ -34,8 +34,15 @@ Mirrors [`src/api/routes/`](../../src/api/routes/).
| [`routes/auth/logout.md`](routes/auth/logout.md) | `POST /auth/logout` |
| [`routes/auth/me.md`](routes/auth/me.md) | `GET /auth/me` |
| [`routes/health.md`](routes/health.md) | `GET /health` |
| [`routes/article/search.md`](routes/article/search.md) | `GET /article/search` |
| [`routes/article/get.md`](routes/article/get.md) | `GET /article/get` |
| [`routes/misc/getSteuer.md`](routes/misc/getSteuer.md) | `GET /misc/getSteuer` |
| [`routes/misc/getCategories.md`](routes/misc/getCategories.md) | `GET /misc/getCategories` |
## Frontend checklist
## DESIGN
- [ ] `credentials: 'include'` on every API call
- [ ] HTTPS in dev (or proxy) so `Secure` cookies work
- for every route we have a file in /src/api/routes
- that should loosly bound to services in /src/services
- for every service we have a CLI tester in /scripts/
- all DB SQL code shall be in /src/db
- with mssql staements in /src/db/mssql/

121
docs/api/routes/article/get.md Normal file
View File

@@ -0,0 +1,121 @@
# `GET /article/get`
Protected. Requires a valid session cookie (`credentials: 'include'`).
Full article detail by **exact** match. Use after the user picks a row from [`GET /article/search`](search.md).
## Query parameters
| Param | Required | Description |
|-------|----------|-------------|
| `target` | yes | Exact article number (`cArtNr`), packaging EAN (`tGebinde.cEAN`), or barcode (`cBarcode`). |
## Response `200`
```json
{
"article": {
"kArtikel": 49,
"cArtNr": "42000044",
"cName": "BioBizz AllMix Peat Free 20L",
"cAktiv": "Y",
"fVKNEtto": 11.3445378151261,
"kSteuerklasse": 1,
"fBestand": null,
"cHersteller": null,
"cBarcode": null,
"KATs": [{ "kKategorie": 16 }, { "kKategorie": 39 }],
"lief": [],
"staffel": [],
"EANs": [],
"merkmale": [],
"attribute": []
}
}
```
The object is enriched with related data in parallel. Fields below are always present on success; arrays may be empty.
### Core fields
| Field | Type | Notes |
|-------|------|-------|
| `kArtikel` | number | Internal ID |
| `cArtNr` | string | Article number |
| `cName` | string | Name |
| `cBeschreibung` | string | Long description (HTML) |
| `cKurzBeschreibung` | string | Short description |
| `cAktiv` | string | `"Y"` or `"N"` |
| `fVKNEtto` | number | Net sales price |
| `kSteuerklasse` | number | `1` / `2` / `3` |
| `fUVP` | number | RRP |
| `fBestand` | number \| null | Stock warehouse 1 |
| `fGewicht` | number | Weight |
| `cBarcode` | string \| null | |
| `cHersteller` | string \| null | Manufacturer name |
| `cAnmerkung` | string | Internal note |
| `kVersandklasse` | number | Shipping class ID |
| `tVersandklassecName` | string | Shipping class name |
| `nIstVater` | number | `1` if parent article with variants |
| `kVaterArtikel` | number | Parent article ID (variants) |
| `kStueckliste` | number | Bill-of-materials ID; `0` if none |
| `kEigenschaftKombi` | number | Variant combination |
| `cEigenschaftName` | string \| null | Variant property name |
| `cEigenschaftWertName` | string \| null | Variant value name |
| `cLiefArtNr96` | string \| null | Supplier 96 article number |
| `nVPE` | number | Sales unit flag |
| `kMassEinheit` | number \| null | Unit of measure |
| `fMassMenge` | number | Unit quantity |
| `shops` | number \| null | Shop bitmask sum |
| `garage` | number \| undefined | Extra storage slot 0 qty |
| `keller` | number \| undefined | Extra storage slot 1 qty |
| `cHerstellerGPSR` | string \| null | Manufacturer GPSR text |
| `herstellerBild` | string \| null | Manufacturer logo, base64 PNG |
### Related arrays / objects
| Field | Description |
|-------|-------------|
| `children` | Variant rows (when `nIstVater === 1`) |
| `vater` | Parent `{ cArtNr }` (when variant) |
| `liste` | Stückliste / BOM components |
| `fAndereLager` | Stock in other warehouses `[{ fSumme }]` |
| `EANs` | `[{ cEAN }]` |
| `KATs` | `[{ kKategorie }]` |
| `lief` | Suppliers; `cAnmerkung` may be parsed into `anmerkung` |
| `incoming` | Open supplier purchase orders |
| `orders` | Open incidents (`order_count`, `order_label`, `order_free`) |
| `merkmale` | Features `[{ kMerkmal, cName, cWert, … }]` |
| `attribute` | Custom attributes |
| `staffel` | Tier prices `[{ menge, fVKBrutto }]` — brutto pre-formatted string |
### Supplier row (`lief[]`)
| Field | Notes |
|-------|-------|
| `kLieferant`, `cFirma` | Supplier |
| `cLiefArtNr` | Supplier article number |
| `nStandard` | Preferred supplier flag |
| `fEKNetto`, `fMwSt` | Purchase price / VAT |
| `fLagerbestand` | Supplier stock |
| `cEmail`, `cAnmerkung` | Contact / note |
## Errors
| Status | Body |
|--------|------|
| 400 | `{ "error": "Query parameter \"target\" is required" }` |
| 401 | `{ "error": "Unauthorized" }` |
| 404 | `{ "error": "Article not found" }` |
| 500 | `{ "error": "..." }` |
## Example
```js
// User selected cArtNr from search results
const res = await fetch(
'http://localhost:4208/api/article/get?target=42000044',
{ credentials: 'include' }
);
const { article } = await res.json();
```

100
docs/api/routes/article/search.md Normal file
View File

@@ -0,0 +1,100 @@
# `GET /article/search`
Protected. Requires a valid session cookie (`credentials: 'include'`).
Fuzzy article search against JTL-Wawi (MSSQL). Use this to build a search box / result list.
## Query parameters
| Param | Required | Description |
|-------|----------|-------------|
| `target` | yes | Search string. Split on spaces; each word must match (AND). Each word is matched with `LIKE %word%` against EAN, supplier article number, name, article number, or barcode. |
| `filter` | no | Comma-separated category IDs. Omit or leave empty to search all categories. See [Category filter](#category-filter). |
## Search behaviour
- Multiple spaces are collapsed to one.
- Example: `target=bizz allmix` → both `bizz` **and** `allmix` must match somewhere on the article.
- By default only **active** articles (`cAktiv = 'Y'`) are returned.
- Without a category filter, at most **2000** rows are returned.
- Results are ordered by product name ascending.
## Category filter
| `filter` value | Effect |
|----------------|--------|
| *(omitted or empty)* | All categories; `TOP 2000` |
| `751` | Include inactive articles (no `cAktiv = 'Y'` restriction). Still uses category branch logic if other IDs are present. |
| `16` or `16,39` | Restrict to articles in those categories (OR). No row limit. |
Pass category IDs as a comma-separated list: `filter=16,39`.
## Response `200`
```json
{
"katagg": {
"16": 12,
"39": 8
},
"recordset": [
{
"katList": "16,39",
"fVerfuegbar": 0,
"kArtikel": 49,
"fBestand": null,
"cArtNr": "42000044",
"cName": "BioBizz AllMix Peat Free 20L",
"fVKNEtto": 11.3445378151261,
"kSteuerklasse": 1
}
]
}
```
### `recordset[]` fields
| Field | Type | Notes |
|-------|------|-------|
| `kArtikel` | number | Internal article ID |
| `cArtNr` | string | Article number — pass to [`GET /article/get`](get.md) |
| `cName` | string | Display name |
| `fBestand` | number \| null | Stock in warehouse 1 |
| `fVerfuegbar` | number \| null | Available stock |
| `fVKNEtto` | number | Net sales price |
| `kSteuerklasse` | number | Tax class: `1` = 19%, `2` = 7%, `3` = 0% |
| `katList` | string \| null | Comma-separated category IDs on the article |
### `katagg`
Map of category ID → count of matching articles in that category (including parent categories in the tree). Use for category sidebar / facet counts.
### Display price (frontend)
Brutto VK is not returned; compute client-side using [`GET /misc/getSteuer`](../misc/getSteuer.md):
```js
function getBrutto(netto, kSteuerklasse, steuerklassen) {
const row = steuerklassen.find((s) => s.kSteuerklasse === kSteuerklasse);
if (!row) return null;
return netto * (1 + row.fSteuersatz / 100);
}
```
## Errors
| Status | Body |
|--------|------|
| 400 | `{ "error": "Query parameter \"target\" is required" }` |
| 401 | `{ "error": "Unauthorized" }` |
| 500 | `{ "error": "..." }` |
## Example
```js
const res = await fetch(
'http://localhost:4208/api/article/search?target=bizz%20allmix',
{ credentials: 'include' }
);
const { katagg, recordset } = await res.json();
```

78
docs/api/routes/misc/getCategories.md Normal file
View File

@@ -0,0 +1,78 @@
# `GET /misc/getCategories`
Protected. Requires a valid session cookie (`credentials: 'include'`).
Returns the full JTL category list and a nested tree. Same data source as the legacy `getKat` socket handler in dashApp.
## Response `200`
```json
{
"categories": [
{
"kKategorie": 16,
"kOberKategorie": 0,
"nSort": 10,
"cName": "Dünger",
"count": 142
}
],
"tree": [
{
"kKategorie": 16,
"kOberKategorie": 0,
"nSort": 10,
"cName": "Dünger",
"count": 142,
"children": [
{
"kKategorie": 39,
"kOberKategorie": 16,
"nSort": 0,
"cName": "Bio",
"count": 47,
"children": []
}
]
}
]
}
```
### `categories[]`
Flat list — useful for lookups by ID (`katNames`-style maps).
| Field | Type | Description |
|-------|------|-------------|
| `kKategorie` | number | Category ID |
| `kOberKategorie` | number | Parent category ID (`0` = root) |
| `nSort` | number | Sort order among siblings |
| `cName` | string \| null | German display name (Sprache 1, Plattform 1, Shop 0) |
| `count` | number | Active articles directly in this category |
### `tree[]`
Nested hierarchy rooted at `kOberKategorie === 0` (or orphaned nodes). Each node has the same fields plus `children[]`, sorted by `nSort` then `cName`.
Use `tree` for sidebar navigation; use `categories` for ID → name maps or [`GET /article/search`](../article/search.md) `filter` param.
## Errors
| Status | Body |
|--------|------|
| 401 | `{ "error": "Unauthorized" }` |
| 500 | `{ "error": "..." }` |
## Example
```js
const res = await fetch('http://localhost:4208/api/misc/getCategories', {
credentials: 'include',
});
const { categories, tree } = await res.json();
const katNames = Object.fromEntries(
categories.map((kat) => [kat.kKategorie, kat.cName])
);
```

63
docs/api/routes/misc/getSteuer.md Normal file
View File

@@ -0,0 +1,63 @@
# `GET /misc/getSteuer`
Protected. Requires a valid session cookie (`credentials: 'include'`).
Returns tax classes and their rates from JTL-Wawi (`tSteuerklasse` + `tSteuersatz`, domestic zone `kSteuerzone = 1`).
## Response `200`
```json
{
"steuerklassen": [
{
"kSteuerklasse": 1,
"cName": "Normaler Steuersatz",
"nStandard": 1,
"fSteuersatz": 19
},
{
"kSteuerklasse": 2,
"cName": "Ermäßigter Steuersatz",
"nStandard": 0,
"fSteuersatz": 7
}
]
}
```
| Field | Description |
|-------|-------------|
| `kSteuerklasse` | Tax class ID (used on articles as `kSteuerklasse`) |
| `cName` | Display name |
| `nStandard` | `1` if this is the default tax class |
| `fSteuersatz` | VAT rate in percent |
### Brutto calculation
Look up the article's `kSteuerklasse` in `steuerklassen`, then:
```js
function getBrutto(netto, kSteuerklasse, steuerklassen) {
const row = steuerklassen.find((s) => s.kSteuerklasse === kSteuerklasse);
if (!row) return null;
return netto * (1 + row.fSteuersatz / 100);
}
```
Load once on app init and reuse for search results and article detail.
## Errors
| Status | Body |
|--------|------|
| 401 | `{ "error": "Unauthorized" }` |
| 500 | `{ "error": "..." }` |
## Example
```js
const res = await fetch('http://localhost:4208/api/misc/getSteuer', {
credentials: 'include',
});
const { steuerklassen } = await res.json();
```