reports/docs/api/README.md

# API отчётов по спринтам

REST API для веб-интерфейса сводки по спринтам. Все ответы — JSON в кодировке UTF-8.

## Базовый URL

| Окружение | URL |
|-----------|-----|
| Docker (nginx) | `http://localhost/api` |
| Локальная разработка | `http://localhost:8080/api` |

Точка входа: `public/index.php`.

## Общие сведения

- Поддерживаются только **GET**-запросы (чтение данных).
- Заголовок ответа: `Content-Type: application/json; charset=utf-8`.
- Авторизация не требуется.
- Даты и время возвращаются в формате PostgreSQL `TIMESTAMPTZ` (ISO 8601 с часовым поясом).
- Поля с отсутствующими данными имеют значение `null`.

## Коды ответов

| Код | Описание |
|-----|----------|
| `200` | Успешный ответ |
| `204` | `OPTIONS` (preflight) |
| `404` | Маршрут или ресурс не найден |
| `500` | Ошибка сервера |

### Формат ошибки

```json
{
  "error": "Описание ошибки"
}
```

---

## Документация по сущностям

| Сущность | Описание |
|----------|----------|
| [Команды](teams.md) | Список команд |
| [Спринты](sprints.md) | Сводные метрики по спринтам |
| [Задачи](tasks.md) | Задачи спринта и команды (с пагинацией) |
| [Конфигурация](config.md) | Публичные настройки для фронтенда |

---

## Сводка эндпоинтов

| Метод | Путь | Сущность | Описание |
|-------|------|----------|----------|
| `GET` | [`/api/teams`](teams.md#get-apiteams) | [Team](teams.md) | Список команд |
| `GET` | [`/api/teams/{teamId}/sprints`](sprints.md#get-apiteamsteamidsprints) | [Sprint](sprints.md) | Спринты команды со сводкой |
| `GET` | [`/api/teams/{teamId}/tasks`](tasks.md#get-apiteamsteamidtasks) | [PaginatedTeamTasks](tasks.md) | Все задачи команды (пагинация) |
| `GET` | [`/api/sprints/{sprintId}`](sprints.md#get-apisprintssprintid) | [Sprint](sprints.md) | Один спринт со сводкой |
| `GET` | [`/api/sprints/{sprintId}/tasks`](tasks.md#get-apisprintssprintidtasks) | [SprintTask](tasks.md) | Задачи спринта |
| `GET` | [`/api/config`](config.md#get-apiconfig) | [AppConfig](config.md) | Публичная конфигурация |

### Связи между сущностями

```
Team ──< Sprint ──< SprintTask
  │                    ↑
  └──── TeamTask ──────┘ (через sprint_id, sprint_name)
AppConfig (jira_url для ссылок на задачи)
```

- [Team](teams.md) → [Sprint](sprints.md): `GET /api/teams/{teamId}/sprints`
- [Team](teams.md) → [TeamTask](tasks.md): `GET /api/teams/{teamId}/tasks`
- [Sprint](sprints.md) → [SprintTask](tasks.md): `GET /api/sprints/{sprintId}/tasks`
- [AppConfig](config.md) используется вместе с [SprintTask](tasks.md) и [TeamTask](tasks.md) для ссылок `{jira_url}/browse/{task_key}`

---

## Быстрые примеры

```bash
curl http://localhost/api/teams
curl http://localhost/api/config
curl http://localhost/api/teams/1/sprints
curl http://localhost/api/teams/1/tasks
curl http://localhost/api/teams/1/tasks?page=2&per_page=50
curl http://localhost/api/sprints/42
curl http://localhost/api/sprints/42/tasks
```

Подробности — в документации соответствующей сущности.

---

## Реализация

| Компонент | Путь |
|-----------|------|
| Точка входа | `public/index.php` |
| Бизнес-логика | `src/Features/Reports/ReportsApi.php` |

Перцентили в сводке по спринтам вычисляются в PostgreSQL функцией `percentile_cont`. Подробнее — в [документации по спринтам](sprints.md#метрики).