feat: add manual revision and dashboard list apis

app/application/services/order_service.py

@@ -1,11 +1,20 @@
 """Order application service."""
 
 from fastapi import HTTPException, status
-from sqlalchemy import select
+from math import ceil
+
+from sqlalchemy import String, cast, func, or_, select
 from sqlalchemy.orm import selectinload
 
 from app.api.schemas.asset import AssetRead
-from app.api.schemas.order import CreateOrderRequest, CreateOrderResponse, OrderDetailResponse
+from app.api.schemas.order import (
+    CreateOrderRequest,
+    CreateOrderResponse,
+    OrderDetailResponse,
+    OrderListItemResponse,
+    OrderListResponse,
+)
+from app.application.services.revision_service import RevisionService
 from app.application.services.workflow_service import WorkflowService
 from app.domain.enums import CustomerLevel, OrderStatus, ServiceMode
 from app.infra.db.models.order import OrderORM
@@ -18,6 +27,7 @@ class OrderService:
 
     def __init__(self) -> None:
         self.workflow_service = WorkflowService()
+        self.revision_service = RevisionService()
 
     async def create_order(self, session, payload: CreateOrderRequest) -> CreateOrderResponse:
         """Create an order, persist a workflow run, and start Temporal execution."""
@@ -87,6 +97,7 @@ class OrderService:
 
         workflow_run = order.workflow_runs[0] if order.workflow_runs else None
         final_asset = next((asset for asset in order.assets if asset.id == order.final_asset_id), None)
+        snapshot = await self.revision_service.get_revision_snapshot(session, order_id)
 
         return OrderDetailResponse(
             order_id=order.id,
@@ -100,11 +111,96 @@ class OrderService:
             final_asset_id=order.final_asset_id,
             workflow_id=workflow_run.workflow_id if workflow_run else None,
             current_step=workflow_run.current_step if workflow_run else None,
+            current_revision_asset_id=snapshot.current_revision_asset_id,
+            current_revision_version=snapshot.current_revision_version,
+            latest_revision_asset_id=snapshot.latest_revision_asset_id,
+            latest_revision_version=snapshot.latest_revision_version,
+            revision_count=snapshot.revision_count,
+            review_task_status=snapshot.review_task_status,
+            pending_manual_confirm=snapshot.pending_manual_confirm,
             final_asset=AssetRead.model_validate(final_asset) if final_asset else None,
             created_at=order.created_at,
             updated_at=order.updated_at,
         )
 
+    async def list_orders(
+        self,
+        session,
+        *,
+        page: int = 1,
+        limit: int = 20,
+        query: str | None = None,
+        status_filter: OrderStatus | None = None,
+        order_id: int | None = None,
+    ) -> OrderListResponse:
+        """Return recent orders for dashboard overview pages."""
+
+        filters = []
+
+        if status_filter is not None:
+            filters.append(OrderORM.status == status_filter)
+
+        if order_id is not None:
+            filters.append(OrderORM.id == order_id)
+
+        if query:
+            search_term = query.strip()
+            if search_term:
+                filters.append(
+                    or_(
+                        cast(OrderORM.id, String).ilike(f"{search_term}%"),
+                        OrderORM.workflow_runs.any(
+                            WorkflowRunORM.workflow_id.ilike(f"%{search_term}%")
+                        ),
+                    )
+                )
+
+        query = select(OrderORM).options(selectinload(OrderORM.workflow_runs))
+        count_query = select(func.count()).select_from(OrderORM)
+
+        if filters:
+            query = query.where(*filters)
+            count_query = count_query.where(*filters)
+
+        total = (await session.execute(count_query)).scalar_one()
+        total_pages = ceil(total / limit) if total else 0
+        offset = (page - 1) * limit
+
+        query = query.order_by(OrderORM.updated_at.desc(), OrderORM.id.desc()).offset(offset).limit(limit)
+
+        result = await session.execute(query)
+        orders = result.scalars().all()
+
+        items = []
+        for order in orders:
+            workflow_run = order.workflow_runs[0] if order.workflow_runs else None
+            snapshot = await self.revision_service.get_revision_snapshot(session, order.id)
+            items.append(
+                OrderListItemResponse(
+                    order_id=order.id,
+                    workflow_id=workflow_run.workflow_id if workflow_run else None,
+                    customer_level=order.customer_level,
+                    service_mode=order.service_mode,
+                    status=order.status,
+                    current_step=workflow_run.current_step if workflow_run else None,
+                    updated_at=order.updated_at,
+                    final_asset_id=order.final_asset_id,
+                    review_task_status=snapshot.review_task_status,
+                    latest_revision_asset_id=snapshot.latest_revision_asset_id,
+                    latest_revision_version=snapshot.latest_revision_version,
+                    revision_count=snapshot.revision_count,
+                    pending_manual_confirm=snapshot.pending_manual_confirm,
+                )
+            )
+
+        return OrderListResponse(
+            page=page,
+            limit=limit,
+            total=total,
+            total_pages=total_pages,
+            items=items,
+        )
+
     @staticmethod
     def _validate_mode(customer_level: CustomerLevel, service_mode: ServiceMode) -> None:
         """Validate the allowed customer-level and service-mode combinations."""
