feat: add schedule items CRUD API

- Add ScheduleItem Pydantic schemas with metadata support - Add repository layer with CRUD operations - Add service layer with authorization - Add FastAPI router with all endpoints - Add unit and integration tests - Update API documentation
2026-02-28 11:03:29 +08:00
parent dbd3f68dd4
commit 50b38de488
12 changed files with 1114 additions and 0 deletions
@@ -6,6 +6,7 @@ from core.http.models import HealthResponse
 from v1.agent_chat.router import router as agent_chat_router
 from v1.auth.router import router as auth_router
 from v1.infra.router import router as infra_router
+from v1.schedule_items.router import router as schedule_items_router
 from v1.users.router import router as users_router


@@ -14,6 +15,7 @@ router.include_router(auth_router)
 router.include_router(infra_router)
 router.include_router(users_router)
 router.include_router(agent_chat_router)
+router.include_router(schedule_items_router)


@router.get("/health", response_model=HealthResponse)
@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from core.auth.models import CurrentUser
+from core.db import get_db
+from v1.schedule_items.repository import SQLAlchemyScheduleItemRepository
+from v1.schedule_items.service import ScheduleItemService
+from v1.users.dependencies import get_current_user
+
+
+async def get_schedule_item_repository(
+    session: Annotated[AsyncSession, Depends(get_db)],
+) -> SQLAlchemyScheduleItemRepository:
+    return SQLAlchemyScheduleItemRepository(session)
+
+
+def get_schedule_item_service(
+    session: Annotated[AsyncSession, Depends(get_db)],
+    user: Annotated[CurrentUser, Depends(get_current_user)],
+) -> ScheduleItemService:
+    repository = SQLAlchemyScheduleItemRepository(session)
+    return ScheduleItemService(
+        repository=repository,
+        session=session,
+        current_user=user,
+    )
@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Protocol
+from uuid import UUID
+
+from sqlalchemy import select, update
+from sqlalchemy.exc import SQLAlchemyError
+
+from core.db.base_repository import BaseRepository
+from core.logging import get_logger
+from models.schedule_items import ScheduleItem
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+logger = get_logger("v1.schedule_items.repository")
+
+
+class ScheduleItemRepository(Protocol):
+    async def get_by_item_id(
+        self, item_id: UUID, owner_id: UUID
+    ) -> ScheduleItem | None: ...
+    async def create(self, data: dict) -> ScheduleItem: ...
+    async def update_by_item_id(
+        self, item_id: UUID, owner_id: UUID, data: dict
+    ) -> ScheduleItem | None: ...
+    async def delete_by_item_id(
+        self, item_id: UUID, owner_id: UUID
+    ) -> ScheduleItem | None: ...
+    async def list_by_date_range(
+        self, owner_id: UUID, start_at: datetime, end_at: datetime
+    ) -> list[ScheduleItem]: ...
+
+
+class SQLAlchemyScheduleItemRepository(BaseRepository[ScheduleItem]):
+    def __init__(self, session: AsyncSession) -> None:
+        super().__init__(session, ScheduleItem)
+
+    async def get_by_item_id(
+        self, item_id: UUID, owner_id: UUID
+    ) -> ScheduleItem | None:
+        try:
+            stmt = (
+                select(ScheduleItem)
+                .where(ScheduleItem.id == item_id)
+                .where(ScheduleItem.owner_id == owner_id)
+                .where(ScheduleItem.deleted_at.is_(None))
+            )
+            result = await self._session.execute(stmt)
+            return result.scalar_one_or_none()
+        except SQLAlchemyError:
+            logger.exception(
+                "Schedule item lookup failed",
+                item_id=str(item_id),
+                owner_id=str(owner_id),
+            )
+            raise
+
+    async def create(self, data: dict) -> ScheduleItem:
+        try:
+            item = ScheduleItem(**data)
+            self._session.add(item)
+            await self._session.flush()
+            return item
+        except SQLAlchemyError:
+            logger.exception("Schedule item creation failed")
+            raise
+
+    async def update_by_item_id(
+        self, item_id: UUID, owner_id: UUID, data: dict
+    ) -> ScheduleItem | None:
+        if not data:
+            return await self.get_by_item_id(item_id, owner_id)
+        try:
+            existing = await self.get_by_item_id(item_id, owner_id)
+            if existing is None:
+                return None
+            stmt = (
+                update(ScheduleItem)
+                .where(ScheduleItem.id == item_id)
+                .where(ScheduleItem.owner_id == owner_id)
+                .where(ScheduleItem.deleted_at.is_(None))
+                .values(**data)
+                .returning(ScheduleItem)
+            )
+            result = await self._session.execute(stmt)
+            await self._session.flush()
+            return result.scalar_one_or_none()
+        except SQLAlchemyError:
+            logger.exception("Schedule item update failed", item_id=str(item_id))
+            raise
+
+    async def delete_by_item_id(
+        self, item_id: UUID, owner_id: UUID
+    ) -> ScheduleItem | None:
+        try:
+            return await self.soft_delete_by_id(item_id)
+        except SQLAlchemyError:
+            logger.exception("Schedule item delete failed", item_id=str(item_id))
+            raise
+
+    async def list_by_date_range(
+        self, owner_id: UUID, start_at: datetime, end_at: datetime
+    ) -> list[ScheduleItem]:
+        try:
+            stmt = (
+                select(ScheduleItem)
+                .where(ScheduleItem.owner_id == owner_id)
+                .where(ScheduleItem.deleted_at.is_(None))
+                .where(ScheduleItem.start_at >= start_at)
+                .where(ScheduleItem.start_at <= end_at)
+                .order_by(ScheduleItem.start_at.asc())
+            )
+            result = await self._session.execute(stmt)
+            return list(result.scalars().all())
+        except SQLAlchemyError:
+            logger.exception("Schedule item list failed", owner_id=str(owner_id))
+            raise
@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query
+
+from v1.schedule_items.dependencies import get_schedule_item_service
+from v1.schedule_items.schemas import (
+    ScheduleItemCreateRequest,
+    ScheduleItemListItem,
+    ScheduleItemListRequest,
+    ScheduleItemResponse,
+    ScheduleItemUpdateRequest,
+)
+from v1.schedule_items.service import ScheduleItemService
+
+
+router = APIRouter(prefix="/schedule-items", tags=["schedule-items"])
+
+
+@router.post("", response_model=ScheduleItemResponse, status_code=201)
+async def create_schedule_item(
+    request: ScheduleItemCreateRequest,
+    service: Annotated[ScheduleItemService, Depends(get_schedule_item_service)],
+) -> ScheduleItemResponse:
+    return await service.create(request)
+
+
+@router.get("", response_model=list[ScheduleItemListItem])
+async def list_schedule_items(
+    service: Annotated[ScheduleItemService, Depends(get_schedule_item_service)],
+    start_at: datetime = Query(..., description="Start date/time for range query"),
+    end_at: datetime = Query(..., description="End date/time for range query"),
+) -> list[ScheduleItemListItem]:
+    request = ScheduleItemListRequest(start_at=start_at, end_at=end_at)
+    items = await service.list_by_date_range(request)
+    return [
+        ScheduleItemListItem(
+            id=item.id,
+            title=item.title,
+            start_at=item.start_at,
+            end_at=item.end_at,
+            timezone=item.timezone,
+            status=item.status,
+        )
+        for item in items
+    ]
+
+
+@router.get("/{item_id}", response_model=ScheduleItemResponse)
+async def get_schedule_item(
+    item_id: UUID,
+    service: Annotated[ScheduleItemService, Depends(get_schedule_item_service)],
+) -> ScheduleItemResponse:
+    return await service.get_by_id(item_id)
+
+
+@router.patch("/{item_id}", response_model=ScheduleItemResponse)
+async def update_schedule_item(
+    item_id: UUID,
+    request: ScheduleItemUpdateRequest,
+    service: Annotated[ScheduleItemService, Depends(get_schedule_item_service)],
+) -> ScheduleItemResponse:
+    return await service.update(item_id, request)
+
+
+@router.delete("/{item_id}", status_code=204)
+async def delete_schedule_item(
+    item_id: UUID,
+    service: Annotated[ScheduleItemService, Depends(get_schedule_item_service)],
+) -> None:
+    await service.delete(item_id)
@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import ClassVar
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class AttachmentType(str, Enum):
+    DOCUMENT = "document"
+    REMINDER = "reminder"
+
+
+class ScheduleItemMetadataAttachment(BaseModel):
+    name: str
+    type: AttachmentType
+    visible_to: list[UUID] = []
+    url: str | None = None
+    note: str | None = None
+    content: str | None = None
+
+
+class ScheduleItemMetadata(BaseModel):
+    color: str | None = None
+    location: str | None = None
+    notes: str | None = None
+    attachments: list[ScheduleItemMetadataAttachment] = []
+    version: int = 1
+
+
+class ScheduleItemStatus(str, Enum):
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    CANCELED = "canceled"
+    ARCHIVED = "archived"
+
+
+class ScheduleItemSourceType(str, Enum):
+    MANUAL = "manual"
+    IMPORTED = "imported"
+    AGENT_GENERATED = "agent_generated"
+
+
+class ScheduleItemCreateRequest(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
+    title: str = Field(min_length=1, max_length=255)
+    description: str | None = Field(default=None, max_length=2000)
+    start_at: datetime
+    end_at: datetime | None = None
+    timezone: str = "UTC"
+    metadata: ScheduleItemMetadata | None = None
+
+
+class ScheduleItemUpdateRequest(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
+    title: str | None = Field(default=None, min_length=1, max_length=255)
+    description: str | None = Field(default=None, max_length=2000)
+    start_at: datetime | None = None
+    end_at: datetime | None = None
+    timezone: str | None = None
+    metadata: ScheduleItemMetadata | None = None
+    status: ScheduleItemStatus | None = None
+
+    @field_validator("end_at", mode="before")
+    @classmethod
+    def validate_end_at(cls, v: datetime | None, info) -> datetime | None:
+        return v
+
+
+class ScheduleItemResponse(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(from_attributes=True)
+
+    id: UUID
+    title: str
+    description: str | None = None
+    start_at: datetime
+    end_at: datetime | None = None
+    timezone: str
+    metadata: ScheduleItemMetadata | None = None
+    status: ScheduleItemStatus
+    source_type: ScheduleItemSourceType
+    created_at: datetime
+    updated_at: datetime
+
+
+class ScheduleItemListItem(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(from_attributes=True)
+
+    id: UUID
+    title: str
+    start_at: datetime
+    end_at: datetime | None = None
+    timezone: str
+    status: ScheduleItemStatus
+
+
+class ScheduleItemListRequest(BaseModel):
+    start_at: datetime
+    end_at: datetime
@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from fastapi import HTTPException
+from sqlalchemy.exc import SQLAlchemyError
+
+from core.auth.models import CurrentUser
+from core.db.base_service import BaseService
+from core.logging import get_logger
+from models.schedule_items import ScheduleItem
+from v1.schedule_items.repository import ScheduleItemRepository
+from v1.schedule_items.schemas import (
+    ScheduleItemCreateRequest,
+    ScheduleItemListRequest,
+    ScheduleItemMetadata,
+    ScheduleItemResponse,
+    ScheduleItemUpdateRequest,
+    ScheduleItemSourceType,
+    ScheduleItemStatus,
+)
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+logger = get_logger("v1.schedule_items.service")
+
+
+class ScheduleItemService(BaseService):
+    _repository: ScheduleItemRepository
+    _session: AsyncSession
+
+    def __init__(
+        self,
+        repository: ScheduleItemRepository,
+        session: AsyncSession,
+        current_user: CurrentUser | None,
+    ) -> None:
+        super().__init__(current_user=current_user)
+        self._repository = repository
+        self._session = session
+
+    async def create(self, request: ScheduleItemCreateRequest) -> ScheduleItemResponse:
+        user_id = self.require_user_id()
+
+        if request.end_at and request.end_at <= request.start_at:
+            raise HTTPException(status_code=400, detail="end_at must be after start_at")
+
+        data = {
+            "owner_id": user_id,
+            "title": request.title,
+            "description": request.description,
+            "start_at": request.start_at,
+            "end_at": request.end_at,
+            "timezone": request.timezone,
+            "metadata": request.metadata.model_dump() if request.metadata else {},
+            "source_type": ScheduleItemSourceType.MANUAL,
+            "status": ScheduleItemStatus.ACTIVE,
+            "created_by": user_id,
+        }
+
+        try:
+            item = await self._repository.create(data)
+            await self._session.commit()
+        except SQLAlchemyError:
+            await self._session.rollback()
+            logger.exception("Failed to create schedule item")
+            raise HTTPException(
+                status_code=503, detail="Schedule item store unavailable"
+            )
+
+        return self._to_response(item)
+
+    async def get_by_id(self, item_id: UUID) -> ScheduleItemResponse:
+        user_id = self.require_user_id()
+
+        try:
+            item = await self._repository.get_by_item_id(item_id, user_id)
+        except SQLAlchemyError:
+            logger.exception("Failed to get schedule item", item_id=str(item_id))
+            raise HTTPException(
+                status_code=503, detail="Schedule item store unavailable"
+            )
+
+        if item is None:
+            raise HTTPException(status_code=404, detail="Schedule item not found")
+
+        return self._to_response(item)
+
+    async def update(
+        self, item_id: UUID, request: ScheduleItemUpdateRequest
+    ) -> ScheduleItemResponse:
+        user_id = self.require_user_id()
+
+        existing = await self._repository.get_by_item_id(item_id, user_id)
+        if existing is None:
+            raise HTTPException(status_code=404, detail="Schedule item not found")
+
+        update_data: dict = {}
+        if request.title is not None:
+            update_data["title"] = request.title
+        if request.description is not None:
+            update_data["description"] = request.description
+        if request.start_at is not None:
+            update_data["start_at"] = request.start_at
+        if request.end_at is not None:
+            update_data["end_at"] = request.end_at
+        if request.timezone is not None:
+            update_data["timezone"] = request.timezone
+        if request.status is not None:
+            update_data["status"] = request.status
+        if request.metadata is not None:
+            update_data["metadata"] = request.metadata.model_dump()
+
+        if request.end_at and request.start_at and request.end_at <= request.start_at:
+            raise HTTPException(status_code=400, detail="end_at must be after start_at")
+
+        if not update_data:
+            return self._to_response(existing)
+
+        try:
+            item = await self._repository.update_by_item_id(
+                item_id, user_id, update_data
+            )
+            await self._session.commit()
+        except SQLAlchemyError:
+            await self._session.rollback()
+            logger.exception("Failed to update schedule item", item_id=str(item_id))
+            raise HTTPException(
+                status_code=503, detail="Schedule item store unavailable"
+            )
+
+        if item is None:
+            raise HTTPException(status_code=404, detail="Schedule item not found")
+
+        return self._to_response(item)
+
+    async def delete(self, item_id: UUID) -> None:
+        user_id = self.require_user_id()
+
+        existing = await self._repository.get_by_item_id(item_id, user_id)
+        if existing is None:
+            raise HTTPException(status_code=404, detail="Schedule item not found")
+
+        try:
+            await self._repository.delete_by_item_id(item_id, user_id)
+            await self._session.commit()
+        except SQLAlchemyError:
+            await self._session.rollback()
+            logger.exception("Failed to delete schedule item", item_id=str(item_id))
+            raise HTTPException(
+                status_code=503, detail="Schedule item store unavailable"
+            )
+
+    async def list_by_date_range(
+        self, request: ScheduleItemListRequest
+    ) -> list[ScheduleItemResponse]:
+        user_id = self.require_user_id()
+
+        if request.end_at <= request.start_at:
+            raise HTTPException(status_code=400, detail="end_at must be after start_at")
+
+        try:
+            items = await self._repository.list_by_date_range(
+                user_id, request.start_at, request.end_at
+            )
+        except SQLAlchemyError:
+            logger.exception("Failed to list schedule items")
+            raise HTTPException(
+                status_code=503, detail="Schedule item store unavailable"
+            )
+
+        return [self._to_response(item) for item in items]
+
+    def _to_response(self, item: ScheduleItem) -> ScheduleItemResponse:
+        return ScheduleItemResponse(
+            id=item.id,
+            title=item.title,
+            description=item.description,
+            start_at=item.start_at,
+            end_at=item.end_at,
+            timezone=item.timezone,
+            metadata=ScheduleItemMetadata.model_validate(item.extra_metadata)
+            if item.extra_metadata
+            else None,
+            status=ScheduleItemStatus(item.status.value),
+            source_type=ScheduleItemSourceType(item.source_type.value),
+            created_at=item.created_at,
+            updated_at=item.updated_at,
+        )