feature: 新增小说封面图片生成功能

Author: xiamuceer-j

.gitignore

@@ -79,6 +79,7 @@ backend/data/*.db-shm
 backend/data/*.db-wal
 backend/data/users.json
 backend/data/admins.json
+backend/storage/
 
 # Temporary files
 *.bak

backend/alembic/postgres/versions/20260316_1056_8e3ac0236b27_添加小说封面生成配置.py

@@ -0,0 +1,48 @@
+"""添加小说封面生成配置
+
+Revision ID: 8e3ac0236b27
+Revises: d4d253e3f4c6
+Create Date: 2026-03-16 10:56:31.489936
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '8e3ac0236b27'
+down_revision: Union[str, None] = 'd4d253e3f4c6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column('projects', sa.Column('cover_image_url', sa.String(length=1000), nullable=True, comment='封面图片访问地址'))
+    op.add_column('projects', sa.Column('cover_prompt', sa.Text(), nullable=True, comment='最近一次生成封面使用的提示词'))
+    op.add_column('projects', sa.Column('cover_status', sa.String(length=20), nullable=False, server_default='none', comment='封面状态: none/generating/ready/failed'))
+    op.add_column('projects', sa.Column('cover_error', sa.Text(), nullable=True, comment='最近一次封面生成失败原因'))
+    op.add_column('projects', sa.Column('cover_updated_at', sa.DateTime(), nullable=True, comment='最近一次封面生成成功时间'))
+    op.add_column('settings', sa.Column('cover_api_provider', sa.String(length=50), nullable=True, comment='封面图片API提供商'))
+    op.add_column('settings', sa.Column('cover_api_key', sa.String(length=500), nullable=True, comment='封面图片API密钥'))
+    op.add_column('settings', sa.Column('cover_api_base_url', sa.String(length=500), nullable=True, comment='封面图片自定义API地址'))
+    op.add_column('settings', sa.Column('cover_image_model', sa.String(length=100), nullable=True, comment='封面图片模型名称'))
+    op.add_column('settings', sa.Column('cover_enabled', sa.Boolean(), nullable=False, server_default=sa.text('false'), comment='是否启用封面图片生成'))
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column('settings', 'cover_enabled')
+    op.drop_column('settings', 'cover_image_model')
+    op.drop_column('settings', 'cover_api_base_url')
+    op.drop_column('settings', 'cover_api_key')
+    op.drop_column('settings', 'cover_api_provider')
+    op.drop_column('projects', 'cover_updated_at')
+    op.drop_column('projects', 'cover_error')
+    op.drop_column('projects', 'cover_status')
+    op.drop_column('projects', 'cover_prompt')
+    op.drop_column('projects', 'cover_image_url')
+    # ### end Alembic commands ###

backend/alembic/sqlite/versions/20260316_1058_17ce752ed7cc_添加小说封面生成配置.py

@@ -0,0 +1,56 @@
+"""添加小说封面生成配置
+
+Revision ID: 17ce752ed7cc
+Revises: d887fd1a30a6
+Create Date: 2026-03-16 10:58:55.143700
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '17ce752ed7cc'
+down_revision: Union[str, None] = 'd887fd1a30a6'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('projects', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('cover_image_url', sa.String(length=1000), nullable=True, comment='封面图片访问地址'))
+        batch_op.add_column(sa.Column('cover_prompt', sa.Text(), nullable=True, comment='最近一次生成封面使用的提示词'))
+        batch_op.add_column(sa.Column('cover_status', sa.String(length=20), nullable=False, server_default='none', comment='封面状态: none/generating/ready/failed'))
+        batch_op.add_column(sa.Column('cover_error', sa.Text(), nullable=True, comment='最近一次封面生成失败原因'))
+        batch_op.add_column(sa.Column('cover_updated_at', sa.DateTime(), nullable=True, comment='最近一次封面生成成功时间'))
+
+    with op.batch_alter_table('settings', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('cover_api_provider', sa.String(length=50), nullable=True, comment='封面图片API提供商'))
+        batch_op.add_column(sa.Column('cover_api_key', sa.String(length=500), nullable=True, comment='封面图片API密钥'))
+        batch_op.add_column(sa.Column('cover_api_base_url', sa.String(length=500), nullable=True, comment='封面图片自定义API地址'))
+        batch_op.add_column(sa.Column('cover_image_model', sa.String(length=100), nullable=True, comment='封面图片模型名称'))
+        batch_op.add_column(sa.Column('cover_enabled', sa.Boolean(), nullable=False, server_default=sa.text('0'), comment='是否启用封面图片生成'))
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('settings', schema=None) as batch_op:
+        batch_op.drop_column('cover_enabled')
+        batch_op.drop_column('cover_image_model')
+        batch_op.drop_column('cover_api_base_url')
+        batch_op.drop_column('cover_api_key')
+        batch_op.drop_column('cover_api_provider')
+
+    with op.batch_alter_table('projects', schema=None) as batch_op:
+        batch_op.drop_column('cover_updated_at')
+        batch_op.drop_column('cover_error')
+        batch_op.drop_column('cover_status')
+        batch_op.drop_column('cover_prompt')
+        batch_op.drop_column('cover_image_url')
+
+    # ### end Alembic commands ###

backend/app/api/project_covers.py

@@ -0,0 +1,66 @@
+"""项目封面生成与下载 API"""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import FileResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.services.cover_generation_service import cover_generation_service
+
+router = APIRouter(prefix="/projects", tags=["项目封面"])
+
+
+class CoverGenerateRequest(BaseModel):
+    overwrite: bool = Field(default=True, description="是否覆盖已有封面")
+
+
+class CoverGenerateResponse(BaseModel):
+    project_id: str
+    cover_status: str
+    cover_image_url: str | None = None
+    cover_prompt: str | None = None
+    provider: str | None = None
+    model: str | None = None
+    message: str
+
+
+@router.post("/{project_id}/cover/generate", response_model=CoverGenerateResponse, summary="生成项目封面")
+async def generate_project_cover(
+    project_id: str,
+    payload: CoverGenerateRequest,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+):
+    user_id = getattr(request.state, "user_id", None)
+    if not user_id:
+        raise HTTPException(status_code=401, detail="未登录")
+
+    result = await cover_generation_service.generate_cover(
+        db=db,
+        user_id=user_id,
+        project_id=project_id,
+        overwrite=payload.overwrite,
+    )
+    return CoverGenerateResponse(**result)
+
+
+@router.get("/{project_id}/cover/download", summary="下载项目封面")
+async def download_project_cover(
+    project_id: str,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+):
+    user_id = getattr(request.state, "user_id", None)
+    if not user_id:
+        raise HTTPException(status_code=401, detail="未登录")
+
+    project, file_path = await cover_generation_service.get_cover_download_path(
+        db=db,
+        user_id=user_id,
+        project_id=project_id,
+    )
+    suffix = file_path.suffix or ".png"
+    filename = f"{project.title}-cover{suffix}"
+    return FileResponse(path=file_path, filename=filename, media_type="application/octet-stream")

backend/app/api/settings.py

@@ -14,6 +14,7 @@
 
 from app.database import get_db
 from app.models.settings import Settings
+from app.services.cover_generation_service import cover_generation_service
 from app.schemas.settings import (
     SettingsCreate, SettingsUpdate, SettingsResponse,
     APIKeyPreset, APIKeyPresetConfig, PresetCreateRequest,
@@ -29,6 +30,13 @@
 router = APIRouter(prefix="/settings", tags=["设置管理"])
 
 
+class CoverSettingsTestRequest(BaseModel):
+    cover_api_provider: str
+    cover_api_key: str
+    cover_api_base_url: Optional[str] = None
+    cover_image_model: str
+
+
 def read_env_defaults() -> Dict[str, Any]:
     """从.env文件读取默认配置（仅读取，不修改）"""
     return {
@@ -142,6 +150,25 @@ async def get_settings(
     return settings
 
 
+@router.post("/cover/test")
+async def test_cover_settings(
+    data: CoverSettingsTestRequest,
+    user: User = Depends(require_login),
+):
+    result = await cover_generation_service.test_cover_settings(
+        provider=data.cover_api_provider,
+        api_key=data.cover_api_key,
+        api_base_url=data.cover_api_base_url,
+        model=data.cover_image_model,
+    )
+    return {
+        "success": result.success,
+        "message": result.message,
+        "provider": result.provider,
+        "model": result.model,
+    }
+
+
 @router.post("", response_model=SettingsResponse)
 async def save_settings(
     data: SettingsCreate,

backend/app/main.py

@@ -130,7 +130,8 @@ async def db_session_stats():
     wizard_stream, relationships, organizations,
     auth, users, settings, writing_styles, memories,
     mcp_plugins, admin, inspiration, prompt_templates,
-    changelog, careers, foreshadows, prompt_workshop, book_import
+    changelog, careers, foreshadows, prompt_workshop, book_import,
+    project_covers
 )
 
 app.include_router(auth.router, prefix="/api")
@@ -139,6 +140,7 @@ async def db_session_stats():
 app.include_router(admin.router, prefix="/api")
 
 app.include_router(projects.router, prefix="/api")
+app.include_router(project_covers.router, prefix="/api")
 app.include_router(wizard_stream.router, prefix="/api")
 app.include_router(inspiration.router, prefix="/api")
 app.include_router(outlines.router, prefix="/api")
@@ -157,8 +159,12 @@ async def db_session_stats():
 app.include_router(book_import.router, prefix="/api")  # 拆书导入API
 
 static_dir = Path(__file__).parent.parent / "static"
+generated_assets_root_dir = Path(__file__).parent.parent / "storage"
+generated_covers_dir = generated_assets_root_dir / "generated_covers"
+generated_covers_dir.mkdir(parents=True, exist_ok=True)
 if static_dir.exists():
     app.mount("/assets", StaticFiles(directory=str(static_dir / "assets")), name="assets")
+    app.mount("/generated-assets/covers", StaticFiles(directory=str(generated_covers_dir)), name="generated-covers")
 
     @app.get("/{full_path:path}")
     async def serve_spa(full_path: str):

backend/app/models/project.py

@@ -32,6 +32,13 @@ class Project(Base):
     chapter_count = Column(Integer, comment="章节数量")
     narrative_perspective = Column(String(50), comment="叙事视角：first_person/third_person/omniscient")
     character_count = Column(Integer, default=5, comment="角色数量")
+
+    # 封面字段
+    cover_image_url = Column(String(1000), comment="封面图片访问地址")
+    cover_prompt = Column(Text, comment="最近一次生成封面使用的提示词")
+    cover_status = Column(String(20), default="none", nullable=False, comment="封面状态: none/generating/ready/failed")
+    cover_error = Column(Text, comment="最近一次封面生成失败原因")
+    cover_updated_at = Column(DateTime, comment="最近一次封面生成成功时间")
 
     created_at = Column(DateTime, server_default=func.now(), comment="创建时间")
     updated_at = Column(DateTime, server_default=func.now(), onupdate=func.now(), comment="更新时间")
@@ -41,7 +48,11 @@ class Project(Base):
             "outline_mode IN ('one-to-one', 'one-to-many')",
             name='check_outline_mode'
         ),
+        CheckConstraint(
+            "cover_status IN ('none', 'generating', 'ready', 'failed')",
+            name='check_cover_status'
+        ),
     )
 
     def __repr__(self):
-        return f"<Project(id={self.id}, title={self.title})>"
+        return f"<Project(id={self.id}, title={self.title})>"

backend/app/models/settings.py

@@ -1,5 +1,5 @@
 """设置数据模型"""
-from sqlalchemy import Column, String, Text, Float, Integer, DateTime, Index
+from sqlalchemy import Column, String, Text, Float, Integer, DateTime, Boolean, Index
 from sqlalchemy.sql import func
 from app.database import Base
 import uuid
@@ -18,6 +18,14 @@ class Settings(Base):
     temperature = Column(Float, default=0.7, comment="温度参数")
     max_tokens = Column(Integer, default=2000, comment="最大token数")
     system_prompt = Column(Text, comment="系统级别提示词，每次AI调用都会使用")
+
+    # 封面图片生成配置
+    cover_api_provider = Column(String(50), comment="封面图片API提供商")
+    cover_api_key = Column(String(500), comment="封面图片API密钥")
+    cover_api_base_url = Column(String(500), comment="封面图片自定义API地址")
+    cover_image_model = Column(String(100), comment="封面图片模型名称")
+    cover_enabled = Column(Boolean, default=False, server_default="0", nullable=False, comment="是否启用封面图片生成")
+
     preferences = Column(Text, comment="其他偏好设置(JSON)")
     created_at = Column(DateTime, server_default=func.now(), comment="创建时间")
     updated_at = Column(DateTime, server_default=func.now(), onupdate=func.now(), comment="更新时间")
@@ -27,4 +35,4 @@ class Settings(Base):
     )
 
     def __repr__(self):
-        return f"<Settings(id={self.id}, user_id={self.user_id}, api_provider={self.api_provider})>"
+        return f"<Settings(id={self.id}, user_id={self.user_id}, api_provider={self.api_provider})>"

backend/app/schemas/project.py

@@ -55,6 +55,11 @@ class ProjectResponse(ProjectBase):
     chapter_count: Optional[int] = None
     narrative_perspective: Optional[str] = None
     character_count: Optional[int] = None
+    cover_image_url: Optional[str] = None
+    cover_prompt: Optional[str] = None
+    cover_status: Optional[str] = None
+    cover_error: Optional[str] = None
+    cover_updated_at: Optional[datetime] = None
     outline_mode: str  # 显式声明以确保响应中包含
     created_at: datetime
     updated_at: datetime

backend/app/schemas/settings.py

@@ -15,6 +15,11 @@ class SettingsBase(BaseModel):
     temperature: Optional[float] = Field(default=0.7, ge=0.0, le=2.0, description="温度参数")
     max_tokens: Optional[int] = Field(default=2000, ge=1, description="最大token数")
     system_prompt: Optional[str] = Field(default=None, description="系统级别提示词，每次AI调用都会使用")
+    cover_api_provider: Optional[str] = Field(default=None, description="封面图片API提供商")
+    cover_api_key: Optional[str] = Field(default=None, description="封面图片API密钥")
+    cover_api_base_url: Optional[str] = Field(default=None, description="封面图片自定义API地址")
+    cover_image_model: Optional[str] = Field(default=None, description="封面图片模型名称")
+    cover_enabled: Optional[bool] = Field(default=False, description="是否启用封面图片生成")
     preferences: Optional[str] = Field(default=None, description="其他偏好设置(JSON)")