xiaoxia-saas/apps/api/app/api/routes/assets.py

import logging
from typing import Any, Optional

from app.api.routes._helpers import check_project_access, format_utc_datetime
from app.auth import AuthenticatedUser, get_current_user
from app.core.storage import get_storage_service
from app.dependencies import (
    get_asset_library_repository,
    get_asset_repository,
    get_project_repository,
    get_tag_repository,
)
from app.schemas.asset import (
    AssetResponse,
    BatchClassifyRequest,
    BatchDeleteRequest,
    BatchGetRequest,
    BatchMarkRequest,
    BatchOperationResponse,
    BatchTagRequest,
    ListAssetsResponse,
    SmartMatchItem,
    SmartMatchRequest,
    SmartMatchResponse,
    UpdateAssetRequest,
    UpdateAssetReviewRequest,
)
from app.schemas.tag import TagAssetsRequest
from app.services.asset_segment_tracker import compute_asset_availability, get_asset_recent_use_counts
from fastapi import APIRouter, Depends, HTTPException, Query, Response

from packages.domain.smart_match import smart_select_assets

logger = logging.getLogger(__name__)

router = APIRouter()


def _asset_availability_fields(item) -> dict:
    """视频素材返回余量四字段；非视频/无时长/异常时返回 None + usable=True（零影响）。"""
    try:
        info = compute_asset_availability(item)
    except Exception:
        logger.warning("计算素材余量失败，按可用处理: asset_id=%s", getattr(item, "id", "?"), exc_info=True)
        info = None
    if info is None:
        return {
            "used_duration": None,
            "available_duration": None,
            "used_ratio": None,
            "usable": True,
        }
    return info


def _to_asset_response(item, storage_service=None) -> AssetResponse:
    # 生成签名文件 URL（用于视频播放 / 文件下载）
    file_url = None
    if item.storage_key:
        try:
            svc = storage_service or get_storage_service()
            file_url = svc.get_download_url(item.storage_key)
        except Exception:
            logger.warning("生成签名URL失败: storage_key=%s", item.storage_key, exc_info=True)
            file_url = None

    # 缩略图：存储的是 storage_key，需要生成签名 URL 供前端使用
    # 不再降级使用视频文件 URL（浏览器 <img> 无法渲染 .mp4，会显示黑屏）
    thumbnail_url = None
    if item.thumbnail_url:
        try:
            svc = storage_service or get_storage_service()
            thumbnail_url = svc.get_download_url(item.thumbnail_url)
        except Exception:
            logger.warning("生成缩略图签名URL失败: key=%s", item.thumbnail_url, exc_info=True)
            thumbnail_url = None

    return AssetResponse(
        id=item.id,
        project_id=item.project_id,
        library_id=item.library_id,
        name=item.name,
        storage_key=item.storage_key,
        mime_type=item.mime_type,
        metadata=item.metadata,
        file_size=item.file_size,
        file_url=file_url,
        thumbnail_url=thumbnail_url,
        duration=item.duration,
        width=item.width,
        height=item.height,
        fps=item.fps,
        codec=item.codec,
        status=item.status.value,
        classification_status=item.classification_status.value,
        quality_score=item.quality_score,
        created_at=format_utc_datetime(item.created_at),
        uploaded_by_user_id=item.uploaded_by_user_id,
        tag_ids=getattr(item, "tag_ids", []),
        **_asset_availability_fields(item),
    )