@@ -119,4 +215,3 @@ class OrderService:
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail="Mid-level customers only support semi_pro",
             )
-

app/application/services/review_service.py

@@ -3,9 +3,11 @@
 from fastapi import HTTPException, status
 from sqlalchemy import select
 
+from app.api.schemas.revision import ConfirmRevisionRequest, ConfirmRevisionResponse
 from app.api.schemas.review import PendingReviewResponse, SubmitReviewRequest, SubmitReviewResponse
+from app.application.services.revision_service import RevisionService
 from app.application.services.workflow_service import WorkflowService
-from app.domain.enums import OrderStatus, ReviewTaskStatus
+from app.domain.enums import OrderStatus, ReviewDecision, ReviewTaskStatus
 from app.infra.db.models.asset import AssetORM
 from app.infra.db.models.order import OrderORM
 from app.infra.db.models.review_task import ReviewTaskORM
@@ -18,6 +20,7 @@ class ReviewService:
 
     def __init__(self) -> None:
         self.workflow_service = WorkflowService()
+        self.revision_service = RevisionService()
 
     async def list_pending_reviews(self, session) -> list[PendingReviewResponse]:
         """Return all pending review tasks."""
@@ -25,20 +28,29 @@ class ReviewService:
         result = await session.execute(
             select(ReviewTaskORM, WorkflowRunORM)
             .join(WorkflowRunORM, WorkflowRunORM.order_id == ReviewTaskORM.order_id)
-            .where(ReviewTaskORM.status == ReviewTaskStatus.PENDING)
+            .where(ReviewTaskORM.status.in_([ReviewTaskStatus.PENDING, ReviewTaskStatus.REVISION_UPLOADED]))
             .order_by(ReviewTaskORM.created_at.asc())
         )
 
-        return [
-            PendingReviewResponse(
-                review_task_id=review_task.id,
-                order_id=review_task.order_id,
-                workflow_id=workflow_run.workflow_id,
-                current_step=workflow_run.current_step,
-                created_at=review_task.created_at,
+        pending_reviews = []
+        for review_task, workflow_run in result.all():
+            snapshot = await self.revision_service.get_revision_snapshot(session, review_task.order_id)
+            pending_reviews.append(
+                PendingReviewResponse(
+                    review_task_id=review_task.id,
+                    order_id=review_task.order_id,
+                    workflow_id=workflow_run.workflow_id,
+                    current_step=workflow_run.current_step,
+                    review_task_status=review_task.status,
+                    latest_revision_asset_id=snapshot.latest_revision_asset_id,
+                    current_revision_asset_id=snapshot.current_revision_asset_id,
+                    latest_revision_version=snapshot.latest_revision_version,
+                    revision_count=snapshot.revision_count,
+                    pending_manual_confirm=snapshot.pending_manual_confirm,
+                    created_at=review_task.created_at,
+                )
             )
-            for review_task, workflow_run in result.all()
-        ]
+        return pending_reviews
 
     async def submit_review(self, session, order_id: int, payload: SubmitReviewRequest) -> SubmitReviewResponse:
         """Persist the review submission and signal the Temporal workflow."""
@@ -71,7 +83,7 @@ class ReviewService:
             select(ReviewTaskORM)
             .where(
                 ReviewTaskORM.order_id == order_id,
-                ReviewTaskORM.status == ReviewTaskStatus.PENDING,
+                ReviewTaskORM.status.in_([ReviewTaskStatus.PENDING, ReviewTaskStatus.REVISION_UPLOADED]),
             )
             .order_by(ReviewTaskORM.created_at.desc())
         )
@@ -80,10 +92,22 @@ class ReviewService:
             review_task = ReviewTaskORM(order_id=order_id, status=ReviewTaskStatus.SUBMITTED)
             session.add(review_task)
 
