Привёл описания /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>
Без этих эндпоинтов 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>
