Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: Update documentation for advanced rating system

Browse Source 
- Update feature list to reflect half-star precision
- Document backend 10-point scale conversion
- Update API documentation for rating endpoints
- Explain rating scale and half-star precision
- Update README with detailed rating system explanation
This commit is contained in:
john-okeefe
2026-01-26 13:49:13 -05:00
parent baa46a8a63
commit e8cafc634c
1 changed files with 14 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+14 -8
View File
@@ -11,7 +11,7 @@ A self-hosted ebook management system built with Go, PostgreSQL, HTMX, and Tailw
- **🌙 Multiple Themes**: 11 beautiful themes including Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, and Catppuccin variants (Mocha, Macchiato, Frappé, Latte) with user preferences saved to database - **🌙 Multiple Themes**: 11 beautiful themes including Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, and Catppuccin variants (Mocha, Macchiato, Frappé, Latte) with user preferences saved to database
- **🎨 Theme Persistence**: User theme choices sync between browser and server - **🎨 Theme Persistence**: User theme choices sync between browser and server
- **📖 Reading Progress**: User-specific reading progress tracking - **📖 Reading Progress**: User-specific reading progress tracking
- **⭐ Interactive Rating System**: 5-star rating system with interactive dashboard controls and zero-rating fallback - **⭐ Advanced Rating System**: 5-star rating with half-star precision, dialog-based input, and zero-rating fallback
- **📁 Multiple Folder Support**: Configure multiple ebook folders per user for comprehensive library management - **📁 Multiple Folder Support**: Configure multiple ebook folders per user for comprehensive library management
- **🔍 Enhanced Scanner**: Intelligent ebook discovery with Calibre folder structure support and comprehensive metadata extraction - **🔍 Enhanced Scanner**: Intelligent ebook discovery with Calibre folder structure support and comprehensive metadata extraction
- **👀 Real-Time Monitoring**: File system monitoring for automatic ebook detection and updates - **👀 Real-Time Monitoring**: File system monitoring for automatic ebook detection and updates
@@ -162,8 +162,8 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
### Ratings (Protected) ### Ratings (Protected)
- `GET /api/ebooks/:id/rating` - Get user's rating for ebook (returns 0 when no rating exists) - `GET /api/ebooks/:id/rating` - Get user's rating for ebook (returns 0 when no rating exists)
- `POST /api/ebooks/:id/rating` - Create or update ebook rating (1-5 stars) - `POST /api/ebooks/:id/rating` - Create or update ebook rating (1-10 scale for half-star precision)
- `PUT /api/ebooks/:id/rating` - Create or update ebook rating (1-5 stars) - `PUT /api/ebooks/:id/rating` - Create or update ebook rating (1-10 scale for half-star precision)
- `DELETE /api/ebooks/:id/rating` - Delete user's rating - `DELETE /api/ebooks/:id/rating` - Delete user's rating
- `GET /api/ebooks/:id/ratings` - Get all ratings for ebook - `GET /api/ebooks/:id/ratings` - Get all ratings for ebook
@@ -177,23 +177,29 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
Bookmann features a fully interactive 5-star rating system integrated directly into the dashboard: Bookmann features a fully interactive 5-star rating system integrated directly into the dashboard:
### Rating Scale ### Rating Scale
- **1-5 stars**: Standard rating scale for ebooks - **Backend**: 1-10 scale where odd numbers represent half-stars
- 1,3,5,7,9 = 0.5,1.5,2.5,3.5,4.5 stars (half-star precision)
- 2,4,6,8,10 = 1,2,3,4,5 stars (full stars)
- **Frontend**: 1-5 star display with half-star precision
- **0 stars**: Automatically shown when no rating exists - **0 stars**: Automatically shown when no rating exists
- **User-specific**: Each user has their own ratings per ebook - **User-specific**: Each user has their own ratings per ebook
### Dashboard Integration ### Dashboard Integration
- **Visual Rating Display**: Interactive star widgets for each ebook - **Visual Rating Display**: 5-star widgets with half-star precision
- **Click-to-Rate**: Simply click on stars to set/update ratings - **Dialog-based Rating**: Click stars to open rating dialog with 0.5 increments
- **Half-star Precision**: Support for ratings like 3.5, 4.0, 4.5 stars
- **Real-time Updates**: Rating changes reflect immediately without page reload - **Real-time Updates**: Rating changes reflect immediately without page reload
- **Graceful Fallback**: Shows empty stars (☆) for unrated books - **Graceful Fallback**: Shows empty stars (☆) for unrated books
### API Behavior ### API Behavior
- **GET /api/ebooks/:id/rating**: Returns rating 0 (HTTP 200) when no rating exists - **GET /api/ebooks/:id/rating**: Returns rating 0 (HTTP 200) when no rating exists
- **POST/PUT /api/ebooks/:id/rating**: Create or update ratings (1-5) - **POST/PUT /api/ebooks/:id/rating**: Create or update ratings (1-10 for half-star precision)
- **DELETE /api/ebooks/:id/rating**: Remove user's rating - **DELETE /api/ebooks/:id/rating**: Remove user's rating
- **pgx v5 Standards**: All database operations use modern pgx error handling - **pgx v5 Standards**: All database operations use modern pgx error handling
### Frontend Features ### Frontend Features
- **Dialog Input**: Click stars to rate with precise 0.5 increment control
- **Visual Half-stars**: Different symbols (⭐) for half-star display
- **HTMX Integration**: Smooth interactions without full page refreshes - **HTMX Integration**: Smooth interactions without full page refreshes
- **Responsive Design**: Mobile-friendly rating controls - **Responsive Design**: Mobile-friendly rating controls
- **Theme Support**: Rating stars adapt to user's selected theme - **Theme Support**: Rating stars adapt to user's selected theme
@@ -339,7 +345,7 @@ Use the included Bruno collection in the `bruno/` directory for testing the API:
- **Multiple Folder Support**: Users can configure multiple ebook directories with per-user folder management - **Multiple Folder Support**: Users can configure multiple ebook directories with per-user folder management
- **Real-Time Monitoring**: File system watching for automatic ebook updates with dynamic subfolder detection - **Real-Time Monitoring**: File system watching for automatic ebook updates with dynamic subfolder detection
- **Scan Settings**: User-configurable scan frequency and auto-scan options - **Scan Settings**: User-configurable scan frequency and auto-scan options
- **Interactive Rating System**: 5-star dashboard controls with click-to-rate functionality, zero-rating fallback, and full CRUD operations - **Advanced Rating System**: 5-star display with half-star precision, dialog-based rating input, 10-point backend scale, and full CRUD operations
### Frontend Redesign ### Frontend Redesign
- **Beautiful Homepage**: Hero section with features showcase and modern design - **Beautiful Homepage**: Hero section with features showcase and modern design