+        current_task_status = review_task.status
+        selected_asset_id = payload.selected_asset_id
+        if selected_asset_id is None and current_task_status == ReviewTaskStatus.REVISION_UPLOADED:
+            selected_asset_id = review_task.resume_asset_id or review_task.latest_revision_asset_id
+        if selected_asset_id is not None:
+            asset = await session.get(AssetORM, selected_asset_id)
+            if asset is None or asset.order_id != order_id:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Selected asset does not belong to the order",
+                )
+
         review_task.status = ReviewTaskStatus.SUBMITTED
         review_task.decision = payload.decision
         review_task.reviewer_id = payload.reviewer_id
-        review_task.selected_asset_id = payload.selected_asset_id
+        review_task.selected_asset_id = selected_asset_id
         review_task.comment = payload.comment
         await session.commit()
 
@@ -93,7 +117,7 @@ class ReviewService:
                 ReviewSignalPayload(
                     decision=payload.decision,
                     reviewer_id=payload.reviewer_id,
-                    selected_asset_id=payload.selected_asset_id,
+                    selected_asset_id=selected_asset_id,
                     comment=payload.comment,
                 ),
             )
@@ -110,3 +134,88 @@ class ReviewService:
             status="submitted",
         )
 
+    async def confirm_revision_continue(
+        self,
+        session,
+        order_id: int,
+        payload: ConfirmRevisionRequest,
+    ) -> ConfirmRevisionResponse:
+        """Confirm the latest revision and resume the existing workflow."""
+
+        order = await session.get(OrderORM, order_id)
+        if order is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Order not found")
+        if order.status != OrderStatus.WAITING_REVIEW:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="Order is not waiting for review",
+            )
+
+        workflow_result = await session.execute(
+            select(WorkflowRunORM).where(WorkflowRunORM.order_id == order_id)
+        )
+        workflow_run = workflow_result.scalar_one_or_none()
+        if workflow_run is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Workflow not found")
+
+        review_result = await session.execute(
+            select(ReviewTaskORM)
+            .where(
+                ReviewTaskORM.order_id == order_id,
+                ReviewTaskORM.status.in_([ReviewTaskStatus.PENDING, ReviewTaskStatus.REVISION_UPLOADED]),
+            )
+            .order_by(ReviewTaskORM.created_at.desc(), ReviewTaskORM.id.desc())
+        )
+        review_task = review_result.scalars().first()
+        if review_task is None:
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="No active review task")
+        if review_task.status != ReviewTaskStatus.REVISION_UPLOADED:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="No uploaded revision to confirm",
+            )
+
+        revision_asset_id = review_task.resume_asset_id or review_task.latest_revision_asset_id
+        if revision_asset_id is None:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="No uploaded revision to confirm",
+            )
+
+        revision_asset = await session.get(AssetORM, revision_asset_id)
+        if revision_asset is None or revision_asset.order_id != order_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Revision asset does not belong to the order",
+            )
+
+        review_task.status = ReviewTaskStatus.SUBMITTED
+        review_task.decision = ReviewDecision.APPROVE
+        review_task.reviewer_id = payload.reviewer_id
+        review_task.selected_asset_id = revision_asset_id
+        review_task.comment = payload.comment
+        await session.commit()
+
+        try:
+            await self.workflow_service.signal_review(
+                workflow_run.workflow_id,
+                ReviewSignalPayload(
+                    decision=ReviewDecision.APPROVE,
+                    reviewer_id=payload.reviewer_id,
+                    selected_asset_id=revision_asset_id,
+                    comment=payload.comment,
+                ),
+            )
+        except Exception as exc:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail=f"Failed to signal Temporal workflow: {exc}",
+            ) from exc
+
+        return ConfirmRevisionResponse(
+            order_id=order_id,
+            workflow_id=workflow_run.workflow_id,
+            revision_asset_id=revision_asset_id,
+            decision=ReviewDecision.APPROVE,
+            status="submitted",
+        )

app/application/services/revision_service.py

@@ -0,0 +1,251 @@
+"""Manual revision application service."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from fastapi import HTTPException, status
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.schemas.revision import (
+    RegisterRevisionRequest,
+    RegisterRevisionResponse,
+    RevisionChainItem,
+    RevisionChainResponse,
+)
+from app.domain.enums import AssetType, OrderStatus, ReviewTaskStatus, WorkflowStepName
+from app.infra.db.models.asset import AssetORM
+from app.infra.db.models.order import OrderORM
+from app.infra.db.models.review_task import ReviewTaskORM
+from app.infra.db.models.workflow_run import WorkflowRunORM
+
+
+@dataclass(slots=True)
+class RevisionSnapshot:
+    """Revision summary used by the order, queue, and workflow responses."""
+
+    current_revision_asset_id: int | None
+    current_revision_version: int | None
+    latest_revision_asset_id: int | None
+    latest_revision_version: int | None
+    revision_count: int
+    review_task_status: ReviewTaskStatus | None
+    pending_manual_confirm: bool
+    root_asset_id: int | None
+
+
+class RevisionService:
+    """Application service for manual revision registration and lookup."""
+
+    async def get_revision_snapshot(self, session: AsyncSession, order_id: int) -> RevisionSnapshot:
+        """Return the current revision summary for an order."""
+
+        await self._require_order(session, order_id)
+
+        revision_result = await session.execute(
+            select(AssetORM)
+            .where(
+                AssetORM.order_id == order_id,
+                AssetORM.asset_type == AssetType.MANUAL_REVISION,
+            )
+            .order_by(AssetORM.version_no.asc(), AssetORM.created_at.asc(), AssetORM.id.asc())
+        )
+        revisions = revision_result.scalars().all()
+        latest_revision = revisions[-1] if revisions else None
+
+        review_result = await session.execute(
+            select(ReviewTaskORM)
+            .where(ReviewTaskORM.order_id == order_id)
+            .order_by(ReviewTaskORM.created_at.desc(), ReviewTaskORM.id.desc())
+        )
+        latest_review_task = review_result.scalars().first()
+
+        return RevisionSnapshot(
+            current_revision_asset_id=latest_revision.id if latest_revision else None,
+            current_revision_version=latest_revision.version_no if latest_revision else None,
+            latest_revision_asset_id=latest_revision.id if latest_revision else None,
+            latest_revision_version=latest_revision.version_no if latest_revision else None,
+            revision_count=len(revisions),
+            review_task_status=latest_review_task.status if latest_review_task else None,
+            pending_manual_confirm=bool(
+                latest_review_task and latest_review_task.status == ReviewTaskStatus.REVISION_UPLOADED
+            ),
+            root_asset_id=latest_revision.root_asset_id if latest_revision else None,
+        )
+
+    async def register_revision(
+        self,
+        session: AsyncSession,
+        order_id: int,
+        payload: RegisterRevisionRequest,
+    ) -> RegisterRevisionResponse:
+        """Register an offline manual revision asset for a waiting-review order."""
+
+        order = await self._require_order(session, order_id)
+        if order.status != OrderStatus.WAITING_REVIEW:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="Order is not waiting for review",
+            )
+
+        workflow_run = await self._require_workflow_run(session, order_id)
+        review_task = await self._get_active_review_task(session, order_id)
+
+        parent_asset = await session.get(AssetORM, payload.parent_asset_id)
+        if parent_asset is None or parent_asset.order_id != order_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Parent asset does not belong to the order",
+            )
+
+        root_asset_id = parent_asset.root_asset_id or parent_asset.id
+        version_result = await session.execute(
+            select(func.max(AssetORM.version_no)).where(
+                AssetORM.order_id == order_id,
+                AssetORM.asset_type == AssetType.MANUAL_REVISION,
+                AssetORM.root_asset_id == root_asset_id,
+            )
+        )
+        latest_version = version_result.scalar_one()
+        if parent_asset.asset_type != AssetType.MANUAL_REVISION and latest_version:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="Parent asset is not the current revision version",
+            )
+        if parent_asset.asset_type == AssetType.MANUAL_REVISION and not parent_asset.is_current_version:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="Parent asset is not the current revision version",
+            )
+
+        version_no = (latest_version or 0) + 1
+        current_version_result = await session.execute(
+            select(AssetORM).where(
+                AssetORM.order_id == order_id,
+                AssetORM.asset_type == AssetType.MANUAL_REVISION,
+                AssetORM.root_asset_id == root_asset_id,
+                AssetORM.is_current_version.is_(True),
+            )
+        )
+        current_version_asset = current_version_result.scalar_one_or_none()
+        if current_version_asset is not None:
+            current_version_asset.is_current_version = False
+
+        asset = AssetORM(
+            order_id=order_id,
+            asset_type=AssetType.MANUAL_REVISION,
+            step_name=WorkflowStepName.REVIEW,
+            parent_asset_id=payload.parent_asset_id,
+            root_asset_id=root_asset_id,
+            version_no=version_no,
+            is_current_version=True,
+            uri=payload.uploaded_uri,
+            metadata_json={
+                "reviewer_id": payload.reviewer_id,
+                "comment": payload.comment,
+                "source": "manual_revision",
+            },
+        )
+        session.add(asset)
+        await session.flush()
+
+        review_task.status = ReviewTaskStatus.REVISION_UPLOADED
+        review_task.latest_revision_asset_id = asset.id
+        review_task.resume_asset_id = asset.id
+        review_task.selected_asset_id = asset.id
+        review_task.reviewer_id = payload.reviewer_id
+        review_task.comment = payload.comment
+        await session.commit()
+
+        revision_count = await self.count_manual_revisions(session, order_id)
+        return RegisterRevisionResponse(
+            order_id=order_id,
+            workflow_id=workflow_run.workflow_id,
+            asset_id=asset.id,
+            parent_asset_id=asset.parent_asset_id or payload.parent_asset_id,
+            root_asset_id=asset.root_asset_id or root_asset_id,
+            version_no=asset.version_no,
+            review_task_status=review_task.status,
+            latest_revision_asset_id=asset.id,
+            revision_count=revision_count,
+        )
+
+    async def list_revision_chain(
+        self,
+        session: AsyncSession,
+        order_id: int,
+    ) -> RevisionChainResponse:
+        """List all manual revisions for an order in version order."""
+
+        await self._require_order(session, order_id)
+
+        result = await session.execute(
+            select(AssetORM)
+            .where(
+                AssetORM.order_id == order_id,
+                AssetORM.asset_type == AssetType.MANUAL_REVISION,
+            )
+            .order_by(AssetORM.version_no.asc(), AssetORM.created_at.asc(), AssetORM.id.asc())
+        )
+        assets = result.scalars().all()
+        snapshot = await self.get_revision_snapshot(session, order_id)
+
+        return RevisionChainResponse(
+            order_id=order_id,
+            latest_revision_asset_id=snapshot.latest_revision_asset_id,
+            revision_count=len(assets),
+            items=[
+                RevisionChainItem(
+                    asset_id=asset.id,
+                    order_id=asset.order_id,
+                    parent_asset_id=asset.parent_asset_id,
+                    root_asset_id=asset.root_asset_id,
+                    version_no=asset.version_no,
+                    is_current_version=asset.is_current_version,
+                    uri=asset.uri,
+                    created_at=asset.created_at,
+                )
+                for asset in assets
+            ],
+        )
+
+    async def count_manual_revisions(self, session: AsyncSession, order_id: int) -> int:
+        """Return the number of manual revision assets for an order."""
+
+        result = await session.execute(
+            select(func.count(AssetORM.id)).where(
+                AssetORM.order_id == order_id,
+                AssetORM.asset_type == AssetType.MANUAL_REVISION,
+            )
+        )
+        return result.scalar_one()
+
+    async def _require_order(self, session: AsyncSession, order_id: int) -> OrderORM:
+        order = await session.get(OrderORM, order_id)
+        if order is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Order not found")
+        return order
+
+    async def _require_workflow_run(self, session: AsyncSession, order_id: int) -> WorkflowRunORM:
+        result = await session.execute(select(WorkflowRunORM).where(WorkflowRunORM.order_id == order_id))
+        workflow_run = result.scalar_one_or_none()
+        if workflow_run is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Workflow not found")
+        return workflow_run
+
+    async def _get_active_review_task(self, session: AsyncSession, order_id: int) -> ReviewTaskORM:
+        result = await session.execute(
+            select(ReviewTaskORM)
+            .where(
+                ReviewTaskORM.order_id == order_id,
+                ReviewTaskORM.status.in_(
+                    [ReviewTaskStatus.PENDING, ReviewTaskStatus.REVISION_UPLOADED]
+                ),
+            )
+            .order_by(ReviewTaskORM.created_at.desc(), ReviewTaskORM.id.desc())
+        )
+        review_task = result.scalars().first()
+        if review_task is None:
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="No active review task")
+        return review_task

app/application/services/workflow_service.py

@@ -7,12 +7,20 @@
 """
 
 from datetime import timedelta
