From 1f09e620e3899afaa2777858b8f6b5c10ce06b85 Mon Sep 17 00:00:00 2001 From: seb Date: Mon, 12 Oct 2026 13:11:28 +0200 Subject: [PATCH] u --- docs/api/README.md | 3 +- docs/api/routes-all.md | 7 +- docs/api/routes.md | 7 +- docs/api/routes/order/_id/shipping.post.md | 8 +- .../routes/shipping/{_id.md => _id.delete.md} | 4 + docs/api/routes/shipping/_id.patch.md | 61 ++++++++ src/api/routes/shipping.js | 147 +++++++++++++++++- src/db/shipping.js | 5 + 8 files changed, 233 insertions(+), 9 deletions(-) rename docs/api/routes/shipping/{_id.md => _id.delete.md} (77%) create mode 100644 docs/api/routes/shipping/_id.patch.md diff --git a/docs/api/README.md b/docs/api/README.md index 8cc069b..61aa911 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -206,7 +206,8 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route | [`routes/quote/update.md`](routes/quote/update.md) | `PATCH /quote/{id}` | | [`routes/serper/image.md`](routes/serper/image.md) | `POST /serper/image` | | [`routes/serper/images.md`](routes/serper/images.md) | `POST /serper/images` | -| [`routes/shipping/_id.md`](routes/shipping/_id.md) | `DELETE /shipping/{id}` | +| [`routes/shipping/_id.delete.md`](routes/shipping/_id.delete.md) | `DELETE /shipping/{id}` | +| [`routes/shipping/_id.patch.md`](routes/shipping/_id.patch.md) | `PATCH /shipping/{id}` | | [`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}` | diff --git a/docs/api/routes-all.md b/docs/api/routes-all.md index d60eb12..46d4053 100644 --- a/docs/api/routes-all.md +++ b/docs/api/routes-all.md @@ -1,6 +1,6 @@ # Dash API Routes Overview (All) -Overview of all 209 API endpoints across all modules. +Overview of all 210 API endpoints across all modules. ### Notation @@ -563,7 +563,7 @@ _none_ - Params: `id: int` - Returns: `200 { shippings: T39[] }` #### Create shipping for an order — `POST /order/{id}/shipping` -- Params: `id: int, body: { type: str, state: str }` +- Params: `id: int, body: { type: str, state: str, warehouseId?: int }` - Returns: `201 { shipping: T39 }` ### Section: /package @@ -700,6 +700,9 @@ _none_ #### Delete shipping — `DELETE /shipping/{id}` - Params: `id: int` - Returns: `204 void` +#### Update shipping — `PATCH /shipping/{id}` +- Params: `id: int, body: { type?: str, state?: str, warehouseId?: int }` +- Returns: `200 { shipping: T39 }` #### List packages of a shipping — `GET /shipping/{id}/package` - Params: `id: int` - Returns: `200 { packages: { id: int, shippingId: int, entityaddressId: int, number: str, type: str, state: str, details?: str|null }[] }` diff --git a/docs/api/routes.md b/docs/api/routes.md index 6eb784d..023757b 100644 --- a/docs/api/routes.md +++ b/docs/api/routes.md @@ -1,6 +1,6 @@ # Dash API Routes Overview -Overview of all 162 API endpoints across all modules. +Overview of all 163 API endpoints across all modules. ### Notation @@ -464,7 +464,7 @@ _none_ - Params: `id: int` - Returns: `200 { shippings: T35[] }` #### Create shipping for an order — `POST /order/{id}/shipping` -- Params: `id: int, body: { type: str, state: str }` +- Params: `id: int, body: { type: str, state: str, warehouseId?: int }` - Returns: `201 { shipping: T35 }` ### Section: /package @@ -544,6 +544,9 @@ _none_ #### Delete shipping — `DELETE /shipping/{id}` - Params: `id: int` - Returns: `204 void` +#### Update shipping — `PATCH /shipping/{id}` +- Params: `id: int, body: { type?: str, state?: str, warehouseId?: int }` +- Returns: `200 { shipping: T35 }` #### List packages of a shipping — `GET /shipping/{id}/package` - Params: `id: int` - Returns: `200 { packages: { id: int, shippingId: int, entityaddressId: int, number: str, type: str, state: str, details?: str|null }[] }` diff --git a/docs/api/routes/order/_id/shipping.post.md b/docs/api/routes/order/_id/shipping.post.md index 80f8b82..f7c29f9 100644 --- a/docs/api/routes/order/_id/shipping.post.md +++ b/docs/api/routes/order/_id/shipping.post.md @@ -6,6 +6,7 @@ Create shipping for an order Creates a shipping for the order. The shipping number is allocated from the `shipping` number sequence (prefix and counter from the numbers API). +If `state` is `shipped`, stock is adjusted via the ledger and article history is written. ## Path parameters @@ -20,11 +21,13 @@ Creates a shipping for the order. The shipping number is allocated from the |-------|----------|------|-------------| | `type` | yes | string | | | `state` | yes | string | | +| `warehouseId` | no | integer | Optional warehouse ID for stock deduction when state is shipped | ```json { "type": "…", - "state": "…" + "state": "…", + "warehouseId": 1 } ``` @@ -51,7 +54,8 @@ Created shipping | 400 | Validation error or no company selected — `{"error":"…"}` | | 401 | Unauthorized — `{"error":"…"}` | | 403 | Not authorized — `{"error":"…"}` | -| 404 | Order not found — `{"error":"…"}` | +| 404 | Order or warehouse not found — `{"error":"…"}` | +| 409 | Order already shipped — `{"error":"…"}` | --- diff --git a/docs/api/routes/shipping/_id.md b/docs/api/routes/shipping/_id.delete.md similarity index 77% rename from docs/api/routes/shipping/_id.md rename to docs/api/routes/shipping/_id.delete.md index b00bd2a..bd51332 100644 --- a/docs/api/routes/shipping/_id.md +++ b/docs/api/routes/shipping/_id.delete.md @@ -5,6 +5,8 @@ Protected. Requires a valid session cookie (`credentials: 'include'`). Delete shipping Deletes a shipping of the selected company. Its packages are removed as well. +Shipped shippings cannot be deleted because stock movements have been ledgered. + ## Path parameters @@ -25,6 +27,8 @@ _No content_ | 400 | Invalid ID or no company selected — `{"error":"…"}` | | 401 | Unauthorized — `{"error":"…"}` | | 403 | Not authorized — `{"error":"…"}` | +| 404 | Shipping not found — `{"error":"…"}` | +| 409 | Shipped shipping cannot be deleted — `{"error":"…"}` | --- diff --git a/docs/api/routes/shipping/_id.patch.md b/docs/api/routes/shipping/_id.patch.md new file mode 100644 index 0000000..d2e525c --- /dev/null +++ b/docs/api/routes/shipping/_id.patch.md @@ -0,0 +1,61 @@ +# `PATCH /shipping/{id}` + +Protected. Requires a valid session cookie (`credentials: 'include'`). + +Update shipping + +Updates a shipping record. If transitioned to `shipped`, stock is adjusted +via ledger and article history is written. Once shipped, it cannot be undone. + + +## Path parameters + +| Param | Required | Type | Description | +|-------|----------|------|-------------| +| `id` | yes | integer | Shipping ID | + +## Body (JSON) + +| Field | Required | Type | Description | +|-------|----------|------|-------------| +| `type` | no | string | | +| `state` | no | string | | +| `warehouseId` | no | integer | Warehouse ID for stock deduction when transitioning to shipped | + +```json +{ + "type": "…", + "state": "…", + "warehouseId": 1 +} +``` + +## Response `200` + +Updated shipping + +```json +{ + "shipping": { + "id": 1, + "manifestId": 1, + "number": "…", + "type": "…", + "state": "…" + } +} +``` + +## Errors + +| Status | Description | +|--------|-------------| +| 400 | Validation error or no company selected — `{"error":"…"}` | +| 401 | Unauthorized — `{"error":"…"}` | +| 403 | Not authorized — `{"error":"…"}` | +| 404 | Shipping or warehouse not found — `{"error":"…"}` | +| 409 | Shipped shipping cannot be undone, or order already shipped — `{"error":"…"}` | + +--- + +_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._ diff --git a/src/api/routes/shipping.js b/src/api/routes/shipping.js index 3e59dae..9f9816d 100644 --- a/src/api/routes/shipping.js +++ b/src/api/routes/shipping.js @@ -1,4 +1,5 @@ import * as db from '../../db/shipping.js'; +import { emit } from '../sse.js'; // #region Helpers @@ -23,9 +24,23 @@ function shippingErrorStatus(error) { if (error.message === 'Not authorized') return 403; if (error.message?.endsWith(' not found')) return 404; if (error.message?.endsWith(' required')) return 400; + if ( + error.message?.includes('cannot be deleted') || + error.message?.includes('cannot be undone') || + error.message?.includes('already shipped') + ) { + return 409; + } return 500; } +function emitShippingEvents(companyId) { + emit('stock', { companyId }); + emit('ledger', { companyId }); + emit('articles', { companyId }); + emit('order', { companyId }); +} + // #endregion /** @@ -115,6 +130,7 @@ export function register(app, basePath = '') { * description: | * Creates a shipping for the order. The shipping number is allocated from the * `shipping` number sequence (prefix and counter from the numbers API). + * If `state` is `shipped`, stock is adjusted via the ledger and article history is written. * security: * - cookieAuth: [] * parameters: @@ -136,6 +152,9 @@ export function register(app, basePath = '') { * type: string * state: * type: string + * warehouseId: + * type: integer + * description: Optional warehouse ID for stock deduction when state is shipped * responses: * 201: * description: Created shipping @@ -165,7 +184,13 @@ export function register(app, basePath = '') { * schema: * $ref: '#/components/schemas/Error' * 404: - * description: Order not found + * description: Order or warehouse not found + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + * 409: + * description: Order already shipped * content: * application/json: * schema: @@ -189,6 +214,9 @@ export function register(app, basePath = '') { ...(req.body ?? {}), manifestId: parsedId.id, }); + if (String(shipping.state || '').trim().toLowerCase() === 'shipped') { + emitShippingEvents(selected.companyId); + } res.status(201).json({ shipping }); } catch (error) { const status = shippingErrorStatus(error); @@ -199,13 +227,116 @@ export function register(app, basePath = '') { // #endregion + /** + * @openapi + * /shipping/{id}: + * patch: + * tags: [Shipping] + * summary: Update shipping + * description: | + * Updates a shipping record. If transitioned to `shipped`, stock is adjusted + * via ledger and article history is written. Once shipped, it cannot be undone. + * security: + * - cookieAuth: [] + * parameters: + * - in: path + * name: id + * required: true + * schema: + * type: integer + * description: Shipping ID + * requestBody: + * required: true + * content: + * application/json: + * schema: + * type: object + * properties: + * type: + * type: string + * state: + * type: string + * warehouseId: + * type: integer + * description: Warehouse ID for stock deduction when transitioning to shipped + * responses: + * 200: + * description: Updated shipping + * content: + * application/json: + * schema: + * type: object + * properties: + * shipping: + * $ref: '#/components/schemas/Shipping' + * 400: + * description: Validation error or no company selected + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + * 401: + * description: Unauthorized + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + * 403: + * description: Not authorized + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + * 404: + * description: Shipping or warehouse not found + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + * 409: + * description: Shipped shipping cannot be undone, or order already shipped + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + */ + // #region PATCH /shipping/:id + + app.patch(`${basePath}/shipping/:id`, async (req, res) => { + const selected = requireSelectedCompany(req); + if (selected.error) { + return res.status(400).json({ error: selected.error }); + } + + const parsedId = parsePositiveInt(req.params.id, 'id'); + if (parsedId.error) { + return res.status(400).json({ error: parsedId.error }); + } + + try { + const shipping = await db.update(req.user.id, parsedId.id, req.body ?? {}); + if (String(shipping.state || '').trim().toLowerCase() === 'shipped') { + emitShippingEvents(selected.companyId); + } + res.status(200).json({ shipping }); + } catch (error) { + const status = shippingErrorStatus(error); + if (status === 500) console.error('Update shipping failed:', error); + res.status(status).json({ error: error.message }); + } + }); + + // #endregion + /** * @openapi * /shipping/{id}: * delete: * tags: [Shipping] * summary: Delete shipping - * description: Deletes a shipping of the selected company. Its packages are removed as well. + * description: | + * Deletes a shipping of the selected company. Its packages are removed as well. + * Shipped shippings cannot be deleted because stock movements have been ledgered. * security: * - cookieAuth: [] * parameters: @@ -236,6 +367,18 @@ export function register(app, basePath = '') { * application/json: * schema: * $ref: '#/components/schemas/Error' + * 404: + * description: Shipping not found + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + * 409: + * description: Shipped shipping cannot be deleted + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ // #region DELETE /shipping/:id diff --git a/src/db/shipping.js b/src/db/shipping.js index bab6d8f..647814c 100644 --- a/src/db/shipping.js +++ b/src/db/shipping.js @@ -10,6 +10,11 @@ export async function create(googleAuthId, data) { return store.shipping.create(googleAuthId, data); } +export async function update(googleAuthId, id, patch) { + const store = await getStore(); + return store.shipping.update(googleAuthId, id, patch); +} + export async function remove(googleAuthId, id) { const store = await getStore(); return store.shipping.delete(googleAuthId, id);