u

2026-10-16 22:09:15 +02:00
parent 188cd71f63
commit d7f7d669f9
13 changed files with 446 additions and 171 deletions
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -159,8 +159,7 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
 | [`routes/labeltemplate/get.md`](routes/labeltemplate/get.md) | `GET /labeltemplate/{id}` |
 | [`routes/labeltemplate/update.md`](routes/labeltemplate/update.md) | `PATCH /labeltemplate/{id}` |
 | [`routes/labeltemplate/update.md`](routes/labeltemplate/update.md) | `PUT /labeltemplate/{id}` |
-| [`routes/ledger.get.md`](routes/ledger.get.md) | `GET /ledger` |
-| [`routes/ledger.post.md`](routes/ledger.post.md) | `POST /ledger` |
+| [`routes/ledger.md`](routes/ledger.md) | `GET /ledger` |
 | [`routes/ledger/manifestarticle/_manifestarticleId.md`](routes/ledger/manifestarticle/_manifestarticleId.md) | `GET /ledger/manifestarticle/{manifestarticleId}` |
 | [`routes/ledger/sku/_sku.md`](routes/ledger/sku/_sku.md) | `GET /ledger/sku/{sku}` |
 | [`routes/mcp.md`](routes/mcp.md) | `POST /mcp` |
@@ -248,7 +247,9 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
 | [`routes/shipping/_id/package.get.md`](routes/shipping/_id/package.get.md) | `GET /shipping/{id}/package` |
 | [`routes/shipping/_id/package.post.md`](routes/shipping/_id/package.post.md) | `POST /shipping/{id}/package` |
 | [`routes/smallthumb/get.md`](routes/smallthumb/get.md) | `GET /smallthumb/{fullHash}` |
+| [`routes/stock/accept.md`](routes/stock/accept.md) | `POST /stock/accept` |
 | [`routes/stock/adjust.md`](routes/stock/adjust.md) | `POST /stock/adjust` |
+| [`routes/stock/ship.md`](routes/stock/ship.md) | `POST /stock/ship` |
 | [`routes/supplier/list.md`](routes/supplier/list.md) | `GET /supplier` |
 | [`routes/supplier/create.md`](routes/supplier/create.md) | `POST /supplier` |
 | [`routes/supplier/delete.md`](routes/supplier/delete.md) | `DELETE /supplier/{id}` |
@@ -291,13 +292,13 @@ Clients subscribe via [`GET /events`](routes/events.md) (`text/event-stream`). A
 | Signal | Emitted by |
 |--------|------------|
 | `article-<sku>` | `PUT /article/{sku}/brand`, `PUT /article/{sku}/categories`, `PUT /article/{sku}/eans`, `POST /article/{sku}/image`, `DELETE /article/{sku}/image/{fullHash}`, `PUT /article/{sku}/images/order`, `PUT /article/{sku}/prices`, `POST /article/{sku}/supplier`, `PUT /article/{sku}/supplier/order`, `DELETE /article/{sku}/supplier/{id}`, `PATCH /article/{sku}/supplier/{id}`, `PUT /article/{sku}/track_stock`, `PUT /article/{sku}/weight`, `POST /stock/adjust` |
-| `articles` | `POST /article`, `DELETE /article/{sku}`, `PATCH /article/{sku}`, `DELETE /category/{id}`, `POST /stock/adjust` |
+| `articles` | `POST /article`, `DELETE /article/{sku}`, `PATCH /article/{sku}`, `DELETE /category/{id}`, `POST /stock/accept`, `POST /stock/adjust`, `POST /stock/ship` |
 | `attributename` | `POST /attributename`, `PUT /attributename/order`, `DELETE /attributename/{id}`, `PATCH /attributename/{id}`, `DELETE /attributevalue/{id}/image`, `POST /attributevalue/{id}/image` |
 | `brand` | `POST /brand`, `DELETE /brand/{id}`, `PATCH /brand/{id}`, `DELETE /brand/{id}/image`, `POST /brand/{id}/image` |
 | `category` | `POST /category`, `PUT /category/order`, `DELETE /category/{id}`, `PATCH /category/{id}`, `DELETE /category/{id}/image`, `POST /category/{id}/image` |
-| `delivery` | `DELETE /delivery/{id}/file/{fileId}`, `POST /delivery/{id}/pdf` |
+| `delivery` | `DELETE /delivery/{id}/file/{fileId}`, `POST /delivery/{id}/pdf`, `POST /stock/accept` |
 | `labeltemplate` | `POST /labeltemplate`, `DELETE /labeltemplate/{id}`, `PATCH /labeltemplate/{id}`, `PUT /labeltemplate/{id}` |
