"""
通用分页：offset/limit 参数与分页结果结构。
各 feature 的 router 按需使用，成功响应直接返回 Pydantic model，不强制包装。
"""

from typing import Generic, TypeVar

from pydantic import BaseModel

T = TypeVar("T")


class PageParams(BaseModel):
    """常用分页查询参数（router 中通过 Depends 注入）。"""

    offset: int = 0
    limit: int = 20

    def clamp_limit(self, max_limit: int = 100) -> int:
        return min(max(1, self.limit), max_limit)


class Page(BaseModel, Generic[T]):
    """分页结果：items + total（可选）。"""

    items: list[T]
    total: int | None = None
    offset: int = 0
    limit: int = 20