feat(media): 为媒体素材库添加分页加载功能

- 新增 PaginatedResult 泛型类型统一分页返回数据结构
- 重构后端媒体素材列表接口，支持分页参数并返回完整分页信息
- 前端媒体素材页面添加分页控件，适配分页加载逻辑
- 上传素材后自动重置页码至第一页并重新加载列表
- 更新接口文档和用户文档，补充分页API使用规范
- 新增对应测试用例覆盖分页接口与前端调用逻辑

WonderQ-Admin/app/routers/admin.py

@@ -1500,9 +1500,28 @@ def update_lead_status(lead_id: str, body: LeadStatusIn, request: Request, _user
 
 
 @router.get("/media-assets")
-def list_media_assets(_user: AdminUser = Depends(require_admin_permission("admin:media:read")), db: Session = Depends(get_db)):
-    assets = db.scalars(apply_data_scope(select(MediaAsset), MediaAsset, _user, db).order_by(MediaAsset.createdAt.desc()).limit(200)).all()
-    return success_response({"items": [media_model_dict(asset) for asset in assets]})
+def list_media_assets(
+    pageNum: int = Query(default=1, ge=1),
+    pageSize: int = Query(default=20, ge=1, le=200),
+    _user: AdminUser = Depends(require_admin_permission("admin:media:read")),
+    db: Session = Depends(get_db),
+):
+    offset = (pageNum - 1) * pageSize
+    assets_stmt = (
+        select(MediaAsset)
+        .order_by(MediaAsset.createdAt.desc())
+        .offset(offset)
+        .limit(pageSize)
+    )
+    assets = db.scalars(apply_data_scope(assets_stmt, MediaAsset, _user, db)).all()
+    total_stmt = apply_data_scope(select(func.count()).select_from(MediaAsset), MediaAsset, _user, db)
+    total = db.scalar(total_stmt) or 0
+    return success_response({
+        "items": [media_model_dict(asset) for asset in assets],
+        "total": total,
+        "pageNum": pageNum,
+        "pageSize": pageSize,
+    })
 
 
 @router.post("/media-assets/upload", status_code=status.HTTP_201_CREATED)

WonderQ-Admin/tests/test_api_contracts.py

@@ -590,6 +590,39 @@ def test_admin_media_upload_rejects_non_image_file():
     assert not fake_db.committed
 
 
+def test_admin_media_assets_endpoint_returns_paginated_results():
+    assets = [
+        MediaAsset(
+            id="asset-1",
+            url="https://cdn.example.test/asset-1.jpg",
+            name="asset-1.jpg",
+            mimeType="image/jpeg",
+            sizeBytes=1024,
+            group="general",
+            createdAt=datetime(2026, 1, 2),
+            updatedAt=datetime(2026, 1, 2),
+        )
+    ]
+    fake_db = FakeDb(scalar_results=[assets], scalar_values=[3])
+    app = authenticated_app(fake_db)
+
+    try:
+        response = TestClient(app).get(
+            "/api/admin/media-assets",
+            params={"pageNum": 2, "pageSize": 1},
+        )
+    finally:
+        app.dependency_overrides.clear()
+
+    assert response.status_code == 200
+    body = response.json()["data"]
+    assert body["items"][0]["id"] == "asset-1"
+    assert body["total"] == 3
+    assert body["pageNum"] == 2
+    assert body["pageSize"] == 1
+    assert len(fake_db.scalar_statements) == 2
+
+
 def test_admin_leads_endpoint_accepts_source_keyword_and_created_range_filters():
     fake_db = FakeDb(scalar_results=[[]])
     app = authenticated_app(fake_db)