perf(batch): paginate batch tasks

[shark0F0497]

Pull Request Checklist

Please ensure your PR meets the following requirements:

• Code follows the style guidelines
• Tests pass locally
• Code is formatted
• Documentation updated if needed
• Commit messages follow conventional commits
• PR description is complete and clear

---

Summary

This PR adds optional pagination to the batch task listing endpoint while preserving the legacy full-response behavior for existing callers that do not pass pagination parameters.

---

Motivation

• Batch detail pages can contain hundreds or thousands of associated tasks. Returning every task in a single /batches/:id/tasks response increases DB, network, memory, and rendering pressure.
• Existing batch editing and robot-control flows still rely on the full task list, so the endpoint needs a backward-compatible pagination path.

---

Changes

Modified Files

• internal/api/handlers/batch.go - Adds optional limit and offset query parameters to ListBatchTasks; when present, the endpoint returns paginated results with total, limit, offset, hasNext, and hasPrev. When omitted, the endpoint keeps returning the full task list for backward compatibility.
• internal/api/handlers/batch.go - Keeps the MySQL timestamp formatting for production and uses a sqlite-compatible expression in handler tests.
• internal/api/handlers/batch_test.go - Adds coverage for legacy full responses, paginated responses, and invalid pagination inputs.

Added Files

None

Deleted Files

None

---

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update (documentation changes only)
• Refactoring (code improvement without functional changes)
• Performance improvement (code changes that improve performance)
• Test changes (adding, modifying, or removing tests)

---

Impact Analysis

Breaking Changes

None

Backward Compatibility

Fully backward compatible. Existing callers that omit limit and offset still receive all tasks for the batch.

---

Testing

Test Environment

Local development environment with Go test cache redirected to /tmp/go-build-cache.

Test Cases

• Unit tests pass locally
• Integration tests pass locally
• E2E tests pass (if applicable)
• Manual testing completed

Manual Testing Steps

Not performed in this backend-only PR.

Test Coverage

• New tests added
• Existing tests updated
• Coverage maintained or improved

Commands run:

env GOCACHE=/tmp/go-build-cache go test ./internal/api/handlers -v
git diff --check

---

Screenshots / Recordings

Not applicable.

---

Performance Impact

• Memory usage: Decreased for paginated batch task consumers
• CPU usage: Decreased for paginated batch task consumers
• Throughput: Improved for batch detail task loading
• Lock contention: No change

---

Documentation

• README.md updated
• ARCHITECTURE.md updated
• CONTRIBUTING.md updated
• API documentation updated
• Design docs updated in docs/designs/
• No documentation changes needed

---

Related Issues

• Refers to the worktree1 review item about avoiding unbounded frontend entity and task enumeration.

---

Additional Notes

• This backend change is intended to pair with the Synapse PR that makes the batch detail page request tasks page by page.

---

Reviewers

None specified.

---

Notes for Reviewers

• Please review the backward-compatibility behavior in ListBatchTasks: no pagination parameters keep the previous full response, while passing limit or offset enables pagination.
• Please review the pagination metadata and validation behavior for consistency with other list endpoints.

---

Checklist for Reviewers

• Code changes are correct and well-implemented
• Tests are adequate and pass
• Documentation is updated and accurate
• No unintended side effects
• Performance impact is acceptable
• Backward compatibility maintained (if applicable)