u

src/api/routes/category.js

@@ -907,4 +907,122 @@ export function register(app, basePath = '') {
     });
 
     // #endregion
+
+    /**
+     * @openapi
+     * /category/{id}/image/generate:
+     *   post:
+     *     tags: [Category]
+     *     summary: Generate category mosaic image from contents
+     *     description: |
+     *       Generates a 2x2, 3x3, or 4x4 mosaic image from the category's and its subcategories'
+     *       articles (grouped by subcategory) and sets it as the new main picture for the category.
+     *       If size is not specified, defaults to 3 (3x3), falling back to 2 (2x2) if fewer than 7 images are available.
+     *     security:
+     *       - cookieAuth: []
+     *     x-signals: [category]
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: integer
+     *         description: Category id
+     *     requestBody:
+     *       required: false
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             properties:
+     *               size:
+     *                 type: integer
+     *                 enum: [2, 3, 4]
+     *                 description: Mosaic grid size (2 for 2x2, 3 for 3x3, 4 for 4x4). Defaults to 3x3 (or 2x2 if < 7 images).
+     *     responses:
+     *       200:
+     *         description: Mosaic image generated and linked as category main picture
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: object
+     *               properties:
+     *                 category:
+     *                   type: object
+     *                   properties:
+     *                     id:
+     *                       type: integer
+     *                     fullHash:
+     *                       type: string
+     *                     thumbW:
+     *                       type: integer
+     *                     thumbH:
+     *                       type: integer
+     *                     thumbHash:
+     *                       type: string
+     *                     size:
+     *                       type: integer
+     *                     grid:
+     *                       type: string
+     *                     articleCount:
+     *                       type: integer
+     *       400:
+     *         description: Invalid category ID or size
+     *         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: Category not found or no article images found
+     *         content:
+     *           application/json:
+     *             schema:
+     *               $ref: '#/components/schemas/Error'
+     */
+    // #region POST /category/:id/image/generate
+
+    app.post(
+        `${basePath}/category/:id/image/generate`,
+        express.json(),
+        async (req, res) => {
+            const parsed = parsePositiveInt(req.params.id, 'id');
+            if (parsed.error) {
+                return res.status(400).json({ error: parsed.error });
+            }
+
+            const rawSize = req.body?.size;
+            let size = undefined;
+            if (rawSize !== undefined && rawSize !== null && rawSize !== '') {
+                size = Number(rawSize);
+                if (![2, 3, 4].includes(size)) {
+                    return res.status(400).json({ error: 'Invalid size, must be 2, 3, or 4' });
+                }
+            }
+
+            try {
+                const category = await db.generateImage(req.user.id, parsed.id, { size });
+                emitCategorySignal(req);
+                res.status(200).json({ category });
+            } catch (error) {
+                const status = categoryErrorStatus(error);
+                if (status === 500) console.error('Generate category image failed:', error);
+                res.status(status).json({ error: error.message });
+            }
+        },
+    );
+
+    // #endregion
 }
+