docs: update Carousel Dashboard plan and resolve verification checklist discrepancies
Updated Carousel Dashboard documentation to reflect finalized architecture decisions and resolve discrepancies between plan and verification checklist. ## CAROUSEL_DASHBOARD_PLAN.md Changes ### Added Phase 4.5: Collections Preview Endpoint - Documented why preview endpoint is required (web UI + mobile apps) - Explained why client-side preview is a bad idea (download entire library, code duplication, maintenance nightmare) - Added full PreviewCollection handler implementation - Added Bruno test specification ### Enhanced Phase 7: Router Registration & Config Setup - Renamed from "Router Registration" to "Router Registration & Config Setup" - Added Step 1: Update router.go Config struct with line numbers - Added Step 2: Update main.go initialization with line numbers - Added Step 3: Update test_helpers.go with line numbers - Added explanation: Why both DashboardService AND DashboardHandler? ### Updated Phase 10.5.4: Collections Preview Endpoint - Referenced Phase 4.5 (endpoint already implemented earlier) - Clarified needed for web UI AND mobile apps - Noted no additional work needed ### Added Phase 10.6: Implementation Checklist - 30+ checklist items with file paths and verification commands - Organized by layer (Database, Service, Handler, Router, Templates, TypeScript, Tests, Docs) - Added Build & Verification section - Added Timeline Estimate (20-26 hours) - Added Post-Implementation Tasks ## CAROUSEL_DASHBOARD_VERIFICATION_CHECKLIST.md Changes ### Added Clarification Section (at top) - Explained all discrepancies between plan and checklist - Preview endpoint IS in plan (Phase 4.5) - Custom Section Builder IS in plan (Phase 10.5.2 and 10.5.3) - Service method names - Plan is correct - Config struct - Documented with exact line numbers - DashboardService vs DashboardHandler - Explained why both needed ### Updated Service Method Names (Section 3.2) Changed to match plan's actual implementation: - GetDashboardSections (not GetSectionItems) - filterHiddenCollections (not filterHiddenSections) - reorderCollections (not reorderSections) - sortByPriority (new method) - getUserCollectionItems (not getCollectionSections) - getCollectionItemsByQueryType (renamed) ### Enhanced Config Verification (Section 6.4) Added exact line numbers for all 3 files: - internal/router/router.go lines 58-59 - cmd/server/main.go lines 123-124, 172-173 - cmd/server/tests/test_helpers.go lines 419-420, 458-459 ### Updated Preview Endpoint Section (Section 6.3) Added clear explanation of why endpoint is REQUIRED and why NOT client-side. ### Clarified Custom Section Builder (Sections 8.5, 9.4) Both now explicitly state "IS in the plan (Phase 10.5)" ## docs/developer/api/dashboard.md Changes Updated API documentation to match new unified collections architecture: - Terminology: "smart sections" → "system collections" - Field: `type: string` → `is_system: boolean` - Field: `id` → `media_item_id` for books - Request: `hidden_sections` → `hidden_collections` - Request: `section_order` → `collection_order` - Removed: "in-progress" and "unread" smart sections - Added: Update Dashboard Preferences endpoint - Added: Restore System Collection endpoint - Updated: Example responses with new field names and types - Updated: Error responses table ## Impact These changes clarify: 1. Preview endpoint is required for both web UI custom section builder and mobile apps 2. Custom Section Builder IS a major feature in the plan (not missing) 3. Service method names use "collections" terminology consistently 4. Config struct updates are clearly documented with exact line numbers (3 files only) 5. Why both DashboardService AND DashboardHandler are needed in Config All documentation now accurately reflects the finalized Carousel Dashboard architecture.
This commit is contained in:
+3444
-267
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -2,7 +2,7 @@
|
||||
|
||||
## Get Dashboard Sections
|
||||
|
||||
Retrieve all dashboard sections for a specific library, including smart sections and user collections.
|
||||
Retrieve all dashboard sections for a specific library, including system collections and user collections.
|
||||
|
||||
**Endpoint**: `GET /api/dashboard/sections`
|
||||
|
||||
@@ -17,20 +17,19 @@ Retrieve all dashboard sections for a specific library, including smart sections
|
||||
|
||||
### Response
|
||||
|
||||
Returns array of sections in user's customized order (respects `section_order` and `hidden_sections` preferences).
|
||||
Returns array of sections in user's customized order (respects `collection_order` and `hidden_collections` preferences).
|
||||
|
||||
**Section Types**:
|
||||
- `smart`: Auto-generated sections based on reading activity
|
||||
- `collection`: User-created collections with `show_on_dashboard: true`
|
||||
- `is_system: true`: System collections (4 pre-seeded defaults)
|
||||
- `is_system: false`: User-created collections with `show_on_dashboard: true`
|
||||
|
||||
**Smart Sections**:
|
||||
**System Collections**:
|
||||
| ID | Title | Icon | Description |
|
||||
|-----------------|------------------|------|--------------------------------------------------|
|
||||
| continue-reading| Continue Reading | 📖 | Books with progress > 0% and < 100% |
|
||||
| in-progress | In Progress | 📚 | Books with progress > 0% |
|
||||
| recently-added | Recently Added | 🆕 | Newest items in library |
|
||||
| recently-read | Recently Read | ✅ | Books with progress = 100% |
|
||||
| unread | Not Started | 📕 | Books with no reading progress |
|
||||
| not-started | Not Started | 📕 | Books with no reading progress |
|
||||
|
||||
### Example Response
|
||||
|
||||
@@ -39,26 +38,30 @@ Returns array of sections in user's customized order (respects `section_order` a
|
||||
"sections": [
|
||||
{
|
||||
"id": "continue-reading",
|
||||
"type": "smart",
|
||||
"is_system": true,
|
||||
"title": "Continue Reading",
|
||||
"description": "Books you're currently reading (0 < progress < 1)",
|
||||
"icon": "📖",
|
||||
"items": [
|
||||
{
|
||||
"id": "uuid-here",
|
||||
"media_item_id": "uuid-here",
|
||||
"title": "Book Title",
|
||||
"author": "Author Name",
|
||||
"cover_image_path": "/path/to/cover.jpg"
|
||||
}
|
||||
],
|
||||
"view_all_url": "/section/continue-reading"
|
||||
"view_all_url": "/section/continue-reading",
|
||||
"priority": 1
|
||||
},
|
||||
{
|
||||
"id": "collection-uuid",
|
||||
"type": "collection",
|
||||
"is_system": false,
|
||||
"title": "My Favorites",
|
||||
"description": "My favorite books",
|
||||
"icon": "⭐",
|
||||
"items": [],
|
||||
"view_all_url": null
|
||||
"view_all_url": "",
|
||||
"priority": 100
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -68,15 +71,71 @@ Returns array of sections in user's customized order (respects `section_order` a
|
||||
|
||||
The endpoint respects user's dashboard preferences:
|
||||
|
||||
- **`section_order`**: Sections returned in user's custom order
|
||||
- **`hidden_sections`**: Hidden sections excluded from response
|
||||
- **`collection_order`**: Sections returned in user's custom order
|
||||
- **`hidden_collections`**: Hidden collections excluded from response
|
||||
- **`items_per_section`**: Default limit from user preferences (overridden by `?limit=` query param)
|
||||
|
||||
## Update Dashboard Preferences
|
||||
|
||||
Save or update user dashboard preferences for a specific library.
|
||||
|
||||
**Endpoint**: `PUT /api/dashboard/preferences`
|
||||
|
||||
**Authentication**: Required (Bearer token)
|
||||
|
||||
### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "uuid",
|
||||
"hidden_collections": ["not-started"],
|
||||
"collection_order": ["recently-added", "continue-reading", "recently-read"],
|
||||
"items_per_section": 20
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
Returns updated preferences object.
|
||||
|
||||
## Restore System Collection
|
||||
|
||||
Reset a system collection to its default state (removes user customizations).
|
||||
|
||||
**Endpoint**: `POST /api/dashboard/restore-system-collection`
|
||||
|
||||
**Authentication**: Required (Bearer token)
|
||||
|
||||
### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"collection_name": "continue-reading"
|
||||
}
|
||||
```
|
||||
|
||||
Valid `collection_name` values:
|
||||
- `continue-reading`
|
||||
- `recently-added`
|
||||
- `recently-read`
|
||||
- `not-started`
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "System collection restored to defaults"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Responses
|
||||
|
||||
| Status | Description |
|
||||
|--------|------------------------|
|
||||
| 400 | Missing library_id |
|
||||
| 400 | Invalid library_id |
|
||||
| 401 | Unauthorized |
|
||||
| 500 | Failed to load sections |
|
||||
| Status | Description |
|
||||
|--------|--------------------------------|
|
||||
| 400 | Missing library_id |
|
||||
| 400 | Invalid library_id |
|
||||
| 400 | Invalid collection_name |
|
||||
| 401 | Unauthorized |
|
||||
| 500 | Failed to load sections |
|
||||
| 500 | Failed to save preferences |
|
||||
| 500 | Failed to restore collection |
|
||||
|
||||
Reference in New Issue
Block a user