@router.get("", response_model=ListAssetsResponse)
def list_assets(
    library_id: Optional[str] = Query(None),
    project_id: Optional[str] = Query(None),
    kind: Optional[str] = Query(None, pattern="^(video|voice|image)$"),
    keyword: Optional[str] = Query(None, description="按名称模糊匹配"),
    gender: Optional[str] = Query(None, description="按 metadata.gender 筛选"),
    style: Optional[str] = Query(None, description="按 metadata.style 筛选"),
    tag_ids: Optional[str] = Query(None, description="按标签 ID 筛选（逗号分隔，取交集）"),
    smart_view: Optional[str] = Query(
        None,
        description="智能视图筛选：recommended=推荐(质量分≥80)、cautious=慎用(60-79)、risky=高风险(<60或已驳回)、unused=未使用、used=已使用、pending_review=待复核",
        pattern="^(recommended|cautious|risky|unused|used|pending_review)$",
    ),
    classification: Optional[str] = Query(
        None,
        description="按内容分类筛选：scenic=风景、product=产品、person=人物、animal=动物、food=美食、tech=科技、sport=运动、music=音乐、other=其他",
    ),
    status: Optional[str] = Query(
        "default",
        description="按状态筛选，逗号分隔多值；默认返回除deleted外的所有状态；传deleted查看回收站；传all返回所有状态",
    ),
    page: Optional[int] = Query(None, ge=1, description="页码，从1开始；与 page_size 配对使用，优先于 skip/limit"),
    page_size: Optional[int] = Query(None, ge=1, le=500, description="每页数量；与 page 配对使用"),
    skip: int = Query(0, ge=0),
    limit: int = Query(100, ge=1, le=500),
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    asset_library_repository: Any = Depends(get_asset_library_repository),
    project_repository: Any = Depends(get_project_repository),
) -> ListAssetsResponse:
    user_id = authenticated_user.user.id

    # ── 分页：page/page_size 优先于 skip/limit
    if page is not None and page_size is not None:
        skip = (page - 1) * page_size
        limit = page_size

    # ── 解析 status 过滤
    status_list: list[str] | None
    if status and status.lower() == "all":
        status_list = None  # None = 不过滤，返回所有状态
    elif status and status.lower() == "deleted":
        status_list = ["deleted"]  # 仅查回收站
    elif status and status.lower() == "default":
        status_list = ["ready", "uploading", "processing", "error"]  # 默认排除deleted
    elif status:
        status_list = [s.strip() for s in status.split(",") if s.strip()]
        if not status_list:
            status_list = ["ready", "uploading", "processing", "error"]
    else:
        status_list = ["ready", "uploading", "processing", "error"]

    # kind → file_type 映射（voice 对应 audio）
    kind_to_file_type = {"video": "video", "voice": "audio", "image": "image"}

    # 解析 tag_ids 参数（逗号分隔）
    filter_tag_ids: list[str] | None = None
    if tag_ids:
        filter_tag_ids = [t.strip() for t in tag_ids.split(",") if t.strip()]
        if not filter_tag_ids:
            filter_tag_ids = None

    # 需要内存过滤的标志（keyword/gender/style/tag_ids/smart_view/classification 无法在 DB 层过滤）
    needs_memory_filter = bool(keyword or gender or style or filter_tag_ids or smart_view or classification)

    def _apply_memory_filters(items):
        """应用 keyword / gender / style / tag_ids / smart_view / classification 内存过滤。"""
        result = items
        if keyword:
            kw = keyword.lower()
            result = [i for i in result if kw in (i.name or "").lower()]
        if gender:
            result = [i for i in result if (i.metadata or {}).get("gender") == gender]
        if style:
            result = [i for i in result if (i.metadata or {}).get("style") == style]
        if classification:
            result = [i for i in result if (i.metadata or {}).get("classification") == classification]
        if filter_tag_ids:
            tag_set = set(filter_tag_ids)
            result = [i for i in result if tag_set.issubset(set(getattr(i, "tag_ids", [])))]
        if smart_view:

            def __meta(a):
                return a.metadata or {}

            def __use_count(a):
                return int(__meta(a).get("generation_use_count") or 0)

            def __review_status(a):
                return __meta(a).get("review_status", "")

            if smart_view == "recommended":
                result = [i for i in result if i.quality_score is not None and i.quality_score >= 80]
            elif smart_view == "cautious":
                result = [i for i in result if i.quality_score is not None and 60 <= i.quality_score < 80]
            elif smart_view == "risky":
                result = [
                    i
                    for i in result
                    if (i.quality_score is not None and i.quality_score < 60) or __review_status(i) == "rejected"
                ]
            elif smart_view == "unused":
                result = [i for i in result if __use_count(i) == 0]
            elif smart_view == "used":
                result = [i for i in result if __use_count(i) > 0]
            elif smart_view == "pending_review":
                result = [i for i in result if __review_status(i) == "pending_review"]
        return result

    # ── 优化路径：无内存过滤时，使用 DB 级分页 ──
    if not needs_memory_filter:
        ft = kind_to_file_type.get(kind) if kind else None

        # 模式1：指定 library_id
        if library_id:
            library = asset_library_repository.get(library_id)
            if library is None:
                raise HTTPException(status_code=404, detail=f"AssetLibrary {library_id} not found")
            check_project_access(library.project_id, user_id, project_repository)
            if ft:
                items = asset_repository.find_by_library_and_file_type(
                    library_id, ft, skip=skip, limit=limit, status=status_list
                )
                total = asset_repository.count_by_library_and_file_type(library_id, ft, status=status_list)
            else:
                items = asset_repository.find_by_library(library_id, skip=skip, limit=limit, status=status_list)
                total = asset_repository.count_by_project(library.project_id, status=status_list)
            return ListAssetsResponse(
                items=[_to_asset_response(item) for item in items],
                total=total,
                skip=skip,
                limit=limit,
            )

        # 模式2：指定 project_id
        if project_id:
            check_project_access(project_id, user_id, project_repository)
            if ft:
                items = asset_repository.find_by_project_and_file_type(
                    project_id, ft, skip=skip, limit=limit, status=status_list
                )
                total = asset_repository.count_by_project_and_file_type(project_id, ft, status=status_list)
                paged = items
            else:
                items = asset_repository.find_by_project(project_id, skip=skip, limit=limit, status=status_list)
                total = asset_repository.count_by_project(project_id, status=status_list)
                paged = items
            return ListAssetsResponse(
                items=[_to_asset_response(item) for item in paged],
                total=total,
                skip=skip,
                limit=limit,
            )

        # 模式3：跨项目（无 library_id/project_id）
        try:
            projects = project_repository.find_accessible_projects(user_id)
        except Exception:
            logger.exception("查询用户可访问项目失败: user_id=%s", user_id)
            return ListAssetsResponse(items=[], total=0, skip=skip, limit=limit)

        project_ids = [p.id for p in projects]
        if not project_ids:
            return ListAssetsResponse(items=[], total=0, skip=skip, limit=limit)

        if ft:
            # 有 kind 过滤：逐项目查 file_type，凑够一页
            total = 0
            paged_items: list = []
            offset = skip
            remaining = limit
            for pid in project_ids:
                proj_total = asset_repository.count_by_project_and_file_type(pid, ft, status=status_list)
                total += proj_total
                if offset >= proj_total:
                    offset -= proj_total
                    continue
                proj_items = asset_repository.find_by_project_and_file_type(
                    pid, ft, skip=offset, limit=remaining, status=status_list
                )
                paged_items.extend(proj_items)
                remaining -= len(proj_items)
                offset = 0
                if remaining <= 0:
                    break
        else:
            total = asset_repository.count_by_project_ids(project_ids, status=status_list)
            # 跨项目分页：逐项目累积直到凑够一页
            paged_items = []
            offset = skip
            remaining = limit
            for pid in project_ids:
                proj_total = asset_repository.count_by_project(pid, status=status_list)
                if offset >= proj_total:
                    offset -= proj_total
                    continue
                proj_items = asset_repository.find_by_project(pid, skip=offset, limit=remaining, status=status_list)
                paged_items.extend(proj_items)
                remaining -= len(proj_items)
                offset = 0
                if remaining <= 0:
                    break

        return ListAssetsResponse(
            items=[_to_asset_response(item) for item in paged_items],
            total=total,
            skip=skip,
            limit=limit,
        )

    # ── 内存过滤路径：有 keyword/gender/style 时，加载全量后内存过滤 ──
    if library_id:
        library = asset_library_repository.get(library_id)
        if library is None:
            raise HTTPException(status_code=404, detail=f"AssetLibrary {library_id} not found")
        check_project_access(library.project_id, user_id, project_repository)
        if kind:
            all_items = asset_repository.find_by_library_and_file_type(
                library_id, kind_to_file_type[kind], status=status_list
            )
        else:
            all_items = asset_repository.find_by_library(library_id, status=status_list)
    elif project_id:
        check_project_access(project_id, user_id, project_repository)
        if kind:
            ft = kind_to_file_type.get(kind)
            if ft:
                all_items = asset_repository.find_by_project_and_file_type(project_id, ft, status=status_list)
            else:
                all_items = asset_repository.find_by_project(project_id, status=status_list)
        else:
            all_items = asset_repository.find_by_project(project_id, status=status_list)
    else:
        try:
            projects = project_repository.find_accessible_projects(user_id)
        except Exception:
            logger.exception("查询用户可访问项目失败: user_id=%s", user_id)
            return ListAssetsResponse(items=[], total=0, skip=skip, limit=limit)
        all_items = []
        for proj in projects:
            if kind and kind_to_file_type.get(kind):
                all_items.extend(
                    asset_repository.find_by_project_and_file_type(proj.id, kind_to_file_type[kind], status=status_list)
                )
            else:
                all_items.extend(asset_repository.find_by_project(proj.id, status=status_list))

    # 应用 kind 过滤（如果有）+ keyword/gender/style
    if kind:
        ft = kind_to_file_type.get(kind)
        if ft:
            all_items = [i for i in all_items if i.file_type == ft]
    filtered = _apply_memory_filters(all_items)
    total = len(filtered)
    paged = filtered[skip : skip + limit]
    return ListAssetsResponse(
        items=[_to_asset_response(item) for item in paged],
        total=total,
        skip=skip,
        limit=limit,
    )


