feat: persist story generation states and cache audio

backend/app/api/stories.py

@@ -1,27 +1,28 @@
 """Story related APIs."""
 
-import asyncio
 import json
 import uuid
 from typing import AsyncGenerator
 
-from fastapi import APIRouter, Depends, HTTPException, Request, Response
-from sse_starlette.sse import EventSourceResponse
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.core.deps import require_user
-from app.core.logging import get_logger
-from app.core.rate_limiter import check_rate_limit
-from app.db.database import get_db
-from app.db.models import User
+from fastapi import APIRouter, Depends, Response
+from sse_starlette.sse import EventSourceResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.deps import require_user
+from app.core.logging import get_logger
+from app.core.rate_limiter import check_rate_limit
+from app.db.database import get_db
+from app.db.models import User
 from app.schemas.story_schemas import (
-    GenerateRequest,
-    StoryResponse,
+    AchievementItem,
     FullStoryResponse,
+    GenerateRequest,
+    StoryDetailResponse,
+    StoryImageResponse,
+    StoryListItem,
+    StoryResponse,
     StorybookRequest,
     StorybookResponse,
-    StoryListItem,
-    AchievementItem,
 )
 from app.services import story_service
 from app.services.memory_service import build_enhanced_memory_context
@@ -29,153 +30,202 @@ from app.services.provider_router import (
     generate_story_content,
     generate_image,
 )
