[Customer Portal][BE] Add time cards search endpoint for project scoped to cases

[Rashmika998]

Summary

This PR introduces a new endpoint to search time cards for a project, scoped to cases.

Changes

• Added time cards search endpoint for a project:
  • POST /projects/{id}/time-cards/search
• Implemented filtering logic to fetch time cards linked to cases within the project
• Added validation for project and case associations
• Updated request/response models
• Integrated service-layer query handling

Functionality

The new endpoint enables:

• Searching time cards within a project
• Fetching time cards associated with cases under the project
• Supporting filtering (e.g., by case, user, date range if applicable)
• Handling complex queries via POST payload

Reason

Previously, time cards were not easily searchable at the project level when bound to cases.
This enhancement enables:

• Better visibility into time spent per project
• Case-level time tracking within projects
• Improved reporting and dashboard capabilities
• Reduced need for frontend aggregation

Testing

• Verified time card search scoped to project and cases
• Tested filtering with different parameters
• Confirmed behavior for invalid project/case IDs
• Tested empty result scenarios

Impact

• New endpoint added (non-breaking enhancement)
• No changes to existing APIs
• Improves time tracking and reporting capabilities

Summary by CodeRabbit

• New Features
  • Added a new search endpoint that retrieves and groups time cards by cases, including aggregated billing information (billable/non-billable hours and counts) with support for filtering and pagination.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces a new case-grouped time card search feature, adding a dedicated entity function, API endpoint, service handler, and supporting types. The changes enable searching time cards aggregated by cases rather than as individual records, while preserving existing time card search functionality.

Changes

Cohort / File(s)	Summary
Entity Module modules/entity/entity.bal, modules/entity/types.bal	Added searchTimeCardsGroupedByCases() function to query the /cases/time-cards/search endpoint and new record types (CaseTimeCardBillingInfo, CaseTimeCardSummary, CaseTimeCardsSearchResponse) to model aggregated time card data grouped by cases.
Type System modules/types/types.bal	Removed untyped json... fields from ProductVersion and TimeCard records; added CaseTimeCard and CaseTimeCardsSearchResponse types to support case-grouped search results.
API and Service openapi.yaml, service.bal, utils.bal	Added POST endpoint /projects/{id}/cases/time-cards/search with OpenAPI definition; implemented service handler with authentication and error handling; added mapTimeCardSearchResponseGroupedByCases() mapper to transform entity responses to service response types.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Service as Service Handler
    participant Entity as Entity Module
    participant Backend as Backend API

    Client->>Service: POST /projects/{id}/cases/time-cards/search<br/>(with payload & auth)
    Service->>Service: Validate auth & build filters<br/>(projectIds, dates, states)
    Service->>Entity: searchTimeCardsGroupedByCases<br/>(idToken, payload)
    Entity->>Backend: POST /cases/time-cards/search<br/>(with headers & payload)
    Backend-->>Entity: CaseTimeCardsSearchResponse<br/>(cases, totalRecords)
    Entity-->>Service: CaseTimeCardsSearchResponse
    Service->>Service: mapTimeCardSearchResponseGroupedByCases<br/>(transform to types model)
    Service-->>Client: http:Ok<br/>(caseTimeCards[], pagination)
    
    Note over Service: On error:<br/>400/401/403/500<br/>with typed responses

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• [Customer Portal][BE] Add time cards search endpoints #219: Original time card search feature that this PR extends with case-grouped aggregation variants and new supporting types and endpoints.

Suggested reviewers

• shayanmalinda
• cloby99

Poem

🐰 A rabbit with burrow so deep,
Found time cards in case-grouped heaps!
Grouped and sorted, clean and bright,
Search results mapped just right! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description provides a summary and details of changes, but lacks several required template sections such as Purpose with issue links, Goals, Approach, User stories, Release note, Documentation, Training, Certification, Marketing, Automation tests, Security checks, and Test environment.	Complete the description by adding all required template sections, especially Purpose (with related issue links), Goals, Release note, Documentation, and Automation tests details.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the primary change: adding a new time cards search endpoint for projects scoped to cases.
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

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/customer-portal/backend/openapi.yaml`:
- Around line 2077-2078: The 200 response for the grouped-search endpoint lacks
a JSON schema, so update the OpenAPI entry for the grouped-search response to
reference the correct schema (CaseTimeCardsSearchResponse) and add the missing
components/schemas definitions for CaseTimeCardsSearchResponse and any nested
grouped time-card record objects used by it (e.g., GroupedTimeCard,
TimeCardRecord or similarly named models) under components.schemas; then
regenerate the OpenAPI client artifacts so generated clients use the typed
response.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 97805cc1-82cd-4565-81b2-b3432957f106

📥 Commits

Reviewing files that changed from the base of the PR and between d682d02 and 8abe9f3.

📒 Files selected for processing (6)

• apps/customer-portal/backend/modules/entity/entity.bal
• apps/customer-portal/backend/modules/entity/types.bal
• apps/customer-portal/backend/modules/types/types.bal
• apps/customer-portal/backend/openapi.yaml
• apps/customer-portal/backend/service.bal
• apps/customer-portal/backend/utils.bal