# 分页规范

## 概述

统一使用 `pageNo`/`pageSize` 作为分页参数，Django `Paginator` 封装分页逻辑，返回标准分页结构。

:::tip 分页约定
- 前端传递 `pageNo`（页码，从 1 开始）和 `pageSize`（每页条数）
- 后端返回 `{records, total, size, current, pages}` 结构
- 默认每页 10 条（`PAGE_SIZE = 10`）
:::

## 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `pageNo` | int | 否 | 1 | 页码，从 1 开始 |
| `pageSize` | int | 否 | 10 | 每页条数 |

### 请求示例

```bash
# GET 请求
GET /example/page?pageNo=1&pageSize=10

# 带筛选条件
GET /example/page?pageNo=1&pageSize=10&name=案例&type=1&status=1
```

## 响应格式

```json
{
    "code": 0,
    "data": {
        "records": [
            {
                "id": 1,
                "name": "案例名称",
                "type": 1,
                "status": 1,
                "sort": 1,
                "createUser": "admin",
                "createTime": "2026-01-01 10:00:00"
            }
        ],
        "total": 50,
        "size": 10,
        "current": 1,
        "pages": 5
    },
    "msg": "操作成功",
    "ok": true
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `records` | array | 当前页数据列表 |
| `total` | int | 总记录数 |
| `size` | int | 每页条数 |
| `current` | int | 当前页码 |
| `pages` | int | 总页数 |

## Service 实现

### 分页查询方法

```python
from django.core.paginator import Paginator, PageNotAnInteger, InvalidPage, EmptyPage
from constant.constants import PAGE_SIZE
from utils import R

def get_example_page(request):
    """查询案例分页数据"""
    try:
        # 获取分页参数
        page_no = int(request.GET.get('pageNo', 1))
        page_size = int(request.GET.get('pageSize', PAGE_SIZE))

        # 构建基础查询（只查询未删除的记录）
        query = Example.objects.filter(is_delete=False)

        # 应用筛选条件
        query = _apply_filters(query, request)

        # 按排序字段升序排列
        query = query.order_by("sort")

        # 执行分页查询
        paginator = Paginator(query, page_size)
        try:
            page_list = paginator.page(page_no)
        except (PageNotAnInteger, InvalidPage, EmptyPage):
            # 页码无效时默认返回第一页
            page_list = paginator.page(1)
            page_no = 1

        # 构建并返回分页数据
        page_data = _build_page_data(page_list, paginator, page_no, page_size)
        return R.ok(data=page_data)

    except Exception as e:
        logging.error(f"查询案例分页数据异常: {str(e)}")
        return R.failed(msg="查询失败，请稍后重试")
```

### 分页数据构建

```python
def _build_page_data(page_list, paginator, page_no, page_size):
    """构建分页返回数据"""
    records = []
    for item in page_list:
        record = {
            'id': item.id,
            'name': item.name,
            'type': item.type,
            'status': item.status,
            'sort': item.sort,
            'createUser': item.create_user,
            'createTime': format_datetime(item.create_time),
            'updateUser': item.update_user,
            'updateTime': format_datetime(item.update_time),
        }
        records.append(record)

    return {
        'records': records,
        'total': paginator.count,    # 总记录数
        'size': page_size,           # 每页大小
        'current': page_no,          # 当前页码
        'pages': paginator.num_pages # 总页数
    }
```

### 筛选条件应用

```python
def _apply_filters(queryset, request):
    """应用查询筛选条件"""
    # 名称模糊筛选
    name = request.GET.get('name')
    if name:
        queryset = queryset.filter(name__contains=name)

    # 类型精确筛选
    type = request.GET.get('type')
    if type:
        queryset = queryset.filter(type=type)

    # 状态精确筛选
    status = request.GET.get('status')
    if status:
        queryset = queryset.filter(status=status)

    return queryset
```

:::tip 筛选字段说明
- 字符串字段使用 `__contains` 实现模糊查询（LIKE）
- 整数字段直接使用 `=` 实现精确匹配
- 空值自动跳过，无需手动判断
:::

## View 示例

```python
@method_decorator(check_login, name="get")
class ExamplePageView(PermissionRequired, View):
    """案例分页数据查询视图"""
    permission_required = ("sys:example:page",)

    @operation_log(title="案例管理-查询分页列表", log_type=LogType.QUERY)
    def get(self, request):
        result = services.get_example_page(request)
        return result
```

:::tip 权限标识
分页接口权限标识格式：`sys:{模块名}:page`
:::

## 总结

分页规范统一使用 `pageNo`/`pageSize` 参数，通过 Django `Paginator` 处理分页逻辑。Service 层构建查询、应用筛选、执行分页、构建返回数据。响应使用 `R.ok(data=page_data)` 封装标准分页结构，前端可直接使用 `records`/`total`/`pages` 渲染列表和分页组件。