H-3657: задокументировал /user/index и /user/search

Источник user_id для дальнейшей передачи в user-list-cache.
Раньше в swagger был только /user/profile (один по id) и /user/items
(минимальный список), но не было пагинированного индекса
с фильтрами — а именно через /user/index интегратор собирает
получателей для массового начисления валюты.

- GET /user/index: пагинация (per-page 1..20), сортировка, фильтры
  по основным атрибутам UserSearch (id, email, name, first_name,
  last_name, department_id, reg_status_id, group_id, position, ...),
  expand-поля.
- GET /user/search?q=&limit=&offset=: быстрый компактный поиск
  по ФИО/email/должности. Возвращает {q, users:[{id, name, position,
  departmentName, isBoss, ...}]}. Требует право show-structure-names —
  иначе users:[].

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

v2/swagger.yaml

@@ -558,6 +558,200 @@ paths:
         500:
           description: Server Error
 
+  /user/index:
+    get:
+      tags:
+        - user
+      summary: Список сотрудников
+      description: |
+        Постраничный список активных сотрудников тенанта. Тот же эндпоинт,
+        что использует основной UI HRBox. Видны все сотрудники со
+        `status_id = ACTIVE`, скрытые и не валидные для отображения отфильтрованы.
+
+        ### Типичные кейсы
+
+        - Интеграции, которым нужно собрать `user_id` для последующего
+          `POST /user-list-cache/set-user-list` → массового начисления валюты.
+        - Подразделение-специфичные выгрузки (`department_id`).
+
+        ### Сортировка
+
+        Поддерживается `?sort=name`, `?sort=-created_at`, `-last_login_at` и т.п.
+
+        ### Размер страницы
+
+        Дефолт 10, максимум 20 (`pageSizeLimit = [1, 20]`).
+      operationId: userIndex
+      parameters:
+        - name: page
+          in: query
+          schema: { type: integer, minimum: 1, default: 1 }
+        - name: per-page
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 20, default: 10 }
+        - name: sort
+          in: query
+          schema: { type: string }
+          description: 'Префикс `-` для DESC. Например `-created_at`, `name`, `-last_login_at`.'
+        - name: searchQuery
+          in: query
+          schema: { type: string }
+          description: Сквозной поиск по ФИО / e-mail / телефону / должности.
+        - name: id
+          in: query
+          schema:
+            oneOf:
+              - type: string
+                format: uuid
+              - type: array
+                items: { type: string, format: uuid }
+          description: 'Фильтр по конкретным UUID. Можно массив через `?id[]=...&id[]=...`.'
+        - name: not_id
+          in: query
+          schema: { type: string, format: uuid }
+          description: Исключить конкретного юзера.
+        - name: email
+          in: query
+          schema: { type: string }
+        - name: phone_auth
+          in: query
+          schema: { type: string }
+        - name: name
+          in: query
+          schema: { type: string }
+        - name: first_name
+          in: query
+          schema: { type: string }
+        - name: last_name
+          in: query
+          schema: { type: string }
+        - name: middle_name
+          in: query
+          schema: { type: string }
+        - name: position
+          in: query
+          schema: { type: string }
+        - name: company
+          in: query
+          schema: { type: string }
+        - name: department_id
+          in: query
+          schema:
+            oneOf:
+              - type: string
+                format: uuid
+              - type: array
+                items: { type: string, format: uuid }
+        - name: reg_status_id
+          in: query
+          schema: { type: string }
+          description: Comma-separated `RegStatus` (1=NO_ACCOUNT, 2=INVITED, 3=ACTIVE, 4=BLOCKED).
+        - name: gender_id
+          in: query
+          schema: { type: string }
+        - name: is_boss
+          in: query
+          schema: { type: boolean }
+        - name: is_external
+          in: query
+          schema: { type: boolean }
+        - name: group_id
+          in: query
+          schema: { type: string, format: uuid }
+          description: Фильтр по статической группе сотрудников.
+        - name: duty_id
+          in: query
+          schema: { type: string, format: uuid }
+        - name: spec_id
+          in: query
+          schema: { type: string, format: uuid }
+        - name: created_at
+          in: query
+          schema: { type: string }
+          description: 'Диапазон `from|to` (ISO).'
+        - name: last_login_at
+          in: query
+          schema: { type: string }
+          description: 'Диапазон `from|to` (ISO).'
+        - name: user_list_key
+          in: query
+          schema: { type: string, format: uuid }
+          description: 'Ключ закэшированной выборки (см. `/user-list-cache/set-user-list`).'
+        - name: expand
+          in: query
+          schema: { type: string }
+          description: |
+            Comma-separated extra-fields. Поддерживаются: `isBoss`, `faceUrl`,
+            `iconUrl`, `photoUrl`, `employment`, `cityName`, `statusText`,
+            `profileCorporateContacts`, `isFavoriteUser`, `contacts`, `statusTypes`.
+      responses:
+        200:
+          description: Список сотрудников
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/userProfile'
+                  _links:
+                    $ref: '#/components/schemas/_links'
+                  _meta:
+                    $ref: '#/components/schemas/_meta'
+        401:
+          description: Unauthorized.
+
+  /user/search:
+    get:
+      tags:
+        - user
+      summary: Быстрый поиск сотрудников по строке
+      description: |
+        Лёгкий компактный поиск — возвращает до `limit` юзеров с минимальным
+        набором полей (id, name, position, departmentName, isBoss, iconUrl,
+        employmentId). Использует тот же `UserSearchLogic`, что и сквозной
+        поиск UI.
+
+        Поле `users` будет пустым массивом, если у текущего юзера нет права
+        `show-structure-names`. Также пустой массив, если `q` не передан или пустой.
+      operationId: userSearch
+      parameters:
+        - name: q
+          in: query
+          required: true
+          schema: { type: string, maxLength: 255 }
+          description: Строка поиска (ФИО / e-mail / должность / подразделение).
+        - name: limit
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 100, default: 10 }
+        - name: offset
+          in: query
+          schema: { type: integer, minimum: 0, default: 0 }
+      responses:
+        200:
+          description: Результаты поиска
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  q:
+                    type: string
+                  users:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id: { type: string, format: uuid }
+                        name: { type: string }
+                        employmentId: { type: string, format: uuid, nullable: true }
+                        position: { type: string }
+                        departmentName: { type: string }
+                        isBoss: { type: boolean }
+                        iconUrl: { type: string, nullable: true }
+
   /user/items:
     get:
       tags: