297 lines
10 KiB
Markdown
297 lines
10 KiB
Markdown
# Информационная система управления музыкальными группами
|
||
|
||
## Требования к системе
|
||
|
||
### Функциональные требования
|
||
|
||
1. **Управление объектами MusicBand**
|
||
- Создание нового объекта
|
||
- Получение информации об объекте по ID
|
||
- Обновление объекта (модификация атрибутов)
|
||
- Удаление объекта
|
||
- Каскадное удаление связанных объектов
|
||
|
||
2. **Отображение данных**
|
||
- Список объектов в виде таблицы с пагинацией
|
||
- Фильтрация по имени (неполное совпадение)
|
||
- Сортировка по любому полю
|
||
- Отображение связанных объектов при просмотре
|
||
|
||
3. **Специальные операции**
|
||
- Расчет среднего значения albumsCount
|
||
- Поиск группы с максимальным именем
|
||
- Группировка по numberOfParticipants
|
||
- Добавление сингла к группе
|
||
- Удаление участника из группы
|
||
|
||
4. **Real-time обновления**
|
||
- Автоматическая синхронизация при добавлении/изменении/удалении
|
||
- WebSocket для broadcast обновлений всем клиентам
|
||
- Переподключение при разрыве соединения
|
||
|
||
5. **Валидация**
|
||
- Все ограничения модели данных (NotNull, Positive, NotBlank)
|
||
- Информативные сообщения об ошибках
|
||
- Валидация на уровне UI, бизнес-логики и базы данных
|
||
|
||
### Технологические требования
|
||
|
||
1. **Backend**
|
||
- Jakarta EE 10
|
||
- CDI (Contexts and Dependency Injection)
|
||
- EclipseLink (JPA provider)
|
||
- JAX-RS (REST API)
|
||
- WebSocket
|
||
- PostgreSQL
|
||
|
||
2. **Frontend**
|
||
- Vanilla JavaScript (ES6+)
|
||
- HTML5
|
||
- CSS3
|
||
- WebSocket client
|
||
|
||
## Архитектура системы
|
||
|
||
### Структура проекта
|
||
|
||
```
|
||
ru.akarpov.is1/
|
||
├── entity/ # Сущности JPA
|
||
│ ├── MusicBand.java
|
||
│ ├── Coordinates.java
|
||
│ ├── Album.java
|
||
│ ├── Person.java
|
||
│ ├── Location.java
|
||
│ └── enums/
|
||
├── repository/ # Слой доступа к данным
|
||
│ ├── GenericRepository.java
|
||
│ ├── MusicBandRepository.java
|
||
│ └── MusicBandRepositoryImpl.java
|
||
├── service/ # Бизнес-логика
|
||
│ └── MusicBandService.java
|
||
├── rest/ # REST контроллеры
|
||
│ ├── MusicBandResource.java
|
||
│ └── DatabaseTestResource.java
|
||
├── websocket/ # WebSocket endpoints
|
||
│ └── WebSocketResource.java
|
||
└── config/ # Конфигурация
|
||
├── JaxRsConfig.java
|
||
├── CorsFilter.java
|
||
├── CDIProducer.java
|
||
└── JacksonConfig.java
|
||
```
|
||
|
||
### Слои приложения
|
||
|
||
#### 1. Entity Layer (Сущности)
|
||
- JPA-аннотированные классы
|
||
- Валидация с Jakarta Validation
|
||
- Связи между сущностями (OneToOne, CascadeType.ALL)
|
||
- Автогенерация ID через sequences
|
||
|
||
#### 2. Repository Layer (Репозитории)
|
||
- Generic интерфейс для базовых CRUD операций
|
||
- Специализированные методы для MusicBand
|
||
- Named queries для сложных запросов
|
||
- Транзакционность через @Transactional
|
||
|
||
#### 3. Service Layer (Сервисы)
|
||
- Бизнес-логика и валидация
|
||
- Координация между репозиториями
|
||
- Broadcast WebSocket событий
|
||
- Обработка исключений
|
||
|
||
#### 4. REST Layer (REST API)
|
||
- JAX-RS endpoints
|
||
- JSON сериализация/десериализация
|
||
- Обработка HTTP запросов
|
||
- CORS для cross-origin запросов
|
||
|
||
#### 5. WebSocket Layer
|
||
- Real-time коммуникация с клиентами
|
||
- Ping/pong для keep-alive
|
||
- Управление сессиями
|
||
- Broadcast обновлений
|
||
|
||
## Реализация
|
||
|
||
### Основные компоненты
|
||
|
||
#### MusicBandRepositoryImpl
|
||
|
||
Использует:
|
||
- EntityManager для операций с БД
|
||
- Named queries для оптимизации
|
||
- JPQL для динамических запросов
|
||
- Pagination для больших результатов
|
||
|
||
Ключевые методы:
|
||
- `save()` - создание/обновление с merge
|
||
- `findAllSorted()` - с динамической сортировкой
|
||
- `findByNameContainingSorted()` - фильтрация + сортировка
|
||
- `addSingle()` - атомарное увеличение счетчика
|
||
- `removeParticipant()` - атомарное уменьшение с проверкой
|
||
|
||
#### MusicBandService
|
||
|
||
Координирует:
|
||
- Валидацию через Bean Validation
|
||
- Операции репозитория
|
||
- WebSocket broadcast
|
||
- Обработку ошибок
|
||
|
||
Особенности:
|
||
- `@Transactional` для автоматических транзакций
|
||
- `@Inject` для dependency injection
|
||
- Custom ValidationException
|
||
- Валидация полей сортировки
|
||
|
||
#### WebSocketResource
|
||
|
||
Управляет:
|
||
- Множественными WebSocket соединениями
|
||
- Scheduled executor для ping/pong
|
||
- Автоматическим удалением мертвых соединений
|
||
- JSON serialization через Jackson
|
||
|
||
Механизм работы:
|
||
- Периодический ping каждые 30 секунд
|
||
- Автоматическая очистка закрытых сессий
|
||
- Exponential backoff для переподключений
|
||
- Thread-safe операции с Set<Session>
|
||
|
||
#### Frontend (app.js)
|
||
|
||
Класс MusicBandApp включает:
|
||
- Управление состоянием (пагинация, фильтры, сортировка)
|
||
- REST API клиент с обработкой ошибок
|
||
- WebSocket клиент с переподключением
|
||
- Динамическое обновление UI
|
||
- Валидация форм
|
||
- Toast уведомления
|
||
|
||
Ключевые возможности:
|
||
- Debounced фильтрация
|
||
- Оптимистичное обновление UI
|
||
- Корректная конвертация datetime
|
||
- Highlighting полей с ошибками
|
||
- Автоматическое переподключение WebSocket
|
||
|
||
### База данных
|
||
|
||
#### Схема
|
||
- PostgreSQL с sequences для ID
|
||
- Cascade delete для связанных объектов
|
||
- Ограничения NOT NULL, CHECK
|
||
- Индексы для оптимизации запросов
|
||
|
||
#### Persistence Unit
|
||
- JTA data source
|
||
- EclipseLink provider
|
||
- Connection pooling
|
||
- SQL logging для отладки
|
||
|
||
### Конфигурация
|
||
|
||
#### CDI Beans
|
||
- @ApplicationScoped для синглтонов
|
||
- @Produces для factory methods
|
||
- Validator для Bean Validation
|
||
- ObjectMapper для JSON
|
||
|
||
#### CORS Filter
|
||
- Разрешение всех origins (*)
|
||
- Поддержка preflight OPTIONS
|
||
- Необходимые headers
|
||
|
||
## Развертывание
|
||
|
||
### Требования
|
||
- Java 17+
|
||
- WildFly 26+ / Payara 6+
|
||
- PostgreSQL 12+
|
||
|
||
### Конфигурация DataSource
|
||
|
||
В standalone.xml:
|
||
|
||
```xml
|
||
<datasource jndi-name="java:jboss/datasources/PostgreSQLDS">
|
||
<connection-url>jdbc:postgresql://pg:5432/studs</connection-url>
|
||
<driver>postgresql</driver>
|
||
<security>
|
||
<user-name>your_username</user-name>
|
||
<password>your_password</password>
|
||
</security>
|
||
</datasource>
|
||
```
|
||
|
||
### Сборка
|
||
|
||
```bash
|
||
mvn clean package
|
||
```
|
||
|
||
### Деплой
|
||
|
||
```bash
|
||
cp target/is1.war $WILDFLY_HOME/standalone/deployments/
|
||
```
|
||
|
||
## API Endpoints
|
||
|
||
### REST API
|
||
|
||
- `GET /api/music-bands` - список групп (с пагинацией, фильтрацией, сортировкой)
|
||
- `GET /api/music-bands/{id}` - получить группу по ID
|
||
- `POST /api/music-bands` - создать группу
|
||
- `PUT /api/music-bands/{id}` - обновить группу
|
||
- `DELETE /api/music-bands/{id}` - удалить группу
|
||
- `GET /api/music-bands/statistics/average-albums` - средний albumsCount
|
||
- `GET /api/music-bands/statistics/max-name` - группа с макс. именем
|
||
- `GET /api/music-bands/statistics/group-by-participants` - группировка
|
||
- `POST /api/music-bands/{id}/add-single` - добавить сингл
|
||
- `POST /api/music-bands/{id}/remove-participant` - удалить участника
|
||
|
||
### WebSocket
|
||
|
||
- `ws://host/is1/websocket/bands` - real-time обновления
|
||
|
||
Формат сообщения:
|
||
```json
|
||
{
|
||
"type": "band_update",
|
||
"action": "create|update|delete",
|
||
"data": {...},
|
||
"timestamp": 1234567890
|
||
}
|
||
```
|
||
|
||
## Известные особенности
|
||
|
||
1. **WebSocket переподключение** - автоматическое с exponential backoff
|
||
2. **Валидация дат** - establishmentDate должен быть после 1900 и не в будущем
|
||
3. **Cascade delete** - при удалении группы удаляются связанные объекты
|
||
4. **Atomic operations** - addSingle и removeParticipant выполняются атомарно
|
||
5. **Real-time sync** - все клиенты получают обновления через WebSocket
|
||
|
||
## Решение проблем
|
||
|
||
### WebSocket не подключается
|
||
- Проверьте, что сервер поддерживает WebSocket
|
||
- Проверьте CORS настройки
|
||
- Убедитесь, что путь правильный
|
||
|
||
### Ошибки валидации
|
||
- Все обязательные поля должны быть заполнены
|
||
- Числовые поля должны быть положительными
|
||
- Даты в корректном формате
|
||
|
||
### Проблемы с базой данных
|
||
- Проверьте connection string
|
||
- Убедитесь, что PostgreSQL запущен
|
||
- Проверьте credentials
|
||
|
||
## Автор
|
||
|
||
Разработано для курса "Информационные системы", университет ИТМО |