API

Все маршруты — под /api, отвечают JSON. Вход — cookie сессии (POST /api/auth/login) или API-токен проекта в заголовке Authorization: Bearer tsmc_…: токен действует как редактор и только в своём проекте. Изменяющие запросы из браузера обязаны нести заголовок X-Requested-With: tsmc. Роли включают друг друга: наблюдатель < тестировщик < редактор < администратор. Списки с limit отдают общее число в заголовке X-Total-Count.

Вход и профиль

`GET /api/health`

Жив ли сервер, версия API и приложения. Без входа.

Роль: без входа.

`GET /api/auth/state`

Кто вошёл, нужна ли первичная настройка, демо-режим и стенд.

Роль: без входа.

`POST /api/auth/setup`

Создать первого администратора — только пока нет ни одного пользователя.

Роль: без входа.

Тело (SetupRequest):

Поле	Тип	Обязательно
`email`	string	да
`name`	string	да
`password`	string	да

`POST /api/auth/login`

Войти: ставит cookie сессии.

Роль: без входа.

Тело (LoginRequest):

Поле	Тип	Обязательно
`email`	string	да
`password`	string	да

`POST /api/auth/logout`

Выйти: завершает текущую сессию.

Роль: без входа.

`PATCH /api/auth/me`

Изменить своё имя или пароль.

Роль: наблюдатель.

Тело (ProfilePatch):

Поле	Тип	Обязательно
`name`	string
`currentPassword`	string
`newPassword`	string

Пользователи и журнал

`GET /api/users`

Все пользователи с ролями.

Роль: администратор.

`GET /api/users/directory`

Имена активных пользователей — для выбора исполнителя.

Роль: наблюдатель.

`POST /api/users`

Создать пользователя.

Роль: администратор.

Тело (UserCreate):

Поле	Тип	Обязательно
`email`	string	да
`name`	string	да
`role`	`viewer` \| `tester` \| `editor` \| `admin`
`password`	string	да

`PATCH /api/users/:id`

Изменить роль, имя, пароль; отключить или включить.

Роль: администратор.

Тело (UserPatch):

Поле	Тип	Обязательно
`name`	string
`role`	`viewer` \| `tester` \| `editor` \| `admin`
`password`	string
`disabled`	boolean

`GET /api/audit`

Журнал действий: фильтр по действию или группе, проекту, пользователю; постранично.

Роль: администратор.

Параметры запроса (AuditQuery):

Поле	Тип	Обязательно
`action`	string
`project`	string
`user`	integer
`before`	integer
`limit`	integer

Проекты

`GET /api/projects`

Все проекты.

Роль: наблюдатель.

`POST /api/projects`

Создать проект с ключом.

Роль: администратор.

Тело (ProjectCreate):

Поле	Тип	Обязательно
`key`	string	да
`name`	string	да
`description`	string

`GET /api/projects/:project`

Проект по ключу.

Роль: наблюдатель.

`PATCH /api/projects/:project`

Переименовать проект или изменить описание.

Роль: администратор.

Тело (ProjectPatch):

Поле	Тип	Обязательно
`name`	string
`description`	string

`DELETE /api/projects/:project`

Удалить проект со всем содержимым.

Роль: администратор.

Сьюты

`GET /api/projects/:project/suites`

Дерево сьютов проекта.

Роль: наблюдатель.

`GET /api/projects/:project/suites/case-counts`

Число кейсов в каждом сьюте — для выбора кейсов в прогон.

Роль: наблюдатель.

`POST /api/projects/:project/suites`

Создать сьют.

Роль: редактор.

Тело (SuiteCreate):

Поле	Тип	Обязательно
`name`	string	да
`description`	string
`parentId`	integer \| null
`codePaths`	string[]

`GET /api/suites/:id`

Сьют.

Роль: наблюдатель.

`POST /api/suites/:id/copy`

Скопировать сьют со всеми вложенными сьютами и кейсами.

Роль: редактор.

Тело (SuiteCopy):

Поле	Тип	Обязательно
`parentId`	integer \| null
`name`	string

`PATCH /api/suites/:id`

Переименовать, перенести, поменять место среди соседей, задать шаблоны путей кода.

