feat: uv config other feats

- add uv configuration for the backend
- update frontend to make auth work
- add new auth endpoints
- add bookmars feat
- add reader feat

backend/apps/books/migrations/0002_ebook_file_size_ebook_format_ebook_metadata_json_and_more.py

@@ -0,0 +1,105 @@
+# Generated by Django 5.1.7 on 2026-06-03 22:21
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('books', '0001_initial'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='ebook',
+            name='file_size',
+            field=models.BigIntegerField(default=0),
+        ),
+        migrations.AddField(
+            model_name='ebook',
+            name='format',
+            field=models.CharField(blank=True, default='', editable=False, max_length=20),
+        ),
+        migrations.AddField(
+            model_name='ebook',
+            name='metadata_json',
+            field=models.JSONField(blank=True, default=dict),
+        ),
+        migrations.AddField(
+            model_name='ebook',
+            name='page_count',
+            field=models.PositiveIntegerField(default=0),
+        ),
+        migrations.AddField(
+            model_name='readingprogress',
+            name='device_id',
+            field=models.CharField(blank=True, default='', max_length=128),
+        ),
+        migrations.AddField(
+            model_name='readingprogress',
+            name='device_name',
+            field=models.CharField(blank=True, default='', max_length=128),
+        ),
+        migrations.AddField(
+            model_name='readingprogress',
+            name='version',
+            field=models.PositiveIntegerField(default=1),
+        ),
+        migrations.AlterField(
+            model_name='ebook',
+            name='author',
+            field=models.CharField(blank=True, db_index=True, default='', max_length=256),
+        ),
+        migrations.AlterField(
+            model_name='ebook',
+            name='title',
+            field=models.CharField(db_index=True, max_length=512),
+        ),
+        migrations.CreateModel(
+            name='BookChapter',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('title', models.CharField(max_length=512)),
+                ('index', models.IntegerField(default=0)),
+                ('href', models.CharField(blank=True, default='', max_length=1024)),
+                ('children', models.JSONField(blank=True, default=list)),
+                ('ebook', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='chapters', to='books.ebook')),
+            ],
+            options={
+                'verbose_name': 'Book Chapter',
+                'verbose_name_plural': 'Book Chapters',
+                'db_table': 'books_book_chapter',
+                'ordering': ['index'],
+            },
+        ),
+        migrations.CreateModel(
+            name='DownloadRecord',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('file_size', models.BigIntegerField(default=0)),
+                ('downloaded_at', models.DateTimeField(auto_now_add=True)),
+                ('ebook', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='download_records', to='books.ebook')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='download_records', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'Download Record',
+                'verbose_name_plural': 'Download Records',
+                'db_table': 'books_download_record',
+                'ordering': ['-downloaded_at'],
+            },
+        ),
+        migrations.DeleteModel(
+            name='ReadingSettings',
+        ),
+        migrations.AddIndex(
+            model_name='bookchapter',
+            index=models.Index(fields=['ebook', 'index'], name='books_book__ebook_i_464cd6_idx'),
+        ),
+        migrations.AlterUniqueTogether(
+            name='downloadrecord',
+            unique_together={('user', 'ebook')},
+        ),
+    ]

backend/apps/books/migrations/0003_readingprogress_epub_location.py

@@ -0,0 +1,16 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("books", "0002_ebook_file_size_ebook_format_ebook_metadata_json_and_more"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="readingprogress",
+            name="epub_location",
+            field=models.CharField(blank=True, default="", max_length=2048),
+        ),
+    ]

backend/apps/books/models.py

@@ -111,6 +111,7 @@ class ReadingProgress(models.Model):
     ebook = models.OneToOneField(EBook, on_delete=models.CASCADE, related_name="reading_progress")
     current_position = models.FloatField(default=0.0)
     last_page = models.IntegerField(default=0)
+    epub_location = models.CharField(max_length=2048, blank=True, default="")
     device_id = models.CharField(max_length=128, blank=True, default="")
     device_name = models.CharField(max_length=128, blank=True, default="")
     version = models.PositiveIntegerField(default=1)

backend/apps/books/serializers.py

@@ -1,6 +1,25 @@
 from rest_framework import serializers
 
+import logging
+
 from apps.books.models import Book, BookChapter, EBook, ReadingProgress, ReadingStatus, DownloadRecord
+from apps.books.services.metadata import enrich_ebook_metadata
+from apps.books.services.process_ebook import apply_processing_to_ebook
+from apps.reader.models import ReadingSettings
+
+logger = logging.getLogger(__name__)
+
+class BookReadingSettingsSerializer(serializers.ModelSerializer):
+    font_style = serializers.CharField(source="font_family")
+
+    class Meta:
+        model = ReadingSettings
+        fields = ["font_size", "font_style", "background_color"]
+
+    def validate_font_size(self, value: int) -> int:
+        if value < 12 or value > 36:
+            raise serializers.ValidationError("Font size must be between 12 and 36.")
+        return value
 
 
 class BookChapterSerializer(serializers.ModelSerializer):
@@ -51,10 +70,14 @@ class EBookListSerializer(serializers.ModelSerializer):
     filename = serializers.CharField(read_only=True)
     format = serializers.CharField(read_only=True)
     progress = serializers.SerializerMethodField()
+    started = serializers.SerializerMethodField()
 
     class Meta:
         model = EBook
-        fields = ["id", "title", "author", "filename", "format", "page_count", "file_size", "cover_image", "created_at", "progress"]
+        fields = [
+            "id", "title", "author", "filename", "format", "page_count", "file_size",
+            "cover_image", "created_at", "progress", "started",
+        ]
 
     def get_progress(self, obj):
         try:
@@ -62,16 +85,30 @@ class EBookListSerializer(serializers.ModelSerializer):
         except ReadingProgress.DoesNotExist:
             return None
 
+    def get_started(self, obj):
+        """True when the user has opened the reader and has a saved EPUB location."""
+        try:
+            rp = obj.reading_progress
+        except ReadingProgress.DoesNotExist:
+            return False
+        if rp.current_position >= 99:
+            return False
+        return bool((rp.epub_location or "").strip())
+
 
 class EBookDetailSerializer(serializers.ModelSerializer):
     filename = serializers.CharField(read_only=True)
     format = serializers.CharField(read_only=True)
     file_url = serializers.SerializerMethodField()
     progress = serializers.SerializerMethodField()
+    metadata = serializers.JSONField(source="metadata_json", read_only=True)
 
     class Meta:
         model = EBook
-        fields = ["id", "title", "author", "filename", "format", "page_count", "file_size", "file_url", "cover_image", "created_at", "updated_at", "progress"]
+        fields = [
+            "id", "title", "author", "filename", "format", "page_count", "file_size",
+            "file_url", "cover_image", "metadata", "created_at", "updated_at", "progress",
+        ]
 
     def get_file_url(self, obj):
         request = self.context.get("request")
@@ -82,7 +119,11 @@ class EBookDetailSerializer(serializers.ModelSerializer):
     def get_progress(self, obj):
         try:
             rp = obj.reading_progress
-            return {"current_position": rp.current_position, "last_page": rp.last_page}
+            return {
+                "current_position": rp.current_position,
+                "last_page": rp.last_page,
+                "epub_location": rp.epub_location,
+            }
         except ReadingProgress.DoesNotExist:
             return None
 
@@ -103,22 +144,35 @@ class EBookUploadSerializer(serializers.ModelSerializer):
         return value
 
     def create(self, validated_data):
-        validated_data["user"] = self.context["request"].user
-        # Auto-detect format from file extension
         import os
+
+        validated_data["user"] = self.context["request"].user
         name = str(getattr(validated_data.get("file"), "name", ""))
         ext = os.path.splitext(name)[1].lower().lstrip(".")
         if ext:
             validated_data["format"] = ext
-        return super().create(validated_data)
+        ebook = super().create(validated_data)
+        try:
+            apply_processing_to_ebook(ebook)
+        except Exception:
+            logger.exception("E-book processing failed for ebook %s", ebook.pk)
+        try:
+            enrich_ebook_metadata(ebook)
+        except Exception:
+            logger.exception("Metadata enrichment failed for ebook %s", ebook.pk)
+        ebook.refresh_from_db()
+        return ebook
 
 
 class ReadingProgressSerializer(serializers.ModelSerializer):
     class Meta:
         model = ReadingProgress
-        fields = ["current_position", "last_page", "device_id", "device_name", "version", "updated_at"]
+        fields = [
+            "current_position", "last_page", "epub_location",
+            "device_id", "device_name", "version", "updated_at",
+        ]
         read_only_fields = ["version", "updated_at"]
-        extra_kwargs = {"current_position": {"required": True, "min_value": 0.0, "max_value": 100.0}}
+        extra_kwargs = {"current_position": {"required": False, "min_value": 0.0, "max_value": 100.0}}
 
     def validate_current_position(self, value):
         if value < 0.0 or value > 100.0:
