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
+27
View File
@@ -5,6 +5,7 @@ This document describes the shared test data used across Go integration tests an
## Test Users
### Main Admin Test User
This is the primary test user used in most integration tests.
```json
@@ -19,15 +20,18 @@ This is the primary test user used in most integration tests.
```
**Used in:**
- Go Tests: `cmd/server/tests/test_helpers.go` (getTestUserID, loginTestUser)
- Bruno: `user/auth/Login User.yml`, `user/auth/Register User.yml`
**Notes:**
- Automatically created if doesn't exist
- Deleted and recreated in tests to ensure fresh state
- Used for authentication in most test scenarios
### Max Devices Test User
Used specifically for testing device limit functionality.
```json
@@ -41,9 +45,11 @@ Used specifically for testing device limit functionality.
```
**Used in:**
- Go Tests: `cmd/server/tests/device_cap_test.go` (createTestUserForMaxDevices)
### Secondary Admin Test User
Used for testing admin creation restrictions and multi-admin scenarios.
```json
@@ -58,11 +64,13 @@ Used for testing admin creation restrictions and multi-admin scenarios.
```
**Used in:**
- Bruno: `user/admin/Register Admin User.yml`
## Test Libraries
### Standard Test Library
```json
{
"name": "Test Library",
@@ -72,10 +80,12 @@ Used for testing admin creation restrictions and multi-admin scenarios.
```
**Used in:**
- Go Tests: `cmd/server/tests/test_helpers.go` (createTestEbookID)
- Multiple test files for library management
### Search Test Library
```json
{
"name": "Search Test Library",
@@ -85,11 +95,13 @@ Used for testing admin creation restrictions and multi-admin scenarios.
```
**Used in:**
- Go Tests: `cmd/server/tests/search_test.go`
## Test Books/Media Items
### Standard Test Ebook
```json
{
"title": "Test Ebook",
@@ -101,10 +113,13 @@ Used for testing admin creation restrictions and multi-admin scenarios.
```
**Used in:**
- Go Tests: `cmd/server/tests/test_helpers.go` (createTestEbookID)
### Test Book Variants
Multiple test books with different titles for testing:
- "Test Book 1"
- "Test Book 2"
- "Test Book Title"
@@ -113,6 +128,7 @@ Multiple test books with different titles for testing:
## Test Devices
Test devices typically follow this pattern:
- Device ID: UUID format
- Device Name: "Test Device" or descriptive names
- User association: Linked to test users
@@ -139,23 +155,28 @@ Test devices typically follow this pattern:
## File Paths
### Container Paths (inside Docker container)
- Uploads: `/app/uploads`
- Cache: `/app/cache/kepub`
### Host Paths (when running tests from host)
- Uploads: `./uploads`
- Cache: Docker volume (not on host filesystem)
## How to Use This Data
### In Bruno Tests
1. Start the server: `podman compose up -d`
2. Run "Register User" to create the test admin user
3. Run "Login User" to get the JWT token
4. Use the token for authenticated requests
### In Go Tests
The test helpers automatically create and clean up test data:
```go
ts, db, cfg := setupTestServer(t)
token := loginTestUser(t, ts, db)
@@ -163,7 +184,9 @@ userID := getTestUserID(t, db)
```
### Cross-Referencing
When you find a bug in Bruno tests:
1. Check the same scenario in Go tests using the same credentials
2. Use the same email/password to debug
3. Verify the database state matches expectations
@@ -171,6 +194,7 @@ When you find a bug in Bruno tests:
## Resetting Test Data
### Reset Database
```bash
# Stop containers and remove volumes
podman compose down -v
@@ -180,7 +204,9 @@ podman compose up -d
```
### Reset Specific Test User
If you need to recreate just the test user:
```bash
# Login to database
podman exec -it bookhoard_db psql -U postgres -d bookhoard
@@ -202,6 +228,7 @@ DELETE FROM users WHERE email = 'testuser@example.com';
## Adding New Test Data
When adding new test data:
1. Choose descriptive names following the pattern "Test X"
2. Use consistent email format: `testpurpose@example.com`
3. Document in this file for cross-reference