feat(approvals): implement task locking and conflict resolution for pending approvals

backend/app/api/approvals.py

@@ -30,8 +30,10 @@ from app.schemas.approvals import ApprovalCreate, ApprovalRead, ApprovalStatus,
 from app.schemas.pagination import DefaultLimitOffsetPage
 from app.services.activity_log import record_activity
 from app.services.approval_task_links import (
+    lock_tasks_for_approval,
     load_task_ids_by_approval,
     normalize_task_ids,
+    pending_approval_conflicts_by_task,
     replace_approval_task_links,
     task_counts_for_board,
 )
@@ -114,6 +116,44 @@ def _serialize_approval(approval: ApprovalRead) -> dict[str, object]:
     return approval.model_dump(mode="json")
 
 
+def _pending_conflict_detail(conflicts: dict[UUID, UUID]) -> dict[str, object]:
+    ordered = sorted(conflicts.items(), key=lambda item: str(item[0]))
+    return {
+        "message": "Each task can have only one pending approval.",
+        "conflicts": [
+            {
+                "task_id": str(task_id),
+                "approval_id": str(approval_id),
+            }
+            for task_id, approval_id in ordered
+        ],
+    }
+
+
+async def _ensure_no_pending_approval_conflicts(
+    session: AsyncSession,
+    *,
+    board_id: UUID,
+    task_ids: Sequence[UUID],
+    exclude_approval_id: UUID | None = None,
+) -> None:
+    normalized_task_ids = list({*task_ids})
+    if not normalized_task_ids:
+        return
+    await lock_tasks_for_approval(session, task_ids=normalized_task_ids)
+    conflicts = await pending_approval_conflicts_by_task(
+        session,
+        board_id=board_id,
+        task_ids=normalized_task_ids,
+        exclude_approval_id=exclude_approval_id,
+    )
+    if conflicts:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=_pending_conflict_detail(conflicts),
+        )
+
+
 def _approval_resolution_message(
     *,
     board: Board,
@@ -324,6 +364,12 @@ async def create_approval(
         payload=payload.payload,
     )
     task_id = task_ids[0] if task_ids else None
+    if payload.status == "pending":
+        await _ensure_no_pending_approval_conflicts(
+            session,
+            board_id=board.id,
+            task_ids=task_ids,
+        )
     approval = Approval(
         board_id=board.id,
         task_id=task_id,
@@ -360,7 +406,19 @@ async def update_approval(
     updates = payload.model_dump(exclude_unset=True)
     prior_status = approval.status
     if "status" in updates:
-        approval.status = updates["status"]
+        target_status = updates["status"]
+        if target_status == "pending" and prior_status != "pending":
+            task_ids_by_approval = await load_task_ids_by_approval(session, approval_ids=[approval.id])
+            approval_task_ids = task_ids_by_approval.get(approval.id)
+            if not approval_task_ids and approval.task_id is not None:
+                approval_task_ids = [approval.task_id]
+            await _ensure_no_pending_approval_conflicts(
+                session,
+                board_id=board.id,
+                task_ids=approval_task_ids or [],
+                exclude_approval_id=approval.id,
+            )
+        approval.status = target_status
         if approval.status != "pending":
             approval.resolved_at = utcnow()
     session.add(approval)

backend/app/services/approval_task_links.py

@@ -11,6 +11,7 @@ from sqlmodel import col, select
 
 from app.models.approval_task_links import ApprovalTaskLink
 from app.models.approvals import Approval
+from app.models.tasks import Task
 
 if TYPE_CHECKING:
     from sqlmodel.ext.asyncio.session import AsyncSession
@@ -121,6 +122,88 @@ async def replace_approval_task_links(
         session.add(ApprovalTaskLink(approval_id=approval_id, task_id=task_id))
 
 
+async def lock_tasks_for_approval(
+    session: AsyncSession,
+    *,
+    task_ids: Sequence[UUID],
+) -> None:
+    """Acquire row locks for task ids in deterministic order within a transaction."""
+    normalized_task_ids = sorted({*task_ids}, key=str)
+    if not normalized_task_ids:
+        return
+    statement = (
+        select(col(Task.id))
+        .where(col(Task.id).in_(normalized_task_ids))
+        .order_by(col(Task.id).asc())
+        .with_for_update()
+    )
+    # Materialize results so the lock query fully executes before proceeding.
+    _ = list(await session.exec(statement))
+
+
+async def pending_approval_conflicts_by_task(
+    session: AsyncSession,
+    *,
+    board_id: UUID,
+    task_ids: Sequence[UUID],
+    exclude_approval_id: UUID | None = None,
+) -> dict[UUID, UUID]:
+    """Return the first conflicting pending approval id for each requested task id."""
+    normalized_task_ids = list({*task_ids})
+    if not normalized_task_ids:
+        return {}
+
+    linked_statement = (
+        select(
+            col(ApprovalTaskLink.task_id),
+            col(Approval.id),
+            col(Approval.created_at),
+        )
+        .join(Approval, col(Approval.id) == col(ApprovalTaskLink.approval_id))
+        .where(col(Approval.board_id) == board_id)
+        .where(col(Approval.status) == "pending")
+        .where(col(ApprovalTaskLink.task_id).in_(normalized_task_ids))
+        .order_by(col(Approval.created_at).asc(), col(Approval.id).asc())
+    )
+    if exclude_approval_id is not None:
+        linked_statement = linked_statement.where(col(Approval.id) != exclude_approval_id)
+    linked_rows = list(await session.exec(linked_statement))
+
+    conflicts: dict[UUID, UUID] = {}
+    for task_id, approval_id, _created_at in linked_rows:
+        conflicts.setdefault(task_id, approval_id)
+
+    legacy_statement = (
+        select(
+            col(Approval.task_id),
+            col(Approval.id),
+            col(Approval.created_at),
+        )
+        .where(col(Approval.board_id) == board_id)
+        .where(col(Approval.status) == "pending")
+        .where(col(Approval.task_id).is_not(None))
+        .where(col(Approval.task_id).in_(normalized_task_ids))
+        .where(
+            ~exists(
+                select(1)
+                .where(col(ApprovalTaskLink.approval_id) == col(Approval.id))
+                .correlate(Approval),
+            ),
+        )
+        .order_by(col(Approval.created_at).asc(), col(Approval.id).asc())
+    )
+    if exclude_approval_id is not None:
+        legacy_statement = legacy_statement.where(col(Approval.id) != exclude_approval_id)
+    legacy_rows = list(await session.exec(legacy_statement))
+
+    for task_id, approval_id, _created_at in legacy_rows:
+        if task_id is None:
+            continue
+        conflicts.setdefault(task_id, approval_id)
+
+    return conflicts
+
+
 async def task_counts_for_board(
     session: AsyncSession,
     *,