From 278463e61169ea683685d7d9ac9d37af9d6e88b5 Mon Sep 17 00:00:00 2001
From: Anton Pomorzin <anton@hrbox.io>
Date: Thu, 20 Aug 2026 13:06:12 +0500
Subject: [PATCH] =?UTF-8?q?H-2626:=20=D0=9F=D1=80=D0=B0=D0=B2=D0=BA=D0=B8?=
 =?UTF-8?q?=20=D0=BF=D0=BE=D1=81=D0=BB=D0=B5=20=D1=80=D0=B5=D0=B2=D1=8C?=
 =?UTF-8?q?=D1=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 v2/swagger.yaml | 48 ++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 44 insertions(+), 4 deletions(-)

diff --git a/v2/swagger.yaml b/v2/swagger.yaml
index 331cd1b..6736164 100644
--- a/v2/swagger.yaml
+++ b/v2/swagger.yaml
@@ -8535,6 +8535,7 @@ paths:
       description: |
         `shop_product_id` обязателен — его требует `ShopProductOptionSearch`.
         Дефолтная сортировка `sort_index ASC` через `defaultOrder` search-модели.
+        По умолчанию отдаются только активные (status_id=ACTIVE); чтобы увидеть удалённые — явно передать `status_id`.
       operationId: adminShopProductOptionIndex
       parameters:
         - name: shop_product_id
@@ -8544,8 +8545,9 @@ paths:
         - name: status_id
           in: query
           schema: { type: integer }
-        - name: title
+        - name: name
           in: query
+          description: LIKE-фильтр по названию варианта.
           schema: { type: string }
         - name: sort
           in: query
@@ -8608,6 +8610,8 @@ paths:
     post:
       tags: [admin-shop-product-option]
       summary: Обновить одну опцию
+      description: |
+        Поле `shop_product_id` игнорируется — привязку к товару менять нельзя.
       operationId: adminShopProductOptionUpdate
       parameters:
         - name: id
@@ -8677,7 +8681,23 @@ paths:
           description: Диапазон `<начало>|<конец>` в формате `yyyy-MM-dd`.
         - name: sort
           in: query
-          schema: { type: string }
+          description: |
+            Поддерживаемые поля: `created_at`, `num`, `order_status_id`,
+            `sum_cart_for_sorting`, `count_cart_for_sorting`.
+            Префикс `-` — сортировка по убыванию. Дефолт — `-created_at`.
+          schema:
+            type: string
+            enum:
+              - created_at
+              - "-created_at"
+              - num
+              - "-num"
+              - order_status_id
+              - "-order_status_id"
+              - sum_cart_for_sorting
+              - "-sum_cart_for_sorting"
+              - count_cart_for_sorting
+              - "-count_cart_for_sorting"
       responses:
         200:
           description: Список заказов
@@ -8763,6 +8783,8 @@ paths:
     post:
       tags: [admin-shop-order]
       summary: Удалить позицию заказа
+      description: |
+        Операция допустима только на заказе в статусе NEW; для обработанного/отменённого — 422.
       operationId: adminShopOrderPositionRemove
       requestBody:
         required: true
@@ -8781,11 +8803,15 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/HttpJsonResult'
+        404: { description: Позиция не найдена. }
+        422: { description: Ошибка валидации формы либо заказ уже не в статусе NEW. }
 
   /admin/shop/order/position-restore:
     post:
       tags: [admin-shop-order]
       summary: Восстановить удалённую позицию заказа
+      description: |
+        Операция допустима только на заказе в статусе NEW; для обработанного/отменённого — 422.
       operationId: adminShopOrderPositionRestore
       requestBody:
         required: true
@@ -8803,11 +8829,16 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/HttpJsonResult'
+        400: { description: Параметр `id` не передан или имеет некорректный формат. }
+        404: { description: Позиция не найдена. }
+        422: { description: Заказ уже не в статусе NEW. }
 
   /admin/shop/order/position-change-comment:
     post:
       tags: [admin-shop-order]
       summary: Изменить комментарий к позиции заказа
+      description: |
+        Операция допустима только на заказе в статусе NEW; для обработанного/отменённого — 422.
       operationId: adminShopOrderPositionChangeComment
       requestBody:
         required: true
@@ -8826,6 +8857,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/HttpJsonResult'
+        404: { description: Позиция не найдена. }
+        422: { description: Ошибка валидации формы либо заказ уже не в статусе NEW. }
 
   /admin/shop/order/export-excel:
     post:
@@ -14808,6 +14841,12 @@ components:
           oneOf:
             - { type: object, additionalProperties: true }
             - { type: string, description: JSON-encoded блоки (legacy). }
+        categoriesId:
+          type: string
+          description: |
+            Список UUID категорий через запятую (например `uuid1,uuid2`).
+            Обрабатывается `CategoryTreeItemModelBehavior::afterSave`. Пустая строка
+            снимает все привязки. Без категории товар не будет виден в витрине покупателя.
 
     AdminShopProductOption:
       type: object
@@ -14843,8 +14882,9 @@ components:
       type: object
       description: |
         Поля `id`, `created_user_id`, `updated_user_id`, `tenant_id` подставляются
-        автоматически в `BaseModel::beforeSave` — попытка передать их в payload
-        игнорируется (поля убраны из `safeAttributes`).
+        автоматически behavior'ами модели — попытка передать их в payload
+        перезаписывается серверными значениями.
+        При `update` поле `shop_product_id` игнорируется — привязку к товару менять нельзя.
       properties:
         shop_product_id: { type: string, format: uuid }
         status_id: { type: integer }