-| `ledger` | `POST /stock/adjust` |
+| `ledger` | `POST /stock/accept`, `POST /stock/adjust`, `POST /stock/ship` |
 | `modelconversation` | `POST /modelconversation`, `DELETE /modelconversation/{id}` |
 | `modelconversation-<id>` | `POST /modelconversation/{id}/message` |
 | `order` | `DELETE /order/{id}/file/{fileId}`, `POST /order/{id}/pdf`, `PATCH /shipment/{id}`, `DELETE /shipment/{id}/file/{fileId}` |
@@ -305,7 +306,8 @@ Clients subscribe via [`GET /events`](routes/events.md) (`text/event-stream`). A
 | `propertyname` | `POST /propertyname`, `PUT /propertyname/order`, `DELETE /propertyname/{id}`, `PATCH /propertyname/{id}` |
 | `quote` | `DELETE /quote/{id}/file/{fileId}`, `POST /quote/{id}/pdf` |
 | `shipment` | `PATCH /shipment/{id}`, `DELETE /shipment/{id}/file/{fileId}`, `POST /shipment/{id}/pdf` |
-| `stock` | `POST /stock/adjust` |
+| `shipping` | `POST /stock/ship` |
+| `stock` | `POST /stock/accept`, `POST /stock/adjust`, `POST /stock/ship` |
 | `vfs` | `POST /vfs/applets/restore`, `POST /vfs/mkdir`, `POST /vfs/rename`, `POST /vfs/skills/restore`, `POST /vfs/upload`, `DELETE /vfs/{*path}`, `POST /vfs/{*path}`, `PUT /vfs/{*path}` |
 | `warehouse` | `POST /warehouse`, `PUT /warehouse/order`, `DELETE /warehouse/{id}`, `PUT /warehouse/{id}` |

--- a/docs/api/routes-all.md
+++ b/docs/api/routes-all.md
@@ -1,6 +1,6 @@
 # Dash API Routes Overview (All)

-Overview of all 249 API endpoints across all modules.
+Overview of all 250 API endpoints across all modules.

 ### Notation

@@ -392,8 +392,8 @@ _none_
 ### Section: /delivery

 #### List deliveries — `GET /delivery`
-_none_
- Returns: `200 { deliveries: { id: int, number: str, type: str, supplierId: int|null, date: str, externalNumber?: str|null, createdAt?: str, ledger?: T50 }[] }`
+- Params: `query: offset?: int, limit?: int, search?: str, onlyUnbooked?: bool, supplierId?: int, seekMonths?: int`
+- Returns: `200 { deliveries: { id: int, number: str, type: str, supplierId: int|null, date: str, externalNumber?: str|null, createdAt?: str, ledger?: T50 }[], total: int, unfilteredTotal: int, offset: int, limit: int }`
 #### Create delivery — `POST /delivery`
 - Params: `body: { externalNumber: str, date: str, lines: T33[], supplierId?: int|null, files?: { mimetype: str, name: str, content: str, sort?: int, size?: int, hash?: str, created?: str, modified?: str, meta?: { [k]: str } }[] }`
 - Returns: `201 T9`
@@ -521,9 +521,6 @@ _none_
 #### Query ledger by manifest article ID or SKU — `GET /ledger`
 - Params: `query: manifestarticle_id?: int, sku?: str, transaction_type?: str`
 - Returns: `200 T21`
-#### Add ledger entry — `POST /ledger`
- Params: `body: { manifestarticle_id: int, transaction_type: str, amount: num, transaction_text: str }`
- Returns: `201 { ledger: T22 }`
 #### Query ledger by manifest article ID — `GET /ledger/manifestarticle/{manifestarticleId}`
 - Params: `manifestarticleId: int, query: transaction_type?: str`
 - Returns: `200 T21`
@@ -842,9 +839,15 @@ _none_

 ### Section: /stock

+#### Accept delivery manifest item(s) — `POST /stock/accept`
+- Params: `body: { manifestarticleId?: int, warehouseId?: int, items?: { manifestarticleId: int, warehouseId?: int }[] }`
+- Returns: `200`
 #### Adjust stock manually — `POST /stock/adjust`
 - Params: `body: { sku?: str, warehouseId?: int, amount?: num, text?: str|null, lines?: { sku: str, amount: num, warehouseId?: int, text?: str }[] }`
 - Returns: `201 { manifest: { id: int, number: str, type: str, date: str, createdAt: str }, lines: { manifestarticle_id: int, sku: str, name: str, warehouse_id: int, amount: num, text: str }[], ledger: T22[] }`
+#### Ship shipment manifest item(s) — `POST /stock/ship`
+- Params: `body: { manifestarticleId?: int, warehouseId?: int, items?: { manifestarticleId: int, warehouseId?: int }[] }`
+- Returns: `200`

 ### Section: /supplier

