Merge branch 'feature/H-3821' into 'master'

H-3821: задокументировал /admin/employment в v2 swagger

See merge request hrbox-public/api!37

v2/swagger.yaml

@@ -73,6 +73,8 @@ tags:
     description: Methods for managing personal API tokens (PATs) for server-to-server access. Requires "api-tokens-manage" permission.
   - name: admin-user-api-token
     description: Methods for admin oversight of personal API tokens. Requires "api-tokens-admin" permission.
+  - name: admin-employment
+    description: Methods for administrative read-only access to employee employments, including external identifiers used by integrations. Requires "user-edit" permission.
 
 paths:
   /mobile/bind/{id}/{token}:
@@ -7529,6 +7531,225 @@ paths:
         404:
           description: Токен не найден.
 
+  /admin/employment:
+    get:
+      tags: [admin-employment]
+      summary: Получить список трудоустройств
+      description: |
+        Возвращает постраничный список трудоустройств тенанта с поддержкой
+        фильтрации, сортировки и пагинации. Состав возвращаемых полей и
+        набор параметров фильтрации соответствуют существующему эндпоинту
+        `/api/employment` версии 1.
+
+        ## Получение идентификатора пользователя по внешнему ключу
+
+        Основной сценарий использования для интеграций — получение
+        идентификатора пользователя HRBox (`user_id`) по внешнему
+        идентификатору должности из системы-источника
+        (`origin_id`, `origin_organization_id`).
+
+        Пример запроса:
+
+        ```
+        GET /api/v2/admin/employment
+            ?origin_id=12345
+            &origin_organization_id=default
+        ```
+
+        В поле `data[].user_id` возвращается идентификатор пользователя
+        в формате UUID версии 4, который может быть использован
+        в последующих обращениях к v2 API. Поддерживается передача
+        нескольких значений через массив:
+        `?origin_id[]=...&origin_id[]=...`.
+
+        ## Множественные трудоустройства
+
+        У одного пользователя может быть несколько трудоустройств
+        с различными значениями `origin_id`. Признак основного
+        трудоустройства передаётся в поле `is_main`.
+
+        ## Завершённые трудоустройства
+
+        Записи с заполненным полем `fired_date` включены в выдачу
+        по умолчанию. Для исключения завершённых трудоустройств
+        используйте фильтр `status_id`.
+      operationId: adminEmploymentIndex
+      parameters:
+        - name: page
+          in: query
+          schema: { type: integer, minimum: 1, default: 1 }
+        - name: per-page
+          in: query
+          schema: { type: integer, minimum: 1, default: 20 }
+        - name: sort
+          in: query
+          schema: { type: string }
+          description: |
+            Поле сортировки. Для сортировки по убыванию используется префикс `-`.
+            Допустимые поля: `created_at`, `employment_date`, `fired_date` и другие
+            атрибуты, определённые в `EmploymentSearch::sort()`.
+        - name: id
+          in: query
+          schema: { type: string, format: uuid }
+          description: Идентификатор трудоустройства.
+        - name: user_id
+          in: query
+          schema:
+            oneOf:
+              - type: string
+                format: uuid
+              - type: array
+                items: { type: string, format: uuid }
+          description: |
+            Идентификатор пользователя. Допускается передача нескольких значений
+            в виде массива `?user_id[]=...&user_id[]=...` либо в виде строки
+            со значениями, разделёнными запятой.
+        - name: chief_id
+          in: query
+          schema: { type: string, format: uuid }
+          description: Идентификатор трудоустройства руководителя.
+        - name: department_id
+          in: query
+          schema: { type: string, format: uuid }
+          description: |
+            Идентификатор подразделения. Фильтр учитывает все вложенные
+            подразделения иерархии.
+        - name: origin_id
+          in: query
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+          description: |
+            Внешний идентификатор должности из системы-источника. Допускается
+            передача нескольких значений в виде массива либо строки
+            со значениями, разделёнными запятой.
+        - name: origin_organization_id
+          in: query
+          schema: { type: string }
+          description: |
+            Идентификатор организации в системе-источнике. Применяется
+            в сочетании с `origin_id` для однозначного сопоставления записи.
+        - name: org_num
+          in: query
+          schema: { type: string }
+          description: |
+            Табельный номер. Допускается передача нескольких значений
+            в виде строки, разделённой запятой.
+        - name: first_name
+          in: query
+          schema: { type: string }
+          description: Поиск по имени, регистронезависимое частичное совпадение.
+        - name: last_name
+          in: query
+          schema: { type: string }
+          description: Поиск по фамилии, регистронезависимое частичное совпадение.
+        - name: name
+          in: query
+          schema: { type: string }
+          description: |
+            Поиск по полю `name` пользователя (имя и фамилия),
+            регистронезависимое частичное совпадение.
+        - name: position
+          in: query
+          schema: { type: string }
+          description: Поиск по должности, регистронезависимое частичное совпадение.
+        - name: is_main
+          in: query
+          schema: { type: boolean }
+          description: Признак основного трудоустройства.
+        - name: status_id
+          in: query
+          schema: { type: integer }
+          description: |
+            Статус трудоустройства. Допустимые значения:
+            `1` — действующее, `2` — отключённое.
+        - name: reg_status_id
+          in: query
+          schema: { type: string }
+          description: |
+            Статус регистрации пользователя-владельца трудоустройства.
+            Допустимые значения: `1` — без аккаунта, `2` — приглашён,
+            `3` — активен, `4` — заблокирован. Допускается передача
+            нескольких значений через запятую.
+        - name: created_at
+          in: query
+          schema: { type: string }
+          description: |
+            Период создания записи в формате `<начало>|<конец>`,
+            где даты указаны по ISO 8601.
+        - name: employment_date
+          in: query
+          schema: { type: string }
+          description: |
+            Период даты приёма на работу в формате `<начало>|<конец>`.
+        - name: fired_date
+          in: query
+          schema: { type: string }
+          description: |
+            Период даты увольнения в формате `<начало>|<конец>`.
+        - name: user_list_key
+          in: query
+          schema: { type: string, format: uuid }
+          description: |
+            Ключ закэшированной выборки пользователей, полученный
+            от `/user-list-cache/set-user-list`.
+        - name: chief_only
+          in: query
+          schema: { type: boolean }
+          description: |
+            Ограничить выборку прямыми подчинёнными текущего пользователя.
+        - name: chief_only_all
+          in: query
+          schema: { type: boolean }
+          description: |
+            Ограничить выборку всеми подчинёнными текущего пользователя
+            с учётом вложенной иерархии.
+        - name: multipleEmployment
+          in: query
+          schema: { type: boolean }
+          description: |
+            Ограничить выборку пользователями, у которых более одного
+            трудоустройства.
+      responses:
+        200:
+          description: Список трудоустройств.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdminEmploymentList'
+        403:
+          description: |
+            У текущего пользователя отсутствует право `user-edit`.
+
+  /admin/employment/view:
+    get:
+      tags: [admin-employment]
+      summary: Получить трудоустройство по идентификатору
+      operationId: adminEmploymentView
+      parameters:
+        - name: id
+          in: query
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        200:
+          description: Запись трудоустройства.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AdminEmployment'
+        400:
+          description: Параметр `id` имеет некорректный формат.
+        403:
+          description: |
+            У текущего пользователя отсутствует право `user-edit`.
+        404:
+          description: |
+            Запись не найдена. Включает случаи обращения к записям,
+            принадлежащим другим тенантам.
+
 components:
   securitySchemes:
     SessionAuth:
