docs: update comprehensive API documentation and project guides

This commit updates all documentation files throughout the project:

- Updated IMPLEMENTATION_PLAN.md with new implementation details
- Updated PROJECT_GUIDELINES.md with coding standards and practices
- Updated README.md with current project information
- Updated SCREENSHOT_AUTOMATION.md with new automation details
- Added TEST_DATA.md with test fixtures data
- Updated cover_image_serving_plan.md with static URL patterns

Documentation API updates:
- Updated API reference documentation for all endpoints including:
  - Authentication (login, logout, register, refresh_token)
  - Book matching (auto_link, bulk_link, link_book, search)
  - Collections (CRUD operations, shelf mappings, auto-assign rules)
  - Conflicts (bulk operations, resolve/dismiss)
  - Devices (registration, approval, shelf management)
  - Highlights (create, update, delete, get)
  - Kobo sync (bookmark, markup, initialization, sync)
  - KOReader sync (library, metadata, bookmarks, progress)
  - Libraries (CRUD, folders, media items, stats)
  - Media items (bulk operations, CRUD)
  - Notes (CRUD operations)
  - OPDS (acquisition, feeds, publication)
  - Progress (reading progress tracking)
  - Queue (device queue management)
  - Ratings (star ratings)
  - Scanner (watch mode, scan operations)
  - Sync protocols (Kobo, KOReader)
  - Users (profile, password, admin operations)
  - WebSocket protocols

- Updated user guides (admin, dashboard, settings, sync)
- Updated device setup guides (Kobo, KOReader)
- Updated developer guides (testing, contributing, operations)
- Updated scripts/README.md
This commit is contained in:
2026-02-27 17:06:22 -05:00
parent 6562b20ee5
commit 4d321528b2
154 changed files with 2817 additions and 2152 deletions
+20 -6
View File
@@ -21,12 +21,14 @@ Retrieve the current system-wide scan settings.
**Authentication**: Admin role required
**Response**:
- **200 OK**: Returns current scan settings
- **401 Unauthorized**: Invalid or missing authentication
- **403 Forbidden**: User does not have admin role
- **500 Internal Server Error**: Server error
**Response Body**:
```json
{
"scan_frequency_minutes": 60,
@@ -35,10 +37,12 @@ Retrieve the current system-wide scan settings.
```
**Fields**:
- `scan_frequency_minutes` (integer): How often to scan all libraries in minutes (15-1440)
- `auto_scan_enabled` (boolean): Whether auto-scanning is enabled system-wide
**Example**:
```bash
curl -X GET https://bookhoard.example.com/api/libraries/scan-settings \
-H "Authorization: Bearer <admin_token>"
@@ -55,6 +59,7 @@ Update the system-wide scan settings.
**Authentication**: Admin role required
**Request Body**:
```json
{
"scan_frequency_minutes": 30,
@@ -63,6 +68,7 @@ Update the system-wide scan settings.
```
**Fields**:
- `scan_frequency_minutes` (integer, required): How often to scan all libraries in minutes
- Minimum: 15 (15 minutes)
- Maximum: 1440 (24 hours)
@@ -71,6 +77,7 @@ Update the system-wide scan settings.
- Default: true
**Response**:
- **200 OK**: Settings updated successfully
- **400 Bad Request**: Invalid request parameters
- **401 Unauthorized**: Invalid or missing authentication
@@ -78,6 +85,7 @@ Update the system-wide scan settings.
- **500 Internal Server Error**: Server error
**Success Response Body**:
```json
{
"scan_frequency_minutes": 30,
@@ -87,6 +95,7 @@ Update the system-wide scan settings.
```
**Error Response Body**:
```json
{
"error": "error message"
@@ -94,10 +103,12 @@ Update the system-wide scan settings.
```
**Validation Rules**:
- `scan_frequency_minutes` must be between 15 and 1440 minutes
- Both fields are required
**Example**:
```bash
curl -X PUT https://bookhoard.example.com/api/libraries/scan-settings \
-H "Authorization: Bearer <admin_token>" \
@@ -117,6 +128,7 @@ curl -X PUT https://bookhoard.example.com/api/libraries/scan-settings \
The `scan_frequency_minutes` setting determines how often the system will automatically scan all libraries for new media files. The scheduler will trigger scans for all libraries at the configured interval.
**Constraints**:
- Minimum: 15 minutes (to prevent excessive scanning)
- Maximum: 1440 minutes (24 hours)
- Default: 60 minutes (1 hour)
@@ -124,6 +136,7 @@ The `scan_frequency_minutes` setting determines how often the system will automa
### Auto-Scan Toggle
The `auto_scan_enabled` setting acts as a master switch for automatic scanning:
- When `true`: All libraries will be scanned automatically at the configured interval
- When `false`: No automatic scans will occur (manual scans still available)
@@ -135,12 +148,12 @@ These settings apply to **all libraries** in the system. Individual users can no
## Error Codes
| Status Code | Error Description |
|-------------|-------------------|
| 400 | Invalid request parameters (e.g., frequency outside range) |
| 401 | Missing or invalid JWT token |
| 403 | User lacks admin role |
| 500 | Internal server error (e.g., database connection issue) |
| Status Code | Error Description |
| ----------- | ---------------------------------------------------------- |
| 400 | Invalid request parameters (e.g., frequency outside range) |
| 401 | Missing or invalid JWT token |
| 403 | User lacks admin role |
| 500 | Internal server error (e.g., database connection issue) |
---
@@ -162,6 +175,7 @@ This API replaces the previous per-user scan settings system. The following chan
- **Preserved**: Endpoint paths remain the same for backward compatibility
The migration ensures that:
1. All libraries scan at the same frequency
2. Only administrators can modify scan settings
3. The API endpoints remain unchanged for existing clients