@@ -155,7 +209,11 @@ class DownloadRecordSerializer(serializers.ModelSerializer):
     def get_progress(self, obj):
         try:
             rp = obj.ebook.reading_progress
-            return {"current_position": rp.current_position, "last_page": rp.last_page}
+            return {
+                "current_position": rp.current_position,
+                "last_page": rp.last_page,
+                "epub_location": rp.epub_location,
+            }
         except ReadingProgress.DoesNotExist:
             return None
 

backend/apps/books/services/metadata.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+
+from django.core.files.base import ContentFile
+
+from apps.books.models import EBook
+from apps.books.services.openlibrary import (
+    HIGH_CONFIDENCE,
+    download_cover,
+    fetch_metadata,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def enrich_ebook_metadata(ebook: EBook) -> EBook:
+    """Fetch Open Library metadata and update the ebook. Never raises to callers."""
+    user_title = ebook.title
+    user_author = ebook.author or ""
+
+    try:
+        result = fetch_metadata(user_title, user_author)
+    except Exception:
+        logger.exception("Open Library metadata fetch failed for ebook %s", ebook.pk)
+        return ebook
+
+    if result is None:
+        return ebook
+
+    now = datetime.now(timezone.utc).isoformat()
+    metadata = {
+        "source": "openlibrary",
+        "matched_at": now,
+        "match_language": result.match_language,
+        "match_score": result.match_score,
+        "match_status": result.match_status,
+        "user_input": {"title": user_title, "author": user_author},
+        "openlibrary": result.openlibrary,
+    }
+    ebook.metadata_json = metadata
+
+    update_fields = ["metadata_json", "updated_at"]
+
+    if result.match_status == "not_found":
+        ebook.save(update_fields=update_fields)
+        return ebook
+
+    ol = result.openlibrary
+    cover_id = ol.get("cover_id")
+
+    cover_missing = (
+        not ebook.cover_image
+        or not ebook.cover_image.name
+        or not ebook.cover_image.storage.exists(ebook.cover_image.name)
+    )
+    if cover_id and cover_missing:
+        if ebook.cover_image:
+            ebook.cover_image.delete(save=False)
+        cover_bytes = download_cover(int(cover_id))
+        if cover_bytes:
+            filename = f"ol_cover_{ebook.pk}_{cover_id}.jpg"
+            ebook.cover_image.save(filename, ContentFile(cover_bytes), save=False)
+            update_fields.append("cover_image")
+
+    if result.match_score >= HIGH_CONFIDENCE:
+        ol_title = ol.get("title")
+        ol_authors = ol.get("authors") or []
+        if ol_title:
+            ebook.title = ol_title[:512]
+            update_fields.append("title")
+        if ol_authors:
+            ebook.author = ol_authors[0][:256]
+            update_fields.append("author")
+
+    ebook.save(update_fields=list(dict.fromkeys(update_fields)))
+    return ebook

backend/apps/books/services/openlibrary.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import logging
+import re
+import unicodedata
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+from typing import Any
+
+import httpx
+from config.settings import settings
+
+logger = logging.getLogger(__name__)
+
+SEARCH_URL = "https://openlibrary.org/search.json"
+COVERS_URL = "https://covers.openlibrary.org/b/id/{cover_id}-{size}.jpg"
+SEARCH_FIELDS = (
+    "key,title,author_name,cover_i,first_publish_year,subject,language,"
+    "edition_key,number_of_pages_median,publisher"
+)
+
+HIGH_CONFIDENCE = 0.8
+LOW_CONFIDENCE = 0.6
+
+# EPUB release noise often copied from filenames, e.g. "Title [6494] (r2.3)"
+_TITLE_NOISE_PATTERNS = (
+    re.compile(r"\s*\[\d+\]"),  # [6494]
+    re.compile(r"\s*\([rv][\d.]+\)", re.IGNORECASE),  # (r2.3), (v1.0)
+    re.compile(r"\s*\(rev[\d.]*\)", re.IGNORECASE),  # (rev2)
+)
+
+
+def _sanitize_search_title(title: str) -> str:
+    cleaned = title.strip()
+    for pattern in _TITLE_NOISE_PATTERNS:
+        cleaned = pattern.sub("", cleaned)
+    return re.sub(r"\s+", " ", cleaned).strip()
+
+
+@dataclass(frozen=True)
+class OpenLibraryHit:
+    work_key: str
+    title: str
+    authors: list[str]
+    cover_id: int | None
+    first_publish_year: int | None
+    subjects: list[str]
+    languages: list[str]
+    publishers: list[str]
+    edition_key: str | None
+    number_of_pages_median: int | None
+    match_language: str
+    score: float
+
+
+@dataclass(frozen=True)
+class OpenLibraryMetadata:
+    match_language: str
+    match_score: float
+    match_status: str
+    openlibrary: dict[str, Any]
+
+
+def _normalize(text: str) -> str:
+    cleaned = re.sub(r"[^\w\s]", " ", _strip_accents(text).lower())
+    return re.sub(r"\s+", " ", cleaned).strip()
+
+
+def _strip_accents(text: str) -> str:
+    normalized = unicodedata.normalize("NFKD", text)
+    return "".join(ch for ch in normalized if not unicodedata.combining(ch))
+
+
+def _build_search_params(
+    title: str,
+    author: str,
+    *,
+    lang: str | None,
+    search_mode: str,
+) -> dict[str, str | int]:
+    title = title.strip()
+    author = author.strip()
+    params: dict[str, str | int] = {"limit": 10, "fields": SEARCH_FIELDS}
+
+    if search_mode == "spanish_q":
+        q_parts = ["language:spa", title]
+        if author:
+            q_parts.append(author)
+        params["q"] = " ".join(q_parts)
+    elif search_mode == "q":
+        params["q"] = " ".join(part for part in (title, author) if part)
+    elif search_mode == "q_unaccent":
+        params["q"] = " ".join(
+            part for part in (_strip_accents(title), _strip_accents(author) if author else "") if part
+        )
+    else:
+        params["title"] = title
+        if author:
+            params["author"] = author
+
+    if lang:
+        params["lang"] = lang
+    return params
+
+
+def _title_similarity(a: str, b: str) -> float:
+    na, nb = _normalize(a), _normalize(b)
+    if not na or not nb:
+        return 0.0
+    if na in nb or nb in na:
+        return 1.0
+    return SequenceMatcher(None, na, nb).ratio()
+
+
+def _author_overlap(user_author: str, ol_authors: list[str]) -> float:
+    if not user_author.strip():
+        return 0.5 if ol_authors else 0.0
+    user_tokens = set(_normalize(user_author).split())
+    if not user_tokens:
+        return 0.0
+    best = 0.0
+    for name in ol_authors:
+        name_tokens = set(_normalize(name).split())
+        if not name_tokens:
+            continue
+        overlap = len(user_tokens & name_tokens) / len(user_tokens)
+        best = max(best, overlap)
+        if user_tokens <= name_tokens or name_tokens <= user_tokens:
+            best = max(best, 0.95)
+    return best
+
+
+def _score_hit(title: str, author: str, doc: dict[str, Any], *, lang: str) -> float:
+    ol_title = doc.get("title") or ""
+    ol_authors = doc.get("author_name") or []
+    title_score = _title_similarity(title, ol_title)
+    author_score = _author_overlap(author, ol_authors)
+    combined = (title_score * 0.6) + (author_score * 0.4)
+    if doc.get("cover_i"):
+        combined += 0.05
+    return min(combined, 1.0)
+
+
+def _parse_hit(doc: dict[str, Any], *, lang: str, score: float) -> OpenLibraryHit:
+    edition_keys = doc.get("edition_key") or []
+    edition_key = edition_keys[0] if edition_keys else None
+    cover_id = doc.get("cover_i")
+    return OpenLibraryHit(
+        work_key=doc.get("key") or "",
+        title=doc.get("title") or "",
+        authors=list(doc.get("author_name") or []),
+        cover_id=int(cover_id) if cover_id else None,
+        first_publish_year=doc.get("first_publish_year"),
+        subjects=list(doc.get("subject") or [])[:10],
+        languages=list(doc.get("language") or []),
+        publishers=list(doc.get("publisher") or [])[:5],
+        edition_key=edition_key,
+        number_of_pages_median=doc.get("number_of_pages_median"),
+        match_language=lang,
+        score=score,
+    )
+
+
+def build_cover_url(cover_id: int, size: str = "L") -> str:
+    return COVERS_URL.format(cover_id=cover_id, size=size)
+
+
+def _client() -> httpx.Client:
+    read_timeout = settings.OPENLIBRARY_TIMEOUT_SECONDS
+    connect_timeout = settings.OPENLIBRARY_CONNECT_TIMEOUT_SECONDS
+    return httpx.Client(
+        timeout=httpx.Timeout(
+            connect=connect_timeout,
+            read=read_timeout,
+            write=read_timeout,
+            pool=connect_timeout,
+        ),
+        headers={"User-Agent": settings.OPENLIBRARY_USER_AGENT},
+        follow_redirects=True,
+    )
+
+
+def search_works(
+    title: str,
+    author: str,
+    *,
+    lang: str | None = None,
+    search_mode: str = "title",
+    client: httpx.Client | None = None,
+) -> list[OpenLibraryHit]:
+    if not title.strip():
+        return []
+
+    params = _build_search_params(title, author, lang=lang, search_mode=search_mode)
+
+    try:
+        if client is not None:
+            response = client.get(SEARCH_URL, params=params)
+            response.raise_for_status()
+            docs = response.json().get("docs") or []
+        else:
+            with _client() as owned_client:
+                response = owned_client.get(SEARCH_URL, params=params)
+                response.raise_for_status()
+                docs = response.json().get("docs") or []
+    except (httpx.HTTPError, ValueError) as exc:
+        logger.warning("Open Library search failed: %s", exc)
+        return []
+
+    hits: list[OpenLibraryHit] = []
+    for doc in docs:
+        score = _score_hit(title, author, doc, lang=lang or "")
+        if score < LOW_CONFIDENCE:
+            continue
+        hits.append(_parse_hit(doc, lang=lang or "", score=score))
+    hits.sort(key=lambda h: (h.score, h.cover_id is not None), reverse=True)
+    return hits
+
+
+def pick_best_match(title: str, author: str, hits: list[OpenLibraryHit]) -> OpenLibraryHit | None:
+    return hits[0] if hits else None
+
+
+def download_cover(cover_id: int) -> bytes | None:
+    url = build_cover_url(cover_id, size="L")
+    try:
+        with _client() as client:
+            response = client.get(url)
+            if response.status_code == 404:
+                return None
+            response.raise_for_status()
+            content_type = response.headers.get("content-type", "")
+            if not content_type.startswith("image/"):
+                return None
+            return response.content
+    except httpx.HTTPError as exc:
+        logger.warning("Open Library cover download failed for %s: %s", cover_id, exc)
+        return None
+
+
+def _hit_to_openlibrary_dict(hit: OpenLibraryHit) -> dict[str, Any]:
+    return {
+        "work_key": hit.work_key,
+        "edition_key": hit.edition_key,
+        "title": hit.title,
+        "authors": hit.authors,
+        "cover_id": hit.cover_id,
+        "cover_url": build_cover_url(hit.cover_id) if hit.cover_id else None,
+        "first_publish_year": hit.first_publish_year,
+        "subjects": hit.subjects,
+        "languages": hit.languages,
+        "publishers": hit.publishers,
+        "number_of_pages_median": hit.number_of_pages_median,
+    }
+
+
+def fetch_metadata(title: str, author: str) -> OpenLibraryMetadata | None:
+    if not settings.OPENLIBRARY_ENABLED:
+        return None
+
+    preferred = settings.OPENLIBRARY_PREFERRED_LANG
+    fallback = settings.OPENLIBRARY_FALLBACK_LANG
+    search_title = _sanitize_search_title(title)
+
+    if not search_title:
+        return OpenLibraryMetadata(
+            match_language=preferred,
+            match_score=0.0,
+            match_status="not_found",
+            openlibrary={},
+        )
+
+    search_plan: list[tuple[str, str | None]] = [
+        ("spanish_q", preferred),
+        ("title", preferred),
+        ("q", None),
+        ("q_unaccent", None),
+    ]
+    if fallback != preferred:
+        search_plan.extend([("title", fallback), ("q", fallback)])
+
+    hits: list[OpenLibraryHit] = []
+    with _client() as client:
+        for search_mode, lang in search_plan:
+            hits = search_works(search_title, author, lang=lang, search_mode=search_mode, client=client)
+            if hits:
+                break
+
+    hit = pick_best_match(title, author, hits)
+    if not hit:
+        return OpenLibraryMetadata(
+            match_language=preferred,
+            match_score=0.0,
+            match_status="not_found",
+            openlibrary={},
+        )
+
+    status = "matched" if hit.score >= HIGH_CONFIDENCE else "partial"
+    return OpenLibraryMetadata(
+        match_language=hit.match_language,
+        match_score=hit.score,
+        match_status=status,
+        openlibrary=_hit_to_openlibrary_dict(hit),
+    )

backend/apps/books/services/process_ebook.py

@@ -0,0 +1,177 @@
+"""Extract TOC, metadata, and page count from uploaded EPUB/PDF files."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from apps.books.models import BookChapter, EBook
+
+logger = logging.getLogger(__name__)
+
+
+def process_ebook(file_path: str, original_filename: str | None = None) -> dict[str, Any]:
+    """Parse an e-book file and return format, metadata, TOC, and page count."""
+    ext = Path(original_filename or file_path).suffix.lower()
+    if ext == ".epub" or file_path.lower().endswith(".epub"):
+        return _process_epub(file_path)
+    if ext == ".pdf" or file_path.lower().endswith(".pdf"):
+        return _process_pdf(file_path)
+    return {"format": ext.lstrip(".") or "unknown", "page_count": 0, "metadata": {}, "toc": []}
+
+
+def store_chapters(ebook: EBook, toc: list[dict[str, Any]], parent_index: int = 0) -> None:
+    """Recursively store TOC entries as BookChapter records."""
+    for idx, entry in enumerate(toc):
+        BookChapter.objects.create(
+            ebook=ebook,
+            title=entry.get("title", "Untitled"),
+            index=parent_index + idx,
+            href=entry.get("href", ""),
+            children=entry.get("children", []),
+        )
+        children = entry.get("children", [])
+        if children:
+            store_chapters(ebook, children, parent_index + idx + 1)
+
+
+def apply_processing_to_ebook(ebook: EBook) -> dict[str, Any]:
+    """Run processing on an EBook instance and persist chapters + metadata."""
+    if not ebook.file:
+        raise ValueError("No file found for this e-book.")
+
+    file_path = ebook.file.path
+    result = process_ebook(file_path, original_filename=ebook.filename())
+
+    ebook.format = result.get("format", ebook.format)
+    ebook.page_count = result.get("page_count", 0)
+    file_metadata = result.get("metadata") or {}
+    if file_metadata:
+        merged = dict(ebook.metadata_json or {})
+        merged["file"] = file_metadata
+        ebook.metadata_json = merged
+    ebook.save(update_fields=["format", "page_count", "metadata_json", "updated_at"])
+
+    raw_toc: list[dict[str, Any]] = result.get("toc", [])
+    BookChapter.objects.filter(ebook=ebook).delete()
+    store_chapters(ebook, raw_toc)
+
+    return {
+        "format": ebook.format,
+        "page_count": ebook.page_count,
+        "metadata": ebook.metadata_json,
+        "toc_count": len(raw_toc),
+        "status": "processed",
+    }
+
+
+def _process_epub(file_path: str) -> dict[str, Any]:
+    from ebooklib import epub, ITEM_DOCUMENT
+
+    book = epub.read_epub(file_path)
+    metadata = _extract_epub_metadata(book)
+    toc = _extract_epub_toc(book)
+
+    if not toc:
+        toc = _fallback_toc_from_spine(book, ITEM_DOCUMENT)
+
+    flat_count = _count_toc_entries(toc)
+    page_count = flat_count or len(book.spine)
+
+    return {
+        "format": "epub",
+        "page_count": page_count,
+        "metadata": metadata,
+        "toc": toc,
+    }
+
+
+def _process_pdf(file_path: str) -> dict[str, Any]:
+    return {"format": "pdf", "page_count": 0, "metadata": {}, "toc": []}
+
+
+def _extract_epub_metadata(book) -> dict[str, Any]:
+    metadata: dict[str, Any] = {}
+
+    def first(namespace: str, name: str) -> str:
+        values = book.get_metadata(namespace, name)
+        if values:
+            return str(values[0][0])
+        return ""
+
+    title = first("DC", "title")
+    if title:
+        metadata["title"] = title
+    creator = first("DC", "creator")
+    if creator:
+        metadata["author"] = creator
+    language = first("DC", "language")
+    if language:
+        metadata["language"] = language
+    identifier = first("DC", "identifier")
+    if identifier:
+        metadata["identifier"] = identifier
+    return metadata
+
+
+def _parse_toc_item(item) -> dict[str, Any]:
+    from ebooklib import epub
+
+    if isinstance(item, epub.Link):
+        return {
+            "title": item.title or "Untitled",
+            "href": item.href or "",
+            "children": [],
+        }
+    if isinstance(item, tuple):
+        section, children = item
+        entry = {
+            "title": getattr(section, "title", None) or "Untitled",
+            "href": getattr(section, "href", None) or "",
+            "children": [],
+        }
+        for child in children:
+            entry["children"].append(_parse_toc_item(child))
+        return entry
+    if hasattr(item, "title"):
+        return {
+            "title": item.title or "Untitled",
+            "href": getattr(item, "href", "") or "",
+            "children": [],
+        }
+    return {"title": "Untitled", "href": "", "children": []}
+
+
+def _extract_epub_toc(book) -> list[dict[str, Any]]:
+    return [_parse_toc_item(item) for item in book.toc]
+
+
+def _fallback_toc_from_spine(book, item_document_type) -> list[dict[str, Any]]:
+    toc: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    chapter_num = 0
+
+    for spine_entry in book.spine:
+        item_id = spine_entry[0] if isinstance(spine_entry, tuple) else spine_entry
+        item = book.get_item_with_id(item_id)
+        if not item or item.get_type() != item_document_type:
+            continue
+        href = item.get_name() or ""
+        if not href or href in seen:
+            continue
+        seen.add(href)
+        chapter_num += 1
+        title = os.path.splitext(os.path.basename(href))[0] or f"Chapter {chapter_num}"
+        toc.append({"title": title.replace("_", " ").replace("-", " "), "href": href, "children": []})
+
+    return toc
+
+
+def _count_toc_entries(toc: list[dict[str, Any]]) -> int:
+    count = 0
+    for entry in toc:
+        count += 1
+        count += _count_toc_entries(entry.get("children", []))
+    return count

backend/apps/books/urls.py

@@ -1,15 +1,13 @@
 from django.urls import include, path
 from rest_framework.routers import DefaultRouter
 
-from apps.books.views import BookViewSet, EBookViewSet
+from apps.books.views import BookViewSet, EBookViewSet, book_reading_settings_view
 
 router = DefaultRouter()
+router.register(r"ebooks", EBookViewSet, basename="ebook")
 router.register(r"", BookViewSet, basename="book")
 
-ebook_router = DefaultRouter()
-ebook_router.register(r"ebooks", EBookViewSet, basename="ebook")
-
 urlpatterns = [
+    path("settings/", book_reading_settings_view, name="book-settings"),
     path("", include(router.urls)),
-    path("", include(ebook_router.urls)),
-]
+]

backend/apps/books/views.py

@@ -4,9 +4,10 @@ import logging
 from typing import Any
 
 from django.db.models import QuerySet, Q
+from django.http import FileResponse
 from django_filters.rest_framework import DjangoFilterBackend
 from rest_framework import parsers, permissions, status, viewsets
-from rest_framework.decorators import action
+from rest_framework.decorators import action, api_view, permission_classes
 from rest_framework.filters import OrderingFilter, SearchFilter
 from rest_framework.permissions import AllowAny, IsAuthenticated
 from rest_framework.request import Request
@@ -14,11 +15,13 @@ from rest_framework.response import Response
 
 from apps.books.models import Book, BookChapter, DownloadRecord, EBook, ReadingProgress
 from apps.books.serializers import (
-    BookChapterSerializer, BookDetailSerializer, BookListSerializer, BookSerializer,
-    DownloadRecordSerializer, EBookContentSerializer, EBookDetailSerializer,
+    BookChapterSerializer, BookDetailSerializer, BookListSerializer, BookReadingSettingsSerializer,
+    BookSerializer, DownloadRecordSerializer, EBookContentSerializer, EBookDetailSerializer,
     EBookListSerializer, EBookTocSerializer, EBookUploadSerializer,
     ReadingProgressSerializer, StorageSummarySerializer,
 )
+from apps.reader.models import ReadingSettings
+from apps.books.services.metadata import enrich_ebook_metadata
 
 logger = logging.getLogger(__name__)
 
@@ -107,6 +110,22 @@ class EBookViewSet(viewsets.ModelViewSet):
         serializer.save()
         return Response(serializer.data)
 
+    @action(detail=True, methods=["post"], url_path="enrich-metadata")
+    def enrich_metadata(self, request: Request, pk: int | None = None) -> Response:
+        """Re-fetch Open Library metadata and cover for this ebook."""
+        ebook = self.get_object()
+        try:
+            enrich_ebook_metadata(ebook)
+        except Exception:
+            logger.exception("Manual metadata enrichment failed for ebook %s", ebook.id)
+            return Response(
+                {"error": "Metadata enrichment failed."},
+                status=status.HTTP_502_BAD_GATEWAY,
+            )
+        ebook.refresh_from_db()
+        serializer = EBookDetailSerializer(ebook, context={"request": request})
+        return Response(serializer.data)
+
     @action(detail=True, methods=["post"])
     def process(self, request: Request, pk: int | None = None) -> Response:
         """Trigger e-book processing: metadata extraction, TOC building, page counting."""
@@ -115,33 +134,31 @@ class EBookViewSet(viewsets.ModelViewSet):
             return Response({"error": "No file found for this e-book."}, status=status.HTTP_400_BAD_REQUEST)
 
         try:
-            from apps.books.services import process_ebook
+            from apps.books.services.process_ebook import apply_processing_to_ebook
 
-            file_path = ebook.file.path
-            result = process_ebook(file_path, original_filename=ebook.filename())
-
-            # Update ebook with extracted data
-            ebook.format = result.get("format", ebook.format)
-            ebook.page_count = result.get("page_count", 0)
-            ebook.metadata_json = result.get("metadata", {})
-            ebook.save(update_fields=["format", "page_count", "metadata_json", "updated_at"])
-
-            # Store chapters in DB
-            raw_toc: list[dict[str, Any]] = result.get("toc", [])
-            BookChapter.objects.filter(ebook=ebook).delete()
-            _store_chapters(ebook, raw_toc)
-
-            return Response({
-                "format": ebook.format,
-                "page_count": ebook.page_count,
-                "metadata": ebook.metadata_json,
-                "toc_count": len(raw_toc),
-                "status": "processed",
-            })
+            result = apply_processing_to_ebook(ebook)
+            return Response(result)
         except Exception as exc:
             logger.exception("Failed to process ebook %s", ebook.id)
             return Response({"error": f"Processing failed: {exc}"}, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
 
+    @action(detail=True, methods=["get"])
+    def file(self, request: Request, pk: int | None = None) -> FileResponse | Response:
+        """Stream the EPUB file for authenticated in-browser reading."""
+        ebook = self.get_object()
+        if ebook.format != "epub":
+            return Response(
+                {"error": "Reader supports EPUB only."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        if not ebook.file:
+            return Response({"error": "No file found for this e-book."}, status=status.HTTP_400_BAD_REQUEST)
+        return FileResponse(
+            ebook.file.open("rb"),
+            content_type="application/epub+zip",
+            filename=ebook.filename(),
+        )
+
     @action(detail=True, methods=["get"])
     def toc(self, request: Request, pk: int | None = None) -> Response:
         """Return hierarchical table of contents."""
@@ -229,21 +246,6 @@ class EBookViewSet(viewsets.ModelViewSet):
         return Response(status=status.HTTP_204_NO_CONTENT)
 
 
-def _store_chapters(ebook: EBook, toc: list[dict[str, Any]], parent_index: int = 0) -> None:
-    """Recursively store TOC entries as BookChapter records."""
-    for idx, entry in enumerate(toc):
-        BookChapter.objects.create(
-            ebook=ebook,
-            title=entry.get("title", "Untitled"),
-            index=parent_index + idx,
-            href=entry.get("href", ""),
-            children=entry.get("children", []),
-        )
-        children = entry.get("children", [])
-        if children:
-            _store_chapters(ebook, children, parent_index + idx + 1)
-
-
 def _fetch_chapter_content(ebook: EBook, chapter: BookChapter) -> str:
     """Fetch HTML content for a chapter from the e-book file."""
     if ebook.format == "epub":
@@ -276,4 +278,20 @@ def _fetch_epub_chapter_content(file_path: str, chapter: BookChapter) -> str:
         return ""
     except Exception:
         logger.exception("Failed to fetch EPUB chapter content for %s", chapter.href)
-        return ""
+        return ""
+
+
+@api_view(["GET", "PATCH"])
+@permission_classes([IsAuthenticated])
+def book_reading_settings_view(request: Request) -> Response:
+    """Get or update reading settings via the books API contract."""
+    settings, _created = ReadingSettings.objects.get_or_create(user=request.user)
+
+    if request.method == "GET":
+        serializer = BookReadingSettingsSerializer(settings)
+        return Response(serializer.data)
+
+    serializer = BookReadingSettingsSerializer(settings, data=request.data, partial=True)
+    serializer.is_valid(raise_exception=True)
+    serializer.save()
+    return Response(serializer.data)