Approved Claims Query Service
Component Detail
Description
Queries the database for approved expense claims within a configurable date range, grouped by peer mentor and expense type as required by accounting export specifications. Returns a structured claim set ready for field mapping, pre-filtered to exclude already-exported records.
approved-claims-query
Summaries
The Approved Claims Query Service is the data retrieval foundation for the accounting export process. It ensures that only legitimately approved expense claims — scoped to the correct organization and date range — are ever presented for export, preventing premature or unauthorized claim inclusion. By grouping results by peer mentor and expense type before they reach the export mappers, it reduces downstream processing complexity and ensures the output format aligns with accounting team expectations. Accurate, well-scoped claim retrieval is the first line of defense against export errors and the foundation of a trustworthy reimbursement workflow.
The Approved Claims Query Service is a medium-complexity backend component with no service dependencies, making it an ideal early deliverable. It must be completed and validated before any export mapper or file generator can be meaningfully tested with realistic data. Key risks include date range edge cases (timezone handling, inclusive/exclusive boundaries), claim status transition timing, and query performance on large claim datasets. The groupByPeerMentorAndType() output contract must be agreed with the downstream Dynamics Exporter and Xledger Exporter teams before integration work begins to avoid interface mismatch rework.
getApprovedClaimsForExport() filters by orgId, claim status = 'approved', and a date range against the claim submission or approval date — confirm which timestamp with product. Index on (orgId, status, approvalDate) for query performance. groupByPeerMentorAndType() is a pure in-memory transform returning a map keyed by [peerId, expenseTypeId] — keep this stateless for testability. getClaimsByIds() supports bulk fetch for re-hydration after ID-based filtering by Double-Export Guard.
countApprovedClaims() should use a COUNT query, not load full records. Ensure the service never returns claims in 'pending' or 'rejected' status regardless of other filters to enforce the approval gate.
Responsibilities
- Fetch approved claims for a given org within the requested date range
- Group results by peer mentor and expense type
- Exclude claims not in approved status
- Return structured query result for downstream mapping and validation
Interfaces
getApprovedClaimsForExport(orgId, dateRange): ExpenseClaim[]
groupByPeerMentorAndType(claims): GroupedClaims
getClaimsByIds(claimIds): ExpenseClaim[]
countApprovedClaims(orgId, dateRange): int
Relationships
Related Data Entities (4)
Data entities managed by this component