Роль: редактор.

Тело (SuitePatch):

Поле	Тип	Обязательно
`name`	string
`description`	string
`parentId`	integer \| null
`position`	integer
`codePaths`	string[]

`DELETE /api/suites/:id`

Удалить сьют с вложенными сьютами и кейсами.

Роль: редактор.

Кейсы

`GET /api/projects/:project/cases`

Кейсы проекта: полнотекстовый поиск, фильтры, постранично (всего — в X-Total-Count).

Роль: наблюдатель.

Параметры запроса (CaseListQuery):

Поле	Тип	Обязательно
`suiteId`	integer
`recursive`	`true` \| `false`
`q`	string
`tag`	string
`status`	`draft` \| `active` \| `deprecated`
`priority`	`low` \| `medium` \| `high` \| `critical`
`limit`	integer
`offset`	integer

`POST /api/projects/:project/cases/bulk`

Массовое действие над выбранными кейсами: перенос, теги, статус, приоритет, удаление.

Роль: редактор.

`POST /api/cases/:id/copy`

Копия кейса без ключа автотеста, результатов и вложений.

Роль: редактор.

Тело (CaseCopy):

Поле	Тип	Обязательно
`suiteId`	integer
`title`	string

`POST /api/cases/:id/place`

Перенести кейс в сьют и/или поставить перед другим кейсом.

Роль: редактор.

Тело (CasePlace):

Поле	Тип	Обязательно
`suiteId`	integer	да
`before`	integer \| null

`POST /api/projects/:project/cases`

Создать кейс.

Роль: редактор.

Тело (CaseCreate):

Поле	Тип	Обязательно
`suiteId`	integer	да
`title`	string	да
`description`	string
`preconditions`	string
`priority`	`low` \| `medium` \| `high` \| `critical`
`type`	`functional` \| `smoke` \| `regression` \| `acceptance` \| `performance` \| `security` \| `usability` \| `other`
`status`	`draft` \| `active` \| `deprecated`
`automationKey`	string \| null
`tags`	string[]
`steps`	object[]
`codePaths`	string[]
`dataset`	object \| null

`GET /api/cases/by-key/:key`

Кейс по ключу, например SHOP-12.

Роль: наблюдатель.

`GET /api/cases/:id`

Кейс.

Роль: наблюдатель.

`PATCH /api/cases/:id`

Изменить кейс — новая версия; expectedVersion ловит одновременную правку.

Роль: редактор.

Тело (CasePatch):

Поле	Тип	Обязательно
`suiteId`	integer
`title`	string
`description`	string
`preconditions`	string
`priority`	`low` \| `medium` \| `high` \| `critical`
`type`	`functional` \| `smoke` \| `regression` \| `acceptance` \| `performance` \| `security` \| `usability` \| `other`
`status`	`draft` \| `active` \| `deprecated`
`automationKey`	string \| null
`tags`	string[]
`steps`	object[]
`codePaths`	string[]
`dataset`	object \| null
`expectedVersion`	integer

`DELETE /api/cases/:id`

Удалить кейс. В прогонах остаётся его копия.

Роль: редактор.

`GET /api/cases/:id/versions`

История версий кейса: автор, канал, что изменилось.

Роль: наблюдатель.

`GET /api/cases/:id/versions/:version`

Версия кейса целиком.

Роль: наблюдатель.

`GET /api/cases/:id/results`

Результаты кейса во всех прогонах.

Роль: наблюдатель.

Общие шаги

`GET /api/projects/:project/shared-steps`

Общие шаги проекта.

Роль: наблюдатель.

`POST /api/projects/:project/shared-steps`

Создать общий шаг.

Роль: редактор.

Тело (SharedStepCreate):

Поле	Тип	Обязательно
`name`	string	да
`steps`	object[]	да

`GET /api/shared-steps/:id`

Общий шаг и кейсы, где он используется.

Роль: наблюдатель.

`PATCH /api/shared-steps/:id`

Изменить общий шаг: все кейсы с ним получают новую версию; ответ — сколько кейсов обновлено.

Роль: редактор.

Тело (SharedStepPatch):

Поле	Тип	Обязательно
`name`	string
`steps`	object[]
`expectedVersion`	integer

`DELETE /api/shared-steps/:id`

Удалить общий шаг: в кейсах его шаги остаются обычными.

Роль: редактор.

Прогоны

`GET /api/projects/:project/runs`

Прогоны: закреплённые первыми, фильтр по статусу, архиву и вехе, постранично.

Роль: наблюдатель.

Параметры запроса (RunListQuery):

Поле	Тип	Обязательно
`status`	`open` \| `closed`
`milestone`	integer
`archived`	`0` \| `1` \| `true` \| `false`
`limit`	integer
`offset`	integer

`POST /api/projects/:project/runs`

Создать прогон из выбранных кейсов.

Роль: тестировщик.

Тело (RunCreate):

Поле	Тип	Обязательно
`name`	string	да
`description`	string
`build`	string
`environment`	string
`milestoneId`	integer \| null
`icon`	`computer` \| `ps` \| `x` \| `android` \| `apple` \| `smoke` \| `alert` \| null
`selection`	object

`POST /api/projects/:project/runs/preview`

Сколько кейсов попадёт в прогон при таком выборе — ничего не создаёт.

Роль: наблюдатель.

Тело (RunSelection):

Поле	Тип	Обязательно
`caseIds`	integer[]
`suiteIds`	integer[]
`tags`	string[]
`priorities`	`low` \| `medium` \| `high` \| `critical`[]
`pick`	object
`statuses`	`draft` \| `active` \| `deprecated`[]
`keepOrder`	boolean

`GET /api/runs/:id`

Прогон с кейсами и результатами.

Роль: наблюдатель.

`PATCH /api/runs/:id`

Изменить название, описание, сборку, окружение, веху, иконку.

Роль: тестировщик.

Тело (RunPatch):

Поле	Тип	Обязательно
`name`	string
`description`	string
`build`	string
`environment`	string
`milestoneId`	integer \| null
`icon`	`computer` \| `ps` \| `x` \| `android` \| `apple` \| `smoke` \| `alert` \| null

`POST /api/runs/:id/close`

Закрыть прогон.

Роль: тестировщик.

`POST /api/projects/:project/runs/:id/close`

Закрыть прогон с проверкой проекта — для CI с токеном проекта.

Роль: тестировщик.

`POST /api/runs/:id/reopen`

Переоткрыть прогон (и вернуть из архива).

Роль: тестировщик.

`POST /api/runs/:id/archive`

Отправить в архив: прогон закрывается и уходит из списка, в отчётах остаётся.

Роль: тестировщик.

`POST /api/runs/:id/unarchive`

Вернуть из архива.

Роль: тестировщик.

`POST /api/runs/:id/pin`

Закрепить наверху списка прогонов для всех.

Роль: тестировщик.

`POST /api/runs/:id/unpin`

Открепить.

Роль: тестировщик.

`POST /api/runs/:id/rerun`

Новый прогон тех же кейсов в текущих версиях, без результатов.

Роль: тестировщик.

Тело (RunRerun):

Поле	Тип	Обязательно
`name`	string	да
`description`	string
`build`	string
`environment`	string
`milestoneId`	integer \| null
`icon`	`computer` \| `ps` \| `x` \| `android` \| `apple` \| `smoke` \| `alert` \| null

`DELETE /api/runs/:id`

Удалить прогон с результатами.

Роль: редактор.

`POST /api/runs/:id/cases`

Добавить кейсы в открытый прогон.

Роль: тестировщик.

Тело (RunAddCases):

Поле	Тип	Обязательно
`caseIds`	integer[]	да

Результаты в прогоне

`GET /api/run-cases/:id`

Кейс в прогоне: зафиксированная версия, результат, шаги, вложения, баги.

Роль: наблюдатель.

`PATCH /api/run-cases/:id`

Поставить результат, статусы шагов, комментарий, время, исполнителя.

Роль: тестировщик.

Тело (ResultPatch):

Поле	Тип	Обязательно
`status`	`untested` \| `passed` \| `failed` \| `blocked` \| `skipped` \| `retest`
`comment`	string
`durationMs`	integer \| null
`stepResults`	`passed` \| `failed` \| `blocked` \| `skipped` \| null[]
`assigneeId`	integer \| null

