From b8d17240abb65539252fb2d7e01e32232a425454 Mon Sep 17 00:00:00 2001 From: Denis Date: Fri, 22 May 2026 16:06:44 +0300 Subject: [PATCH] =?UTF-8?q?H-3657:=20=D0=B7=D0=B0=D0=B4=D0=BE=D0=BA=D1=83?= =?UTF-8?q?=D0=BC=D0=B5=D0=BD=D1=82=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D0=BB=20?= =?UTF-8?q?/user/index=20=D0=B8=20/user/search?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Источник 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) --- v2/swagger.yaml | 194 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) diff --git a/v2/swagger.yaml b/v2/swagger.yaml index 9676bbf..2655a4d 100644 --- a/v2/swagger.yaml +++ b/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: