u

src/api/routes/shipment.js

@@ -27,7 +27,11 @@ function shipmentErrorStatus(error) {
     if (
         error.message?.endsWith(' required') ||
         error.message?.startsWith('Article (') ||
-        error.message?.includes('Invalid lines')
+        error.message?.includes('Invalid lines') ||
+        error.message === 'Invalid state' ||
+        error.message === 'Invalid offset' ||
+        error.message === 'Invalid limit' ||
+        error.message === 'Invalid seekMonths'
     ) {
         return 400;
     }
@@ -134,9 +138,12 @@ export function register(app, basePath = '') {
      *     tags: [Shipment]
      *     summary: Create shipment for an order
      *     description: |
-     *       Creates a new partial or full shipment manifest for the order.
-     *       Validates that article positions belong to the order and cumulative shipped quantities
-     *       do not exceed ordered quantities.
+     *       Creates a new shipment manifest (Lieferschein) for an order containing one, some, or all items from the order.
+     *       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`.
+     *       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.
      *     security:
      *       - cookieAuth: []
      *     parameters:
@@ -147,28 +154,32 @@ export function register(app, basePath = '') {
      *           type: integer
      *         description: Order ID
      *     requestBody:
-     *       required: true
+     *       required: false
      *       content:
      *         application/json:
      *           schema:
      *             type: object
-     *             required: [lines]
      *             properties:
      *               date:
      *                 type: string
      *                 format: date
+     *                 description: Optional shipment date (defaults to current date)
      *               externalNumber:
      *                 type: string
+     *                 description: Optional external delivery note reference (defaults to order.externalNumber or order.number)
      *               lines:
      *                 type: array
+     *                 description: Optional positions to ship. If omitted, all remaining unshipped items are shipped.
      *                 items:
      *                   type: object
-     *                   required: [sku, amount]
+     *                   required: [sku]
      *                   properties:
      *                     sku:
      *                       type: string
+     *                       description: Article SKU
      *                     amount:
      *                       type: number
+     *                       description: Quantity to ship. Defaults to remaining unshipped quantity for this SKU.
      *                     name:
      *                       type: string
      *                     pu:
@@ -210,7 +221,7 @@ export function register(app, basePath = '') {
      *             schema:
      *               $ref: '#/components/schemas/Error'
      *       409:
-     *         description: Cumulative shipment amount exceeds ordered amount
+     *         description: Cumulative shipment amount exceeds ordered amount, or all items are already shipped
      *         content:
      *           application/json:
      *             schema:
@@ -245,6 +256,157 @@ export function register(app, basePath = '') {
 
     // #endregion
 
+    /**
+     * @openapi
+     * /shipment:
+     *   get:
+     *     tags: [Shipment]
+     *     summary: List shipments
+     *     description: |
+     *       Company-wide paginated list of shipment manifests (`manifest` rows with `type = 'shipment'`)
+     *       with delivery state, package tracking info, and order references.
+     *     security:
+     *       - cookieAuth: []
+     *     parameters:
+     *       - in: query
+     *         name: offset
+     *         schema:
+     *           type: integer
+     *           default: 0
+     *           minimum: 0
+     *         description: Number of shipments to skip
+     *       - in: query
+     *         name: limit
+     *         schema:
+     *           type: integer
+     *           default: 50
+     *           minimum: 1
+     *           maximum: 100
+     *         description: Number of shipments to return
+     *       - in: query
+     *         name: search
+     *         schema:
+     *           type: string
+     *         description: Free-text search matching shipment number, order number, external number, tracking code, or customer name
+     *       - in: query
+     *         name: state
+     *         schema:
+     *           type: string
+     *           enum: [new, delivered, returned]
+     *         description: Optional filter by delivery state
+     *       - in: query
+     *         name: seekMonths
+     *         schema:
+     *           type: integer
+     *         description: Negative integer for cutoff months ago (e.g. -1 for shipments older than 1 month)
+     *     responses:
+     *       200:
+     *         description: Paginated shipment list
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: object
+     *               required: [shipments, total, unfilteredTotal, offset, limit]
+     *               properties:
+     *                 shipments:
+     *                   type: array
+     *                   items:
+     *                     $ref: '#/components/schemas/ShipmentSummary'
+     *                 total:
+     *                   type: integer
+     *                 unfilteredTotal:
+     *                   type: integer
+     *                 offset:
+     *                   type: integer
+     *                 limit:
+     *                   type: integer
+     *       400:
+     *         description: Invalid query parameters 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'
+     */
+    // #region GET /shipment
+
+    app.get(`${basePath}/shipment`, async (req, res) => {
+        const selected = requireSelectedCompany(req);
+        if (selected.error) {
+            return res.status(400).json({ error: selected.error });
+        }
+
+        const rawOffset = req.query.offset;
+        const rawLimit = req.query.limit;
+
+        let offset = 0;
+        let limit = 50;
+
+        if (rawOffset !== undefined) {
+            offset = parseInt(rawOffset, 10);
+            if (!Number.isInteger(offset) || offset < 0) {
+                return res.status(400).json({ error: 'offset must be an integer >= 0' });
+            }
+        }
+
+        if (rawLimit !== undefined) {
+            limit = parseInt(rawLimit, 10);
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                return res.status(400).json({ error: 'limit must be an integer between 1 and 100' });
+            }
+        }
+
+        const search = typeof req.query.search === 'string' && req.query.search.trim() !== ''
+            ? req.query.search.trim()
+            : undefined;
+
+        let state = undefined;
+        if (typeof req.query.state === 'string' && req.query.state.trim() !== '') {
+            const trimmedState = req.query.state.trim().toLowerCase();
+            if (!['new', 'delivered', 'returned'].includes(trimmedState)) {
+                return res.status(400).json({ error: 'Invalid state' });
+            }
+            state = trimmedState;
+        }
+
+        let seekMonths = undefined;
+        if (req.query.seekMonths !== undefined && req.query.seekMonths !== '') {
+            const parsedSeek = parseInt(req.query.seekMonths, 10);
+            if (!Number.isInteger(parsedSeek)) {
+                return res.status(400).json({ error: 'seekMonths must be an integer' });
+            }
+            seekMonths = parsedSeek;
+        }
+
+        try {
+            const result = await db.list(req.user.id, {
+                offset,
+                limit,
+                search,
+                state,
+                seekMonths,
+            });
+            res.status(200).json(result);
+        } catch (error) {
+            const status = shipmentErrorStatus(error);
+            if (status === 500) console.error('List shipments failed:', error);
+            res.status(status).json({ error: error.message });
+        }
+    });
+
+    // #endregion
+
     /**
      * @openapi
      * /shipment/{id}:
@@ -315,6 +477,102 @@ export function register(app, basePath = '') {
 
     // #endregion
 
+    /**
+     * @openapi
+     * /shipment/{id}:
+     *   patch:
+     *     tags: [Shipment]
+     *     summary: Update shipment state or metadata
+     *     description: |
+     *       Updates delivery state (`new`, `delivered`, `returned`) for the shipment.
+     *       Emits SSE events (`shipment`, `order`) so connected clients rerender in real time.
+     *     security:
+     *       - cookieAuth: []
+     *     x-signals: [shipment, order]
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: integer
+     *         description: Shipment ID
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             properties:
+     *               state:
+     *                 type: string
+     *                 enum: [new, delivered, returned]
+     *                 description: Delivery state
+     *             example:
+     *               state: delivered
+     *     responses:
+     *       200:
+     *         description: Updated shipment
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: object
+     *               properties:
+     *                 shipment:
+     *                   $ref: '#/components/schemas/Shipment'
+     *       400:
+     *         description: Invalid state, invalid ID, or no company selected
+     *         content:
+     *           application/json:
+     *             schema:
+     *               $ref: '#/components/schemas/Error'
+     *       401:
+     *         description: Unauthorized
+     *         content:
+     *           application/json:
+     *             schema:
+     *               $ref: '#/components/schemas/Error'
+     *       404:
+     *         description: Shipment not found
+     *         content:
+     *           application/json:
+     *             schema:
+     *               $ref: '#/components/schemas/Error'
+     */
+    // #region PATCH /shipment/:id
+
+    app.patch(`${basePath}/shipment/: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 });
+        }
+
+        const { state } = req.body ?? {};
+        if (state !== undefined) {
+            if (typeof state !== 'string' || !['new', 'delivered', 'returned'].includes(state.trim().toLowerCase())) {
+                return res.status(400).json({ error: 'Invalid state' });
+            }
+        }
+
+        try {
+            const shipment = await db.update(req.user.id, parsedId.id, {
+                state: state ? state.trim().toLowerCase() : undefined,
+            });
+            emitShipmentEvents(selected.companyId);
+            res.status(200).json({ shipment });
+        } catch (error) {
+            const status = shipmentErrorStatus(error);
+            if (status === 500) console.error('Update shipment failed:', error);
+            res.status(status).json({ error: error.message });
+        }
+    });
+
+    // #endregion
+
     /**
      * @openapi
      * /shipment/{id}: