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#метрики).
|