-
-logger = get_logger(__name__)
-router = APIRouter()
-
-RATE_LIMIT_WINDOW = 60  # seconds
-RATE_LIMIT_REQUESTS = 10
-
-
-@router.post("/stories/generate", response_model=StoryResponse)
-async def generate_story(
-    request: GenerateRequest,
-    user: User = Depends(require_user),
-    db: AsyncSession = Depends(get_db),
-):
-    """Generate or enhance a story."""
-    await check_rate_limit(f"story:{user.id}", RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW)
-    return await story_service.generate_and_save_story(request, user.id, db)
-
-
-@router.post("/stories/generate/full", response_model=FullStoryResponse)
-async def generate_story_full(
-    request: GenerateRequest,
-    user: User = Depends(require_user),
-    db: AsyncSession = Depends(get_db),
-):
-    """Generate complete story (story + parallel image/audio generation)."""
-    await check_rate_limit(f"story:{user.id}", RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW)
-    return await story_service.generate_full_story_service(request, user.id, db)
-
-
-@router.post("/stories/generate/stream")
+from app.services.story_status import StoryAssetStatus, sync_story_status
+
+logger = get_logger(__name__)
+router = APIRouter()
+
+RATE_LIMIT_WINDOW = 60  # seconds
+RATE_LIMIT_REQUESTS = 10
+
+
+@router.post("/stories/generate", response_model=StoryResponse)
+async def generate_story(
+    request: GenerateRequest,
+    user: User = Depends(require_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Generate or enhance a story."""
+    await check_rate_limit(f"story:{user.id}", RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW)
+    return await story_service.generate_and_save_story(request, user.id, db)
+
+
+@router.post("/stories/generate/full", response_model=FullStoryResponse)
+async def generate_story_full(
+    request: GenerateRequest,
+    user: User = Depends(require_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Generate complete story (story + parallel image/audio generation)."""
+    await check_rate_limit(f"story:{user.id}", RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW)
+    return await story_service.generate_full_story_service(request, user.id, db)
+
+
+@router.post("/stories/generate/stream")
 async def generate_story_stream(
     request: GenerateRequest,
-    req: Request,
     user: User = Depends(require_user),
     db: AsyncSession = Depends(get_db),
 ):
-    """流式生成故事（SSE）。"""
-    await check_rate_limit(f"story:{user.id}", RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW)
-    
-    # Validation
-    profile_id, universe_id = await story_service.validate_profile_and_universe(
-        request.child_profile_id, request.universe_id, user.id, db
-    )
-    
-    # Build Context
-    memory_context = await build_enhanced_memory_context(profile_id, universe_id, db)
-
-    async def event_generator() -> AsyncGenerator[dict, None]:
-        story_id = str(uuid.uuid4())
-        yield {"event": "started", "data": json.dumps({"story_id": story_id})}
-
-        # Step 1: Generate Content
-        try:
-            result = await generate_story_content(
-                input_type=request.type,
-                data=request.data,
-                education_theme=request.education_theme,
-                memory_context=memory_context,
-                db=db,
-            )
-        except Exception as e:
-            logger.error("sse_story_generation_failed", error=str(e))
-            yield {"event": "story_failed", "data": json.dumps({"error": str(e)})}
-            return
-
-        # Save Story
-        story = await story_service.create_story_from_result(
-            result, user.id, profile_id, universe_id, db
-        )
-
+    """流式生成故事（SSE）。"""
+    await check_rate_limit(f"story:{user.id}", RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW)
+    
+    # Validation
+    profile_id, universe_id = await story_service.validate_profile_and_universe(
+        request.child_profile_id, request.universe_id, user.id, db
+    )
+    
+    # Build Context
+    memory_context = await build_enhanced_memory_context(profile_id, universe_id, db)
+
+    async def event_generator() -> AsyncGenerator[dict, None]:
+        story_id = str(uuid.uuid4())
+        yield {"event": "started", "data": json.dumps({"story_id": story_id})}
+
+        # Step 1: Generate Content
+        try:
+            result = await generate_story_content(
+                input_type=request.type,
+                data=request.data,
+                education_theme=request.education_theme,
+                memory_context=memory_context,
+                db=db,
+            )
+        except Exception as e:
+            logger.error("sse_story_generation_failed", error=str(e))
+            yield {"event": "story_failed", "data": json.dumps({"error": str(e)})}
+            return
+
+        # Save Story
+        story = await story_service.create_story_from_result(
+            result, user.id, profile_id, universe_id, db
+        )
+
         yield {
             "event": "story_ready",
             "data": json.dumps({
                 "id": story.id,
                 "title": story.title,
-                "content": story.story_text,
+                "content": story.story_text,
                 "cover_prompt": story.cover_prompt,
                 "mode": story.mode,
                 "child_profile_id": story.child_profile_id,
                 "universe_id": story.universe_id,
+                "generation_status": story.generation_status,
+                "image_status": story.image_status,
+                "audio_status": story.audio_status,
+                "last_error": story.last_error,
             }),
         }
 
         # Step 2: Generate Image
         if story.cover_prompt:
+            sync_story_status(story, image_status=StoryAssetStatus.GENERATING)
+            await db.commit()
             try:
                 # Direct call to provider router's generate_image, sharing db session
                 image_url = await generate_image(story.cover_prompt, db=db)
                 story.image_url = image_url
+                sync_story_status(
+                    story,
+                    image_status=StoryAssetStatus.READY,
+                )
                 await db.commit()
-                yield {"event": "image_ready", "data": json.dumps({"image_url": image_url})}
+                yield {
+                    "event": "image_ready",
+                    "data": json.dumps(
+                        {
+                            "image_url": image_url,
+                            "generation_status": story.generation_status,
+                            "image_status": story.image_status,
+                            "audio_status": story.audio_status,
+                            "last_error": story.last_error,
+                        }
+                    ),
+                }
             except Exception as e:
+                sync_story_status(
+                    story,
+                    image_status=StoryAssetStatus.FAILED,
+                    last_error=str(e),
+                )
+                await db.commit()
                 logger.warning("sse_image_generation_failed", story_id=story.id, error=str(e))
-                yield {"event": "image_failed", "data": json.dumps({"error": str(e)})}
+                yield {
+                    "event": "image_failed",
+                    "data": json.dumps(
+                        {
+                            "error": str(e),
+                            "generation_status": story.generation_status,
+                            "image_status": story.image_status,
+                            "audio_status": story.audio_status,
+                            "last_error": story.last_error,
+                        }
+                    ),
+                }
 
-        yield {"event": "complete", "data": json.dumps({"story_id": story.id})}
-
-    return EventSourceResponse(event_generator())
-
-
-@router.post("/storybook/generate", response_model=StorybookResponse)
-async def generate_storybook_api(
-    request: StorybookRequest,
-    user: User = Depends(require_user),
-    db: AsyncSession = Depends(get_db),
-):
-    """Generate storybook."""
-    await check_rate_limit(f"story:{user.id}", RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW)
-    return await story_service.generate_storybook_service(request, user.id, db)
-
-
-# ==================== Missing Endpoints (Issue #5) ====================
-
-@router.get("/stories", response_model=list[StoryListItem])
-async def list_stories(
-    limit: int = 20,
-    offset: int = 0,
-    user: User = Depends(require_user),
-    db: AsyncSession = Depends(get_db),
-):
-    """List stories."""
-    return await story_service.list_stories(user.id, limit, offset, db)
-
-
-@router.get("/stories/{story_id}", response_model=StoryResponse)
+        yield {
+            "event": "complete",
+            "data": json.dumps(
+                {
+                    "story_id": story.id,
+                    "generation_status": story.generation_status,
+                    "image_status": story.image_status,
+                    "audio_status": story.audio_status,
+                    "last_error": story.last_error,
+                }
+            ),
+        }
+
+    return EventSourceResponse(event_generator())
+
+
+@router.post("/storybook/generate", response_model=StorybookResponse)
+async def generate_storybook_api(
+    request: StorybookRequest,
+    user: User = Depends(require_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Generate storybook."""
+    await check_rate_limit(f"story:{user.id}", RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW)
+    return await story_service.generate_storybook_service(request, user.id, db)
+
+
+# ==================== Missing Endpoints (Issue #5) ====================
+
+@router.get("/stories", response_model=list[StoryListItem])
+async def list_stories(
+    limit: int = 20,
+    offset: int = 0,
+    user: User = Depends(require_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """List stories."""
+    return await story_service.list_stories(user.id, limit, offset, db)
+
+
+@router.get("/stories/{story_id}", response_model=StoryDetailResponse)
 async def get_story(
     story_id: int,
     user: User = Depends(require_user),
     db: AsyncSession = Depends(get_db),
 ):
-    """Get story detail."""
-    return await story_service.get_story_detail(story_id, user.id, db)
-
-
-@router.delete("/stories/{story_id}")
-async def delete_story(
-    story_id: int,
-    user: User = Depends(require_user),
-    db: AsyncSession = Depends(get_db),
-):
-    """Delete story."""
-    await story_service.delete_story(story_id, user.id, db)
-    return {"message": "Deleted"}
-
-
-@router.post("/image/generate/{story_id}")
+    """Get story detail."""
+    return await story_service.get_story_detail(story_id, user.id, db)
+
+
+@router.delete("/stories/{story_id}")
+async def delete_story(
+    story_id: int,
+    user: User = Depends(require_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete story."""
+    await story_service.delete_story(story_id, user.id, db)
+    return {"message": "Deleted"}
+
+
+@router.post("/image/generate/{story_id}", response_model=StoryImageResponse)
 async def generate_story_image(
     story_id: int,
     user: User = Depends(require_user),
@@ -183,25 +233,32 @@ async def generate_story_image(
 ):
     """Generate cover image for story."""
     url = await story_service.generate_story_cover(story_id, user.id, db)
-    return {"image_url": url}
-
-
-@router.get("/audio/{story_id}")
-async def get_story_audio(
-    story_id: int,
-    user: User = Depends(require_user),
-    db: AsyncSession = Depends(get_db),
-):
-    """Get story audio (MP3)."""
-    audio_bytes = await story_service.generate_story_audio(story_id, user.id, db)
-    return Response(content=audio_bytes, media_type="audio/mpeg")
-
-
-@router.get("/stories/{story_id}/achievements", response_model=list[AchievementItem])
-async def get_story_achievements(
-    story_id: int,
-    user: User = Depends(require_user),
-    db: AsyncSession = Depends(get_db),
-):
-    """Get story achievements."""
-    return await story_service.get_story_achievements(story_id, user.id, db)
+    story = await story_service.get_story_detail(story_id, user.id, db)
+    return {
+        "image_url": url,
+        "generation_status": story.generation_status,
+        "image_status": story.image_status,
+        "audio_status": story.audio_status,
+        "last_error": story.last_error,
+    }
+
+
+@router.get("/audio/{story_id}")
+async def get_story_audio(
+    story_id: int,
+    user: User = Depends(require_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get story audio (MP3)."""
+    audio_bytes = await story_service.generate_story_audio(story_id, user.id, db)
+    return Response(content=audio_bytes, media_type="audio/mpeg")
+
+
+@router.get("/stories/{story_id}/achievements", response_model=list[AchievementItem])
+async def get_story_achievements(
+    story_id: int,
+    user: User = Depends(require_user),
+    db: AsyncSession = Depends(get_db),
+):
+    """Get story achievements."""
+    return await story_service.get_story_achievements(story_id, user.id, db)

backend/app/core/config.py

@@ -1,130 +1,134 @@
-from pydantic import Field, model_validator
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-
-class Settings(BaseSettings):
-    """应用全局配置"""
-
-    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
-
-    # 应用基础配置
-    app_name: str = "DreamWeaver"
-    debug: bool = False
-    secret_key: str = Field(..., description="JWT 签名密钥")
-    base_url: str = Field("http://localhost:8000", description="后端对外回调地址")
-
-    # 数据库
-    database_url: str = Field(..., description="SQLAlchemy async URL")
-
-    # OAuth - GitHub
-    github_client_id: str = ""
-    github_client_secret: str = ""
-
-    # OAuth - Google
-    google_client_id: str = ""
-    google_client_secret: str = ""
-
-    # AI Capability Keys
-    text_api_key: str = ""
-    tts_api_base: str = ""
-    tts_api_key: str = ""
-    image_api_key: str = ""
-
-    # Additional Provider API Keys
-    openai_api_key: str = ""
-    elevenlabs_api_key: str = ""
-    cqtai_api_key: str = ""
-    minimax_api_key: str = ""
-    minimax_group_id: str = ""
-    antigravity_api_key: str = ""
-    antigravity_api_base: str = ""
-
-    # AI Model Configuration
-    text_model: str = "gemini-2.0-flash"
-    openai_model: str = "gpt-4o-mini"
-    tts_model: str = ""
-    image_model: str = "nano-banana-pro"
-    tts_minimax_model: str = "speech-2.6-turbo"
-    tts_elevenlabs_model: str = "eleven_multilingual_v2"
-    tts_edge_voice: str = "zh-CN-XiaoxiaoNeural"
-    antigravity_model: str = "gemini-3-pro-image"
-
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """应用全局配置"""
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+    # 应用基础配置
+    app_name: str = "DreamWeaver"
+    debug: bool = False
+    secret_key: str = Field(..., description="JWT 签名密钥")
+    base_url: str = Field("http://localhost:8000", description="后端对外回调地址")
+
+    # 数据库
+    database_url: str = Field(..., description="SQLAlchemy async URL")
+
+    # OAuth - GitHub
+    github_client_id: str = ""
+    github_client_secret: str = ""
+
+    # OAuth - Google
+    google_client_id: str = ""
+    google_client_secret: str = ""
+
+    # AI Capability Keys
+    text_api_key: str = ""
+    tts_api_base: str = ""
+    tts_api_key: str = ""
+    image_api_key: str = ""
+
+    # Additional Provider API Keys
+    openai_api_key: str = ""
+    elevenlabs_api_key: str = ""
+    cqtai_api_key: str = ""
+    minimax_api_key: str = ""
+    minimax_group_id: str = ""
+    antigravity_api_key: str = ""
+    antigravity_api_base: str = ""
+
+    # AI Model Configuration
+    text_model: str = "gemini-2.0-flash"
+    openai_model: str = "gpt-4o-mini"
+    tts_model: str = ""
+    image_model: str = "nano-banana-pro"
+    tts_minimax_model: str = "speech-2.6-turbo"
+    tts_elevenlabs_model: str = "eleven_multilingual_v2"
+    tts_edge_voice: str = "zh-CN-XiaoxiaoNeural"
+    antigravity_model: str = "gemini-3-pro-image"
+
     # Provider routing (ordered lists)
     text_providers: list[str] = Field(default_factory=lambda: ["gemini"])
     image_providers: list[str] = Field(default_factory=lambda: ["cqtai"])
     tts_providers: list[str] = Field(default_factory=lambda: ["minimax", "elevenlabs", "edge_tts"])
+    story_audio_cache_dir: str = Field(
+        "storage/audio",
+        description="Directory for cached story audio files",
+    )
 
     # Celery (Redis)
     celery_broker_url: str = Field("redis://localhost:6379/0")
-    celery_result_backend: str = Field("redis://localhost:6379/0")
-    
-    # Generic Redis
-    redis_url: str = Field("redis://localhost:6379/0", description="Redis connection URL")
-    redis_sentinel_enabled: bool = Field(False, description="Whether to enable Redis Sentinel")
-    redis_sentinel_nodes: str = Field(
-        "",
-        description="Comma-separated Redis Sentinel nodes, e.g. host1:26379,host2:26379",
-    )
-    redis_sentinel_master_name: str = Field("mymaster", description="Redis Sentinel master name")
-    redis_sentinel_password: str = Field("", description="Password for Redis Sentinel (optional)")
-    redis_sentinel_db: int = Field(0, description="Redis DB index when using Sentinel")
-    redis_sentinel_socket_timeout: float = Field(
-        0.5,
-        description="Socket timeout in seconds for Sentinel clients",
-    )
-
-    # Admin console
-    enable_admin_console: bool = False
-    admin_username: str = "admin"
-    admin_password: str = "admin123"  # 建议通过环境变量覆盖
-
-    # CORS
-    cors_origins: list[str] = Field(default_factory=lambda: ["http://localhost:5173"])
-
-    @model_validator(mode="after")
-    def _require_core_settings(self) -> "Settings":  # type: ignore[override]
-        missing = []
-        if not self.secret_key or self.secret_key == "change-me-in-production":
-            missing.append("SECRET_KEY")
-        if not self.database_url:
-            missing.append("DATABASE_URL")
-        if self.redis_sentinel_enabled and not self.redis_sentinel_nodes.strip():
-            missing.append("REDIS_SENTINEL_NODES")
-        if missing:
-            raise ValueError(f"Missing required settings: {', '.join(missing)}")
-        return self
-
-    @property
-    def redis_sentinel_hosts(self) -> list[tuple[str, int]]:
-        """Parse Redis Sentinel nodes into (host, port) tuples."""
-        nodes = []
-        raw = self.redis_sentinel_nodes.strip()
-        if not raw:
-            return nodes
-
-        for item in raw.split(","):
-            value = item.strip()
-            if not value:
-                continue
-            if ":" not in value:
-                raise ValueError(f"Invalid sentinel node format: {value}")
-            host, port_text = value.rsplit(":", 1)
-            if not host:
-                raise ValueError(f"Invalid sentinel node host: {value}")
-            try:
-                port = int(port_text)
-            except ValueError as exc:
-                raise ValueError(f"Invalid sentinel node port: {value}") from exc
-            nodes.append((host, port))
-        return nodes
-
-    @property
-    def redis_sentinel_urls(self) -> list[str]:
-        """Build Celery-compatible Sentinel URLs with DB index."""
-        return [
-            f"sentinel://{host}:{port}/{self.redis_sentinel_db}"
-            for host, port in self.redis_sentinel_hosts
-        ]
-
-
-settings = Settings()
+    celery_result_backend: str = Field("redis://localhost:6379/0")
+    
+    # Generic Redis
+    redis_url: str = Field("redis://localhost:6379/0", description="Redis connection URL")
+    redis_sentinel_enabled: bool = Field(False, description="Whether to enable Redis Sentinel")
+    redis_sentinel_nodes: str = Field(
+        "",
+        description="Comma-separated Redis Sentinel nodes, e.g. host1:26379,host2:26379",
+    )
+    redis_sentinel_master_name: str = Field("mymaster", description="Redis Sentinel master name")
+    redis_sentinel_password: str = Field("", description="Password for Redis Sentinel (optional)")
+    redis_sentinel_db: int = Field(0, description="Redis DB index when using Sentinel")
+    redis_sentinel_socket_timeout: float = Field(
+        0.5,
+        description="Socket timeout in seconds for Sentinel clients",
+    )
+
+    # Admin console
+    enable_admin_console: bool = False
+    admin_username: str = "admin"
+    admin_password: str = "admin123"  # 建议通过环境变量覆盖
+
+    # CORS
+    cors_origins: list[str] = Field(default_factory=lambda: ["http://localhost:5173"])
+
+    @model_validator(mode="after")
+    def _require_core_settings(self) -> "Settings":  # type: ignore[override]
+        missing = []
+        if not self.secret_key or self.secret_key == "change-me-in-production":
+            missing.append("SECRET_KEY")
+        if not self.database_url:
+            missing.append("DATABASE_URL")
+        if self.redis_sentinel_enabled and not self.redis_sentinel_nodes.strip():
+            missing.append("REDIS_SENTINEL_NODES")
+        if missing:
+            raise ValueError(f"Missing required settings: {', '.join(missing)}")
+        return self
+
+    @property
+    def redis_sentinel_hosts(self) -> list[tuple[str, int]]:
+        """Parse Redis Sentinel nodes into (host, port) tuples."""
+        nodes = []
+        raw = self.redis_sentinel_nodes.strip()
+        if not raw:
+            return nodes
+
+        for item in raw.split(","):
+            value = item.strip()
+            if not value:
+                continue
+            if ":" not in value:
+                raise ValueError(f"Invalid sentinel node format: {value}")
+            host, port_text = value.rsplit(":", 1)
+            if not host:
+                raise ValueError(f"Invalid sentinel node host: {value}")
+            try:
+                port = int(port_text)
+            except ValueError as exc:
+                raise ValueError(f"Invalid sentinel node port: {value}") from exc
+            nodes.append((host, port))
+        return nodes
+
+    @property
+    def redis_sentinel_urls(self) -> list[str]:
+        """Build Celery-compatible Sentinel URLs with DB index."""
+        return [
+            f"sentinel://{host}:{port}/{self.redis_sentinel_db}"
+            for host, port in self.redis_sentinel_hosts
+        ]
+
+
+settings = Settings()

backend/app/db/models.py

@@ -27,10 +27,10 @@ class User(Base):
 
     __tablename__ = "users"
 
-    id: Mapped[str] = mapped_column(String(255), primary_key=True)  # OAuth provider user ID
+    id: Mapped[str] = mapped_column(String(255), primary_key=True)
     name: Mapped[str] = mapped_column(String(255), nullable=False)
     avatar_url: Mapped[str | None] = mapped_column(String(500))
-    provider: Mapped[str] = mapped_column(String(50), nullable=False)  # github / google
+    provider: Mapped[str] = mapped_column(String(50), nullable=False)
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now()
     )
@@ -59,11 +59,22 @@ class Story(Base):
         String(36), ForeignKey("story_universes.id", ondelete="SET NULL"), nullable=True
     )
     title: Mapped[str] = mapped_column(String(255), nullable=False)
-    story_text: Mapped[str] = mapped_column(Text, nullable=True)  # 允许为空（绘本模式下）
-    pages: Mapped[list[dict] | None] = mapped_column(JSON, default=list)  # 绘本分页数据
+    story_text: Mapped[str | None] = mapped_column(Text, nullable=True)
+    pages: Mapped[list[dict] | None] = mapped_column(JSON, default=list)
     cover_prompt: Mapped[str | None] = mapped_column(Text)
     image_url: Mapped[str | None] = mapped_column(String(500))
     mode: Mapped[str] = mapped_column(String(20), nullable=False, default="generated")
+    generation_status: Mapped[str] = mapped_column(
+        String(32), nullable=False, default="narrative_ready"
+    )
+    image_status: Mapped[str] = mapped_column(
+        String(32), nullable=False, default="not_requested"
+    )
+    audio_status: Mapped[str] = mapped_column(
+        String(32), nullable=False, default="not_requested"
+    )
+    audio_path: Mapped[str | None] = mapped_column(String(500))
+    last_error: Mapped[str | None] = mapped_column(Text)
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now()
     )
@@ -123,6 +134,7 @@ class ChildProfile(Base):
 
 class StoryUniverse(Base):
     """Story universe entity."""
+
     __tablename__ = "story_universes"
 
     id: Mapped[str] = mapped_column(String(36), primary_key=True, default=_uuid)
@@ -142,7 +154,9 @@ class StoryUniverse(Base):
         DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
     )
 
-    child_profile: Mapped["ChildProfile"] = relationship("ChildProfile", back_populates="story_universes")
+    child_profile: Mapped["ChildProfile"] = relationship(
+        "ChildProfile", back_populates="story_universes"
+    )
 
 
 class ReadingEvent(Base):
@@ -163,6 +177,7 @@ class ReadingEvent(Base):
         DateTime(timezone=True), server_default=func.now(), index=True
     )
 
+
 class PushConfig(Base):
     """Push configuration entity."""
 

backend/app/schemas/story_schemas.py

@@ -1,4 +1,4 @@
-"""故事相关 Pydantic 模型。"""
+"""Story-related Pydantic schemas."""
 
 from datetime import datetime
 from typing import Literal
@@ -11,7 +11,13 @@ MAX_EDU_THEME_LENGTH = 200
 MAX_TTS_LENGTH = 4000
 
 
-# ==================== 故事模型 ====================
+class StoryStatusMixin(BaseModel):
+    """Shared generation status fields returned by story APIs."""
+
+    generation_status: str
+    image_status: str
+    audio_status: str
+    last_error: str | None = None
 
 
 class GenerateRequest(BaseModel):
@@ -24,8 +30,8 @@ class GenerateRequest(BaseModel):
     universe_id: str | None = None
 
 
-class StoryResponse(BaseModel):
-    """Story response."""
+class StoryResponse(StoryStatusMixin):
+    """Story generation response."""
 
     id: int
     title: str
@@ -37,7 +43,7 @@ class StoryResponse(BaseModel):
     universe_id: str | None = None
 
 
-class StoryListItem(BaseModel):
+class StoryListItem(StoryStatusMixin):
     """Story list item."""
 
     id: int
@@ -47,8 +53,8 @@ class StoryListItem(BaseModel):
     mode: str
 
 
-class FullStoryResponse(BaseModel):
-    """完整故事响应（含图片和音频状态）。"""
+class FullStoryResponse(StoryStatusMixin):
+    """Full story response with asset status."""
 
     id: int
     title: str
@@ -62,22 +68,19 @@ class FullStoryResponse(BaseModel):
     universe_id: str | None = None
 
 
-# ==================== 绘本模型 ====================
-
-
 class StorybookRequest(BaseModel):
-    """Storybook 生成请求。"""
+    """Storybook generation request."""
 
     keywords: str = Field(..., min_length=1, max_length=200)
     page_count: int = Field(default=6, ge=4, le=12)
     education_theme: str | None = Field(default=None, max_length=MAX_EDU_THEME_LENGTH)
-    generate_images: bool = Field(default=False, description="是否同时生成插图")
+    generate_images: bool = Field(default=False, description="Whether to generate images too.")
     child_profile_id: str | None = None
     universe_id: str | None = None
 
 
 class StorybookPageResponse(BaseModel):
-    """故事书单页响应。"""
+    """One storybook page."""
 
     page_number: int
     text: str
@@ -85,8 +88,8 @@ class StorybookPageResponse(BaseModel):
     image_url: str | None = None
 
 
-class StorybookResponse(BaseModel):
-    """故事书响应。"""
+class StorybookResponse(StoryStatusMixin):
+    """Storybook generation response."""
 
     id: int | None = None
     title: str
@@ -97,10 +100,29 @@ class StorybookResponse(BaseModel):
     cover_url: str | None = None
 
 
-# ==================== 成就模型 ====================
+class StoryDetailResponse(StoryStatusMixin):
+    """Story detail response for both stories and storybooks."""
+
+    id: int
+    title: str
+    story_text: str | None = None
+    pages: list[StorybookPageResponse] | None = None
+    cover_prompt: str | None
+    image_url: str | None
+    mode: str
+    child_profile_id: str | None = None
+    universe_id: str | None = None
+
+
+class StoryImageResponse(StoryStatusMixin):
+    """Cover image generation response."""
+
+    image_url: str | None
 
 
 class AchievementItem(BaseModel):
+    """Achievement item returned for a story."""
+
     type: str
     description: str
     obtained_at: str | None = None

backend/app/services/audio_storage.py

@@ -0,0 +1,38 @@
+"""Story audio cache storage helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from app.core.config import settings
+
+
+def build_story_audio_path(story_id: int) -> str:
+    """Build the cache path for a story audio file."""
+
+    return str(Path(settings.story_audio_cache_dir) / f"story-{story_id}.mp3")
+
+
+def audio_cache_exists(audio_path: str | None) -> bool:
+    """Whether the cached audio file exists on disk."""
+
+    return bool(audio_path) and Path(audio_path).is_file()
+
+
+def read_audio_cache(audio_path: str) -> bytes:
+    """Read cached story audio bytes."""
+
+    return Path(audio_path).read_bytes()
+
+
+def write_story_audio_cache(story_id: int, audio_data: bytes) -> str:
+    """Persist story audio and return the saved file path."""
+
+    final_path = Path(build_story_audio_path(story_id))
+    final_path.parent.mkdir(parents=True, exist_ok=True)
+
+    temp_path = final_path.with_suffix(".tmp")
+    temp_path.write_bytes(audio_data)
+    temp_path.replace(final_path)
+
+    return str(final_path)

backend/app/services/story_service.py

@@ -1,12 +1,9 @@
 """Story business logic service."""
 
 import asyncio
-import json
-import uuid
-from typing import Literal
 
 from fastapi import HTTPException
-from sqlalchemy import select, desc
+from sqlalchemy import desc, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import joinedload
 
@@ -15,90 +12,151 @@ from app.db.models import ChildProfile, Story, StoryUniverse
 from app.schemas.story_schemas import (
     GenerateRequest,
     StorybookRequest,
-    FullStoryResponse,
-    StorybookResponse,
+    FullStoryResponse,
+    StorybookResponse,
     StorybookPageResponse,
     AchievementItem,
 )
+from app.services.audio_storage import (
+    audio_cache_exists,
+    read_audio_cache,
+    write_story_audio_cache,
+)
 from app.services.memory_service import build_enhanced_memory_context
 from app.services.provider_router import (
     generate_story_content,
     generate_image,
     generate_storybook,
 )
+from app.services.story_status import (
+    StoryAssetStatus,
+    sync_story_status,
+)
 from app.tasks.achievements import extract_story_achievements
 
 logger = get_logger(__name__)
 
 
-async def validate_profile_and_universe(
-    profile_id: str | None,
-    universe_id: str | None,
-    user_id: str,
-    db: AsyncSession,
-) -> tuple[str | None, str | None]:
-    """Validate child profile and universe ownership/relationship."""
-    if not profile_id and not universe_id:
-        return None, None
+def _build_storybook_error_message(
+    *,
+    cover_failed: bool,
+    failed_pages: list[int],
+) -> str | None:
+    """Summarize storybook image generation errors for the latest attempt."""
 
-    if profile_id:
-        result = await db.execute(
-            select(ChildProfile).where(
-                ChildProfile.id == profile_id,
-                ChildProfile.user_id == user_id,
-            )
-        )
-        profile = result.scalar_one_or_none()
-        if not profile:
-            raise HTTPException(status_code=404, detail="孩子档案不存在")
-
-    if universe_id:
-        result = await db.execute(
-            select(StoryUniverse)
-            .join(ChildProfile, StoryUniverse.child_profile_id == ChildProfile.id)
-            .where(
-                StoryUniverse.id == universe_id,
-                ChildProfile.user_id == user_id,
-            )
-        )
-        universe = result.scalar_one_or_none()
-        if not universe:
-            raise HTTPException(status_code=404, detail="故事宇宙不存在")
-        if profile_id and universe.child_profile_id != profile_id:
-            raise HTTPException(status_code=400, detail="故事宇宙与孩子档案不匹配")
-        if not profile_id:
-            profile_id = universe.child_profile_id
-
-    return profile_id, universe_id
+    parts: list[str] = []
+    if cover_failed:
+        parts.append("封面生成失败")
+    if failed_pages:
+        pages = "、".join(str(page) for page in sorted(failed_pages))
+        parts.append(f"第 {pages} 页插图生成失败")
+    return "；".join(parts) if parts else None
 
 
+def _resolve_storybook_image_status(
+    *,
+    generate_images: bool,
+    cover_prompt: str | None,
+    cover_url: str | None,
+    pages_data: list[dict],
+) -> StoryAssetStatus:
+    """Resolve the persisted image status for a storybook."""
+
+    if not generate_images:
+        return StoryAssetStatus.NOT_REQUESTED
+
+    expected_assets = 0
+    ready_assets = 0
+
+    if cover_prompt or cover_url:
+        expected_assets += 1
+    if cover_url:
+        ready_assets += 1
+
+    for page in pages_data:
+        if not page.get("image_prompt") and not page.get("image_url"):
+            continue
+        expected_assets += 1
+        if page.get("image_url"):
+            ready_assets += 1
+
+    if expected_assets == 0:
+        return StoryAssetStatus.NOT_REQUESTED
+
+    if ready_assets == expected_assets:
+        return StoryAssetStatus.READY
+
+    return StoryAssetStatus.FAILED
+
+
+async def validate_profile_and_universe(
+    profile_id: str | None,
+    universe_id: str | None,
+    user_id: str,
+    db: AsyncSession,
+) -> tuple[str | None, str | None]:
+    """Validate child profile and universe ownership/relationship."""
+    if not profile_id and not universe_id:
+        return None, None
+
+    if profile_id:
+        result = await db.execute(
+            select(ChildProfile).where(
+                ChildProfile.id == profile_id,
+                ChildProfile.user_id == user_id,
+            )
+        )
+        profile = result.scalar_one_or_none()
+        if not profile:
+            raise HTTPException(status_code=404, detail="孩子档案不存在")
+
+    if universe_id:
+        result = await db.execute(
+            select(StoryUniverse)
+            .join(ChildProfile, StoryUniverse.child_profile_id == ChildProfile.id)
+            .where(
+                StoryUniverse.id == universe_id,
+                ChildProfile.user_id == user_id,
+            )
+        )
+        universe = result.scalar_one_or_none()
+        if not universe:
+            raise HTTPException(status_code=404, detail="故事宇宙不存在")
+        if profile_id and universe.child_profile_id != profile_id:
+            raise HTTPException(status_code=400, detail="故事宇宙与孩子档案不匹配")
+        if not profile_id:
+            profile_id = universe.child_profile_id
+
+    return profile_id, universe_id
+
+
 async def generate_and_save_story(
     request: GenerateRequest,
     user_id: str,
     db: AsyncSession,
 ) -> Story:
-    """Generate generic story content and save to DB."""
-    # 1. Validate
-    profile_id, universe_id = await validate_profile_and_universe(
-        request.child_profile_id, request.universe_id, user_id, db
-    )
-    
-    # 2. Build Context
-    memory_context = await build_enhanced_memory_context(profile_id, universe_id, db)
-
-    # 3. Generate
-    try:
-        result = await generate_story_content(
-            input_type=request.type,
-            data=request.data,
-            education_theme=request.education_theme,
-            memory_context=memory_context,
-            db=db,
-        )
-    except Exception as exc:
-        raise HTTPException(status_code=502, detail="Story generation failed, please try again.") from exc
-
-    # 4. Save
+    """Generate generic story content and save to DB."""
+    # 1. Validate
+    profile_id, universe_id = await validate_profile_and_universe(
+        request.child_profile_id, request.universe_id, user_id, db
+    )
+    
+    # 2. Build Context
+    memory_context = await build_enhanced_memory_context(profile_id, universe_id, db)
+
+    # 3. Generate
+    try:
+        result = await generate_story_content(
+            input_type=request.type,
+            data=request.data,
+            education_theme=request.education_theme,
+            memory_context=memory_context,
+            db=db,
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail="Story generation failed, please try again.") from exc
+
+    # 4. Save
     story = Story(
         user_id=user_id,
         child_profile_id=profile_id,
@@ -108,170 +166,209 @@ async def generate_and_save_story(
         cover_prompt=result.cover_prompt_suggestion,
         mode=result.mode,
     )
+    sync_story_status(
+        story,
+        image_status=StoryAssetStatus.NOT_REQUESTED,
+        audio_status=StoryAssetStatus.NOT_REQUESTED,
+        last_error=None,
+    )
     db.add(story)
     await db.commit()
     await db.refresh(story)
-
-    # 5. Trigger Async Tasks
-    if universe_id:
-        extract_story_achievements.delay(story.id, universe_id)
-
-    return story
-
-
+
+    # 5. Trigger Async Tasks
+    if universe_id:
+        extract_story_achievements.delay(story.id, universe_id)
+
+    return story
+
+
 async def generate_full_story_service(
     request: GenerateRequest,
     user_id: str,
     db: AsyncSession,
 ) -> FullStoryResponse:
-    """Generate story with parallel image generation."""
-    # 1. Generate text part
-    # We can reuse logic or call generate_story_content directly if we want finer control
-    # reusing generate_and_save_story to ensure consistency (it handles validation + saving)
-    story = await generate_and_save_story(request, user_id, db)
-
-    # 2. Generate Image (Parallel/Async step in this flow)
+    """Generate story with parallel image generation."""
+    # 1. Generate text part
+    # We can reuse logic or call generate_story_content directly if we want finer control
+    # reusing generate_and_save_story to ensure consistency (it handles validation + saving)
+    story = await generate_and_save_story(request, user_id, db)
+
+    # 2. Generate Image (Parallel/Async step in this flow)
     image_url: str | None = None
     errors: dict[str, str | None] = {}
 
     if story.cover_prompt:
+        sync_story_status(story, image_status=StoryAssetStatus.GENERATING)
+        await db.commit()
         try:
             image_url = await generate_image(story.cover_prompt, db=db)
             story.image_url = image_url
+            sync_story_status(
+                story,
+                image_status=StoryAssetStatus.READY,
+            )
             await db.commit()
         except Exception as exc:
             errors["image"] = str(exc)
+            sync_story_status(
+                story,
+                image_status=StoryAssetStatus.FAILED,
+                last_error=str(exc),
+            )
+            await db.commit()
             logger.warning("image_generation_failed", story_id=story.id, error=str(exc))
 
     return FullStoryResponse(
         id=story.id,
         title=story.title,
-        story_text=story.story_text,
-        cover_prompt=story.cover_prompt,
-        image_url=image_url,
+        story_text=story.story_text,
+        cover_prompt=story.cover_prompt,
+        image_url=image_url,
         audio_ready=False,
         mode=story.mode,
         errors=errors,
         child_profile_id=story.child_profile_id,
         universe_id=story.universe_id,
+        generation_status=story.generation_status,
+        image_status=story.image_status,
+        audio_status=story.audio_status,
+        last_error=story.last_error,
     )
-
-
+
+
 async def generate_storybook_service(
     request: StorybookRequest,
     user_id: str,
     db: AsyncSession,
 ) -> StorybookResponse:
-    """Generate storybook with parallel image generation for pages."""
-    # 1. Validate
-    profile_id, universe_id = await validate_profile_and_universe(
-        request.child_profile_id, request.universe_id, user_id, db
-    )
-    
-    logger.info(
-        "storybook_request",
-        user_id=user_id,
-        keywords=request.keywords,
-        page_count=request.page_count,
-        profile_id=profile_id,
-        universe_id=universe_id,
-    )
-
-    # 2. Context
-    memory_context = await build_enhanced_memory_context(profile_id, universe_id, db)
-
-    # 3. Generate Text Structure
-    try:
-        storybook = await generate_storybook(
-            keywords=request.keywords,
-            page_count=request.page_count,
-            education_theme=request.education_theme,
-            memory_context=memory_context,
-            db=db,
-        )
-    except Exception as e:
-        logger.error("storybook_generation_failed", error=str(e))
-        raise HTTPException(status_code=500, detail=f"故事书生成失败: {e}")
-
+    """Generate storybook with parallel image generation for pages."""
+    # 1. Validate
+    profile_id, universe_id = await validate_profile_and_universe(
+        request.child_profile_id, request.universe_id, user_id, db
+    )
+    
+    logger.info(
+        "storybook_request",
+        user_id=user_id,
+        keywords=request.keywords,
+        page_count=request.page_count,
+        profile_id=profile_id,
+        universe_id=universe_id,
+    )
+
+    # 2. Context
+    memory_context = await build_enhanced_memory_context(profile_id, universe_id, db)
+
+    # 3. Generate Text Structure
+    try:
+        storybook = await generate_storybook(
+            keywords=request.keywords,
+            page_count=request.page_count,
+            education_theme=request.education_theme,
+            memory_context=memory_context,
+            db=db,
+        )
+    except Exception as e:
+        logger.error("storybook_generation_failed", error=str(e))
+        raise HTTPException(status_code=500, detail=f"故事书生成失败: {e}")
+
     # 4. Parallel Image Generation
     final_cover_url = storybook.cover_url
+    cover_failed = False
+    failed_pages: list[int] = []
+
     if request.generate_images:
         logger.info("storybook_parallel_generation_start", page_count=len(storybook.pages))
-        
+
         tasks = []
 
-        # Cover Task
         async def _gen_cover():
+            nonlocal cover_failed
+
             if storybook.cover_prompt and not storybook.cover_url:
                 try:
                     return await generate_image(storybook.cover_prompt, db=db)
-                except Exception as e:
-                    logger.warning("cover_gen_failed", error=str(e))
+                except Exception as exc:
+                    cover_failed = True
+                    logger.warning("cover_gen_failed", error=str(exc))
             return storybook.cover_url
+
         tasks.append(_gen_cover())
 
-        # Page Tasks
         async def _gen_page(page):
             if page.image_prompt and not page.image_url:
                 try:
-                    url = await generate_image(page.image_prompt, db=db)
-                    page.image_url = url
-                except Exception as e:
-                    logger.warning("page_gen_failed", page=page.page_number, error=str(e))
+                    page.image_url = await generate_image(page.image_prompt, db=db)
+                except Exception as exc:
+                    failed_pages.append(page.page_number)
+                    logger.warning("page_gen_failed", page=page.page_number, error=str(exc))
 
         for page in storybook.pages:
             tasks.append(_gen_page(page))
 
-        # Execute
         results = await asyncio.gather(*tasks, return_exceptions=True)
-        
-        # Update cover result
+
         cover_res = results[0]
         if isinstance(cover_res, str):
             final_cover_url = cover_res
 
         logger.info("storybook_parallel_generation_complete")
-
-    # 5. Save to DB
-    pages_data = [
-        {
-            "page_number": p.page_number,
-            "text": p.text,
-            "image_prompt": p.image_prompt,
-            "image_url": p.image_url,
-        }
-        for p in storybook.pages
-    ]
-
+
+    # 5. Save to DB
+    pages_data = [
+        {
+            "page_number": p.page_number,
+            "text": p.text,
+            "image_prompt": p.image_prompt,
+            "image_url": p.image_url,
+        }
+        for p in storybook.pages
+    ]
+
     story = Story(
         user_id=user_id,
         child_profile_id=profile_id,
         universe_id=universe_id,
         title=storybook.title,
-        mode="storybook",
-        pages=pages_data,
+        mode="storybook",
+        pages=pages_data,
         story_text=None,
         cover_prompt=storybook.cover_prompt,
         image_url=final_cover_url,
     )
+    sync_story_status(
+        story,
+        image_status=_resolve_storybook_image_status(
+            generate_images=request.generate_images,
+            cover_prompt=storybook.cover_prompt,
+            cover_url=final_cover_url,
+            pages_data=pages_data,
+        ),
+        audio_status=StoryAssetStatus.NOT_REQUESTED,
+        last_error=_build_storybook_error_message(
+            cover_failed=cover_failed,
+            failed_pages=failed_pages,
+        ),
+    )
     db.add(story)
     await db.commit()
     await db.refresh(story)
-
-    if universe_id:
-        extract_story_achievements.delay(story.id, universe_id)
-
-    # 6. Build Response
-    response_pages = [
-        StorybookPageResponse(
-            page_number=p["page_number"],
-            text=p["text"],
-            image_prompt=p["image_prompt"],
-            image_url=p.get("image_url"),
-        )
-        for p in pages_data
-    ]
-
+
+    if universe_id:
+        extract_story_achievements.delay(story.id, universe_id)
+
+    # 6. Build Response
+    response_pages = [
+        StorybookPageResponse(
+            page_number=p["page_number"],
+            text=p["text"],
+            image_prompt=p["image_prompt"],
+            image_url=p.get("image_url"),
+        )
+        for p in pages_data
+    ]
+
     return StorybookResponse(
         id=story.id,
         title=storybook.title,
@@ -280,155 +377,209 @@ async def generate_storybook_service(
         pages=response_pages,
         cover_prompt=storybook.cover_prompt,
         cover_url=final_cover_url,
+        generation_status=story.generation_status,
+        image_status=story.image_status,
+        audio_status=story.audio_status,
+        last_error=story.last_error,
     )
-
-
-# ==================== Missing Endpoints Logic (for Issue #5) ====================
-
-async def list_stories(
-    user_id: str,
-    limit: int,
-    offset: int,
-    db: AsyncSession,
-) -> list[Story]:
-    """List stories for user."""
-    result = await db.execute(
-        select(Story)
-        .where(Story.user_id == user_id)
-        .order_by(desc(Story.created_at))
-        .offset(offset)
-        .limit(limit)
-    )
-    return result.scalars().all()
-
-
-async def get_story_detail(
-    story_id: int,
-    user_id: str,
-    db: AsyncSession,
-) -> Story:
-    """Get story detail."""
-    result = await db.execute(
-        select(Story).where(Story.id == story_id, Story.user_id == user_id)
-    )
-    story = result.scalar_one_or_none()
-    if not story:
-        raise HTTPException(status_code=404, detail="Story not found")
-    return story
-
-
-async def delete_story(
-    story_id: int,
-    user_id: str,
-    db: AsyncSession,
-) -> None:
-    """Delete a story."""
-    story = await get_story_detail(story_id, user_id, db)
-    await db.delete(story)
-    await db.commit()
-
-
+
+
+# ==================== Missing Endpoints Logic (for Issue #5) ====================
+
+async def list_stories(
+    user_id: str,
+    limit: int,
+    offset: int,
+    db: AsyncSession,
+) -> list[Story]:
+    """List stories for user."""
+    result = await db.execute(
+        select(Story)
+        .where(Story.user_id == user_id)
+        .order_by(desc(Story.created_at))
+        .offset(offset)
+        .limit(limit)
+    )
+    return result.scalars().all()
+
+
+async def get_story_detail(
+    story_id: int,
+    user_id: str,
+    db: AsyncSession,
+) -> Story:
+    """Get story detail."""
+    result = await db.execute(
+        select(Story).where(Story.id == story_id, Story.user_id == user_id)
+    )
+    story = result.scalar_one_or_none()
+    if not story:
+        raise HTTPException(status_code=404, detail="Story not found")
+    return story
+
+
+async def delete_story(
+    story_id: int,
+    user_id: str,
+    db: AsyncSession,
+) -> None:
+    """Delete a story."""
+    story = await get_story_detail(story_id, user_id, db)
+    await db.delete(story)
+    await db.commit()
+
+
 async def create_story_from_result(
     result,  # StoryOutput
     user_id: str,
     profile_id: str | None,
     universe_id: str | None,
-    db: AsyncSession,
-) -> Story:
-    """Save a generated story to DB (helper for stream endpoint)."""
-    story = Story(
-        user_id=user_id,
-        child_profile_id=profile_id,
-        universe_id=universe_id,
+    db: AsyncSession,
+) -> Story:
+    """Save a generated story to DB (helper for stream endpoint)."""
+    story = Story(
+        user_id=user_id,
+        child_profile_id=profile_id,
+        universe_id=universe_id,
         title=result.title,
         story_text=result.story_text,
         cover_prompt=result.cover_prompt_suggestion,
         mode=result.mode,
     )
+    sync_story_status(
+        story,
+        image_status=StoryAssetStatus.NOT_REQUESTED,
+        audio_status=StoryAssetStatus.NOT_REQUESTED,
+        last_error=None,
+    )
     db.add(story)
     await db.commit()
     await db.refresh(story)
-
-    if universe_id:
-        extract_story_achievements.delay(story.id, universe_id)
-        
-    return story
-
-
+
+    if universe_id:
+        extract_story_achievements.delay(story.id, universe_id)
+        
+    return story
+
+
 async def generate_story_cover(
     story_id: int,
     user_id: str,
     db: AsyncSession,
 ) -> str:
-    """Generate cover image for an existing story."""
-    story = await get_story_detail(story_id, user_id, db)
-    
+    """Generate cover image for an existing story."""
+    story = await get_story_detail(story_id, user_id, db)
+    
     if not story.cover_prompt:
         raise HTTPException(status_code=400, detail="Story has no cover prompt")
-        
+
+    sync_story_status(story, image_status=StoryAssetStatus.GENERATING)
+    await db.commit()
+
     try:
         image_url = await generate_image(story.cover_prompt, db=db)
         story.image_url = image_url
+        sync_story_status(
+            story,
+            image_status=StoryAssetStatus.READY,
+        )
         await db.commit()
         return image_url
     except Exception as e:
+        sync_story_status(
+            story,
+            image_status=StoryAssetStatus.FAILED,
+            last_error=str(e),
+        )
+        await db.commit()
         logger.error("cover_generation_failed", story_id=story_id, error=str(e))
         raise HTTPException(status_code=500, detail=f"Image generation failed: {e}")
-
-
+
+
 async def generate_story_audio(
     story_id: int,
     user_id: str,
     db: AsyncSession,
 ) -> bytes:
-    """Generate audio for a story."""
-    story = await get_story_detail(story_id, user_id, db)
-    
+    """Generate audio for a story."""
+    story = await get_story_detail(story_id, user_id, db)
+    
     if not story.story_text:
         raise HTTPException(status_code=400, detail="Story has no text")
 
-    # TODO: Check if audio is already cached/saved? 
-    # For now, generate on the fly via provider
+    if story.audio_path and audio_cache_exists(story.audio_path):
+        if story.audio_status != StoryAssetStatus.READY.value:
+            sync_story_status(story, audio_status=StoryAssetStatus.READY)
+            await db.commit()
+        return read_audio_cache(story.audio_path)
+
+    if story.audio_path and not audio_cache_exists(story.audio_path):
+        logger.warning(
+            "story_audio_cache_missing",
+            story_id=story_id,
+            audio_path=story.audio_path,
+        )
+        story.audio_path = None
+        if story.audio_status == StoryAssetStatus.READY.value:
+            sync_story_status(story, audio_status=StoryAssetStatus.NOT_REQUESTED)
+            await db.commit()
+
     from app.services.provider_router import text_to_speech
-    
+
+    sync_story_status(story, audio_status=StoryAssetStatus.GENERATING)
+    await db.commit()
+
     try:
         audio_data = await text_to_speech(story.story_text, db=db)
+        story.audio_path = write_story_audio_cache(story.id, audio_data)
+        sync_story_status(
+            story,
+            audio_status=StoryAssetStatus.READY,
+        )
+        await db.commit()
         return audio_data
     except Exception as e:
+        story.audio_path = None
+        sync_story_status(
+            story,
+            audio_status=StoryAssetStatus.FAILED,
+            last_error=str(e),
+        )
+        await db.commit()
         logger.error("audio_generation_failed", story_id=story_id, error=str(e))
         raise HTTPException(status_code=500, detail=f"Audio generation failed: {e}")
-
-
-async def get_story_achievements(
-    story_id: int,
-    user_id: str,
-    db: AsyncSession,
-) -> list[AchievementItem]:
-    """Get achievements unlocked by a specific story."""
-    result = await db.execute(
-        select(Story)
-        .options(joinedload(Story.story_universe))
-        .where(Story.id == story_id, Story.user_id == user_id)
-    )
-    story = result.scalar_one_or_none()
-
-    if not story:
-        raise HTTPException(status_code=404, detail="Story not found")
-
-    if not story.universe_id or not story.story_universe:
-        return []
-
-    universe = story.story_universe
-    if not universe.achievements:
-        return []
-
-    results = []
-    for ach in universe.achievements:
-        if isinstance(ach, dict) and ach.get("source_story_id") == story_id:
-             results.append(AchievementItem(
-                 type=ach.get("type", "Unknown"),
-                 description=ach.get("description", ""),
-                 obtained_at=ach.get("obtained_at")
-             ))
-    return results
-
+
+
+async def get_story_achievements(
+    story_id: int,
+    user_id: str,
+    db: AsyncSession,
+) -> list[AchievementItem]:
+    """Get achievements unlocked by a specific story."""
+    result = await db.execute(
+        select(Story)
+        .options(joinedload(Story.story_universe))
+        .where(Story.id == story_id, Story.user_id == user_id)
+    )
+    story = result.scalar_one_or_none()
+
+    if not story:
+        raise HTTPException(status_code=404, detail="Story not found")
+
+    if not story.universe_id or not story.story_universe:
+        return []
+
+    universe = story.story_universe
+    if not universe.achievements:
+        return []
+
+    results = []
+    for ach in universe.achievements:
+        if isinstance(ach, dict) and ach.get("source_story_id") == story_id:
+             results.append(AchievementItem(
+                 type=ach.get("type", "Unknown"),
+                 description=ach.get("description", ""),
+                 obtained_at=ach.get("obtained_at")
+             ))
+    return results
+

backend/app/services/story_status.py

@@ -0,0 +1,112 @@
+"""Story generation status helpers."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Protocol
+
+
+class StoryGenerationStatus(str, Enum):
+    """Overall story generation lifecycle."""
+
+    NARRATIVE_READY = "narrative_ready"
+    ASSETS_GENERATING = "assets_generating"
+    COMPLETED = "completed"
+    DEGRADED_COMPLETED = "degraded_completed"
+    FAILED = "failed"
+
+
+class StoryAssetStatus(str, Enum):
+    """Asset generation state for image and audio."""
+
+    NOT_REQUESTED = "not_requested"
+    GENERATING = "generating"
+    READY = "ready"
+    FAILED = "failed"
+
+
+class StoryLike(Protocol):
+    """Protocol for story-like objects used by status helpers."""
+
+    story_text: str | None
+    pages: list[dict] | None
+    generation_status: str
+    image_status: str
+    audio_status: str
+    last_error: str | None
+
+
+_ERROR_UNSET = object()
+
+
+def _normalize_asset_status(value: str | None) -> StoryAssetStatus:
+    if not value:
+        return StoryAssetStatus.NOT_REQUESTED
+
+    try:
+        return StoryAssetStatus(value)
+    except ValueError:
+        return StoryAssetStatus.NOT_REQUESTED
+
+
+def has_narrative_content(story: StoryLike) -> bool:
+    """Whether the story already has readable content."""
+
+    return bool(story.story_text) or bool(story.pages)
+
+
+def resolve_story_generation_status(story: StoryLike) -> StoryGenerationStatus:
+    """Derive the overall status from narrative and asset states."""
+
+    if not has_narrative_content(story):
+        return StoryGenerationStatus.FAILED
+
+    image_status = _normalize_asset_status(story.image_status)
+    audio_status = _normalize_asset_status(story.audio_status)
+
+    if StoryAssetStatus.GENERATING in (image_status, audio_status):
+        return StoryGenerationStatus.ASSETS_GENERATING
+
+    if StoryAssetStatus.FAILED in (image_status, audio_status):
+        return StoryGenerationStatus.DEGRADED_COMPLETED
+
+    if (
+        image_status == StoryAssetStatus.NOT_REQUESTED
+        and audio_status == StoryAssetStatus.NOT_REQUESTED
+    ):
+        return StoryGenerationStatus.NARRATIVE_READY
+
+    return StoryGenerationStatus.COMPLETED
+
+
+def has_failed_assets(story: StoryLike) -> bool:
+    """Whether any persisted asset is still in a failed state."""
+
+    image_status = _normalize_asset_status(story.image_status)
+    audio_status = _normalize_asset_status(story.audio_status)
+    return StoryAssetStatus.FAILED in (image_status, audio_status)
+
+
+def sync_story_status(
+    story: StoryLike,
+    *,
+    image_status: StoryAssetStatus | None = None,
+    audio_status: StoryAssetStatus | None = None,
+    last_error: str | None | object = _ERROR_UNSET,
+) -> None:
+    """Update asset statuses and refresh overall generation status."""
+
+    if image_status is not None:
+        story.image_status = image_status.value
+
+    if audio_status is not None:
+        story.audio_status = audio_status.value
+
+    if last_error is not _ERROR_UNSET:
+        story.last_error = last_error
+
+    generation_status = resolve_story_generation_status(story)
+    story.generation_status = generation_status.value
+
+    if last_error is _ERROR_UNSET and not has_failed_assets(story):
+        story.last_error = None