1

video-gen-api/app/api/admin/private_portrait.py

@@ -10,127 +10,59 @@ from app.dependencies import get_admin_user, get_db
 from app.models.user import User
 from app.schemas.private_portrait import (
     PrivatePortraitAdminConfigUpdate,
+    PrivatePortraitAdminStatsOut,
     PrivatePortraitAssetListOut,
     PrivatePortraitConfigOut,
     PrivatePortraitProjectListOut,
 )
 from app.services.operation_log import log_operation
-from app.services.private_portrait.asset_service import (
-    asset_to_out,
-    get_user_private_portrait_config,
-    list_assets,
-    set_user_private_portrait_limit,
-)
-from app.services.private_portrait.project_service import list_projects, project_to_out
+from app.services.private_portrait.admin.asset_query_service import admin_list_assets
+from app.services.private_portrait.admin.project_query_service import admin_list_projects
+from app.services.private_portrait.admin.stats_query_service import admin_get_private_portrait_stats
+from app.services.private_portrait.quota_service import get_user_private_portrait_config, set_user_private_portrait_limit
 
-router = APIRouter(prefix="/admin/private-portrait", tags=["admin-private-portrait"])
+router = APIRouter(prefix="/admin/private-portrait", tags=["管理后台-私域人像素材库"])
 
 
 def _json_detail(data: dict[str, Any]) -> str:
     return json.dumps(data, ensure_ascii=False, default=str)
 
 
-@router.get("/users/{user_id}/config", response_model=PrivatePortraitConfigOut)
-async def admin_get_private_portrait_config(
-    user_id: str,
-    admin: User = Depends(get_admin_user),
-    db: AsyncSession = Depends(get_db),
-):
+@router.get("/users/{user_id}/config", response_model=PrivatePortraitConfigOut, summary="管理后台：查看用户私域人像素材额度")
+async def admin_get_private_portrait_config(user_id: str, admin: User = Depends(get_admin_user), db: AsyncSession = Depends(get_db)):
     config = await get_user_private_portrait_config(db, user_id=user_id)
-    await log_operation(
-        db,
-        admin.id,
-        admin.username,
-        "查看真人素材库配置",
-        "GET",
-        f"/admin/private-portrait/users/{user_id}/config",
-        detail=_json_detail({"target_user_id": user_id, "config": config.model_dump(mode="json")}),
-    )
+    await log_operation(db, admin.id, admin.username, "查看私域人像素材库配置", "GET", f"/admin/private-portrait/users/{user_id}/config", detail=_json_detail({"target_user_id": user_id, "config": config.model_dump(mode="json")}))
     return config
 
 
-@router.put("/users/{user_id}/config", response_model=PrivatePortraitConfigOut)
-async def admin_update_private_portrait_config(
-    user_id: str,
-    payload: PrivatePortraitAdminConfigUpdate,
-    admin: User = Depends(get_admin_user),
-    db: AsyncSession = Depends(get_db),
-):
+@router.put("/users/{user_id}/config", response_model=PrivatePortraitConfigOut, summary="管理后台：设置用户私域人像素材总量")
+async def admin_update_private_portrait_config(user_id: str, payload: PrivatePortraitAdminConfigUpdate, admin: User = Depends(get_admin_user), db: AsyncSession = Depends(get_db)):
     before = await get_user_private_portrait_config(db, user_id=user_id)
-    await set_user_private_portrait_limit(db, user_id=user_id, limit=payload.private_portrait_image_limit)
+    await set_user_private_portrait_limit(db, user_id=user_id, limit=payload.private_portrait_asset_limit)
     after = await get_user_private_portrait_config(db, user_id=user_id)
-    await log_operation(
-        db,
-        admin.id,
-        admin.username,
-        f"设置真人素材库数量限制：{before.image_limit} -> {after.image_limit}",
-        "PUT",
-        f"/admin/private-portrait/users/{user_id}/config",
-        detail=_json_detail(
-            {
-                "target_user_id": user_id,
-                "before": before.model_dump(mode="json"),
-                "after": after.model_dump(mode="json"),
-            }
-        ),
-    )
+    await log_operation(db, admin.id, admin.username, f"设置私域人像素材总量限制：{before.asset_limit} -> {after.asset_limit}", "PUT", f"/admin/private-portrait/users/{user_id}/config", detail=_json_detail({"target_user_id": user_id, "before": before.model_dump(mode="json"), "after": after.model_dump(mode="json")}))
+    await db.commit()
     return after
 
 
