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

u

Browse Source
This commit is contained in:
seb
2026-10-20 05:33:14 +02:00
parent de3e74c928
commit fde381937c
9 changed files with 137 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/api/README.md
View File

@@ -242,6 +242,7 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
| [`routes/quote/_id/pdf.md`](routes/quote/_id/pdf.md) | `POST /quote/{id}/pdf` |
| [`routes/serper/image.md`](routes/serper/image.md) | `POST /serper/image` |
| [`routes/serper/images.md`](routes/serper/images.md) | `POST /serper/images` |
| [`routes/shipment.md`](routes/shipment.md) | `GET /shipment` |
| [`routes/shipment/_id.delete.md`](routes/shipment/_id.delete.md) | `DELETE /shipment/{id}` |
| [`routes/shipment/_id.get.md`](routes/shipment/_id.get.md) | `GET /shipment/{id}` |
| [`routes/shipment/_id.patch.md`](routes/shipment/_id.patch.md) | `PATCH /shipment/{id}` |
@@ -305,23 +306,23 @@ 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/accept`, `POST /stock/adjust`, `POST /stock/ship` |
| `articles` | `POST /article`, `DELETE /article/{sku}`, `PATCH /article/{sku}`, `DELETE /category/{id}`, `DELETE /shipment/{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` |
| `carrier` | `POST /carrier`, `PUT /carrier/order`, `DELETE /carrier/{id}`, `PATCH /carrier/{id}` |
| `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`, `POST /stock/accept` |
| `labeltemplate` | `POST /labeltemplate`, `DELETE /labeltemplate/{id}`, `PATCH /labeltemplate/{id}`, `PUT /labeltemplate/{id}` |
| `ledger` | `POST /stock/accept`, `POST /stock/adjust`, `POST /stock/ship` |
| `ledger` | `DELETE /shipment/{id}`, `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}` |
| `order` | `DELETE /order/{id}/file/{fileId}`, `POST /order/{id}/pdf`, `DELETE /shipment/{id}`, `PATCH /shipment/{id}`, `DELETE /shipment/{id}/file/{fileId}` |
| `printer` | `POST /printer`, `PUT /printer/order`, `DELETE /printer/{id}`, `PATCH /printer/{id}`, `PUT /printer/{id}` |
| `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` |
| `shipment` | `DELETE /shipment/{id}`, `PATCH /shipment/{id}`, `DELETE /shipment/{id}/file/{fileId}`, `POST /shipment/{id}/pdf` |
| `shipping` | `POST /stock/ship` |
| `stock` | `POST /stock/accept`, `POST /stock/adjust`, `POST /stock/ship` |
| `stock` | `DELETE /shipment/{id}`, `POST /stock/accept`, `POST /stock/adjust`, `POST /stock/ship` |
| `subagentschedule` | `POST /subagentschedule`, `DELETE /subagentschedule/{id}`, `PUT /subagentschedule/{id}` |
| `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}` |

7
docs/api/routes-all.md
View File

@@ -1,6 +1,6 @@
# Dash API Routes Overview (All)
Overview of all 263 API endpoints across all modules.
Overview of all 264 API endpoints across all modules.
### Notation
@@ -653,7 +653,7 @@ _none_
- Params: `id: int`
- Returns: `200 { shipments: T3[] }`
#### Create shipment for an order — `POST /order/{id}/shipment`
- Params: `id: int, body?: { date?: str, externalNumber?: str, lines?: { sku: str, amount?: num, name?: str, pu?: num, net?: num, rebate?: num, taxrate?: num, comment?: str }[] }`
- Params: `id: int, body: { lines: { sku: str, amount?: num, name?: str, pu?: num, net?: num, rebate?: num, taxrate?: num, comment?: str }[], date?: str, warehouseId?: int, externalNumber?: str }`
- Returns: `201 { shipment: T3 }`
#### List shippings of an order — `GET /order/{id}/shipping`
- Params: `id: int`
@@ -805,6 +805,9 @@ _none_
### Section: /shipment
#### List shipments — `GET /shipment`
- Params: `query: offset?: int, limit?: int, search?: str, state?: str, seekMonths?: int`
- Returns: `200 { shipments: { id: int, number: str, type: str, date: str, positions: int, totalQuantity: num, packageCount: int, state: str, entityId?: int|null, externalNumber?: str|null, createdAt?: str|null, orderId?: int|null, orderNumber?: str|null, customerName?: str|null, carrier?: str|null, trackingCode?: str|null }[], total: int, unfilteredTotal: int, offset: int, limit: int }`
#### Delete shipment — `DELETE /shipment/{id}`
- Params: `id: int`
- Returns: `204 void`

7
docs/api/routes.md
View File

@@ -1,6 +1,6 @@
# Dash API Routes Overview
Overview of all 186 API endpoints across all modules.
Overview of all 187 API endpoints across all modules.
### Notation
@@ -466,7 +466,7 @@ _none_
- Params: `id: int`
- Returns: `200 { shipments: T3[] }`
#### Create shipment for an order — `POST /order/{id}/shipment`
- Params: `id: int, body?: { date?: str, externalNumber?: str, lines?: { sku: str, amount?: num, name?: str, pu?: num, net?: num, rebate?: num, taxrate?: num, comment?: str }[] }`
- Params: `id: int, body: { lines: { sku: str, amount?: num, name?: str, pu?: num, net?: num, rebate?: num, taxrate?: num, comment?: str }[], date?: str, warehouseId?: int, externalNumber?: str }`
- Returns: `201 { shipment: T3 }`
#### List shippings of an order — `GET /order/{id}/shipping`
- Params: `id: int`
@@ -558,6 +558,9 @@ _none_
### Section: /shipment
#### List shipments — `GET /shipment`
- Params: `query: offset?: int, limit?: int, search?: str, state?: str, seekMonths?: int`
- Returns: `200 { shipments: { id: int, number: str, type: str, date: str, positions: int, totalQuantity: num, packageCount: int, state: str, entityId?: int|null, externalNumber?: str|null, createdAt?: str|null, orderId?: int|null, orderNumber?: str|null, customerName?: str|null, carrier?: str|null, trackingCode?: str|null }[], total: int, unfilteredTotal: int, offset: int, limit: int }`
#### Delete shipment — `DELETE /shipment/{id}`
- Params: `id: int`
- Returns: `204 void`

11
docs/api/routes/order/_id/shipment.post.md
View File

@@ -8,8 +8,9 @@ Creates a new shipment manifest (Lieferschein) for an order containing one, some
If `lines` is omitted or empty, all remaining unshipped items from the order are included automatically.
On individual line items, `amount` is optional and defaults to the remaining unshipped quantity for that article.
Auto-assigns the shipment number formatted as `<order_number><shipment_prefix><index>`, e.g. `AUF-000001-L-1`.
Automatically books shipment lines out on the ledger and deducts warehouse stock for stock-tracked articles.
Updates the materialized `ordersummary` table (`shipped_quantity`, `is_shipped`) and emits SSE events
(`order`, `shipment`) so that the order list and summary tables are rerendered in real time.
(`order`, `shipment`, `stock`, `ledger`, `articles`) so that inventory and summaries are rerendered in real time.
## Path parameters
@@ -18,13 +19,14 @@ Updates the materialized `ordersummary` table (`shipped_quantity`, `is_shipped`)
|-------|----------|------|-------------|
| `id` | yes | integer | Order ID |
## Body (JSON) — _optional_
## Body (JSON)
| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `date` | no | string | Optional shipment date (defaults to current date) |
| `warehouseId` | no | integer | Optional target warehouse ID to deduct stock from (defaults to company default warehouse) |
| `externalNumber` | no | string | Optional external delivery note reference (defaults to order.externalNumber or order.number) |
| `lines` | no | object[] | Optional positions to ship. If omitted, all remaining unshipped items are shipped. |
| `lines` | yes | object[] | Positions to ship |
| `lines[].sku` | yes | string | Article SKU |
| `lines[].amount` | no | number | Quantity to ship. Defaults to remaining unshipped quantity for this SKU. |
| `lines[].name` | no | string | |
@@ -37,6 +39,7 @@ Updates the materialized `ordersummary` table (`shipped_quantity`, `is_shipped`)
```json
{
"date": "2026-08-10",
"warehouseId": 1,
"externalNumber": "…",
"lines": [
{
@@ -124,7 +127,7 @@ Created shipment
| 400 | Validation error or article not in order — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
| 404 | Order not found — `{"error":"…"}` |
| 409 | Cumulative shipment amount exceeds ordered amount, or all items are already shipped — `{"error":"…"}` |
| 409 | Cumulative shipment amount exceeds ordered amount, or insufficient stock — `{"error":"…"}` |
---

64
docs/api/routes/shipment.md Normal file
View File

@@ -0,0 +1,64 @@
# `GET /shipment`
Protected. Requires a valid session cookie (`credentials: 'include'`).
List shipments
Company-wide paginated list of shipment manifests (`manifest` rows with `type = 'shipment'`)
with delivery state, entityId, package tracking info, and order references.
## Query parameters
| Param | Required | Type | Description |
|-------|----------|------|-------------|
| `offset` | no | integer | Number of shipments to skip |
| `limit` | no | integer | Number of shipments to return |
| `search` | no | string | Free-text search matching shipment number, order number, external number, tracking code, or customer name |
| `state` | no | string | Optional filter by delivery state (cancelled shipments hidden by default) |
| `seekMonths` | no | integer | Negative integer for cutoff months ago (e.g. -1 for shipments older than 1 month) |
## Response `200`
Paginated shipment list
```json
{
"shipments": [
{
"id": 1,
"number": "…",
"type": "shipment",
"entityId": 1,
"externalNumber": "…",
"date": "…",
"createdAt": "…",
"orderId": 1,
"orderNumber": "…",
"customerName": "…",
"positions": 1,
"totalQuantity": 1,
"packageCount": 1,
"carrier": "…",
"trackingCode": "…",
"state": "new"
}
],
"total": 1,
"unfilteredTotal": 1,
"offset": 1,
"limit": 1
}
```
## Errors
| Status | Description |
|--------|-------------|
| 400 | Invalid query parameters or no company selected — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
| 403 | Not authorized — `{"error":"…"}` |
---
_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._

8
docs/api/routes/shipment/_id.delete.md
View File

@@ -4,7 +4,7 @@ Protected. Requires a valid session cookie (`credentials: 'include'`).
Delete shipment
Deletes an unshipped shipment manifest. Shipped shipments cannot be deleted.
Deletes an unshipped shipment manifest or cancels a shipped shipment restoring stock. Shipped packages cannot be deleted.
## Path parameters
@@ -12,6 +12,10 @@ Deletes an unshipped shipment manifest. Shipped shipments cannot be deleted.
|-------|----------|------|-------------|
| `id` | yes | integer | Shipment ID |
## Signals
On success, emits SSE signals: `shipment`, `order`, `stock`, `ledger`, `articles` (see [`GET /events`](../events.md)).
## Response `204`
Shipment deleted
@@ -25,7 +29,7 @@ _No content_
| 400 | Invalid ID or no company selected — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
| 404 | Shipment not found — `{"error":"…"}` |
| 409 | Shipped shipment cannot be deleted — `{"error":"…"}` |
| 409 | Shipped shipment cannot be deleted or shipment already cancelled — `{"error":"…"}` |
---