`DELETE /api/run-cases/:id`

Убрать кейс из прогона.

Роль: тестировщик.

`POST /api/run-cases/:id/refresh`

Обновить кейс в прогоне до текущей версии кейса.

Роль: тестировщик.

`GET /api/run-cases/:id/history`

История результата: кто и когда что ставил.

Роль: наблюдатель.

Вехи и спринты

`GET /api/projects/:project/milestones`

Вехи и спринты проекта, свежие первыми, с числом прогонов.

Роль: наблюдатель.

`POST /api/projects/:project/milestones`

Создать веху или спринт с периодом дат.

Роль: администратор.

Тело (MilestoneCreate):

Поле	Тип	Обязательно
`kind`	`milestone` \| `sprint`
`name`	string	да
`description`	string
`startDate`	string	да
`endDate`	string	да

`GET /api/milestones/:id`

Веха или спринт.

Роль: наблюдатель.

`GET /api/milestones/:id/report`

Отчёт по вехе: каждый кейс по последнему результату, доля успешных, что падает, прогоны.

Роль: наблюдатель.

`PATCH /api/milestones/:id`

Изменить тип, название, описание или период.

Роль: администратор.

Тело (MilestonePatch):

Поле	Тип	Обязательно
`kind`	`milestone` \| `sprint`
`name`	string
`description`	string
`startDate`	string
`endDate`	string

`DELETE /api/milestones/:id`

Удалить веху: прогоны остаются без вехи.

Роль: администратор.

Автоматизация и CI

`POST /api/projects/:project/imports/junit`

Загрузить отчёт JUnit XML в новый или открытый прогон (тело — XML; параметры — в запросе).

Роль: тестировщик.

Параметры запроса (JUnitImportQuery):

Поле	Тип	Обязательно
`runId`	integer
`runName`	string
`build`	string
`environment`	string
`createMissing`	`0` \| `1` \| `true` \| `false`
`suite`	string
`close`	`0` \| `1` \| `true` \| `false`

`POST /api/projects/:project/export`

Кейсы проекта для tsmc pull.

Роль: наблюдатель.

Тело (ExportRequest):

Поле	Тип	Обязательно
`bases`	object[]

`POST /api/projects/:project/sync`

tsmc push: изменения из файлов одной атомарной операцией; dryRun — только показать.

Роль: редактор.

Тело (SyncRequest):

Поле	Тип	Обязательно
`suites`	object[]
`cases`	object[]	да
`dryRun`	boolean
`deleteMissing`	boolean

`GET /api/projects/:project/tokens`

API-токены проекта (без самих токенов).

Роль: администратор.

`POST /api/projects/:project/tokens`

Выпустить API-токен: показывается один раз.

Роль: администратор.

Тело (TokenCreate):

Поле	Тип	Обязательно
`name`	string	да

`DELETE /api/tokens/:id`

Отозвать API-токен.

Роль: администратор.

`POST /api/projects/:project/impact`

Какие кейсы прогнать по списку изменённых файлов — с причинами и весами.

Роль: наблюдатель.

Тело (ImpactRequest):

Поле	Тип	Обязательно
`files`	string[]	да
`includeDrafts`	boolean
`createRun`	object

Импорт и экспорт

`POST /api/projects/:project/imports/cases`

Импорт кейсов из TestRail, Qase или CSV; dryRun — предпросмотр.

Роль: редактор.

Тело (CaseImportRequest):

Поле	Тип	Обязательно
`format`	`csv` \| `testrail-xml` \| `qase-json`	да
`content`	string	да
`mapping`	object
`suiteSeparator`	string
`rootSuite`	string
`dryRun`	boolean

`GET /api/projects/:project/exports/cases`

Кейсы проекта или сьюта в CSV или Excel.

Роль: наблюдатель.

`GET /api/runs/:id/export`

Результаты прогона в CSV или Excel.

Роль: наблюдатель.

Параметры запроса (ExportFormat):

Поле	Тип	Обязательно
`format`	`csv` \| `xlsx`

Гигиена

`GET /api/projects/:project/hygiene`

