Коммит 93d83bec создал по автору Radch-enko's avatar Radch-enko
Просмотр файлов

docs: add detailed README for backend modules 

- Added comprehensive READMEs for Authorization, Booking, User, Workspace, and Notifications modules.
- Updated backend README to include module descriptions, architecture, and technology stack details.
- Improved documentation consistency and updated configuration references for all modules.
владелец fe410b28
Скрыть пробелы
Построчно Рядом
backend/README.md
Просмотр файла @ 93d83bec
......@@ -25,11 +25,42 @@ backend/
```
## Technology Stack
- **Framework**: Spring Boot
- **Database**: PostgreSQL
- **API Documentation**: Swagger/OpenAPI
- **Authentication**: JWT-based authentication
- **Build Tool**: Gradle with Kotlin DSL
### Core Technologies
- **Language**: Kotlin 2.1.21
- **Framework**: Spring Boot 3.5.0
- **Build Tool**: Gradle 8.x with Kotlin DSL
- **Java Version**: JDK 17
### Database
- **RDBMS**: PostgreSQL 42.7.6
- **Migration Tool**: Flyway 11.8.2
- **Connection Pool**: HikariCP 6.3.0
- **ORM**: Spring Data JPA
### Security
- **Framework**: Spring Security
- **Authentication**: JWT (JSON Web Token) 0.11.5
- **Authorization**: Role-based access control
### API & Documentation
- **API Style**: RESTful
- **Documentation**: SpringDoc OpenAPI 2.8.8 (Swagger UI)
- **Validation**: Jakarta Bean Validation 3.0.2
### Integration
- **Google Calendar**: Google API Client 1.33.0
- **OAuth**: Google OAuth Client 1.33.3
### Testing
- **Unit Testing**: JUnit 5.12.2
- **Mocking**: MockK 1.14.2
- **Integration Testing**: Testcontainers 1.20.2
### Utilities
- **JSON Processing**: Jackson 2.19.0
- **Logging**: SLF4J 2.0.17 with Logback 1.5.18
- **Environment Variables**: Spring dotenv for .env file support
## API Endpoints
The backend exposes RESTful APIs for:
......
backend/feature/authorization/README.md 0 → 100644
Просмотр файла @ 93d83bec
# Authorization Module
## Overview
The Authorization module provides a flexible and extensible authentication and authorization system for the Effective Office backend. It implements a Chain of Responsibility pattern to support multiple authorization methods, including API key-based authentication and JWT token authentication.
## Features
- Chain of Responsibility pattern for flexible authorization flow
- API key-based authentication
- JWT token authentication
- Integration with Spring Security
- Customizable error handling
## Architecture
The module follows a layered architecture:
```
authorization/
├── apikey/ # API key authentication components
│ ├── config/ # API key configuration
│ ├── entity/ # API key entity classes
│ └── repository/ # API key data access
├── config/ # Security and authorization configuration
├── core/ # Core authorization components
│ └── exception/ # Core-specific exceptions
├── exception/ # Common exception classes
├── security/ # Spring Security integration
└── service/ # Authorization services
```
## Key Components
### Core Components
- **Authorizer**: Interface for authorization chain elements
- **BaseAuthorizer**: Abstract base class for authorizers
- **AuthorizationChain**: Manages the chain of authorizers
- **AuthorizationResult**: Represents the result of an authorization attempt
### API Key Authorization
- **ApiKeyAuthorizer**: Authorizer implementation for API key-based authentication
- **ApiKeyRepository**: Repository for API key storage and retrieval
### Security Integration
- **JwtAuthenticationFilter**: Spring Security filter for JWT authentication
- **SecurityConfig**: Spring Security configuration
### Services
- **AuthorizationService**: Service that coordinates the authorization process
### Configuration
The module provides default configurations that can be customized:
1. **Authorization Chain Configuration**:
```kotlin
@Configuration
class CustomAuthorizationConfig {
@Bean
fun customAuthorizer(): Authorizer {
return CustomAuthorizer()
}
}
```
2. **Security Configuration**:
The module integrates with Spring Security and can be customized through properties or by extending the provided configurations.
### Creating Custom Authorizers
To create a custom authorizer, extend the `BaseAuthorizer` class:
```kotlin
@Component
class CustomAuthorizer : BaseAuthorizer() {
override fun doAuthorize(request: HttpServletRequest): AuthorizationResult {
// Custom authorization logic
return AuthorizationResult(success = true)
}
}
```
## Error Handling
The module provides custom exceptions for different authorization scenarios:
- `AuthorizationException`: Base exception for all authorization errors
- `UnauthorizedException`: Thrown when authorization fails
- `InvalidApiKeyException`: Thrown when an API key is invalid
- `MissingTokenException`: Thrown when a required token is missing
## Integration with Spring Security
The module integrates with Spring Security through the `JwtAuthenticationFilter` and `SecurityConfig` classes. The filter intercepts incoming requests and uses the authorization chain to authenticate them.
## Examples
### Basic Authorization Flow
1. A request comes in with an Authorization header
2. The `JwtAuthenticationFilter` intercepts the request
3. The filter passes the request to the `AuthorizationService`
4. The service uses the `AuthorizationChain` to process the request
5. Each authorizer in the chain attempts to authorize the request
6. If any authorizer succeeds, the request is authorized
7. If all authorizers fail, the request is rejected
### API Key Authorization
API keys are stored in the database in a hashed format. When a request comes in with an API key:
1. The `ApiKeyAuthorizer` extracts the key from the Authorization header
2. The key is hashed using SHA-256
3. The hashed key is compared with keys in the database
4. If a match is found, the request is authorized
## Development
### Adding a New Authorization Method
To add a new authorization method:
1. Create a new authorizer by implementing the `Authorizer` interface or extending `BaseAuthorizer`
2. Register the authorizer as a Spring bean
3. The authorizer will automatically be added to the authorization chain
backend/feature/booking/README.md 0 → 100644
Просмотр файла @ 93d83bec
# Booking Module
## Overview
The Booking module provides functionality for managing resource bookings within the Effective Office system. It enables users to book office resources such as meeting rooms, desks, and equipment, and integrates with calendar systems for scheduling and notifications.
## Features
- Resource booking management
- Calendar integration (Google Calendar and dummy implementation for testing)
- Booking validation and conflict resolution
- Booking notifications
- RESTful API for booking operations
## Architecture
The module follows a layered architecture:
```
booking/
├── calendar/ # Calendar integration components
│ ├── dummy/ # Dummy calendar implementation for testing
│ └── google/ # Google Calendar integration
├── core/ # Core booking functionality
│ ├── config/ # Configuration classes
│ ├── controller/ # REST controllers
│ ├── domain/ # Domain models
│ ├── dto/ # Data Transfer Objects
│ ├── exception/ # Exception handling
│ └── service/ # Business logic services
```
## Key Components
### Core Components
- **BookingController**: REST API endpoints for booking operations
- **BookingService**: Business logic for booking management
- **BookingDomain**: Domain models representing bookings and related entities
- **BookingDTO**: Data Transfer Objects for API communication
### Calendar Integration
- **GoogleCalendarIntegration**: Integration with Google Calendar
- **DummyCalendarImplementation**: Mock implementation for testing and development
## Configuration
The module provides default configurations that can be customized:
1. **Booking Configuration**:
```kotlin
@Configuration
class BookingConfig {
// Configuration properties and beans
}
```
2. **Calendar Integration Configuration**:
The module supports configuration for different calendar providers.
## Error Handling
The module provides custom exceptions for different booking scenarios:
- `BookingException`: Base exception for all booking errors
- `BookingConflictException`: Thrown when a booking conflicts with an existing booking
- `ResourceUnavailableException`: Thrown when a resource is not available for booking
- `InvalidBookingException`: Thrown when booking parameters are invalid
## Integration
The Booking module integrates with:
- Calendar systems (Google Calendar)
- Notification module for booking alerts
- User module for user information
- Workspace module for resource availability
## Examples
### Basic Booking Flow
1. A user requests to book a resource for a specific time period
2. The system validates the booking request
3. If the resource is available, the booking is created
4. The booking is synchronized with the user's calendar
### Booking Conflict Resolution
When a booking conflicts with an existing booking:
1. The system identifies the conflict
2. The user is notified of the conflict
## Development
### Adding a New Calendar Integration
To add a new calendar integration:
1. Create a new implementation in the calendar package
2. Implement the required interfaces
3. Register the implementation in the configuration
\ Нет новой строки в конце файла
backend/feature/calendar-subscription/README.md
Просмотр файла @ 93d83bec
......@@ -11,7 +11,7 @@ This module provides functionality to subscribe to Google Calendar notifications
## Configuration
The module can be configured through the following properties in `application-local.yml` or environment variables:
The module can be configured through the following properties in `application.yml` , `application-local.yml` or environment variables:
| Property | Environment Variable | Description |
|----------|---------------------|-------------|
......
backend/feature/notifications/README.md
Просмотр файла @ 93d83bec
......@@ -40,15 +40,6 @@ class YourService(
fun someMethod() {
// Send an empty notification
notificationSender.sendEmptyMessage("your-topic")
// Send a notification about a workspace modification
notificationSender.sendContentMessage(HttpMethod.POST, workspaceDTO)
// Send a notification about a user modification
notificationSender.sendContentMessage(HttpMethod.PUT, userDto)
// Send a notification about a booking modification
notificationSender.sendContentMessage(HttpMethod.DELETE, bookingDto)
}
}
```
......
backend/feature/user/README.md 0 → 100644
Просмотр файла @ 93d83bec
# User Module
## Overview
The User Module provides functionality for managing users within the Effective Office system. It enables creating, retrieving, updating, and deleting user accounts, as well as managing user-related information.
## Features
- User account management (CRUD operations)
- User authentication integration
- Active user filtering
- RESTful API for user operations
## Architecture
The module follows a layered architecture:
```
user/
├── config/ # Configuration classes
├── controller/ # REST controllers
├── dto/ # Data Transfer Objects
├── repository/ # Data access layer
├── service/ # Business logic services
```
## Key Components
### Core Components
- **UserController**: REST API endpoints for user operations
- **UserService**: Business logic for user management
- **UserRepository**: Data access for user entities
### API Endpoints
The module exposes the following REST endpoints:
- `GET /v1/users`: Get all users
- `GET /v1/users/{id}`: Get user by ID
- `GET /v1/users/by-username/{username}`: Get user by username
- `GET /v1/users/active`: Get all active users
- `POST /v1/users`: Create a new user
- `PUT /v1/users/{id}`: Update an existing user
- `DELETE /v1/users/{id}`: Delete a user
## Integration
The User module integrates with:
- Authentication and authorization module
- Notification module for user-related notifications
- Workspace module for user workspace assignments
backend/feature/workspace/README.md 0 → 100644
Просмотр файла @ 93d83bec
# Workspace Module
## Overview
The Workspace Module provides functionality for managing workspaces within the Effective Office system. It enables retrieving information about different types of workspaces, their zones, utilities, and availability for booking.
## Features
- Workspace management and retrieval
- Workspace zone organization
- Workspace utilities tracking
- Integration with booking system for availability checking
- Filtering workspaces by tags
- RESTful API for workspace operations
## Architecture
The module follows a layered architecture:
```
workspace/
└── core/
├── config/ # Configuration classes
├── controller/ # REST controllers
├── dto/ # Data Transfer Objects
├── repository/ # Data access layer
├── service/ # Business logic services
```
## Key Components
### Core Components
- **WorkspaceController**: REST API endpoints for workspace operations
- **WorkspaceService**: Business logic for workspace management
- **WorkspaceRepository**: Data access for workspace entities
### API Endpoints
The module exposes the following REST endpoints:
- `GET /v1/workspaces/{id}`: Get workspace by ID
- `GET /v1/workspaces?workspace_tag={tag}`: Get workspaces by tag
- `GET /v1/workspaces?workspace_tag={tag}&with_bookings_from={timestamp}&with_bookings_until={timestamp}`: Get workspaces by tag with booking information
- `GET /v1/workspaces/zones`: Get all workspace zones
## Data Models
### Workspace
Represents a physical workspace in the office:
- ID
- Name
- Utilities (equipment and amenities)
- Zone (location within the office)
- Tag (type of workspace, e.g., "meeting", "desk")
### Workspace Zone
Represents a physical area or section within the office:
- ID
- Name
### Utility
Represents equipment or amenities available in a workspace:
- ID
- Name
- Icon URL
- Count
## Integration
The Workspace module integrates with:
- Booking module for checking workspace availability
- User module for workspace assignments
- Notification module for workspace-related notifications
## Examples
### Retrieving Available Workspaces
1. A client application requests workspaces with a specific tag (e.g., "meeting")
2. The client specifies a time range for availability checking
3. The system returns workspaces matching the tag, including their booking information
4. The client can determine which workspaces are available during the specified time period
\ Нет новой строки в конце файла
Поддерживает Markdown
0% или .
You are about to add 0 people to the discussion. Proceed with caution.
Сначала завершите редактирование этого сообщения!
Пожалуйста, зарегистрируйтесь или чтобы прокомментировать