Add cursor-based pagination with Page Token implementation

[Copilot]

Implementation Plan: Cursor-Based Pagination with Page Tokens

Overview

Add cursor-based pagination using Page Tokens as an alternative to offset-based pagination in AutoQuery.

Changes Required

• Add HasCursorKey method to FilterQueryBuilder<TQueryOptions, TData> to configure the cursor property
• Create IQueryCursorOptions interface for cursor-based pagination options
• Create CursorPagedResult<TData> record to hold cursor pagination results
• Add cursor token encoding/decoding utilities (PageToken class)
• Add ApplyQueryCursorPaged extension methods in QueryExtensions
• Update IQueryProcessor interface to include GetCursorKeySelector method
• Create example configuration in AutoQueryApiDemo showing HasCursorKey usage
• Add tests for cursor-based pagination functionality
• Update documentation in README with cursor pagination usage
• Address code review feedback
• Reorganize tests to follow project naming conventions

Test Organization

Following project structure conventions:

• PageTokenTests.cs - Tests for PageToken.cs (9 tests)
• FilterQueryBuilderTests.cs - Tests for FilterQueryBuilder.cs including HasCursorKey() (7 tests)
• Extensions/QueryExtensionsTests.cs - Tests for Extensions/QueryExtensions.cs including ApplyQueryCursorPaged() (new class: QueryExtensionsCursorPaginationTests with 9 tests)

Test Coverage

• 128 total tests passing (118 in AutoQuery, 10 in AutoQuery.AspNetCore)
• 25 tests covering cursor pagination functionality
• All tests follow project naming and folder structure conventions

Implementation Complete

All functionality has been implemented, tested, documented, code-reviewed, and organized according to project conventions. The cursor-based pagination feature is production-ready.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add Page Token Implementation for Cursor-Based Pagination</issue_title>
<issue_description>Implement cursor-based pagination in AutoQuery by introducing Page Tokens. This method overcomes the limitations of traditional offset-based pagination, which can lead to inconsistent results due to data changes between requests and suffer from performance issues on large datasets.

Using opaque Page Tokens to represent the cursor position enables efficient and reliable navigation through result sets without relying on OFFSET and LIMIT clauses. The implementation will include generation, encoding, and decoding of these tokens to facilitate seamless paging.

This enhancement provides a scalable and robust pagination mechanism suitable for high-volume and real-time data access scenarios.</issue_description>

<agent_instructions>幫我使用像是建構器模式設置 HasCursorKey(d => d.Key); 在 IFilterQueryConfiguration 裡面，你可以參考 AutoQueryApiDemo</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Add Page Token Implementation for Cursor-Based Pagination #11

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[willysoft]

我的單元測試檔案，與實際程式碼和資料夾有命名關聯，你看一下專案與單元測試專案結構

[Copilot]

我的單元測試檔案，與實際程式碼和資料夾有命名關聯，你看一下專案與單元測試專案結構

已重新組織測試檔案以符合專案命名規範：

• PageTokenTests.cs - 測試 PageToken.cs
• FilterQueryBuilderTests.cs - 測試 FilterQueryBuilder.cs (包含 HasCursorKey())
• Extensions/QueryExtensionsTests.cs - 測試 Extensions/QueryExtensions.cs (新增 QueryExtensionsCursorPaginationTests 類別測試 ApplyQueryCursorPaged())

已刪除 CursorPaginationTests.cs，所有測試都已移至對應的測試檔案中。測試結構現在與程式碼資料夾結構一致。

Commit: 4e0c18b