98 lines
3.7 KiB
Markdown
98 lines
3.7 KiB
Markdown
# 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/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
|
||
↑
|
||
AppConfig (jira_url для ссылок на задачи)
|
||
```
|
||
|
||
- [Team](teams.md) → [Sprint](sprints.md): `GET /api/teams/{teamId}/sprints`
|
||
- [Sprint](sprints.md) → [SprintTask](tasks.md): `GET /api/sprints/{sprintId}/tasks`
|
||
- [AppConfig](config.md) используется вместе с [SprintTask](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/sprints/42
|
||
curl http://localhost/api/sprints/42/tasks
|
||
```
|
||
|
||
Подробности — в документации соответствующей сущности.
|
||
|
||
---
|
||
|
||
## Реализация
|
||
|
||
| Компонент | Путь |
|
||
|-----------|------|
|
||
| Точка входа | `public/index.php` |
|
||
| Бизнес-логика | `src/Features/Reports/ReportsApi.php` |
|
||
|
||
Перцентили в сводке по спринтам вычисляются в PostgreSQL функцией `percentile_cont`. Подробнее — в [документации по спринтам](sprints.md#метрики).
|