def _apply_asset_review_status(item, review_status: str):
    item.metadata = {
        **item.metadata,
        "review_status": review_status,
    }
    return item


@router.patch("/{asset_id}/review", response_model=AssetResponse)
def update_asset_review_status(
    asset_id: str,
    request: UpdateAssetReviewRequest,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    project_repository: Any = Depends(get_project_repository),
) -> AssetResponse:
    item = asset_repository.get(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
    _apply_asset_review_status(item, request.review_status)
    updated = asset_repository.update(item)
    return _to_asset_response(updated)


@router.post("/batch", response_model=list[AssetResponse])
def batch_get_assets(
    request: BatchGetRequest,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
) -> list[AssetResponse]:
    """批量获取素材详情（根据 ID 列表）。"""
    items = asset_repository.find_by_ids(request.ids)
    storage_service = get_storage_service()
    return [_to_asset_response(item, storage_service) for item in items]


@router.post("/batch-delete", response_model=BatchOperationResponse)
def batch_delete_assets(
    request: BatchDeleteRequest,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    project_repository: Any = Depends(get_project_repository),
) -> BatchOperationResponse:
    """批量删除素材（软删除，标记 status=deleted），需逐项校验项目权限。"""
    user_id = authenticated_user.user.id
    success_ids: list[str] = []
    failed_details: dict[str, str] = {}

    for asset_id in request.asset_ids:
        item = asset_repository.find_by_id(asset_id)
        if item is None:
            failed_details[asset_id] = "not_found"
            continue
        try:
            check_project_access(item.project_id, user_id, project_repository)
            success_ids.append(asset_id)
        except HTTPException:
            failed_details[asset_id] = "access_denied"

    if success_ids:
        asset_repository.batch_delete(success_ids)

    return BatchOperationResponse(
        success_count=len(success_ids),
        failed_ids=list(failed_details.keys()),
        failed_details=failed_details,
    )


@router.post("/batch-tag", response_model=BatchOperationResponse)
def batch_tag_assets(
    request: BatchTagRequest,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    project_repository: Any = Depends(get_project_repository),
    tag_repository: Any = Depends(get_tag_repository),
) -> BatchOperationResponse:
    """批量打标签（添加或替换模式），需逐项校验项目权限和标签权限。"""
    user_id = authenticated_user.user.id
    success_ids: list[str] = []
    failed_details: dict[str, str] = {}

    # 校验标签存在且属于当前用户
    for tag_id in request.tag_ids:
        tag = tag_repository.get(tag_id)
        if tag is None:
            return BatchOperationResponse(
                success_count=0,
                failed_ids=list(request.asset_ids),
                failed_details={aid: f"tag_not_found:{tag_id}" for aid in request.asset_ids},
            )
        if tag.user_id != user_id:
            return BatchOperationResponse(
                success_count=0,
                failed_ids=list(request.asset_ids),
                failed_details={aid: f"tag_access_denied:{tag_id}" for aid in request.asset_ids},
            )

    # 校验素材权限
    for asset_id in request.asset_ids:
        item = asset_repository.find_by_id(asset_id)
        if item is None:
            failed_details[asset_id] = "not_found"
            continue
        try:
            check_project_access(item.project_id, user_id, project_repository)
            success_ids.append(asset_id)
        except HTTPException:
            failed_details[asset_id] = "access_denied"

    if success_ids:
        if request.mode == "replace":
            asset_repository.batch_replace_tags(success_ids, request.tag_ids)
        else:
            asset_repository.batch_add_tags(success_ids, request.tag_ids)

    return BatchOperationResponse(
        success_count=len(success_ids),
        failed_ids=list(failed_details.keys()),
        failed_details=failed_details,
    )


@router.post("/batch-classify", response_model=BatchOperationResponse)
def batch_classify_assets(
    request: BatchClassifyRequest,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    project_repository: Any = Depends(get_project_repository),
) -> BatchOperationResponse:
    """批量修改素材内容分类（person/scenic/product等），存在metadata.category中。"""
    user_id = authenticated_user.user.id
    success_ids: list[str] = []
    failed_details: dict[str, str] = {}

    for asset_id in request.asset_ids:
        item = asset_repository.find_by_id(asset_id)
        if item is None:
            failed_details[asset_id] = "not_found"
            continue
        try:
            check_project_access(item.project_id, user_id, project_repository)
            success_ids.append(asset_id)
        except HTTPException:
            failed_details[asset_id] = "access_denied"

    if success_ids:
        asset_repository.batch_update_metadata(success_ids, {"category": request.category})

    return BatchOperationResponse(
        success_count=len(success_ids),
        failed_ids=list(failed_details.keys()),
        failed_details=failed_details,
    )


@router.post("/batch-mark", response_model=BatchOperationResponse)
def batch_mark_assets(
    request: BatchMarkRequest,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    project_repository: Any = Depends(get_project_repository),
) -> BatchOperationResponse:
    """批量设置智能视图标记（recommended/caution/high_risk），存在metadata.smart_view中。"""
    user_id = authenticated_user.user.id
    success_ids: list[str] = []
    failed_details: dict[str, str] = {}

    for asset_id in request.asset_ids:
        item = asset_repository.find_by_id(asset_id)
        if item is None:
            failed_details[asset_id] = "not_found"
            continue
        try:
            check_project_access(item.project_id, user_id, project_repository)
            success_ids.append(asset_id)
        except HTTPException:
            failed_details[asset_id] = "access_denied"

    if success_ids:
        asset_repository.batch_update_metadata(success_ids, {"smart_view": request.smart_view})

    return BatchOperationResponse(
        success_count=len(success_ids),
        failed_ids=list(failed_details.keys()),
        failed_details=failed_details,
    )


@router.post("/smart-match", response_model=SmartMatchResponse)
def smart_match_assets(
    request: SmartMatchRequest,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    asset_library_repository: Any = Depends(get_asset_library_repository),
    project_repository: Any = Depends(get_project_repository),
) -> SmartMatchResponse:
    """智能选素材：根据素材库内容，按质量分+时长均衡+新鲜度+未使用偏好综合评分，返回 Top N 素材。"""
    library = asset_library_repository.get(request.library_id)
    if library is None:
        raise HTTPException(status_code=404, detail=f"AssetLibrary {request.library_id} not found")
    check_project_access(library.project_id, authenticated_user.user.id, project_repository)

    # 获取素材库中所有 ready 素材（DB 层按 kind 过滤，避免加载不必要的数据到内存）
    # kind → file_type 映射：schema 已校验只允许 video/image/audio，与 file_type 一致
    if request.kind:
        filtered_assets = asset_repository.find_by_library_and_file_type(
            request.library_id, request.kind, status=["ready"], limit=10000
        )
    else:
        filtered_assets = asset_repository.find_by_library(request.library_id, status=["ready"], limit=10000)
    total_candidates = len(filtered_assets)

    # ── 过滤前置：余量 + 高频使用，过滤在评分/截取 limit 之前完成 ──────────
    # 旧实现先 smart_select_assets(limit=N) 再对这 N 条做过滤，过滤后不回补，
    # 当排名靠前的素材恰好都被排除时返回空 items（前端回退全选，smart-match 名存实亡）。
    # 现在先过滤全量候选，每级过滤后为空/不足则回退上一级，最后才评分截取。

    # 1) 余量过滤：usable=False（零重复可切区间耗尽且历史区间均达复用上限）的素材排除
    usable_assets = []
    exhausted_assets = []
    for a in filtered_assets:
        try:
            avail = compute_asset_availability(a)
        except Exception:
            logger.warning(
                "smart-match 余量计算失败，按可用处理: asset_id=%s",
                getattr(a, "id", "?"),
                exc_info=True,
            )
            avail = None
        if avail is not None and not avail["usable"]:
            exhausted_assets.append(a)
        else:
            usable_assets.append(a)

    if exhausted_assets:
        logger.info(
            "smart-match 余量过滤: 候选 %d，可切区间耗尽 %d",
            len(filtered_assets), len(exhausted_assets),
        )

    # 回退策略：余量过滤后为空（全部耗尽）时，保留全部候选，不返回空结果。
    # 宁可让用户在已耗尽素材上复用，也比 smart-match 空结果回退全选更可控
    # （全选同样会选到这些素材，且不经过评分排序）。
    pool = usable_assets if usable_assets else filtered_assets

    # 2) 高频使用排除：同一素材在最近 5 个视频中出现超过 3 次则排除
    MAX_RECENT_USE_COUNT = 3
    high_freq_assets = set()
    if pool:
        asset_ids = [getattr(a, "id", "") for a in pool if getattr(a, "id", "")]
        if asset_ids:
            try:
                use_counts = get_asset_recent_use_counts(
                    db=asset_repository.session,
                    asset_ids=asset_ids,
                    recent_video_count=5,
                )
                for a in pool:
                    aid = getattr(a, "id", "")
                    count = use_counts.get(aid, 0)
                    if count > MAX_RECENT_USE_COUNT:
                        high_freq_assets.add(aid)
                        logger.info(
                            "smart-match 排除高频使用素材: asset_id=%s use_count=%d limit=%d",
                            aid, count, MAX_RECENT_USE_COUNT,
                        )
                # 回退策略：排除后剩余素材不足（为空或不够 limit）时，
                # 不再全部排除，保留全部可用素材
                if high_freq_assets:
                    remaining_count = len(pool) - len(high_freq_assets)
                    enough = request.limit is None or remaining_count >= request.limit
                    if remaining_count > 0 and enough:
                        pool = [a for a in pool if getattr(a, "id", "") not in high_freq_assets]
                    else:
                        logger.info(
                            "smart-match 高频排除后素材不足(%d<%s)，保留全部 %d 条",
                            remaining_count,
                            request.limit if request.limit is not None else "不限",
                            len(pool),
                        )
            except Exception:
                logger.warning("smart-match 高频使用查询失败，跳过排除", exc_info=True)

    # 3) 调用统一智能选素材算法（kind 已在 DB 层过滤，无需重复过滤）
    results = smart_select_assets(pool, limit=request.limit, kind=None)

    # 扁平结构：SmartMatchItem 继承 AssetResponse，素材字段直接在条目顶层，
    # 前端无需解析 item.asset 包装层，item.id / item.usable / 余量字段直接可读
    items = [
        SmartMatchItem(
            **_to_asset_response(r.asset).model_dump(),
            score=r.score,
            breakdown=r.breakdown,
        )
        for r in results
    ]

    return SmartMatchResponse(items=items, total_candidates=total_candidates)


@router.get("/{asset_id}", response_model=AssetResponse)
def get_asset(
    asset_id: str,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    project_repository: Any = Depends(get_project_repository),
) -> AssetResponse:
    item = asset_repository.find_by_id(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
    return _to_asset_response(item)


@router.put("/{asset_id}", response_model=AssetResponse)
def update_asset(
    asset_id: str,
    request: UpdateAssetRequest,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    project_repository: Any = Depends(get_project_repository),
) -> AssetResponse:
    item = asset_repository.find_by_id(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
    check_project_access(item.project_id, authenticated_user.user.id, project_repository)

    # 合并可修改字段
    if request.name is not None:
        item.name = request.name
    if request.metadata is not None:
        item.metadata = {**item.metadata, **request.metadata}
    if request.tags is not None:
        item.metadata = {**item.metadata, "tags": request.tags}

    updated = asset_repository.update(item)
    return _to_asset_response(updated)


@router.delete("/{asset_id}", status_code=204, response_class=Response)
def delete_asset(
    asset_id: str,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    project_repository: Any = Depends(get_project_repository),
) -> None:
    item = asset_repository.find_by_id(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
    asset_repository.delete(asset_id)


@router.post("/{asset_id}/tags", response_model=AssetResponse)
def tag_asset(
    asset_id: str,
    request: TagAssetsRequest,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    project_repository: Any = Depends(get_project_repository),
    tag_repository: Any = Depends(get_tag_repository),
) -> AssetResponse:
    """给素材打标签。"""
    item = asset_repository.find_by_id(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
    for tag_id in request.tag_ids:
        tag = tag_repository.get(tag_id)
        if tag is None:
            raise HTTPException(status_code=404, detail=f"Tag {tag_id} not found")
        if tag.user_id != authenticated_user.user.id:
            raise HTTPException(status_code=403, detail=f"无权使用标签 {tag_id}")
        item.add_tag(tag_id)
    updated = asset_repository.update(item)
    return _to_asset_response(updated)


@router.delete("/{asset_id}/tags/{tag_id}", status_code=204, response_class=Response)
def untag_asset(
    asset_id: str,
    tag_id: str,
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
    asset_repository: Any = Depends(get_asset_repository),
    project_repository: Any = Depends(get_project_repository),
) -> None:
    """取消素材的标签。"""
    item = asset_repository.find_by_id(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
    item.remove_tag(tag_id)
    asset_repository.update(item)


@router.post("", response_model=AssetResponse)
def create_asset() -> None:
    """
    已废弃接口。
    所有素材上传统一走 uploadAssetDirect → completeDirectUpload → ingest-jobs 流程。
    """
    raise HTTPException(
        status_code=410,
        detail="此接口已废弃。请使用 uploadAssetDirect 接口上传素材，Worker 会自动处理（视频转码、图片/音频元数据提取）并创建 Asset 记录。",
    )