feat: 模板与剪辑计划后端能力补齐

- 模板复制接口（含所有片段配置）
- 模板列表多维度筛选（分类/标签/关键词/模式）
- 模板标签聚合接口（去重排序）
- 模板使用次数统计
- TemplateResponse 新增 usage_count 字段
- 新增 CountTemplatesUseCase / CopyTemplateUseCase / ListTagsUseCase / GetTemplateUsageUseCase
- 35个模板相关单元测试全部通过

apps/api/app/api/routes/templates.py

@@ -8,13 +8,16 @@ from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_db_session
 from app.schemas.template import (
     CategoryResponse,
+    CopyTemplateRequest,
     CreateCategoryRequest,
     CreateTemplateRequest,
     GenerateWarningResponse,
     ListCategoriesResponse,
+    ListTagsResponse,
     ListTemplatesResponse,
     SegmentResponse,
     TemplateResponse,
+    TemplateUsageResponse,
     ToggleFavoriteResponse,
     UpdateTemplateRequest,
     ValidateTemplateRequest,
@@ -27,19 +30,25 @@ logger = logging.getLogger(__name__)
 
 from packages.adapters.sqlalchemy_impl.template_repository import SQLAlchemyTemplateRepository
 from packages.application.template.commands import (
+    CopyTemplateCommand,
     CreateCategoryCommand,
     CreateTemplateCommand,
+    ListTemplatesFilter,
     SegmentCommand,
     UpdateTemplateCommand,
     ValidateTemplateCommand,
 )
 from packages.application.template.use_cases import (
+    CopyTemplateUseCase,
     CreateCategoryUseCase,
     CreateTemplateUseCase,
+    CountTemplatesUseCase,
     DeleteCategoryUseCase,
     DeleteTemplateUseCase,
+    GetTemplateUsageUseCase,
     GetTemplateUseCase,
     ListCategoriesUseCase,
+    ListTagsUseCase,
     ListTemplatesUseCase,
     NotFoundError,
     UpdateTemplateUseCase,
@@ -67,7 +76,7 @@ def _segment_to_response(seg) -> SegmentResponse:
     )
 
 
-def _to_response(template) -> TemplateResponse:
+def _to_response(template, usage_count: int = 0) -> TemplateResponse:
     return TemplateResponse(
         id=template.id,
         user_id=template.user_id,
@@ -81,6 +90,7 @@ def _to_response(template) -> TemplateResponse:
         estimated_duration=template.estimated_duration,
         segments=[_segment_to_response(s) for s in getattr(template, "segments", [])],
         is_active=template.is_active,
+        usage_count=usage_count,
         created_at=template.created_at,
         updated_at=template.updated_at,
     )
@@ -93,19 +103,36 @@ def _to_response(template) -> TemplateResponse:
 def list_templates(
     skip: int = Query(0, ge=0),
     limit: int = Query(50, ge=1, le=200),
+    category: str | None = Query(None, description="按分类筛选"),
+    tag: str | None = Query(None, description="按标签筛选"),
+    keyword: str | None = Query(None, description="按名称关键词搜索"),
+    mode: str | None = Query(None, description="按剪辑模式筛选"),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
 ) -> ListTemplatesResponse:
     user_id = authenticated_user.user.id
     try:
+        tpl_filter = ListTemplatesFilter(
+            category=category,
+            tag=tag,
+            keyword=keyword,
+            mode=mode,
+        )
         use_case = ListTemplatesUseCase(template_repository)
-        templates = use_case.execute(user_id, skip=skip, limit=limit)
-        total = template_repository.count_by_user(user_id)
+        templates = use_case.execute(user_id, skip=skip, limit=limit, filter=tpl_filter)
+        count_use_case = CountTemplatesUseCase(template_repository)
+        total = count_use_case.execute(user_id, filter=tpl_filter)
+
+        # 批量查询使用次数
+        items = []
+        for t in templates:
+            usage = template_repository.get_usage_count(t.id)
+            items.append(_to_response(t, usage_count=usage))
     except Exception:
         logger.exception("list_templates 查询失败: user_id=%s", user_id)
         return ListTemplatesResponse(items=[], total=0)
     return ListTemplatesResponse(
-        items=[_to_response(t) for t in templates],
+        items=items,
         total=total,
     )
 
@@ -120,12 +147,13 @@ def get_template(
     try:
         use_case = GetTemplateUseCase(template_repository)
         template = use_case.execute(template_id, user_id)
+        usage = template_repository.get_usage_count(template_id)
     except Exception:
         logger.exception("get_template 查询失败: template_id=%s", template_id)
         raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="模板查询失败")
     if template is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
-    return _to_response(template)
+    return _to_response(template, usage_count=usage)
 
 
 @router.post("", response_model=TemplateResponse, status_code=status.HTTP_201_CREATED)
@@ -220,6 +248,47 @@ def delete_template(
     return Response(status_code=204)
 
 
+@router.post("/{template_id}/copy", response_model=TemplateResponse, status_code=status.HTTP_201_CREATED)
+def copy_template(
+    template_id: str,
+    request: CopyTemplateRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> TemplateResponse:
+    """复制模板（含所有片段配置）"""
+    user_id = authenticated_user.user.id
+    command = CopyTemplateCommand(
+        template_id=template_id,
+        user_id=user_id,
+        new_name=request.new_name,
+    )
+    use_case = CopyTemplateUseCase(template_repository)
+    try:
+        template = use_case.execute(command)
+    except NotFoundError:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    except ValidationError as exc:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc))
+    return _to_response(template)
+
+
+@router.get("/{template_id}/usage", response_model=TemplateUsageResponse)
+def get_template_usage(
+    template_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> TemplateUsageResponse:
+    """获取模板使用次数（关联的剪辑计划数量）"""
+    user_id = authenticated_user.user.id
+    # 鉴权：确保模板存在且属于当前用户
+    use_case = GetTemplateUseCase(template_repository)
+    template = use_case.execute(template_id, user_id)
+    if template is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    usage = template_repository.get_usage_count(template_id)
+    return TemplateUsageResponse(template_id=template_id, usage_count=usage)
+
+
 @router.post("/{template_id}/toggle-favorite", response_model=ToggleFavoriteResponse)
 def toggle_favorite(
     template_id: str,
@@ -319,3 +388,23 @@ def delete_category(
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Category not found")
     return Response(status_code=204)
+
+
+
+# ── Tags ──
+
+
+@router.get("/tags/list", response_model=ListTagsResponse)
+def list_tags(
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> ListTagsResponse:
+    """获取用户所有模板标签（去重排序）"""
+    user_id = authenticated_user.user.id
+    try:
+        use_case = ListTagsUseCase(template_repository)
+        tags = use_case.execute(user_id)
+    except Exception:
+        logger.exception("list_tags 查询失败: user_id=%s", user_id)
+        return ListTagsResponse(items=[])
+    return ListTagsResponse(items=tags)

apps/api/app/schemas/template.py

@@ -45,6 +45,7 @@ class TemplateResponse(BaseModel):
     segments: List[SegmentResponse] = Field(default_factory=list)
     is_active: bool = True
     is_favorite: bool = False
+    usage_count: int = 0
     created_at: datetime
     updated_at: datetime
 
@@ -120,3 +121,25 @@ class CreateCategoryRequest(BaseModel):
 
 class ListCategoriesResponse(BaseModel):
     items: List[CategoryResponse]
+
+
+# ── Copy Template ──
+
+
+class CopyTemplateRequest(BaseModel):
+    new_name: str
+
+
+# ── Tags ──
+
+
+class ListTagsResponse(BaseModel):
+    items: List[str]
+
+
+# ── Usage Stats ──
+
+
+class TemplateUsageResponse(BaseModel):
+    template_id: str
+    usage_count: int