reports/docs/api/sprints.md

# Спринты (Sprint)

← [Сводка API](README.md)

Сущность **Sprint** — закрытый спринт команды со сводными метриками по задачам.

## Связанные сущности

- [Команды](teams.md) — родительская сущность (`team_id`, `team_name`)
- [Задачи](tasks.md) — детализация по задачам спринта: `GET /api/sprints/{sprintId}/tasks`

---

## Модель данных

### Sprint

```json
{
  "id": 42,
  "team_id": 1,
  "team_name": "ts",
  "jira_sprint_id": 2801,
  "sprint_name": "TS 2026_1 до 26.01",
  "sprint_activate_datetime": "2026-01-13 16:35:37.082+04",
  "sprint_complete_datetime": "2026-01-27 16:07:34.138+04",
  "sprint_completion_percentage": 96.08,
  "lead_time_max": 175,
  "lead_time_min": 1,
  "lead_time_p95": 23.5,
  "lead_time_p80": 15.0,
  "lead_time_p50": 6.0,
  "test_count_max": 4,
  "test_count_min": 0,
  "test_count_p95": 2.0,
  "test_count_p80": 1.0,
  "test_count_p50": 0.0,
  "efficiency_min": 1.46,
  "efficiency_max": 84.17,
  "efficiency_p50": 18.75,
  "recast_max": 109.69,
  "recast_min": -70.83,
  "recast_p95": 88.13,
  "recast_p80": 33.33,
  "recast_p50": -7.5
}
```

### Основные поля

| Поле | Тип | Описание |
|------|-----|----------|
| `id` | `integer` | Идентификатор спринта в БД |
| `team_id` | `integer` | Идентификатор [команды](teams.md) |
| `team_name` | `string` | Название команды |
| `jira_sprint_id` | `integer` | Идентификатор спринта в Jira |
| `sprint_name` | `string` | Название спринта |
| `sprint_activate_datetime` | `string` | Дата и время начала спринта |
| `sprint_complete_datetime` | `string` | Дата и время завершения спринта |
| `sprint_completion_percentage` | `number \| null` | Процент закрытия спринта (0–100) |

## Метрики

### Lead Time (рабочие дни)

Агрегаты по полю `tasks.lead_time_days` для всех задач спринта с заполненным Lead Time.

| Поле | Тип | Описание |
|------|-----|----------|
| `lead_time_max` | `integer \| null` | Максимум |
| `lead_time_min` | `integer \| null` | Минимум |
| `lead_time_p95` | `number \| null` | 95-й перцентиль |
| `lead_time_p80` | `number \| null` | 80-й перцентиль |
| `lead_time_p50` | `number \| null` | 50-й перцентиль (медиана) |

### Количество заходов на тестирование

Агрегаты по полю `tasks.test_count` **только для задач**, где исполнитель имеет роль `backend` или `frontend`.

| Поле | Тип | Описание |
|------|-----|----------|
| `test_count_max` | `integer \| null` | Максимум |
| `test_count_min` | `integer \| null` | Минимум |
| `test_count_p95` | `number \| null` | 95-й перцентиль |
| `test_count_p80` | `number \| null` | 80-й перцентиль |
| `test_count_p50` | `number \| null` | 50-й перцентиль |

### Flow Efficiency (КПД, %)

Агрегаты по полю `tasks.efficiency_percentage` для всех задач спринта с заполненным значением.

| Поле | Тип | Описание |
|------|-----|----------|
| `efficiency_min` | `number \| null` | Минимум |
| `efficiency_max` | `number \| null` | Максимум |
| `efficiency_p50` | `number \| null` | 50-й перцентиль |

### Переработка (%, `recast_percentage`)

Агрегаты по полю `tasks.recast_percentage`. Отрицательные значения означают выполнение быстрее оценки.

| Поле | Тип | Описание |
|------|-----|----------|
| `recast_max` | `number \| null` | Максимум |
| `recast_min` | `number \| null` | Минимум |
| `recast_p95` | `number \| null` | 95-й перцентиль |
| `recast_p80` | `number \| null` | 80-й перцентиль |
| `recast_p50` | `number \| null` | 50-й перцентиль |

Перцентили вычисляются в PostgreSQL функцией `percentile_cont`.

---

## Эндпоинты

### `GET /api/teams/{teamId}/sprints`

Возвращает спринты [команды](teams.md) со сводными метриками.

**Параметры пути**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `teamId` | `integer` | Идентификатор команды |

**Ответ:** `200` — массив `Sprint[]`, отсортированный по дате начала (от старых к новым)

**Пример**

```bash
curl http://localhost/api/teams/1/sprints
```

---

### `GET /api/sprints/{sprintId}`

Возвращает один спринт со сводными метриками.

**Параметры пути**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `sprintId` | `integer` | Идентификатор спринта |

**Ответ:** `200` — объект `Sprint`

**Ошибки:** `404` — спринт не найден

**Пример**

```bash
curl http://localhost/api/sprints/42
```

См. также: [задачи этого спринта](tasks.md#get-apisprintssprintidtasks)