@@ -12647,6 +12868,182 @@ components:
         _meta:
           $ref: '#/components/schemas/_meta'
 
+    AdminEmploymentUserShort:
+      type: object
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string, nullable: true }
+        faceUrl: { type: string, format: uri, nullable: true }
+
+    AdminEmploymentChiefUserShort:
+      type: object
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string, nullable: true }
+
+    AdminEmploymentDepartmentShort:
+      type: object
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string, nullable: true }
+        departmentPath:
+          type: string
+          nullable: true
+          description: 'Полный путь от корня структуры через `/`.'
+
+    AdminEmployment:
+      type: object
+      description: |
+        Запись трудоустройства в административной выдаче. Содержит поля
+        самого трудоустройства, а также связанные объекты пользователя,
+        руководителя и подразделения.
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Идентификатор трудоустройства.
+        is_main:
+          type: boolean
+          description: |
+            Признак основного трудоустройства. Для пользователя с несколькими
+            трудоустройствами только одна запись имеет значение `true`.
+        user_id:
+          type: string
+          format: uuid
+          description: |
+            Идентификатор пользователя-владельца трудоустройства. Используется
+            для последующих обращений к v2 API, ожидающих `user_id`.
+        chief_id:
+          type: string
+          format: uuid
+          nullable: true
+          description: |
+            Идентификатор трудоустройства руководителя. Ссылается на запись
+            `Employment`, а не на `User`.
+        department_id:
+          type: string
+          format: uuid
+          nullable: true
+          description: Идентификатор подразделения.
+        position:
+          type: string
+          nullable: true
+          description: Должность.
+        employment_date:
+          type: string
+          nullable: true
+          description: Дата приёма на работу в формате ISO 8601.
+        fired_date:
+          type: string
+          nullable: true
+          description: |
+            Дата увольнения в формате ISO 8601. Поле имеет значение `null`
+            для действующих трудоустройств.
+        status_id:
+          type: integer
+          nullable: true
+          description: |
+            Статус трудоустройства. Допустимые значения: `1` — действующее,
+            `2` — отключённое.
+        origin_id:
+          type: string
+          nullable: true
+          description: |
+            Внешний идентификатор должности из системы-источника.
+        origin_organization_id:
+          type: string
+          nullable: true
+          description: |
+            Идентификатор организации в системе-источнике. Однозначное
+            сопоставление записи определяется парой
+            (`origin_id`, `origin_organization_id`).
+        org_num:
+          type: string
+          nullable: true
+          description: Табельный номер.
+        first_name:
+          type: string
+          nullable: true
+          description: Имя пользователя.
+        last_name:
+          type: string
+          nullable: true
+          description: Фамилия пользователя.
+        photo:
+          type: string
+          nullable: true
+          description: |
+            Имя файла фотографии, полученное от системы-источника.
+        created_at:
+          type: string
+          nullable: true
+          description: Дата создания записи.
+        updated_at:
+          type: string
+          nullable: true
+          description: Дата последнего изменения записи.
+        experience:
+          type: string
+          nullable: true
+          description: |
+            Стаж работы в текстовом представлении (например,
+            «15 years 3 months 19 days»).
+        name:
+          type: string
+          nullable: true
+          description: Имя и фамилия пользователя-владельца трудоустройства.
+        nameDetails:
+          type: string
+          nullable: true
+          description: Расширенное представление имени пользователя.
+        iconUrl:
+          type: string
+          format: uri
+          nullable: true
+          description: URL изображения пользователя.
+        profilePosition:
+          type: string
+          nullable: true
+          description: Должность для отображения в профиле пользователя.
+        user:
+          $ref: '#/components/schemas/AdminEmploymentUserShort'
+        chiefUser:
+          allOf:
+            - $ref: '#/components/schemas/AdminEmploymentChiefUserShort'
+          nullable: true
+        department:
+          allOf:
+            - $ref: '#/components/schemas/AdminEmploymentDepartmentShort'
+          nullable: true
+        createdAt:
+          type: string
+          nullable: true
+          description: Дата создания записи в локализованном представлении.
+        employmentDate:
+          type: string
+          nullable: true
+          description: Дата приёма на работу в локализованном представлении.
+        firedDate:
+          type: string
+          nullable: true
+          description: Дата увольнения в локализованном представлении.
+        statusName:
+          type: string
+          nullable: true
+          description: Локализованное наименование статуса.
+
+    AdminEmploymentList:
+      type: object
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/AdminEmployment'
+        _links:
+          $ref: '#/components/schemas/_links'
+        _meta:
+          $ref: '#/components/schemas/_meta'
+
   parameters:
     boardDateTypeParam:
       in: query