feat: add week 3 audio and timeline enhancements

backend/app/services/story_service.py

@@ -25,6 +25,8 @@ from app.services.adapters.storybook.primary import Storybook
 from app.services.adapters.text.models import StoryOutput
 from app.services.audio_storage import (
     audio_cache_exists,
+    delete_audio_cache,
+    get_audio_cache_metadata,
     read_audio_cache,
     write_story_audio_cache,
 )
@@ -1536,9 +1538,66 @@ async def generate_story_audio(
         raise
 
     raise HTTPException(status_code=500, detail="Audio generation failed")
-
-
-async def get_story_achievements(
+
+
+async def get_story_audio_status(
+    story_id: int,
+    user_id: str,
+    db: AsyncSession,
+) -> dict:
+    """Return audio cache status without generating audio."""
+
+    story = await get_story_detail(story_id, user_id, db)
+    metadata = get_audio_cache_metadata(story.audio_path)
+
+    if story.audio_path and not metadata.exists:
+        logger.warning(
+            "story_audio_cache_missing_on_status",
+            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()
+            metadata = get_audio_cache_metadata(story.audio_path)
+
+    return {
+        "story_id": story.id,
+        "audio_ready": story.audio_status == StoryAssetStatus.READY.value
+        and metadata.exists,
+        "cache_exists": metadata.exists,
+        "cache_size_bytes": metadata.size_bytes,
+        "cache_updated_at": metadata.updated_at,
+        "generation_status": story.generation_status,
+        "text_status": story.text_status,
+        "image_status": story.image_status,
+        "audio_status": story.audio_status,
+        "last_error": story.last_error,
+        "retryable_assets": story.retryable_assets,
+    }
+
+
+async def clear_story_audio_cache(
+    story_id: int,
+    user_id: str,
+    db: AsyncSession,
+) -> dict:
+    """Delete cached audio and mark audio as retryable again."""
+
+    story = await get_story_detail(story_id, user_id, db)
+    delete_audio_cache(story.audio_path)
+    story.audio_path = None
+    sync_story_status(
+        story,
+        audio_status=StoryAssetStatus.NOT_REQUESTED,
+        last_error=None,
+    )
+    await db.commit()
+    return await get_story_audio_status(story_id, user_id, db)
+
+
+async def get_story_achievements(
     story_id: int,
     user_id: str,
     db: AsyncSession,