feat: enable local docker demo mode

backend/app/services/adapters/__init__.py

@@ -1,5 +1,7 @@
 """适配器模块 - 供应商平台化架构核心。"""
 
+# Demo adapters
+from app.services.adapters import demo as _demo_adapters  # noqa: F401
 from app.services.adapters.base import AdapterConfig, BaseAdapter
 
 # Image adapters
@@ -15,6 +17,7 @@ from app.services.adapters.text import gemini as _text_gemini_adapter  # noqa: F
 from app.services.adapters.text import openai as _text_openai_adapter  # noqa: F401
 
 # TTS adapters
+from app.services.adapters.tts import edge_tts as _tts_edge_tts_adapter  # noqa: F401
 from app.services.adapters.tts import elevenlabs as _tts_elevenlabs_adapter  # noqa: F401
 from app.services.adapters.tts import minimax as _tts_minimax_adapter  # noqa: F401
 

backend/app/services/adapters/demo.py

@@ -0,0 +1,151 @@
+"""Local deterministic demo adapters for portfolio Docker demos."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from app.services.adapters.base import BaseAdapter
+from app.services.adapters.registry import AdapterRegistry
+from app.services.adapters.storybook.primary import Storybook, StorybookPage
+from app.services.adapters.text.models import StoryOutput
+
+
+def _compact_topic(data: str) -> str:
+    parts = [
+        item.strip(" ，,。.!！?？")
+        for item in data.replace("\n", " ").split()
+        if item.strip(" ，,。.!！?？")
+    ]
+    if parts:
+        return "、".join(parts[:3])
+    return data.strip()[:20] or "星光森林"
+
+
+def _demo_image_data_url(label: str) -> str:
+    return (
+        "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' "
+        "viewBox='0 0 1200 800'%3E%3Crect width='1200' height='800' "
+        "fill='%23fef3c7'/%3E%3Ccircle cx='250' cy='180' r='130' "
+        "fill='%23f59e0b'/%3E%3Cpath d='M120 600C320 420 520 700 "
+        "720 500S1020 420 1100 560' fill='none' stroke='%237c3aed' "
+        "stroke-width='42'/%3E%3C/svg%3E"
+    )
+
+
+@AdapterRegistry.register("text", "demo")
+class DemoTextAdapter(BaseAdapter[StoryOutput]):
+    """Generate a stable local story without external AI services."""
+
+    adapter_type = "text"
+    adapter_name = "demo"
+
+    async def execute(
+        self,
+        input_type: Literal["keywords", "full_story"],
+        data: str,
+        education_theme: str | None = None,
+        memory_context: str | None = None,
+        **kwargs,
+    ) -> StoryOutput:
+        theme = education_theme or "勇气与想象力"
+        topic = _compact_topic(data)
+        title = f"{topic}的晚安冒险"
+        protagonist = "小星"
+        if memory_context and "名字" in memory_context:
+            protagonist = "故事里的小朋友"
+
+        story_text = (
+            f"睡前，{protagonist}把“{topic}”写在一张小纸条上，轻轻放进枕头下面。"
+            f"月光刚好照进房间，纸条变成了一只会发光的小船，邀请{protagonist}去寻找"
+            f"关于“{theme}”的答案。\n\n"
+            f"小船穿过云朵河，来到一片会唱歌的森林。森林里的小鹿说：真正的勇敢不是"
+            f"一点也不害怕，而是害怕的时候，还愿意牵住朋友的手往前走。{protagonist}"
+            f"听完以后，把一颗星星种进土里，星星长成了照亮回家路的小灯。\n\n"
+            f"回到房间时，纸条已经变成了一枚金色书签。{protagonist}把它夹进故事书，"
+            f"决定明天也带着好奇心和温柔，继续新的冒险。"
+        )
+
+        return StoryOutput(
+            mode="generated" if input_type == "keywords" else "enhanced",
+            title=title,
+            story_text=story_text,
+            cover_prompt_suggestion=f"温暖水彩儿童绘本封面，主题：{topic}，{theme}",
+        )
+
+    async def health_check(self) -> bool:
+        return True
+
+    @property
+    def estimated_cost(self) -> float:
+        return 0.0
+
+
+@AdapterRegistry.register("image", "demo")
+class DemoImageAdapter(BaseAdapter[str]):
+    """Return a compact SVG data URL as a generated-image placeholder."""
+
+    adapter_type = "image"
+    adapter_name = "demo"
+
+    async def execute(self, prompt: str, **kwargs) -> str:
+        return _demo_image_data_url(prompt)
+
+    async def health_check(self) -> bool:
+        return True
+
+    @property
+    def estimated_cost(self) -> float:
+        return 0.0
+
+
+@AdapterRegistry.register("storybook", "demo")
+class DemoStorybookAdapter(BaseAdapter[Storybook]):
+    """Generate a stable local storybook without external AI services."""
+
+    adapter_type = "storybook"
+    adapter_name = "demo"
+
+    async def execute(
+        self,
+        keywords: str,
+        page_count: int = 6,
+        education_theme: str | None = None,
+        memory_context: str | None = None,
+        **kwargs,
+    ) -> Storybook:
+        theme = education_theme or "勇气"
+        topic = _compact_topic(keywords)
+        page_count = max(4, min(page_count, 8))
+        page_texts = [
+            f"小星在枕头下发现一张写着“{topic}”的星光地图。",
+            "地图带他来到云朵河边，一只小船正在等他上船。",
+            f"森林里的小鹿告诉他：{theme}藏在每一次温柔的选择里。",
+            "小星把一颗星星种进土里，星星长成了回家的灯。",
+            "他把今天的发现画进故事本，准备明天讲给家人听。",
+            "月亮轻轻合上窗帘，房间里只剩下甜甜的梦。",
+            "星光地图变成书签，陪他继续下一次冒险。",
+            "每个勇敢的小问题，都能长出一个温暖的故事。",
+        ]
+        pages = [
+            StorybookPage(
+                page_number=index + 1,
+                text=page_texts[index],
+                image_prompt=f"温暖儿童绘本插画，第 {index + 1} 页，{topic}，{theme}",
+            )
+            for index in range(page_count)
+        ]
+
+        return Storybook(
+            title=f"{topic}的星光绘本",
+            main_character="小星",
+            art_style="温暖水彩",
+            pages=pages,
+            cover_prompt=f"温暖水彩儿童绘本封面，{topic}，{theme}",
+        )
+
+    async def health_check(self) -> bool:
+        return True
+
+    @property
+    def estimated_cost(self) -> float:
+        return 0.0

backend/app/services/provider_router.py

@@ -33,14 +33,13 @@ class RoutingStrategy(str, Enum):
     ROUND_ROBIN = "round_robin"  # 轮询
 
 
-# 默认配置映射（当 DB 无配置时使用）
 # 默认配置映射（当 DB 无配置时使用）
 # 这是“代码级”的默认策略，对应 .env 为空的情况
 DEFAULT_PROVIDERS: dict[ProviderType, list[str]] = {
     "text": ["gemini", "openai"],
     "image": ["cqtai"],
     "tts": ["minimax", "elevenlabs", "edge_tts"],
-    "storybook": ["gemini"],
+    "storybook": ["storybook_primary"],
 }
 
 # API Key 映射：adapter_name -> settings 属性名
@@ -88,6 +87,13 @@ def _get_api_key(config_ref: str | None, adapter_name: str) -> str:
 def _get_default_config(adapter_name: str) -> AdapterConfig | None:
     """获取适配器的默认配置（无 DB 记录时使用）。返回 None 表示未知适配器。"""
 
+    if adapter_name == "demo":
+        return AdapterConfig(
+            api_key="",
+            model="demo",
+            timeout_ms=1000,
+        )
+
     # --- Text Defaults ---
     if adapter_name in ("gemini", "text_primary"):
         return AdapterConfig(
@@ -103,7 +109,7 @@ def _get_default_config(adapter_name: str) -> AdapterConfig | None:
         )
 
     # --- Image Defaults ---
-    if adapter_name in ("cqtai"):
+    if adapter_name == "cqtai":
         return AdapterConfig(
             api_key=getattr(settings, "cqtai_api_key", ""),
             model=settings.image_model or "nano-banana-pro",
@@ -194,8 +200,12 @@ async def _get_providers_with_config(
         "text": settings.text_providers,
         "image": settings.image_providers,
         "tts": settings.tts_providers,
+        "storybook": settings.storybook_providers,
     }
     names = settings_map.get(provider_type) or DEFAULT_PROVIDERS[provider_type]
+    if settings.enable_demo_providers and "demo" not in names:
+        names = ["demo", *names]
+
     result = []
     for name in names:
         config = _get_default_config(name)
@@ -273,12 +283,17 @@ async def _route_with_failover(
     # 按策略排序
     sorted_providers = _sort_by_strategy(providers, strategy, provider_type)
 
-    # 如果有 db 会话，过滤掉熔断的供应商
+    # 如果有 db 会话，过滤掉后台管理台中已熔断的供应商。
+    # .env/default provider 没有 providers 表记录，不能写入带外键的健康表。
     if db:
         healthy_providers = []
         for item in sorted_providers:
             name, config, db_provider = item
-            provider_id = db_provider.id if db_provider else name
+            if db_provider is None:
+                healthy_providers.append(item)
+                continue
+
+            provider_id = db_provider.id
             if await health_checker.is_healthy(db, provider_id):
                 healthy_providers.append(item)
             else:
@@ -295,7 +310,7 @@ async def _route_with_failover(
             errors.append(f"{name}: 适配器未注册")
             continue
 
-        provider_id = db_provider.id if db_provider else name
+        provider_id = db_provider.id if db_provider else None
 
         try:
             logger.debug(
@@ -315,8 +330,8 @@ async def _route_with_failover(
             # 更新延迟缓存
             _latency_cache[name] = latency_ms
 
-            # 记录成功指标
-            if db:
+            # 记录成功指标。Provider 指标/健康表带外键，只记录后台管理台里的真实 provider。
+            if db and db_provider and provider_id:
                 await metrics_collector.record_call(
                     db,
                     provider_id=provider_id,
@@ -326,16 +341,16 @@ async def _route_with_failover(
                 )
                 await health_checker.record_call_result(db, provider_id, success=True)
 
-                # 记录用户成本
-                if user_id:
-                    await cost_tracker.record_cost(
-                        db,
-                        user_id=user_id,
-                        provider_name=name,
-                        capability=provider_type,
-                        estimated_cost=adapter.estimated_cost,
-                        provider_id=provider_id if db_provider else None,
-                    )
+            # 记录用户成本；环境变量/default provider 没有 provider_id，保留 provider_name 即可。
+            if db and user_id:
+                await cost_tracker.record_cost(
+                    db,
+                    user_id=user_id,
+                    provider_name=name,
+                    capability=provider_type,
+                    estimated_cost=adapter.estimated_cost,
+                    provider_id=provider_id,
+                )
 
             logger.info(
                 "provider_success",
@@ -355,8 +370,8 @@ async def _route_with_failover(
             )
             errors.append(f"{name}: {exc}")
 
-            # 记录失败指标
-            if db:
+            # 记录失败指标。Provider 指标/健康表带外键，只记录后台管理台里的真实 provider。
+            if db and db_provider and provider_id:
                 await metrics_collector.record_call(
                     db,
                     provider_id=provider_id,