docs: restructure documentation into audience-based portals

BREAKING CHANGE: Documentation URLs have changed New structure: - user/ - End-user documentation (device setup, sync guides, frontend) - developer/ - Developer documentation (API reference, protocols, specs) - operations/ - Operations documentation (deployment, troubleshooting) - contributing/ - Contribution guides Changes: - Created portal INDEX.md files for each audience section - Moved device guides to user/devices/ (kobo-setup.md, koreader-setup.md) - Moved API docs to developer/ (api-reference.md, collections-api.md) - Moved sync guide to user/sync-guide.md - Moved troubleshooting to operations/troubleshooting.md - Moved all split API docs to developer/api/ - Renamed protocol files (kobo-protocol.md, koreader-protocol.md) - Added placeholder user guides (frontend, user-areas, settings, admin) - Updated all internal links to new paths - Updated Go code (http_handler.go, navigation.go) for new paths - Updated main INDEX.md for audience-based navigation Benefits: - Clear separation of user and developer documentation - Scalable structure for future user guide expansion - Better organization and discoverability - Audience-specific landing pages Related to DOCS_IMPLEMENTATION_PLAN.md Phase 2 completion
2026-02-02 15:58:34 -05:00
parent ece90c0f1f
commit 253f56399d
76 changed files with 372 additions and 207 deletions
@@ -0,0 +1,125 @@
+# KOReader Sync Protocol
+
+KOReader uses a custom JSON-based sync protocol.
+
+## KOReader Progress Sync
+
+**Endpoint**: `POST /api/sync/koreader/progress`
+**Auth**: Device token required
+**Content-Type**: `application/json`
+
+### Request Headers
+
+| Header | Type | Required | Description |
+|--------|------|-----------|-------------|
+| Authorization | string | Yes | Bearer device token |
+| Content-Type | string | Yes | application/json |
+
+### Request Body
+
+| Field | Type | Required | Description |
+|--------|------|-----------|-------------|
+| library_id | string | No | Library UUID |
+| books | array | Yes | Array of book sync data |
+| books[].uuid | string | Yes | Book UUID |
+| books[].title | string | Yes | Book title |
+| books[].authors | array | Yes | Array of author names |
+| books[].progress | float | Yes | Progress percentage (0-1) |
+| books[].percentage | float | Yes | Progress percentage (0-1) |
+| books[].last_read | string | Yes | ISO 8601 timestamp |
+| books[].chapter | integer | No | Current chapter |
+| books[].epubcfi | string | No | EPUB CFI location |
+| books[].character | integer | No | Character offset |
+| books[].bookmarks | array | No | Array of bookmarks/highlights |
+
+### Example Request
+
+```json
+{
+  "library_id": "optional-uuid",
+  "books": [
+    {
+      "uuid": "book-uuid",
+      "title": "Book Title",
+      "authors": ["Author Name"],
+      "progress": 0.45,
+      "percentage": 0.45,
+      "last_read": "2026-01-30T20:00:00Z",
+      "chapter": 3,
+      "epubcfi": "epubcfi(/6/4/2:15)",
+      "character": 15432,
+      "bookmarks": [
+        {
+          "chapter": 3,
+          "datetime": "2026-01-30T19:55:00Z",
+          "notes": "highlighted text",
+          "pos0": "epubcfi(/6/4/2:15)",
+          "pos1": "epubcfi(/6/4/2:20)",
+          "page": 45,
+          "text": "highlighted text excerpt",
+          "type": "highlight"
+        }
+      ],
+      "highlights": [],
+      "notes": []
+    }
+  ]
+}
+```
+
+### Response (202 Accepted)
+
+```json
+{
+  "sync_status": "accepted",
+  "books_synced": 1,
+  "conflicts": [
+    {
+      "book_uuid": "book-uuid",
+      "conflict_type": "progress_mismatch",
+      "device_progress": 0.45,
+      "server_progress": 0.42,
+      "resolution": "device_wins"
+    }
+  ]
+}
+```
+
+## KOReader Metadata Fetch
+
+**Endpoint**: `GET /api/sync/koreader/metadata/{book_uuid}`
+**Auth**: Device token required
+
+### Example Request
+
+```http
+GET /api/sync/koreader/metadata/book-uuid
+Authorization: Bearer device-token
+```
+
+### Response (200 OK)
+
+```json
+{
+  "uuid": "book-uuid",
+  "title": "Book Title",
+  "authors": ["Author Name"],
+  "progress": {
+    "percentage": 0.42,
+    "character": 15432,
+    "epubcfi": "epubcfi(/6/4/2:15)",
+    "chapter": 3,
+    "chapter_progress": 0.234
+  },
+  "annotations": {
+    "highlights": [...],
+    "notes": [...],
+    "bookmarks": [...]
+  },
+  "last_sync": "2026-01-30T20:00:00Z"
+}
+```
+
+## Try It Out
+
+<!-- API Explorer will be inserted here in Phase 3 -->