feat: spec for new BaseFilter

[scardanzan]

Summary by CodeRabbit

• New Features
  • Introduced a new filtering abstraction enabling simplified filter-based queries
  • Added support for field-level filtering with annotations, including range predicates and null-handling policies
  • Expanded DAO query methods to accept the new filter model with built-in sorting and pagination support

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 698e71be-7ea7-46de-9804-c85fedc647cd

📥 Commits

Reviewing files that changed from the base of the PR and between 7733411 and 4bcc761.

📒 Files selected for processing (1)

• specs/base-filter.md

---

Walkthrough

This PR adds a comprehensive specification document for a new annotation-driven JPA criteria filtering abstraction. The BaseFilter model provides ordering and pagination, field-level metadata annotations map to predicates, a criteria processor builds typed queries, and DAO extensibility hooks enable customization. The existing QuerySpec API is deprecated without removal, with a migration path to the new approach.

Changes

BaseFilter JPA Criteria Filtering Specification

Layer / File(s)	Summary
BaseFilter model and construction patterns specs/base-filter.md	Defines BaseFilter abstract class with Order enum (ASC/DESC), ordering and pagination fields, convenience addOrder methods, and dual construction via POJO setters or Lombok @SuperBuilder with insertion-order-preserving order map.
Filter metadata annotations specs/base-filter.md	Runtime-retained field-level annotations: @Attribute for dotted-path mapping, @From/@To for inclusive/exclusive range bounds with BETWEEN optimization, @WhenNull for null-skipping or IS_NULL policy, and validation rules tying them together.
DAO integration and criteria processor specs/base-filter.md	Three new DAO overloads (filter, filterWithSingleResult, count) accepting BaseFilter. BaseFilterJpaProcessor pipeline: per-class reflection caching, annotation validation, predicate construction (equality/bounds/ranges with shared path utilities), sort application, hook invocation, and pagination.
Extensibility hooks and migration strategy specs/base-filter.md	Two default no-op customization hooks (customizePredicates, customizeCriteria) on ConversionJpaDaoSupport. Deprecation plan for QuerySpec/Constraint/ConstraintTransformer without removal; path/join helper extracted as non-deprecated utility. Special-case handling for mixed-inclusive range bounds.
Usage example, placement, and scope management specs/base-filter.md	Concrete PersonFilter example demonstrating both construction styles and expected predicate behavior. Module placement guidance, open questions on default sort, validation timing, and field inheritance. Out-of-scope items: operator-specific annotations, boolean composition, pluggable processors, QuerySpec removal, and projections.

---

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change—adding a specification document for a new BaseFilter feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch base-filter

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud