Framework pagination helper (PageParams + paginate) to replace per-module copies with inconsistent validation #513

Tier 3: duplication

Problem

Pagination is reimplemented module by module:

• offset((page - 1) * per_page): users/admin/queries.py:190, file_storage/queries.py:115, background_tasks/outbox_service.py:72
• total_pages clamping: users/admin/views.py:80, file_storage/endpoints/views.py:57, settings/endpoints/views.py:110, audit_log/endpoints/views.py:111

Validation is inconsistent:

• background_tasks/endpoints/views.py:59 and file_storage/endpoints/views.py:32 take page: int = Query(default=1) with no ge.
• tenants/endpoints/admin.py:23,28 takes a bare page: int = 1.

So page=0 or a negative page behaves differently from module to module, and can produce a negative offset.

The frontend has the matching duplication: 7 hand-rolled pagination UIs and no shared component.

Fix

• Backend: add a PageParams dependency (page: int = Query(1, ge=1), per_page: int = Query(25, ge=1, le=200)) and async paginate(session, stmt, params) -> Page[T] returning {items, total, page, pages}, in simple_module_db or simple_module_hosting.
• Frontend: add a PaginationBar to packages/ui that consumes the Page shape.
• Migrate the call sites above.