--- a/docs/api/routes.md
+++ b/docs/api/routes.md
@@ -1,6 +1,6 @@
 # Dash API Routes Overview

-Overview of all 174 API endpoints across all modules.
+Overview of all 175 API endpoints across all modules.

 ### Notation

@@ -310,8 +310,8 @@ _none_
 ### Section: /delivery

 #### List deliveries — `GET /delivery`
-_none_
- Returns: `200 { deliveries: { id: int, number: str, type: str, supplierId: int|null, date: str, externalNumber?: str|null, createdAt?: str, ledger?: T42 }[] }`
+- Params: `query: offset?: int, limit?: int, search?: str, onlyUnbooked?: bool, supplierId?: int, seekMonths?: int`
+- Returns: `200 { deliveries: { id: int, number: str, type: str, supplierId: int|null, date: str, externalNumber?: str|null, createdAt?: str, ledger?: T42 }[], total: int, unfilteredTotal: int, offset: int, limit: int }`
 #### Create delivery — `POST /delivery`
 - Params: `body: { externalNumber: str, date: str, lines: T27[], supplierId?: int|null, files?: { mimetype: str, name: str, content: str, sort?: int, size?: int, hash?: str, created?: str, modified?: str, meta?: { [k]: str } }[] }`
 - Returns: `201 T9`
@@ -402,9 +402,6 @@ _none_
 #### Query ledger by manifest article ID or SKU — `GET /ledger`
 - Params: `query: manifestarticle_id?: int, sku?: str, transaction_type?: str`
 - Returns: `200 T17`
-#### Add ledger entry — `POST /ledger`
- Params: `body: { manifestarticle_id: int, transaction_type: str, amount: num, transaction_text: str }`
- Returns: `201 { ledger: T18 }`
 #### Query ledger by manifest article ID — `GET /ledger/manifestarticle/{manifestarticleId}`
 - Params: `manifestarticleId: int, query: transaction_type?: str`
 - Returns: `200 T17`
@@ -594,9 +591,15 @@ _none_

 ### Section: /stock

+#### Accept delivery manifest item(s) — `POST /stock/accept`
+- Params: `body: { manifestarticleId?: int, warehouseId?: int, items?: { manifestarticleId: int, warehouseId?: int }[] }`
+- Returns: `200`
 #### Adjust stock manually — `POST /stock/adjust`
 - Params: `body: { sku?: str, warehouseId?: int, amount?: num, text?: str|null, lines?: { sku: str, amount: num, warehouseId?: int, text?: str }[] }`
 - Returns: `201 { manifest: { id: int, number: str, type: str, date: str, createdAt: str }, lines: { manifestarticle_id: int, sku: str, name: str, warehouse_id: int, amount: num, text: str }[], ledger: T18[] }`
+#### Ship shipment manifest item(s) — `POST /stock/ship`
+- Params: `body: { manifestarticleId?: int, warehouseId?: int, items?: { manifestarticleId: int, warehouseId?: int }[] }`
+- Returns: `200`

 ### Section: /supplier

--- a/docs/api/routes/delivery/list.md
+++ b/docs/api/routes/delivery/list.md
@@ -5,12 +5,23 @@ Protected. Requires a valid session cookie (`credentials: 'include'`).
 List deliveries

 Lists goods receipts (`manifest` rows with `type = 'delivery'`)
-for the authenticated user's selected company.
+for the authenticated user's selected company. Supports pagination and filtering.


+## Query parameters
+
+| Param | Required | Type | Description |
+|-------|----------|------|-------------|
+| `offset` | no | integer | Number of records to skip |
+| `limit` | no | integer | Number of records to return (1-1000) |
+| `search` | no | string | Substring match for delivery number, external number, or supplier name |
+| `onlyUnbooked` | no | boolean | When true, returns only deliveries with unbooked stock items |
+| `supplierId` | no | integer | Filter by supplier entity id |
+| `seekMonths` | no | integer | Negative integer cutoff months ago (e.g. -1) |
+
 ## Response `200`

-Delivery list
+Delivery list (windowed when pagination/filters are used)

 ```json
 {
@@ -28,7 +39,11 @@ Delivery list
        "completelyOnLedgerPositions": 1
      }
    }
-  ]
+  ],
+  "total": 1,
+  "unfilteredTotal": 1,
+  "offset": 1,
+  "limit": 1
 }
 ```