+from math import ceil
 
 from fastapi import HTTPException, status
-from sqlalchemy import select
+from sqlalchemy import String, cast, func, or_, select
 from sqlalchemy.orm import selectinload
 
-from app.api.schemas.workflow import WorkflowStatusResponse, WorkflowStepRead
+from app.api.schemas.workflow import (
+    WorkflowListItemResponse,
+    WorkflowListResponse,
+    WorkflowStatusResponse,
+    WorkflowStepRead,
+)
+from app.domain.enums import OrderStatus
+from app.application.services.revision_service import RevisionService
 from app.domain.enums import ServiceMode
 from app.infra.db.models.workflow_run import WorkflowRunORM
 from app.infra.temporal.client import get_temporal_client
@@ -25,6 +33,9 @@ from app.workers.workflows.types import PipelineWorkflowInput, ReviewSignalPaylo
 class WorkflowService:
     """Temporal 编排服务。"""
 
+    def __init__(self) -> None:
+        self.revision_service = RevisionService()
+
     @staticmethod
     def workflow_type_for_mode(service_mode: ServiceMode) -> str:
         """根据服务模式返回对应的 workflow 类型名。"""
@@ -81,13 +92,101 @@ class WorkflowService:
         if workflow_run is None:
             raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Workflow not found")
 
