Привёл описания /user/index, /user/search, /file/prepare-upload,
/file/finish-upload, /user-list-cache/* и связанных схем
(UserListForm, UserListData, File, FilePrepareUploadBody,
FilePrepareUploadResponse) к единому нейтральному документационному
стилю — как в H-3821.
Убраны: разговорные обороты («юзер», «флоу», «грабли», «отдаёте»,
«придумываете», «протух», «дефолт», «компактный»), эмодзи в
заголовках секций, ###-маркеры разделов внутри description.
Все формулировки переведены в третье лицо.
Поправлены данные:
- is_public в FilePrepareUploadBody: integer enum [0,1] → boolean
(соответствует @property boolean is_public в File model).
- /user/search?limit: убран искусственный maximum: 100, в контроллере
верхнего предела нет (только default = 10).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Убрал разговорные обороты («главный кейс», «уволенные», «совместительства»,
«юзер», «UUID юзера», «то самое значение», «cross-tenant», «нет права»,
«ilike-поиск»). Описания параметров, полей схемы и ответов
переведены в нейтральный документационный регистр без жаргона
и эмоциональной разметки.
Технический смысл сохранён полностью — изменения только стилистические.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Новый admin read-only API трудоустройств. Основной кейс —
маппинг (origin_id, origin_organization_id) → user_id для
интеграторов (web-zaim, sokolove и др.).
- Тег admin-employment (Methods for admin read-only access...).
- GET /admin/employment: index с полным набором фильтров
EmploymentSearch (origin_id[], origin_organization_id, user_id[],
department_id, chief_id, is_main, status_id, reg_status_id,
employment_date/fired_date/created_at range, name/position ilike,
user_list_key, chief_only*, multipleEmployment).
- GET /admin/employment/view?id=<uuid>: одна запись.
- Доступ: user-edit (тот же perm что в legacy /api/employment v1).
- Схемы AdminEmployment, AdminEmploymentList, AdminEmploymentUserShort,
AdminEmploymentChiefUserShort, AdminEmploymentDepartmentShort.
- В описании метода — главный кейс маппинга origin → user_id,
совместительства, поведение uvol'нённых, батч origin_id[].
Источники: контроллер app\controllers\api\v2\admin\EmploymentController,
testrix tests/v2/admin/test_admin_employment.py +
hrbox/models/v2/AdminEmploymentModel.py (pydantic).
Проверено живьём на denis.hrbox.io: totalCount=9393, все поля
схемы совпадают с реальным ответом.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Без этих эндпоинтов excel-import flow для wallet-транзакций
неполный — интегратор не понимает откуда взять file_id для
POST /admin/wallet-transaction/excel-processing.
- Новый тег `file` (Methods for uploading files via signed-URL...).
- POST /file/prepare-upload: создаёт File-запись + возвращает signedUrl
для PUT-загрузки бинарника напрямую в S3.
- POST /file/finish-upload?id=<uuid>: помечает файл как UPLOADED, после
чего file_id можно использовать в downstream-флоу.
- Подробная описание двухшагового флоу (prepare → PUT signedUrl → finish)
в описании prepare-upload.
- Идемпотентность через повторный prepare-upload с тем же id.
- Схемы File (полная), FilePrepareUploadBody, FilePrepareUploadResponse.
- В WalletExcelFormBody.file_id ссылка на этот upload-флоу — раньше
было просто «UUID предварительно загруженного xlsx».
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Источник 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>
Без этого интегратор не понимает откуда взять usersListKey для
POST /admin/wallet-transaction/create.
- Тег user-list-cache (Methods for caching ad-hoc employee selections...).
- POST /user-list-cache/set-user-list: тело {key, userList:{usersId,...}}.
В описании явно прописал что Content-Type обязательно application/json —
через form-urlencoded вложенный JsonModel не парсится, и сервер
молча сохраняет пустую выборку (грабли которые я сам и наступил
во время smoke-теста).
- GET /user-list-cache/user-list-data?key=<key>: возвращает развёрнутую
выборку (users, departments, userGroups, ...). Схема ответа проверена
живьём на denis.hrbox.io — все ключи совпадают.
- Схемы UserListForm, UserListCacheSetBody, UserListData.
- В описании POST /admin/wallet-transaction/create добавил секцию
«Как получить usersListKey» с пошаговым флоу и ссылкой.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Соглашение: info.description и теги — короткое EN (как workflow,
wallet и др.), а внутри самого метода (summary + description) —
русский, потому что туда смотрит уже сам интегратор и важно дать
максимально понятный how-to. Возвращаю русский для
POST /user-api-token/create.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- info.description: убрал большой блок «Авторизация по личному API-токену»
(он висел на стартовой странице Swagger UI). Вместо него — одна
английская строка-указатель на user-api-token methods, в стиле
остального вступления.
- BearerAuth securityScheme: однострочное EN-описание.
- Теги admin-wallet, admin-wallet-transaction, file-processing,
user-api-token, admin-user-api-token: переведены в формат
«Methods for ...» (как workflow, wallet, shop и т.д.) — короткая
английская строка на тег.
- POST /user-api-token/create description: подробный how-to (создание,
Bearer-header, tenant-резолв, отсутствие scopes, lifecycle,
isValidForDisplay-caveat, запрет на управление под Bearer) — теперь
лежит здесь, на английском, и сворачивается в UI вместе с эндпоинтом.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Listing-схемы (Wallet/WalletTransaction/FileProcessing/UserApiToken{,Admin}):
добавил optional поле `_links` — оно реально возвращается Yii Pagination
на index-эндпоинтах и без него клиент-генератор не видит поле.
- FileProcessing: дополнил схему полями, которые реально приходят в
ответе без `?expand=`:
* `file` — объект с метаданными файла-источника (name, ext, url, ...)
* `created`/`started`/`finished` — локализованные строки для отображения
Уточнил `arguments` и `result` (oneOf object/array).
Все остальные эндпоинты (admin/wallet[/view], admin/wallet-transaction[/view],
admin/wallet-transaction/{create,create-from-excel,excel-processing},
file-processing[/view], user-api-token, admin/user-api-token) после
прогона smoke-теста соответствуют документации:
- response shape ↔ schema
- 400 на not-uuid id
- 404 на несуществующий id
- per-page>100 clamps к 100
- 200 с {success:false, errors:[...]} на пустой POST
- 200 с {success:false, message:{type:warning, text:"Обработка файла не найдена"}}
на несуществующий file_processing_id
- 403 на /user-api-token и /admin/user-api-token под Bearer
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
При тестировании наткнулся на 401 «Login Required» с валидным
live-токеном, потому что у юзера-владельца стоял is_hidden=true.
findIdentityByAccessToken после поиска токена ещё прогоняет
User::isValidForDisplay() — это надо явно упоминать в how-to,
иначе интегратор не поймёт почему не работает.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Фронтенд (frontend/src/api/userApiToken/HRUserApiTokenApi.ts:18) зовёт
именно `${baseUrl}/create`, а не RESTful `POST /user-api-token`.
Оба роута маршрутизируются Yii в actionCreate, но в swagger лучше
документировать тот же путь, что использует прод-клиент — для
консистентности с /admin/wallet-transaction/create.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- info.description: подробная how-to секция «Авторизация по личному API-токену»
(создание, формат Bearer-заголовка, tenant-резолв, отсутствие scopes,
жизненный цикл и автo-revoke при блокировке юзера, запрет на управление
под Bearer).
- securitySchemes.BearerAuth: новая схема http/bearer (PAT).
- security (global): + BearerAuth, чтобы Try-it-out предлагал три способа auth.
- Теги user-api-token и admin-user-api-token.
- Эндпоинты:
* GET /user-api-token, POST /user-api-token, POST /user-api-token/revoke
* GET /admin/user-api-token, POST /admin/user-api-token/revoke
Все management-эндпоинты помечены `security: SessionAuth` и явно
документируют 403 под Bearer (защита от рекурсии).
- Схемы: UserApiToken, UserApiTokenList, UserApiTokenCreated (с plain),
UserApiTokenCreateForm, UserApiTokenAdmin (+ user/updatedByUser),
UserApiTokenAdminList, UserApiTokenStatus.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Новые эндпоинты:
- GET /admin/wallet[/view] — кошельки сотрудников (read-only)
- POST /admin/wallet/export-excel
- GET /admin/wallet-transaction[/view] — транзакции, admin-вид
- POST /admin/wallet-transaction/create — массовое начисление/списание по форме
- POST /admin/wallet-transaction/create-from-excel — проведение по результату парсинга
- POST /admin/wallet-transaction/excel-processing — парсинг xlsx (file_id + mappings)
- POST /admin/wallet-transaction/export-excel
- GET /file-processing[/view] — статусы FileProcessing для поллинга
Permission: wallets-transactions, требует enableWallet=true у тенанта.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
mitrikov
denis
antonandClaude Opus 4.7