--- a/docs/api/routes/ledger.get.md
+++ b/docs/api/routes/ledger.get.md
--- a/docs/api/routes/ledger.post.md
+++ b/docs/api/routes/ledger.post.md
@@ -1,63 +0,0 @@
-# `POST /ledger`
-
-Protected. Requires a valid session cookie (`credentials: 'include'`).
-
-Add ledger entry
-
-Appends a new entry to the append-only ledger table.
-`hash_version` is fixed to 1. `prev_hash` is cryptographically chained:
-for the genesis row it defaults to `TODO_TSE_BASED_INITHASH`, and for subsequent rows
-it is the SHA-512 hex hash of the canonical JSON representation of the previous highest-id entry.
-Requires authentication and membership in the company owning the referenced manifest article.
-
-
-## Body (JSON)
-
-| Field | Required | Type | Description |
-|-------|----------|------|-------------|
-| `manifestarticle_id` | yes | integer | References manifestarticle.id |
-| `transaction_type` | yes | string | Transaction identifier / type (max 100 chars) |
-| `amount` | yes | number | Movement amount |
-| `transaction_text` | yes | string | Transaction memo / details |
-
-```json
-{
-  "manifestarticle_id": 1,
-  "transaction_type": "…",
-  "amount": 1,
-  "transaction_text": "…"
-}
-```
-
-## Response `201`
-
-Ledger entry added successfully
-
-```json
-{
-  "ledger": {
-    "id": 1,
-    "manifestarticle_id": 1,
-    "transaction_type": "…",
-    "amount": 1,
-    "transaction_text": "…",
-    "hash_version": 1,
-    "prev_hash": "…",
-    "sku": "…",
-    "created_at": "2026-08-10T00:00:00.000Z"
-  }
-}
-```
-
-## Errors
-
-| Status | Description |
-|--------|-------------|
-| 400 | Invalid ledger entry or no company selected — `{"error":"…"}` |
-| 401 | Unauthorized — `{"error":"…"}` |
-| 403 | Not authorized — `{"error":"…"}` |
-| 404 | Manifest article or company not found — `{"error":"…"}` |
-
---
-
-_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._
--- a/docs/api/routes/stock/accept.md
+++ b/docs/api/routes/stock/accept.md
@@ -0,0 +1,54 @@
+# `POST /stock/accept`
+
+Protected. Requires a valid session cookie (`credentials: 'include'`).
+
+Accept delivery manifest item(s)
+
+Books acceptance for a delivery manifest item on the ledger (warehouse_id = null).
+If the connected article has stock tracking enabled, an adjustment entry is also
+booked to adjust physical stock in the target warehouse.
+If line amount is negative, books as a delivery return (outgoing).
+
+
+## Body (JSON)
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `manifestarticleId` | no | integer | Manifest article ID of the delivery line |
+| `warehouseId` | no | integer | Optional warehouse ID for inventory intake |
+| `items` | no | object[] |  |
+| `items[].manifestarticleId` | yes | integer |  |
+| `items[].warehouseId` | no | integer |  |
+
+```json
+{
+  "manifestarticleId": 1,
+  "warehouseId": 1,
+  "items": [
+    {
+      "manifestarticleId": 1,
+      "warehouseId": 1
+    }
+  ]
+}
+```
+
+## Signals
+
+On success, emits SSE signals: `stock`, `ledger`, `articles`, `delivery` (see [`GET /events`](../events.md)).
+
+## Response `200`
+
+Delivery item(s) accepted successfully
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 400 | Validation error or no company selected |
+| 404 | Manifest article or warehouse not found |
+| 409 | Delivery line already accepted on ledger |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._
--- a/docs/api/routes/stock/ship.md
+++ b/docs/api/routes/stock/ship.md
@@ -0,0 +1,54 @@
+# `POST /stock/ship`
+
+Protected. Requires a valid session cookie (`credentials: 'include'`).
+
+Ship shipment manifest item(s)
+
+Books shipment for a shipment manifest item on the ledger (warehouse_id = null).
+If the connected article has stock tracking enabled, an adjustment entry is also
+booked to deduct physical stock from the target warehouse.
+If line amount is negative, books as a customer retoure (incoming).
+
+
+## Body (JSON)
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `manifestarticleId` | no | integer | Manifest article ID of the shipment line |
+| `warehouseId` | no | integer | Optional warehouse ID for inventory deduction |
+| `items` | no | object[] |  |
+| `items[].manifestarticleId` | yes | integer |  |
+| `items[].warehouseId` | no | integer |  |
+
+```json
+{
+  "manifestarticleId": 1,
+  "warehouseId": 1,
+  "items": [
+    {
+      "manifestarticleId": 1,
+      "warehouseId": 1
+    }
+  ]
+}
+```
+
+## Signals
+
+On success, emits SSE signals: `stock`, `ledger`, `articles`, `shipping` (see [`GET /events`](../events.md)).
+
+## Response `200`
+
+Shipment item(s) shipped successfully
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 400 | Validation error or no company selected |
+| 404 | Manifest article or warehouse not found |
+| 409 | Shipment line already shipped on ledger |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._