+        snapshot = await self.revision_service.get_revision_snapshot(session, order_id)
+
         return WorkflowStatusResponse(
             order_id=workflow_run.order_id,
             workflow_id=workflow_run.workflow_id,
             workflow_type=workflow_run.workflow_type,
             workflow_status=workflow_run.status,
             current_step=workflow_run.current_step,
+            current_revision_asset_id=snapshot.current_revision_asset_id,
+            current_revision_version=snapshot.current_revision_version,
+            latest_revision_asset_id=snapshot.latest_revision_asset_id,
+            latest_revision_version=snapshot.latest_revision_version,
+            revision_count=snapshot.revision_count,
+            review_task_status=snapshot.review_task_status,
+            pending_manual_confirm=snapshot.pending_manual_confirm,
             steps=[WorkflowStepRead.model_validate(step) for step in workflow_run.steps],
             created_at=workflow_run.created_at,
             updated_at=workflow_run.updated_at,
         )
+
+    async def list_workflows(
+        self,
+        session,
+        *,
+        page: int = 1,
+        limit: int = 20,
+        query: str | None = None,
+        status_filter: OrderStatus | None = None,
+        order_id: int | None = None,
+    ) -> WorkflowListResponse:
+        """Return recent workflow runs for dashboard lookup pages."""
+
+        filters = []
+
+        if status_filter is not None:
+            filters.append(WorkflowRunORM.status == status_filter)
+
+        if order_id is not None:
+            filters.append(WorkflowRunORM.order_id == order_id)
+
+        if query:
+            search_term = query.strip()
+            if search_term:
+                filters.append(
+                    or_(
+                        cast(WorkflowRunORM.order_id, String).ilike(f"{search_term}%"),
+                        WorkflowRunORM.workflow_id.ilike(f"%{search_term}%"),
+                    )
+                )
+
+        query = select(WorkflowRunORM).options(selectinload(WorkflowRunORM.steps))
+        count_query = select(func.count()).select_from(WorkflowRunORM)
+
+        if filters:
+            query = query.where(*filters)
+            count_query = count_query.where(*filters)
+
+        total = (await session.execute(count_query)).scalar_one()
+        total_pages = ceil(total / limit) if total else 0
+        offset = (page - 1) * limit
+
+        query = query.order_by(WorkflowRunORM.updated_at.desc(), WorkflowRunORM.id.desc()).offset(offset).limit(limit)
+
+        result = await session.execute(query)
+        workflow_runs = result.scalars().all()
+
+        items = []
+        for workflow_run in workflow_runs:
+            snapshot = await self.revision_service.get_revision_snapshot(
+                session,
+                workflow_run.order_id,
+            )
+            items.append(
+                WorkflowListItemResponse(
+                    order_id=workflow_run.order_id,
+                    workflow_id=workflow_run.workflow_id,
+                    workflow_type=workflow_run.workflow_type,
+                    workflow_status=workflow_run.status,
+                    current_step=workflow_run.current_step,
+                    updated_at=workflow_run.updated_at,
+                    failure_count=sum(
+                        1 for step in workflow_run.steps if step.step_status.value == "failed"
+                    ),
+                    review_task_status=snapshot.review_task_status,
+                    latest_revision_asset_id=snapshot.latest_revision_asset_id,
+                    latest_revision_version=snapshot.latest_revision_version,
+                    revision_count=snapshot.revision_count,
+                    pending_manual_confirm=snapshot.pending_manual_confirm,
+                )
+            )
+
+        return WorkflowListResponse(
+            page=page,
+            limit=limit,
+            total=total,
+            total_pages=total_pages,
+            items=items,
+        )