-@router.get("/projects", response_model=PrivatePortraitProjectListOut)
-async def admin_list_private_portrait_projects(
-    page: int = Query(1, ge=1),
-    page_size: int = Query(20, ge=1, le=100),
-    user_id: str | None = Query(None),
-    keyword: str | None = Query(None),
-    status: str | None = Query(None),
-    admin: User = Depends(get_admin_user),
-    db: AsyncSession = Depends(get_db),
-):
-    items, total = await list_projects(db, user_id=user_id, page=page, page_size=page_size, keyword=keyword, status=status)
-    await log_operation(
-        db,
-        admin.id,
-        admin.username,
-        "查看真人素材项目列表",
-        "GET",
-        "/admin/private-portrait/projects",
-        detail=_json_detail(
-            {
-                "filters": {"user_id": user_id, "keyword": keyword, "status": status, "page": page, "page_size": page_size},
-                "total": total,
-                "returned_count": len(items),
-            }
-        ),
-    )
-    return PrivatePortraitProjectListOut(items=[project_to_out(item, include_user=True) for item in items], total=total, page=page, page_size=page_size)
+@router.get("/stats", response_model=PrivatePortraitAdminStatsOut, summary="管理后台：私域人像素材统计")
+async def admin_get_private_portrait_stats_api(user_id: str | None = Query(None), library_type: str | None = Query(None), admin: User = Depends(get_admin_user), db: AsyncSession = Depends(get_db)):
+    stats = await admin_get_private_portrait_stats(db, user_id=user_id, library_type=library_type)
+    await log_operation(db, admin.id, admin.username, "查看私域人像素材统计", "GET", "/admin/private-portrait/stats", detail=_json_detail({"filters": {"user_id": user_id, "library_type": library_type}, "stats": stats.model_dump(mode="json")}))
+    return stats
 
 
-@router.get("/assets", response_model=PrivatePortraitAssetListOut)
-async def admin_list_private_portrait_assets(
-    page: int = Query(1, ge=1),
-    page_size: int = Query(20, ge=1, le=100),
-    user_id: str | None = Query(None),
-    project_id: str | None = Query(None),
-    keyword: str | None = Query(None),
-    status: str | None = Query(None),
-    admin: User = Depends(get_admin_user),
-    db: AsyncSession = Depends(get_db),
-):
-    assets, total, project_name_map = await list_assets(db, user_id=user_id, project_id=project_id, status=status, keyword=keyword, page=page, page_size=page_size)
-    await log_operation(
-        db,
-        admin.id,
-        admin.username,
-        "查看真人素材列表",
-        "GET",
-        "/admin/private-portrait/assets",
-        detail=_json_detail(
-            {
-                "filters": {"user_id": user_id, "project_id": project_id, "keyword": keyword, "status": status, "page": page, "page_size": page_size},
-                "total": total,
-                "returned_count": len(assets),
-            }
-        ),
-    )
-    return PrivatePortraitAssetListOut(items=[asset_to_out(asset, project_name=project_name_map.get(asset.project_id), include_user=True) for asset in assets], total=total, page=page, page_size=page_size)
+@router.get("/projects", response_model=PrivatePortraitProjectListOut, summary="管理后台：查询私域人像项目列表")
+async def admin_list_private_portrait_projects(page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), user_id: str | None = Query(None), library_type: str | None = Query(None), keyword: str | None = Query(None), status: str | None = Query(None), admin: User = Depends(get_admin_user), db: AsyncSession = Depends(get_db)):
+    items, total = await admin_list_projects(db, user_id=user_id, library_type=library_type, page=page, page_size=page_size, keyword=keyword, status=status)
+    await log_operation(db, admin.id, admin.username, "查看私域人像素材项目列表", "GET", "/admin/private-portrait/projects", detail=_json_detail({"filters": {"user_id": user_id, "library_type": library_type, "keyword": keyword, "status": status, "page": page, "page_size": page_size}, "total": total, "returned_count": len(items)}))
+    await db.commit()
+    return PrivatePortraitProjectListOut(items=items, total=total, page=page, page_size=page_size)
+
+
+@router.get("/assets", response_model=PrivatePortraitAssetListOut, summary="管理后台：查询私域人像素材列表")
+async def admin_list_private_portrait_assets(page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), user_id: str | None = Query(None), project_id: str | None = Query(None), library_type: str | None = Query(None), asset_type: str | None = Query(None), keyword: str | None = Query(None), status: str | None = Query(None), admin: User = Depends(get_admin_user), db: AsyncSession = Depends(get_db)):
+    items, total = await admin_list_assets(db, user_id=user_id, project_id=project_id, library_type=library_type, asset_type=asset_type, status=status, keyword=keyword, page=page, page_size=page_size)
+    await log_operation(db, admin.id, admin.username, "查看私域人像素材列表", "GET", "/admin/private-portrait/assets", detail=_json_detail({"filters": {"user_id": user_id, "project_id": project_id, "library_type": library_type, "asset_type": asset_type, "keyword": keyword, "status": status, "page": page, "page_size": page_size}, "total": total, "returned_count": len(items)}))
+    await db.commit()
+    return PrivatePortraitAssetListOut(items=items, total=total, page=page, page_size=page_size)

video-gen-api/app/api/v1/__init__.py

@@ -33,6 +33,7 @@ from app.api.v1.home_materials import router as home_materials_router
 from app.api.admin import router as admin_module_router
 from app.api.v1.material_admin import router as material_admin_router
 from app.api.v1.private_portrait import router as private_portrait_router
+from app.api.v1.private_portrait_virtual import router as private_portrait_virtual_router
 
 api_router = APIRouter()
 api_router.include_router(auth_router)
@@ -67,4 +68,5 @@ api_router.include_router(team_router)
 api_router.include_router(home_materials_router)
 api_router.include_router(admin_module_router)
 api_router.include_router(material_admin_router)
-api_router.include_router(private_portrait_router)
+api_router.include_router(private_portrait_router)
+api_router.include_router(private_portrait_virtual_router)

video-gen-api/app/api/v1/admin.py

@@ -174,7 +174,7 @@ async def create_user(
         user_type=req.user_type,
         frontend_user_kind=req.frontend_user_kind if req.user_type == "frontend" else FrontendUserKind.EXTERNAL.value,
         allowed_menus=req.allowed_menus,
-        private_portrait_image_limit=req.private_portrait_image_limit,
+        private_portrait_asset_limit=req.private_portrait_asset_limit,
     )
     user.credits = round(user.credits, 2)
     db.add(user)
@@ -192,7 +192,7 @@ async def create_user(
                 "username": username,
                 "user_type": req.user_type,
                 "frontend_user_kind": user.frontend_user_kind,
-                "private_portrait_image_limit": user.private_portrait_image_limit,
+                "private_portrait_asset_limit": user.private_portrait_asset_limit,
                 "credits": user.credits,
                 "phone": user.phone,
                 "email": user.email,

video-gen-api/app/api/v1/private_portrait.py

@@ -9,9 +9,11 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.dependencies import get_current_user, get_db
 from app.enums.private_portrait import (
+    PrivatePortraitAssetType,
     PrivatePortraitEventSource,
     PrivatePortraitEventStatus,
     PrivatePortraitEventType,
+    PrivatePortraitLibraryType,
     PrivatePortraitProjectStatus,
     PrivatePortraitRemoteDeleteStatus,
 )
@@ -20,6 +22,7 @@ from app.models.user import User
 from app.schemas.private_portrait import (
     PrivatePortraitAssetCreate,
     PrivatePortraitAssetListOut,
+    PrivatePortraitAssetOut,
     PrivatePortraitDeleteOut,
     PrivatePortraitConfigOut,
     PrivatePortraitProjectCreate,
@@ -30,13 +33,13 @@ from app.schemas.private_portrait import (
     PrivatePortraitSelectableAssetListOut,
     PrivatePortraitValidateSessionCreate,
     PrivatePortraitValidateSessionOut,
+    PrivatePortraitEnumMetaOut,
+    build_private_portrait_enum_meta,
 )
 from app.services.operation_log_service import log_operation_error, log_operation_event
 from app.services.private_portrait.asset_service import (
     DOMAIN,
     asset_to_out,
-    create_asset,
-    create_validate_session,
     get_user_private_portrait_config,
     get_validate_session,
     handle_validate_callback,
@@ -47,100 +50,102 @@ from app.services.private_portrait.asset_service import (
     validate_session_to_out,
 )
 from app.services.private_portrait.project_service import (
-    create_project,
     get_user_project,
     list_projects,
     project_to_out,
     refresh_project_counters,
     soft_delete_project,
-    update_project,
+)
+from app.services.private_portrait.real_person.service import (
+    create_real_person_asset,
+    create_real_person_project,
+    create_real_person_validate_session,
+    update_real_person_project,
 )
 
-router = APIRouter(tags=["private-portrait"])
+router = APIRouter(tags=["私域真人素材库"])
 
 
 def _log_task_dispatch_failed(*, task_name: str, user_id: str | None = None, project_id: str | None = None, asset_id: str | None = None, exc: BaseException) -> None:
-    log_operation_error(
-        domain=DOMAIN,
-        event_type=PrivatePortraitEventType.TASK_DISPATCH_FAILED.value,
-        source=PrivatePortraitEventSource.API.value,
-        user_id=user_id,
-        project_id=project_id,
-        asset_id=asset_id,
-        exc=exc,
-        detail={"task_name": task_name},
-    )
+    log_operation_error(domain=DOMAIN, event_type=PrivatePortraitEventType.TASK_DISPATCH_FAILED.value, source=PrivatePortraitEventSource.API.value, user_id=user_id, project_id=project_id, asset_id=asset_id, exc=exc, detail={"task_name": task_name})
 
 
 def _log_task_dispatch_success(*, task_name: str, user_id: str | None = None, project_id: str | None = None, asset_id: str | None = None) -> None:
-    log_operation_event(
-        domain=DOMAIN,
-        event_type=PrivatePortraitEventType.TASK_DISPATCH_SUCCESS.value,
-        event_status=PrivatePortraitEventStatus.SUCCESS.value,
-        source=PrivatePortraitEventSource.API.value,
-        user_id=user_id,
-        project_id=project_id,
-        asset_id=asset_id,
-        detail={"task_name": task_name},
-    )
+    log_operation_event(domain=DOMAIN, event_type=PrivatePortraitEventType.TASK_DISPATCH_SUCCESS.value, event_status=PrivatePortraitEventStatus.SUCCESS.value, source=PrivatePortraitEventSource.API.value, user_id=user_id, project_id=project_id, asset_id=asset_id, detail={"task_name": task_name})
 
 
-@router.get("/private-portrait/config", response_model=PrivatePortraitConfigOut)
+@router.get(
+    "/private-portrait/config",
+    response_model=PrivatePortraitConfigOut,
+    summary="获取当前用户私域人像素材额度配置",
+    description="返回私域人像素材总量限制。额度由真人认证素材库与虚拟人像素材库共用，图片和视频共用，Audio 暂未开放。",
+)
 async def get_my_private_portrait_config(current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
     return await get_user_private_portrait_config(db, user_id=current_user.id)
 
 
-@router.post("/private-portrait/projects", response_model=PrivatePortraitProjectCreateWithValidateOut)
+@router.get(
+    "/private-portrait/meta/enums",
+    response_model=PrivatePortraitEnumMetaOut,
+    summary="获取私域人像素材库枚举说明",
+    description="给前端展示状态、类型、素材库类型使用。Audio 仅作为火山支持项展示，当前业务不开放上传。",
+)
+async def get_private_portrait_enum_meta():
+    return build_private_portrait_enum_meta()
+
+
+@router.post(
+    "/private-portrait/projects",
+    response_model=PrivatePortraitProjectCreateWithValidateOut,
+    summary="创建真人认证素材项目并生成认证会话",
+    description="创建本地真人素材项目，随后调用火山 CreateVisualValidateSession 返回 H5Link。用户完成认证后，回调会创建本地 Asset Group 映射。",
+)
 async def create_private_portrait_project(payload: PrivatePortraitProjectCreate, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
-    project = await create_project(db, user_id=current_user.id, payload=payload)
-    session = await create_validate_session(
-        db,
-        user_id=current_user.id,
-        project_id=project.id,
-        callback_redirect_url=payload.callback_redirect_url,
-    )
-    out = PrivatePortraitProjectCreateWithValidateOut(
-        project=project_to_out(project),
-        validate_session=validate_session_to_out(session),
-        poll_interval_ms=2000,
-    )
+    project = await create_real_person_project(db, user_id=current_user.id, payload=payload)
+    session = await create_real_person_validate_session(db, user_id=current_user.id, project_id=project.id, callback_redirect_url=payload.callback_redirect_url)
+    out = PrivatePortraitProjectCreateWithValidateOut(project=project_to_out(project), validate_session=validate_session_to_out(session), poll_interval_ms=2000)
     await db.commit()
     return out
 
 
-@router.get("/private-portrait/projects", response_model=PrivatePortraitProjectListOut)
+@router.get(
+    "/private-portrait/projects",
+    response_model=PrivatePortraitProjectListOut,
+    summary="查询当前用户真人认证素材项目列表",
+    description="只返回 library_type=real_person 的项目。默认查询 active 项目，可用 status 覆盖。",
+)
 async def list_private_portrait_projects(
-    page: int = Query(1, ge=1),
-    page_size: int = Query(20, ge=1, le=100),
-    keyword: str | None = Query(None),
-    status: str | None = Query(None),
+    page: int = Query(1, ge=1, description="页码，从 1 开始。"),
+    page_size: int = Query(20, ge=1, le=100, description="每页数量，最大 100。"),
+    keyword: str | None = Query(None, description="项目名称模糊搜索。"),
+    status: str | None = Query(None, description="项目状态，不传默认 active。"),
     current_user: User = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     query_status = status or PrivatePortraitProjectStatus.ACTIVE.value
-    items, total = await list_projects(db, user_id=current_user.id, page=page, page_size=page_size, keyword=keyword, status=query_status)
+    items, total = await list_projects(db, user_id=current_user.id, page=page, page_size=page_size, keyword=keyword, status=query_status, library_type=PrivatePortraitLibraryType.REAL_PERSON.value)
     await refresh_project_counters(db, [item.id for item in items])
     await db.commit()
-    items, total = await list_projects(db, user_id=current_user.id, page=page, page_size=page_size, keyword=keyword, status=query_status)
+    items, total = await list_projects(db, user_id=current_user.id, page=page, page_size=page_size, keyword=keyword, status=query_status, library_type=PrivatePortraitLibraryType.REAL_PERSON.value)
     return PrivatePortraitProjectListOut(items=[project_to_out(item) for item in items], total=total, page=page, page_size=page_size)
 
 
-@router.get("/private-portrait/projects/{project_id}", response_model=PrivatePortraitProjectOut)
+@router.get("/private-portrait/projects/{project_id}", response_model=PrivatePortraitProjectOut, summary="获取真人认证素材项目详情")
 async def get_private_portrait_project(project_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
-    return project_to_out(await get_user_project(db, user_id=current_user.id, project_id=project_id))
+    return project_to_out(await get_user_project(db, user_id=current_user.id, project_id=project_id, library_type=PrivatePortraitLibraryType.REAL_PERSON.value))
 
 
-@router.put("/private-portrait/projects/{project_id}", response_model=PrivatePortraitProjectOut)
+@router.put("/private-portrait/projects/{project_id}", response_model=PrivatePortraitProjectOut, summary="更新真人认证素材项目")
 async def update_private_portrait_project(project_id: str, payload: PrivatePortraitProjectUpdate, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
-    project = await update_project(db, user_id=current_user.id, project_id=project_id, payload=payload)
+    project = await update_real_person_project(db, user_id=current_user.id, project_id=project_id, payload=payload)
     out = project_to_out(project)
     await db.commit()
     return out
 
 
-@router.delete("/private-portrait/projects/{project_id}", response_model=PrivatePortraitDeleteOut)
+@router.delete("/private-portrait/projects/{project_id}", response_model=PrivatePortraitDeleteOut, summary="删除真人认证素材项目")
 async def delete_private_portrait_project(project_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
-    project = await soft_delete_project(db, user_id=current_user.id, project_id=project_id)
+    project = await soft_delete_project(db, user_id=current_user.id, project_id=project_id, library_type=PrivatePortraitLibraryType.REAL_PERSON.value)
     project_id_snapshot = project.id
     await db.commit()
     try:
@@ -153,30 +158,26 @@ async def delete_private_portrait_project(project_id: str, current_user: User =
     return PrivatePortraitDeleteOut(success=True, remote_delete_status=PrivatePortraitRemoteDeleteStatus.PENDING.value)
 
 
-@router.post("/private-portrait/projects/{project_id}/validate-sessions", response_model=PrivatePortraitValidateSessionOut)
+@router.post("/private-portrait/projects/{project_id}/validate-sessions", response_model=PrivatePortraitValidateSessionOut, summary="重新创建真人认证会话")
 async def create_private_portrait_validate_session(project_id: str, payload: PrivatePortraitValidateSessionCreate, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
-    session = await create_validate_session(db, user_id=current_user.id, project_id=project_id, callback_redirect_url=payload.callback_redirect_url)
+    session = await create_real_person_validate_session(db, user_id=current_user.id, project_id=project_id, callback_redirect_url=payload.callback_redirect_url)
     out = validate_session_to_out(session)
     await db.commit()
     return out
 
 
-@router.get("/private-portrait/validate-sessions/{session_id}", response_model=PrivatePortraitValidateSessionOut)
+@router.get("/private-portrait/validate-sessions/{session_id}", response_model=PrivatePortraitValidateSessionOut, summary="查询真人认证会话状态")
 async def get_private_portrait_validate_session(session_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
     return validate_session_to_out(await get_validate_session(db, user_id=current_user.id, session_id=session_id))
 
 
-@router.get("/private-portrait/validate-callback")
+@router.get("/private-portrait/validate-callback", summary="火山真人认证回调入口")
 async def private_portrait_validate_callback(session_id: str, request: Request, redirect_url: str | None = None, db: AsyncSession = Depends(get_db)):
     params = dict(request.query_params)
     params.pop("session_id", None)
     params.pop("redirect_url", None)
     session = await handle_validate_callback(db, session_id=session_id, query_params=params)
-    redirect_params = {
-        "session_id": session.id,
-        "status": session.status,
-        "resultCode": session.result_code or "",
-    }
+    redirect_params = {"session_id": session.id, "status": session.status, "resultCode": session.result_code or ""}
     if session.remote_group_id:
         redirect_params["remote_group_id"] = session.remote_group_id
     response = {"session_id": session.id, "status": session.status, "resultCode": session.result_code, "remote_group_id": session.remote_group_id}
@@ -188,9 +189,9 @@ async def private_portrait_validate_callback(session_id: str, request: Request,
     return response
 
 
-@router.post("/private-portrait/projects/{project_id}/assets")
+@router.post("/private-portrait/projects/{project_id}/assets", response_model=PrivatePortraitAssetOut, summary="上传真人认证素材", description="当前支持 Image / Video。Audio 暂不开放。CreateAsset 是异步接口，返回后需要轮询到 Active 才可用于生成。")
 async def create_private_portrait_asset(project_id: str, payload: PrivatePortraitAssetCreate, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
-    asset = await create_asset(db, user_id=current_user.id, project_id=project_id, payload=payload)
+    asset = await create_real_person_asset(db, user_id=current_user.id, project_id=project_id, payload=payload)
     asset_id_snapshot = asset.id
     project_id_snapshot = asset.project_id
     out = asset_to_out(asset)
@@ -205,32 +206,34 @@ async def create_private_portrait_asset(project_id: str, payload: PrivatePortrai
     return out
 
 
-@router.get("/private-portrait/projects/{project_id}/assets", response_model=PrivatePortraitAssetListOut)
-async def list_private_portrait_assets(project_id: str, page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), status: str | None = Query(None), keyword: str | None = Query(None), current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
-    assets, total, project_name_map = await list_assets(db, user_id=current_user.id, project_id=project_id, status=status, keyword=keyword, page=page, page_size=page_size)
+@router.get("/private-portrait/projects/{project_id}/assets", response_model=PrivatePortraitAssetListOut, summary="查询真人认证素材列表")
+async def list_private_portrait_assets(project_id: str, page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), status: str | None = Query(None), keyword: str | None = Query(None), asset_type: str | None = Query(None), current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    assets, total, project_name_map = await list_assets(db, user_id=current_user.id, project_id=project_id, status=status, keyword=keyword, page=page, page_size=page_size, library_type=PrivatePortraitLibraryType.REAL_PERSON.value, asset_type=asset_type)
     return PrivatePortraitAssetListOut(items=[asset_to_out(asset, project_name=project_name_map.get(asset.project_id)) for asset in assets], total=total, page=page, page_size=page_size)
 
 
-@router.get("/private-portrait/assets/{asset_id}")
+@router.get("/private-portrait/assets/{asset_id}", summary="获取真人认证素材详情")
 async def get_private_portrait_asset(asset_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
-    asset = (await db.execute(select(PrivatePortraitAsset).where(PrivatePortraitAsset.id == asset_id, PrivatePortraitAsset.user_id == current_user.id).limit(1))).scalar_one_or_none()
+    asset = (await db.execute(select(PrivatePortraitAsset).where(PrivatePortraitAsset.id == asset_id, PrivatePortraitAsset.user_id == current_user.id, PrivatePortraitAsset.library_type == PrivatePortraitLibraryType.REAL_PERSON.value).limit(1))).scalar_one_or_none()
     if not asset:
-        raise HTTPException(status_code=404, detail="真人素材不存在")
+        raise HTTPException(status_code=404, detail="私域人像素材不存在")
     project = (await db.execute(select(PrivatePortraitProject).where(PrivatePortraitProject.id == asset.project_id).limit(1))).scalar_one_or_none()
     return asset_to_out(asset, project_name=project.name if project else None)
 
 
-@router.post("/private-portrait/assets/{asset_id}/sync")
+@router.post("/private-portrait/assets/{asset_id}/sync", summary="同步真人认证素材状态")
 async def sync_private_portrait_asset(asset_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
     asset = await sync_asset_status(db, user_id=current_user.id, asset_id=asset_id)
+    if asset.library_type != PrivatePortraitLibraryType.REAL_PERSON.value:
+        raise HTTPException(status_code=404, detail="私域人像素材不存在")
     out = asset_to_out(asset)
     await db.commit()
     return out
 
 
-@router.delete("/private-portrait/assets/{asset_id}", response_model=PrivatePortraitDeleteOut)
+@router.delete("/private-portrait/assets/{asset_id}", response_model=PrivatePortraitDeleteOut, summary="删除真人认证素材")
 async def delete_private_portrait_asset(asset_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
-    asset = await soft_delete_asset(db, user_id=current_user.id, asset_id=asset_id)
+    asset = await soft_delete_asset(db, user_id=current_user.id, asset_id=asset_id, library_type=PrivatePortraitLibraryType.REAL_PERSON.value)
     asset_id_snapshot = asset.id
     project_id_snapshot = asset.project_id
     await db.commit()
@@ -244,7 +247,7 @@ async def delete_private_portrait_asset(asset_id: str, current_user: User = Depe
     return PrivatePortraitDeleteOut(success=True, remote_delete_status=PrivatePortraitRemoteDeleteStatus.PENDING.value)
 
 
-@router.get("/private-portrait/selectable-assets", response_model=PrivatePortraitSelectableAssetListOut)
-async def list_private_portrait_selectable_assets(page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), project_id: str | None = Query(None), keyword: str | None = Query(None), current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
-    items, total = await list_selectable_assets(db, user_id=current_user.id, project_id=project_id, keyword=keyword, page=page, page_size=page_size)
+@router.get("/private-portrait/selectable-assets", response_model=PrivatePortraitSelectableAssetListOut, summary="查询可用于生成的真人认证素材")
+async def list_private_portrait_selectable_assets(page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), project_id: str | None = Query(None), keyword: str | None = Query(None), asset_type: str | None = Query(None, description="Image 或 Video，不传查全部。"), current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    items, total = await list_selectable_assets(db, user_id=current_user.id, project_id=project_id, keyword=keyword, page=page, page_size=page_size, library_type=PrivatePortraitLibraryType.REAL_PERSON.value, asset_type=asset_type)
     return PrivatePortraitSelectableAssetListOut(items=items, total=total, page=page, page_size=page_size)

video-gen-api/app/api/v1/private_portrait_virtual.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_current_user, get_db
+from app.enums.private_portrait import (
+    PrivatePortraitEventSource,
+    PrivatePortraitEventStatus,
+    PrivatePortraitEventType,
+    PrivatePortraitLibraryType,
+    PrivatePortraitProjectStatus,
+    PrivatePortraitRemoteDeleteStatus,
+)
+from app.models.private_portrait import PrivatePortraitAsset, PrivatePortraitProject
+from app.models.user import User
+from app.schemas.private_portrait import (
+    PrivatePortraitAssetCreate,
+    PrivatePortraitAssetListOut,
+    PrivatePortraitAssetOut,
+    PrivatePortraitConfigOut,
+    PrivatePortraitDeleteOut,
+    PrivatePortraitEnumMetaOut,
+    PrivatePortraitProjectListOut,
+    PrivatePortraitProjectOut,
+    PrivatePortraitProjectUpdate,
+    PrivatePortraitSelectableAssetListOut,
+    PrivatePortraitVirtualProjectCreate,
+    build_private_portrait_enum_meta,
+)
+from app.services.operation_log_service import log_operation_error, log_operation_event
+from app.services.private_portrait.asset_service import (
+    DOMAIN,
+    asset_to_out,
+    get_user_private_portrait_config,
+    list_assets,
+    list_selectable_assets,
+    soft_delete_asset,
+    sync_asset_status,
+)
+from app.services.private_portrait.project_service import (
+    get_user_project,
+    list_projects,
+    project_to_out,
+    refresh_project_counters,
+    soft_delete_project,
+)
+from app.services.private_portrait.virtual.service import create_virtual_asset, create_virtual_project, update_virtual_project
+
+router = APIRouter(tags=["私域虚拟人像素材库"])
+
+
+def _log_task_dispatch_failed(*, task_name: str, user_id: str | None = None, project_id: str | None = None, asset_id: str | None = None, exc: BaseException) -> None:
+    log_operation_error(domain=DOMAIN, event_type=PrivatePortraitEventType.TASK_DISPATCH_FAILED.value, source=PrivatePortraitEventSource.API.value, user_id=user_id, project_id=project_id, asset_id=asset_id, exc=exc, detail={"task_name": task_name})
+
+
+def _log_task_dispatch_success(*, task_name: str, user_id: str | None = None, project_id: str | None = None, asset_id: str | None = None) -> None:
+    log_operation_event(domain=DOMAIN, event_type=PrivatePortraitEventType.TASK_DISPATCH_SUCCESS.value, event_status=PrivatePortraitEventStatus.SUCCESS.value, source=PrivatePortraitEventSource.API.value, user_id=user_id, project_id=project_id, asset_id=asset_id, detail={"task_name": task_name})
+
+
+@router.get("/private-portrait/virtual/config", response_model=PrivatePortraitConfigOut, summary="获取虚拟人像素材库额度配置", description="额度与真人认证素材库共用；图片/视频共用；Audio 暂不开放。")
+async def get_my_virtual_private_portrait_config(current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    return await get_user_private_portrait_config(db, user_id=current_user.id)
+
+
+@router.get("/private-portrait/virtual-meta/enums", response_model=PrivatePortraitEnumMetaOut, summary="获取虚拟人像素材库枚举说明")
+async def get_virtual_private_portrait_enum_meta():
+    return build_private_portrait_enum_meta()
+
+
+@router.post("/private-portrait/virtual-projects", response_model=PrivatePortraitProjectOut, summary="创建虚拟人像项目组", description="创建本地虚拟人像项目，并同步调用火山 CreateAssetGroup，GroupType=AIGC。ProjectName 必须与后续生成 API Key 所属项目一致，默认使用 default。")
+async def create_private_portrait_virtual_project(payload: PrivatePortraitVirtualProjectCreate, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    project = await create_virtual_project(db, user_id=current_user.id, payload=payload)
+    out = project_to_out(project)
+    await db.commit()
+    return out
+
+
+@router.get("/private-portrait/virtual-projects", response_model=PrivatePortraitProjectListOut, summary="查询当前用户虚拟人像项目列表")
+async def list_private_portrait_virtual_projects(page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), keyword: str | None = Query(None), status: str | None = Query(None), current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    query_status = status or PrivatePortraitProjectStatus.ACTIVE.value
+    items, total = await list_projects(db, user_id=current_user.id, page=page, page_size=page_size, keyword=keyword, status=query_status, library_type=PrivatePortraitLibraryType.AIGC_VIRTUAL.value)
+    await refresh_project_counters(db, [item.id for item in items])
+    await db.commit()
+    items, total = await list_projects(db, user_id=current_user.id, page=page, page_size=page_size, keyword=keyword, status=query_status, library_type=PrivatePortraitLibraryType.AIGC_VIRTUAL.value)
+    return PrivatePortraitProjectListOut(items=[project_to_out(item) for item in items], total=total, page=page, page_size=page_size)
+
+
+@router.get("/private-portrait/virtual-projects/{project_id}", response_model=PrivatePortraitProjectOut, summary="获取虚拟人像项目详情")
+async def get_private_portrait_virtual_project(project_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    return project_to_out(await get_user_project(db, user_id=current_user.id, project_id=project_id, library_type=PrivatePortraitLibraryType.AIGC_VIRTUAL.value))
+
+
+@router.put("/private-portrait/virtual-projects/{project_id}", response_model=PrivatePortraitProjectOut, summary="更新虚拟人像项目")
+async def update_private_portrait_virtual_project(project_id: str, payload: PrivatePortraitProjectUpdate, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    project = await update_virtual_project(db, user_id=current_user.id, project_id=project_id, payload=payload)
+    out = project_to_out(project)
+    await db.commit()
+    return out
+
+
+@router.delete("/private-portrait/virtual-projects/{project_id}", response_model=PrivatePortraitDeleteOut, summary="删除虚拟人像项目")
+async def delete_private_portrait_virtual_project(project_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    project = await soft_delete_project(db, user_id=current_user.id, project_id=project_id, library_type=PrivatePortraitLibraryType.AIGC_VIRTUAL.value)
+    project_id_snapshot = project.id
+    await db.commit()
+    try:
+        from app.tasks.private_portrait_asset_tasks import delete_private_portrait_project_remote
+
+        delete_private_portrait_project_remote.delay(project_id_snapshot)
+        _log_task_dispatch_success(task_name="private_portrait.delete_project_remote", user_id=current_user.id, project_id=project_id_snapshot)
+    except Exception as exc:
+        _log_task_dispatch_failed(task_name="private_portrait.delete_project_remote", user_id=current_user.id, project_id=project_id_snapshot, exc=exc)
+    return PrivatePortraitDeleteOut(success=True, remote_delete_status=PrivatePortraitRemoteDeleteStatus.PENDING.value)
+
+
+@router.post("/private-portrait/virtual-projects/{project_id}/assets", response_model=PrivatePortraitAssetOut, summary="上传虚拟人像素材", description="当前支持 Image / Video。Audio 暂不开放。CreateAsset 是异步接口，返回后需要轮询到 Active 才可用于生成。")
+async def create_private_portrait_virtual_asset(project_id: str, payload: PrivatePortraitAssetCreate, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    asset = await create_virtual_asset(db, user_id=current_user.id, project_id=project_id, payload=payload)
+    asset_id_snapshot = asset.id
+    project_id_snapshot = asset.project_id
+    out = asset_to_out(asset)
+    await db.commit()
+    try:
+        from app.tasks.private_portrait_asset_tasks import poll_private_portrait_asset_status
+
+        poll_private_portrait_asset_status.delay(asset_id_snapshot)
+        _log_task_dispatch_success(task_name="private_portrait.poll_asset_status", user_id=current_user.id, project_id=project_id_snapshot, asset_id=asset_id_snapshot)
+    except Exception as exc:
+        _log_task_dispatch_failed(task_name="private_portrait.poll_asset_status", user_id=current_user.id, project_id=project_id_snapshot, asset_id=asset_id_snapshot, exc=exc)
+    return out
+
+
+@router.get("/private-portrait/virtual-projects/{project_id}/assets", response_model=PrivatePortraitAssetListOut, summary="查询虚拟人像素材列表")
+async def list_private_portrait_virtual_assets(project_id: str, page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), status: str | None = Query(None), keyword: str | None = Query(None), asset_type: str | None = Query(None), current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    assets, total, project_name_map = await list_assets(db, user_id=current_user.id, project_id=project_id, status=status, keyword=keyword, page=page, page_size=page_size, library_type=PrivatePortraitLibraryType.AIGC_VIRTUAL.value, asset_type=asset_type)
+    return PrivatePortraitAssetListOut(items=[asset_to_out(asset, project_name=project_name_map.get(asset.project_id)) for asset in assets], total=total, page=page, page_size=page_size)
+
+
+@router.get("/private-portrait/virtual-assets/{asset_id}", response_model=PrivatePortraitAssetOut, summary="获取虚拟人像素材详情")
+async def get_private_portrait_virtual_asset(asset_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    asset = (await db.execute(select(PrivatePortraitAsset).where(PrivatePortraitAsset.id == asset_id, PrivatePortraitAsset.user_id == current_user.id, PrivatePortraitAsset.library_type == PrivatePortraitLibraryType.AIGC_VIRTUAL.value).limit(1))).scalar_one_or_none()
+    if not asset:
+        raise HTTPException(status_code=404, detail="虚拟人像素材不存在")
+    project = (await db.execute(select(PrivatePortraitProject).where(PrivatePortraitProject.id == asset.project_id).limit(1))).scalar_one_or_none()
+    return asset_to_out(asset, project_name=project.name if project else None)
+
+
+@router.post("/private-portrait/virtual-assets/{asset_id}/sync", response_model=PrivatePortraitAssetOut, summary="同步虚拟人像素材状态")
+async def sync_private_portrait_virtual_asset(asset_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    asset = await sync_asset_status(db, user_id=current_user.id, asset_id=asset_id)
+    if asset.library_type != PrivatePortraitLibraryType.AIGC_VIRTUAL.value:
+        raise HTTPException(status_code=404, detail="虚拟人像素材不存在")
+    out = asset_to_out(asset)
+    await db.commit()
+    return out
+
+
+@router.delete("/private-portrait/virtual-assets/{asset_id}", response_model=PrivatePortraitDeleteOut, summary="删除虚拟人像素材")
+async def delete_private_portrait_virtual_asset(asset_id: str, current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    asset = await soft_delete_asset(db, user_id=current_user.id, asset_id=asset_id, library_type=PrivatePortraitLibraryType.AIGC_VIRTUAL.value)
+    asset_id_snapshot = asset.id
+    project_id_snapshot = asset.project_id
+    await db.commit()
+    try:
+        from app.tasks.private_portrait_asset_tasks import delete_private_portrait_asset_remote
+
+        delete_private_portrait_asset_remote.delay(asset_id_snapshot)
+        _log_task_dispatch_success(task_name="private_portrait.delete_asset_remote", user_id=current_user.id, project_id=project_id_snapshot, asset_id=asset_id_snapshot)
+    except Exception as exc:
+        _log_task_dispatch_failed(task_name="private_portrait.delete_asset_remote", user_id=current_user.id, project_id=project_id_snapshot, asset_id=asset_id_snapshot, exc=exc)
+    return PrivatePortraitDeleteOut(success=True, remote_delete_status=PrivatePortraitRemoteDeleteStatus.PENDING.value)
+
+
+@router.get("/private-portrait/virtual-selectable-assets", response_model=PrivatePortraitSelectableAssetListOut, summary="查询可用于生成的虚拟人像素材")
+async def list_private_portrait_virtual_selectable_assets(page: int = Query(1, ge=1), page_size: int = Query(20, ge=1, le=100), project_id: str | None = Query(None), keyword: str | None = Query(None), asset_type: str | None = Query(None, description="Image 或 Video，不传查全部。"), current_user: User = Depends(get_current_user), db: AsyncSession = Depends(get_db)):
+    items, total = await list_selectable_assets(db, user_id=current_user.id, project_id=project_id, keyword=keyword, page=page, page_size=page_size, library_type=PrivatePortraitLibraryType.AIGC_VIRTUAL.value, asset_type=asset_type)
+    return PrivatePortraitSelectableAssetListOut(items=items, total=total, page=page, page_size=page_size)