docs: update project docs and evaluation history pagination

app/api/evaluations.py

@@ -1,6 +1,6 @@
 from pathlib import Path
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Query
 from fastapi.responses import FileResponse
 from sqlalchemy.orm import Session
 
@@ -15,9 +15,14 @@ router = APIRouter()
 
 
 @router.get("", response_model=ApiResponse[EvaluationListResponse])
-def list_evaluations(ctx: UserContext = Depends(get_user_context), db: Session = Depends(get_db)):
+def list_evaluations(
+    page: int = Query(default=1, ge=1, description="页码，从 1 开始"),
+    page_size: int = Query(default=10, ge=1, le=100, description="每页数量，最大 100"),
+    ctx: UserContext = Depends(get_user_context),
+    db: Session = Depends(get_db),
+):
     """历史评价：基于 user_id 查询完整训练后的评价记录。"""
-    return ok(EvaluationService(db).list_history(ctx.user_id))
+    return ok(EvaluationService(db).list_history(ctx.user_id, page=page, page_size=page_size))
 
 
 @router.get("/{evaluation_id}", response_model=ApiResponse[EvaluationDetailResponse])

app/repositories/evaluation_repository.py

@@ -1,4 +1,4 @@
-from sqlalchemy import delete, select
+from sqlalchemy import delete, func, select
 from sqlalchemy.orm import Session
 
 from app.models.training_record import TrainingRecord, TrainingScoreDetail
@@ -46,12 +46,19 @@ class EvaluationRepository:
         )
         return self.db.scalar(stmt)
 
-    def list_by_user(self, user_id: str) -> list[TrainingRecord]:
+    def count_by_user(self, user_id: str) -> int:
+        """历史评价计数：按外部 user_id 统计完整训练后的评价记录总数。"""
+        stmt = select(func.count()).select_from(TrainingRecord).where(TrainingRecord.external_user_id == user_id)
+        return int(self.db.scalar(stmt) or 0)
+
+    def list_by_user(self, user_id: str, limit: int, offset: int) -> list[TrainingRecord]:
         """历史评价：按外部 user_id 查询完整训练后的评价记录。"""
         stmt = (
             select(TrainingRecord)
             .where(TrainingRecord.external_user_id == user_id)
             .order_by(TrainingRecord.created_at.desc())
+            .limit(limit)
+            .offset(offset)
         )
         return list(self.db.scalars(stmt).all())
 

app/schemas/evaluation.py

@@ -61,10 +61,22 @@ class EvaluationListItem(BaseModel):
     pdf_exported: bool
 
 
+class PaginationMeta(BaseModel):
+    """分页信息：用于历史训练记录列表的前端分页展示。"""
+
+    page: int
+    page_size: int
+    total: int
+    total_pages: int
+    has_next: bool
+    has_prev: bool
+
+
 class EvaluationListResponse(BaseModel):
     """历史评价列表响应。"""
 
     items: list[EvaluationListItem]
+    pagination: PaginationMeta
 
 
 class ExportPdfResponse(BaseModel):

app/services/evaluation_service.py

@@ -19,6 +19,7 @@ from app.schemas.evaluation import (
     EvaluationListItem,
     EvaluationListResponse,
     EvaluationResponse,
+    PaginationMeta,
     ScoreDetailItem,
 )
 from app.services.audit_service import AuditService
@@ -235,9 +236,12 @@ class EvaluationService:
         """用户 ID 兼容：Django 返回的 id 写入 external_user_id，纯数字时同步写入源库 user_id。"""
         return int(user_id) if str(user_id).isdigit() else None
 
-    def list_history(self, user_id: str) -> EvaluationListResponse:
+    def list_history(self, user_id: str, page: int = 1, page_size: int = 10) -> EvaluationListResponse:
         """历史评价：按 Django 用户中心 ID 查询完整训练后的 training_record。"""
-        records = self.eval_repo.list_by_user(user_id)
+        total = self.eval_repo.count_by_user(user_id)
+        offset = (page - 1) * page_size
+        records = self.eval_repo.list_by_user(user_id, limit=page_size, offset=offset)
+        total_pages = (total + page_size - 1) // page_size if total else 0
         return EvaluationListResponse(
             items=[
                 EvaluationListItem(
@@ -249,7 +253,15 @@ class EvaluationService:
                     pdf_exported=bool(record.pdf_file_path),
                 )
                 for record in records
-            ]
+            ],
+            pagination=PaginationMeta(
+                page=page,
+                page_size=page_size,
+                total=total,
+                total_pages=total_pages,
+                has_next=page < total_pages,
+                has_prev=page > 1 and total_pages > 0,
+            ),
         )
 
     def get_detail(self, evaluation_id: int, user_id: str) -> EvaluationDetailResponse: