352 lines
14 KiB
Markdown
352 lines
14 KiB
Markdown
# Руководство по API для фронтенда
|
|
|
|
## Обзор
|
|
|
|
Это руководство описывает API сервиса `Parser`, который собирает и предоставляет новостные данные. API спроектировано для эффективной работы с клиентскими приложениями и поддерживает пагинацию, сортировку и фильтрацию.
|
|
|
|
## Реализация в UI: что мы должны показать пользователю
|
|
|
|
Ниже описаны ключевые элементы интерфейса, которые необходимо создать, используя эндпоинты из этого руководства.
|
|
|
|
### 1. Основной экран: Лента новостей 📰
|
|
|
|
Это главный экран приложения, где пользователь видит все собранные новости.
|
|
|
|
- **Функционал:**
|
|
- **Отображение новостей:** Используйте `GET /api/parser/items` для загрузки и отображения списка новостей. Каждая новость в списке должна показывать заголовок, источник, дату публикации и краткий текст (`rawText` или `analytics.summary`, когда он будет готов).
|
|
- **Пагинация:** Так как новостей может быть много, реализуйте "бесконечную прокрутку" (подгрузка новых статей при скролле вниз) или классические кнопки пагинации («1, 2, 3...»). API полностью это поддерживает.
|
|
- **Сортировка:** По умолчанию новости должны быть отсортированы по дате публикации (`sort=publishedAt,desc`), чтобы пользователь видел сначала самое свежее.
|
|
|
|
### 2. Панель фильтров 🔎
|
|
|
|
Сбоку или сверху от ленты новостей должна быть панель, позволяющая пользователю отфильтровать данные.
|
|
|
|
- **Функционал:**
|
|
- **Фильтр по источнику:** Добавьте выпадающий список или чекбоксы с названиями источников (например, "Kursiv", "Kapital.kz"). При выборе источника отправляйте его в параметре `sourceName` в запросе к `GET /api/parser/items`.
|
|
- **Фильтр по дате:** Добавьте два поля для выбора даты ("от" и "до") с календарем. Это позволит пользователю смотреть новости за конкретный период. Используйте параметры `startDate` и `endDate`.
|
|
|
|
### 3. Дашборд/Статистика 📊
|
|
|
|
Нужно создать отдельную страницу "Дашборд" или "Статистика", где будет отображаться общая информация о системе.
|
|
|
|
- **Функционал:**
|
|
- **Общее количество новостей:** Используйте `GET /api/parser/stats` для получения и отображения общего числа статей в базе (`totalItems`).
|
|
- **Разбивка по источникам:** На основе поля `sourceStatistics` постройте круговую диаграмму (pie chart), которая наглядно покажет, сколько новостей пришло с каждого источника.
|
|
- **Статус системы:** Используйте `GET /api/parser/health`, чтобы показать пользователю (скорее, администратору) текущий статус сервиса и планировщика. Можно добавить зелёный/красный индикатор.
|
|
|
|
### 4. Админ-панель: Управление парсером (опционально, для администраторов) ⚙️
|
|
|
|
Эта часть интерфейса может быть скрыта от обычных пользователей и доступна только администраторам.
|
|
|
|
- **Функционал:**
|
|
- **Ручной запуск парсинга:** Добавьте кнопки "Запустить парсинг Kursiv", "Запустить парсинг Kapital" и "Запустить все". Эти кнопки будут отправлять запросы на эндпоинты `POST /api/parser/parse/{source}` и `POST /api/parser/parse/all`.
|
|
- **Мониторинг состояния БД:** Используйте `GET /api/parser/health/mongodb` для проверки статуса подключения к базе данных и выводите сообщение об успехе или ошибке.
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
### 1. Получение записей с фильтрацией и пагинацией
|
|
|
|
```http
|
|
GET /api/parser/items?page=0&size=10&sort=publishedAt,desc&sourceName=Kursiv&startDate=2025-01-01&endDate=2025-01-31
|
|
```
|
|
|
|
**Параметры:**
|
|
|
|
- `page` (optional, default: 0) - номер страницы
|
|
- `size` (optional, default: 20) - размер страницы
|
|
- `sort` (optional, default: "publishedAt,desc") - сортировка
|
|
- `sourceName` (optional) - фильтр по источнику
|
|
- `startDate` (optional) - начальная дата (ISO format)
|
|
- `endDate` (optional) - конечная дата (ISO format)
|
|
|
|
**Ответ:**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Записи получены успешно",
|
|
"data": {
|
|
"content": [
|
|
{
|
|
"id": "...",
|
|
"sourceName": "Kursiv (Бизнес/экономика)",
|
|
"title": "Заголовок новости",
|
|
"url": "https://kursiv.media/...",
|
|
"publishedAt": "2025-01-14T10:30:00",
|
|
"addedAt": "2025-01-14T12:00:00",
|
|
"rawText": "Текст статьи...",
|
|
"hash": "...",
|
|
"category": "Бизнес",
|
|
"analytics": {
|
|
"summary": null,
|
|
"sentiment": null,
|
|
"tags": [],
|
|
"entities": {}
|
|
}
|
|
}
|
|
],
|
|
"pageable": {
|
|
"sort": {
|
|
"sorted": true,
|
|
"unsorted": false,
|
|
"empty": false
|
|
},
|
|
"pageNumber": 0,
|
|
"pageSize": 10,
|
|
"offset": 0,
|
|
"paged": true,
|
|
"unpaged": false
|
|
},
|
|
"totalElements": 25,
|
|
"totalPages": 3,
|
|
"last": false,
|
|
"first": true,
|
|
"numberOfElements": 10,
|
|
"size": 10,
|
|
"number": 0,
|
|
"sort": {
|
|
"sorted": true,
|
|
"unsorted": false,
|
|
"empty": false
|
|
},
|
|
"empty": false
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Статистика системы
|
|
|
|
```http
|
|
GET /api/parser/stats
|
|
```
|
|
|
|
**Ответ:**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Статистика получена успешно",
|
|
"data": {
|
|
"totalItems": 150,
|
|
"sourceStatistics": {
|
|
"Kursiv (Бизнес/экономика)": 75,
|
|
"Kapital.kz (Бизнес)": 75
|
|
},
|
|
"lastUpdate": "2025-01-14T12:00:00"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Запуск парсинга
|
|
|
|
#### Парсинг всех источников
|
|
|
|
```http
|
|
POST /api/parser/parse/all
|
|
```
|
|
|
|
**Ответ:**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Парсинг всех источников завершен успешно",
|
|
"data": [
|
|
{
|
|
"source": "Kursiv",
|
|
"processedItems": 15,
|
|
"totalItemsInDb": 90,
|
|
"status": "completed"
|
|
},
|
|
{
|
|
"source": "Kapital",
|
|
"processedItems": 12,
|
|
"totalItemsInDb": 90,
|
|
"status": "completed"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Парсинг конкретного источника
|
|
|
|
```http
|
|
POST /api/parser/parse/kursiv
|
|
POST /api/parser/parse/kapital
|
|
```
|
|
|
|
### 4. Проверка состояния
|
|
|
|
#### Общее состояние
|
|
|
|
```http
|
|
GET /api/parser/health
|
|
```
|
|
|
|
**Ответ:**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Сервис работает",
|
|
"data": {
|
|
"status": "UP",
|
|
"service": "RSS Parser System",
|
|
"timestamp": 1705123456789,
|
|
"scheduler": "Enabled - runs every 30 minutes"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Состояние MongoDB
|
|
|
|
```http
|
|
GET /api/parser/health/mongodb
|
|
```
|
|
|
|
**Ответ при успехе:**
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "MongoDB подключение успешно",
|
|
"data": {
|
|
"status": "UP",
|
|
"message": "MongoDB подключение успешно",
|
|
"timestamp": 1705123456789
|
|
}
|
|
}
|
|
```
|
|
|
|
**Ответ при ошибке:**
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Ошибка подключения к MongoDB",
|
|
"data": {
|
|
"status": "DOWN",
|
|
"message": "Ошибка подключения к MongoDB: Command failed with error 13 (Unauthorized)",
|
|
"timestamp": 1705123456789,
|
|
"suggestion": "Проверьте учетные данные в application.properties"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Примеры использования
|
|
|
|
### 1. Получение последних новостей с пагинацией
|
|
|
|
```javascript
|
|
// Получить первую страницу с 10 записями, отсортированными по дате публикации
|
|
fetch('/api/parser/items?page=0&size=10&sort=publishedAt,desc')
|
|
.then((response) => response.json())
|
|
.then((data) => {
|
|
if (data.success) {
|
|
const items = data.data.content;
|
|
const totalPages = data.data.totalPages;
|
|
// Обработка данных
|
|
}
|
|
});
|
|
```
|
|
|
|
### 2. Фильтрация по источнику
|
|
|
|
```javascript
|
|
// Получить только новости от Kursiv
|
|
fetch('/api/parser/items?sourceName=Kursiv (Бизнес/экономика)&page=0&size=20')
|
|
.then((response) => response.json())
|
|
.then((data) => {
|
|
if (data.success) {
|
|
const kursivNews = data.data.content;
|
|
// Обработка данных
|
|
}
|
|
});
|
|
```
|
|
|
|
### 3. Фильтрация по датам
|
|
|
|
```javascript
|
|
// Получить новости за последнюю неделю
|
|
const endDate = new Date().toISOString();
|
|
const startDate = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
|
|
|
|
fetch(`/api/parser/items?startDate=${startDate}&endDate=${endDate}`)
|
|
.then((response) => response.json())
|
|
.then((data) => {
|
|
if (data.success) {
|
|
const recentNews = data.data.content;
|
|
// Обработка данных
|
|
}
|
|
});
|
|
```
|
|
|
|
### 4. Комплексная фильтрация
|
|
|
|
```javascript
|
|
// Получить новости Kapital за последний месяц, отсортированные по дате
|
|
const endDate = new Date().toISOString();
|
|
const startDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
|
|
|
|
fetch(`/api/parser/items?sourceName=Kapital.kz (Бизнес)&startDate=${startDate}&endDate=${endDate}&sort=publishedAt,desc&page=0&size=50`)
|
|
.then((response) => response.json())
|
|
.then((data) => {
|
|
if (data.success) {
|
|
const kapitalNews = data.data.content;
|
|
const totalCount = data.data.totalElements;
|
|
// Обработка данных
|
|
}
|
|
});
|
|
```
|
|
|
|
### 5. Получение статистики
|
|
|
|
```javascript
|
|
fetch('/api/parser/stats')
|
|
.then((response) => response.json())
|
|
.then((data) => {
|
|
if (data.success) {
|
|
const stats = data.data;
|
|
console.log(`Всего новостей: ${stats.totalItems}`);
|
|
console.log('По источникам:', stats.sourceStatistics);
|
|
}
|
|
});
|
|
```
|
|
|
|
## Поддерживаемые форматы дат
|
|
|
|
API поддерживает следующие форматы дат:
|
|
|
|
- `yyyy-MM-dd` (например: 2025-01-14)
|
|
- `yyyy-MM-dd'T'HH:mm:ss` (например: 2025-01-14T10:30:00)
|
|
- `yyyy-MM-dd'T'HH:mm:ss.SSS` (например: 2025-01-14T10:30:00.000)
|
|
- `yyyy-MM-dd HH:mm:ss` (например: 2025-01-14 10:30:00)
|
|
|
|
## Обработка ошибок
|
|
|
|
Все ответы API следуют единому формату:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Описание ошибки",
|
|
"error": "Детальная информация об ошибке"
|
|
}
|
|
```
|
|
|
|
HTTP статус коды:
|
|
|
|
- `200` - Успешный запрос
|
|
- `500` - Внутренняя ошибка сервера
|
|
- `503` - Сервис недоступен (например, MongoDB)
|
|
|
|
## Рекомендации для фронтенда
|
|
|
|
1. **Кэширование**: Используйте кэширование для статистики и часто запрашиваемых данных
|
|
2. **Пагинация**: Реализуйте бесконечную прокрутку или традиционную пагинацию
|
|
3. **Фильтры**: Предоставьте пользователю удобные фильтры по источнику и датам
|
|
4. **Обновление**: Используйте WebSocket или polling для обновления данных в реальном времени
|
|
5. **Обработка ошибок**: Всегда проверяйте поле `success` в ответе
|