mirror of
https://github.com/SamyRai/tercul-backend.git
synced 2025-12-27 05:11:34 +00:00
0a27c84771
Key changes include:
- **Architectural Refactoring (CQRS/DTOs):** Refactored the `work` and `translation` application services to use Data Transfer Objects (DTOs) for query responses. This separates the domain layer from the API layer, improving maintainability and performance.
- **Implemented Core Business Logic:** Implemented the `AnalyzeWork` command, which was previously a stub. This command now performs linguistic analysis on works and translations by calling the analytics service.
- **Dependency Injection Improvements:**
- Refactored the configuration loading in `internal/platform/config/config.go` to use a local `viper` instance, removing the reliance on a global singleton.
- Injected the `analytics.Service` into the `work.Service` to support the `AnalyzeWork` command.
- **Comprehensive Documentation:**
- Created a new root `README.md` with a project overview, setup instructions, and architectural principles.
- Added detailed `README.md` files to key packages (`api`, `analytics`, `auth`, `work`, `db`) to document their purpose and usage.
- **Improved Test Coverage:**
- Added new unit tests for the refactored `work` and `translation` query handlers.
- Added a new test suite for the `translation` queries, which were previously untested.
- Added tests for the new `AnalyzeWork` command.
- Fixed numerous compilation errors in the test suites caused by the refactoring.
57 lines
2.7 KiB
Markdown
57 lines
2.7 KiB
Markdown
# Analytics Service
|
|
|
|
This package is responsible for collecting, processing, and retrieving all analytical data for the Tercul platform. It handles statistics for works, translations, and user engagement.
|
|
|
|
## Architecture Overview
|
|
|
|
The analytics service provides a central point for all statistical operations. It is designed to be called by other application services (e.g., after a user likes a work) to increment or decrement counters. It also provides methods for more complex analytical tasks, such as calculating reading time and sentiment scores.
|
|
|
|
### Key Components
|
|
|
|
- **`service.go`**: The main entry point for the analytics service. It implements the `Service` interface and contains the core business logic for all analytical operations.
|
|
- **`interfaces.go`**: Defines the `Service` and `Repository` interfaces, establishing a clear contract for the service's capabilities and its data persistence requirements.
|
|
- **Repository (external)**: The service relies on an `AnalyticsRepository`, implemented in the `internal/data/sql` package, to interact with the database.
|
|
|
|
## Features
|
|
|
|
- **Counter Management**: Provides methods to increment and decrement statistics like views, likes, comments, and bookmarks for works and translations.
|
|
- **Content Analysis**: Calculates and updates metrics such as:
|
|
- Reading time
|
|
- Complexity (via readability scores)
|
|
- Sentiment analysis
|
|
- **User Engagement Tracking**: Monitors user activities like works read, comments made, and likes given.
|
|
- **Trending System**: Calculates and stores trending works based on a scoring algorithm that considers views, likes, and comments.
|
|
|
|
## Usage
|
|
|
|
The `analytics.Service` is intended to be injected into other application services that need to record analytical events.
|
|
|
|
### Example: Incrementing Work Likes
|
|
|
|
```go
|
|
// In another application service (e.g., the 'like' service)
|
|
err := analyticsService.IncrementWorkLikes(ctx, workID)
|
|
```
|
|
|
|
### Example: Updating Work Analysis
|
|
|
|
```go
|
|
// In a command handler (e.g., work.AnalyzeWork)
|
|
err := analyticsService.UpdateWorkReadingTime(ctx, workID)
|
|
if err != nil {
|
|
// handle error
|
|
}
|
|
|
|
err = analyticsService.UpdateWorkComplexity(ctx, workID)
|
|
if err != nil {
|
|
// handle error
|
|
}
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- **`internal/domain`**: Uses the core domain entities (e.g., `WorkStats`, `TranslationStats`, `Trending`).
|
|
- **`internal/jobs/linguistics`**: Relies on the `linguistics` package for analysis data like readability scores and sentiment.
|
|
- **Database**: Persists all statistical data to the main application database via the `AnalyticsRepository`.
|
|
- **Logging**: Uses the centralized logger from `internal/platform/log`.
|
|
- **OpenTelemetry**: All service methods are instrumented for distributed tracing. |