Находки гигиены: дубли, давно не запускавшиеся, никогда не падающие, нестабильные.

Роль: наблюдатель.

Параметры запроса (HygieneQuery):

Поле	Тип	Обязательно
`threshold`	number
`staleDays`	integer
`minRuns`	integer
`window`	integer

`POST /api/projects/:project/hygiene/ignores`

Скрыть находку («всё в порядке»).

Роль: редактор.

Тело (HygieneIgnore):

Поле	Тип	Обязательно
`kind`	`duplicate` \| `stale` \| `never_failing` \| `flaky`	да
`caseIds`	integer[]	да

`DELETE /api/projects/:project/hygiene/ignores`

Вернуть скрытые находки.

Роль: редактор.

Вложения

`POST /api/projects/:project/attachments`

Загрузить файл к кейсу или к результату в прогоне (тело — сам файл).

Роль: тестировщик.

Параметры запроса (AttachmentUploadQuery):

Поле	Тип	Обязательно
`caseId`	integer
`runCaseId`	integer
`name`	string	да

`GET /api/cases/:id/attachments`

Вложения кейса.

Роль: наблюдатель.

`GET /api/attachments/:id`

Скачать вложение.

Роль: наблюдатель.

`DELETE /api/attachments/:id`

Удалить вложение.

Роль: тестировщик.

Отчёты

`GET /api/projects/:project/dashboard`

Дашборд за период: доля пройденных, провалы по сьютам, время, покрытие, баги, нестабильные тесты.

Роль: наблюдатель.

Параметры запроса (DashboardQuery):

Поле	Тип	Обязательно
`days`	integer

`GET /api/runs/:id/report`

Отчёт по прогону: сводка, провалы, сравнение с предыдущим прогоном.

Роль: наблюдатель.

`GET /api/runs/:id/shares`

Ссылки на отчёт без входа.

Роль: администратор.

`POST /api/runs/:id/shares`

Создать ссылку на отчёт без входа: показывается один раз.

Роль: администратор.

`DELETE /api/report-shares/:id`

Закрыть ссылку на отчёт.

Роль: администратор.

`GET /api/shared/reports/:token`

Отчёт по ссылке — без входа и без вложений.

Роль: без входа.

Трекер задач

`GET /api/projects/:project/integration`

Подключение трекера задач (без токена).

Роль: наблюдатель.

`PUT /api/projects/:project/integration`

Подключить GitHub Issues, Jira или YouTrack.

Роль: администратор.

Тело (IntegrationInput):

Поле	Тип	Обязательно
`kind`	`github` \| `jira` \| `youtrack`	да
`baseUrl`	string	да
`projectRef`	string	да
`username`	string
`issueType`	string
`token`	string

`DELETE /api/projects/:project/integration`

Отключить трекер задач.

Роль: администратор.

`POST /api/projects/:project/integration/check`

Проверить подключение к трекеру.

Роль: администратор.

`GET /api/cases/:id/issues`

Баги, связанные с кейсом.

Роль: наблюдатель.

`POST /api/cases/:id/issues`

Связать задачу с кейсом по ключу или ссылке.

Роль: редактор.

Тело (IssueLinkCreate):

Поле	Тип	Обязательно
`ref`	string	да

`POST /api/run-cases/:id/issues`

Связать задачу с результатом в прогоне.

Роль: тестировщик.

Тело (IssueLinkCreate):

Поле	Тип	Обязательно
`ref`	string	да

`DELETE /api/issue-links/:id`

Убрать связь с задачей.

Роль: тестировщик.

`GET /api/run-cases/:id/issue-draft`

Черновик бага по упавшему кейсу: заголовок и описание из шагов и комментария.

Роль: тестировщик.

`POST /api/run-cases/:id/issues/create`

Завести баг в трекере и связать с результатом.

Роль: тестировщик.

Тело (IssueCreate):

Поле	Тип	Обязательно
`title`	string	да
`body`	string	да
`attachFiles`	boolean

`POST /api/runs/:id/issues/refresh`

Обновить статусы багов прогона (не чаще раза в 10 минут).

Роль: наблюдатель.

`POST /api/issue-links/:id/refresh`

Обновить статус одной задачи.

Роль: наблюдатель.