fix(db): give a contribution its cycle identifier

[sanntotal]

Overview

This PR gives model Contribution an explicit cycle reference so cycle-scoped queries no longer reconstruct the cycle from createdAt timestamp ranges. The contribution scheduler now assigns the cycle when a contribution is recorded, and the reconciliation and payout queries select by that identifier. A migration backfills historical rows where possible and leaves them readable when no cycle can be inferred.

Related Issue

Changes

🗄️ Schema

• [MODIFY] prisma/schema.prisma

  • Contribution gains a cycle reference (nullable, so historical rows remain valid) assigned when the contribution is recorded.
  • ReconciliationMismatch.dbAmount documentation now matches what the schema can express: sum of COMPLETED Contribution records for this user+group in the current cycle, selected by cycle identifier.

• [ADD] prisma/migrations/20260901000000_add_contribution_cycle/migration.sql

  • Adds the cycle column and supporting index.
  • Backfills historical rows from the existing cycle window where it can be inferred; rows that cannot be resolved are left null and remain readable.

⚙️ Write Path

• [MODIFY] src/workers/contribution-scheduler.worker.ts
  • Assigns the cycle identifier when a contribution is recorded, instead of relying on the timestamp window alone.

🔍 Read Path

• [MODIFY] src/workers/contract-sync.worker.ts

  • Cycle-scoped filtering selects by cycle identifier rather than createdAt: { gte: cycleStart, lte: cycleEnd }.
  • Timestamp window retained only as a fallback for historical rows with no cycle.

• [MODIFY] src/services/payout.service.ts

  • Payout cycle queries select by cycle identifier instead of building a window from currentCycleStart / currentCycleEnd.
  • Same fallback for historical rows without a cycle.

🧪 Tests

• [ADD] src/__tests__/contribution-cycle.test.ts
  • Covers a two-cycle sequence: contributions recorded in consecutive cycles are attributed to the correct cycle and are not mixed by timestamp overlap.
  • Covers historical rows with no cycle remaining readable via the fallback path.

Verification Results

npm test
✅ passes locally

Acceptance Criteria	Status
A contribution records the cycle it belongs to	✅ Cycle reference assigned on write in the contribution scheduler
Reconciliation and payout queries select by that identifier rather than by timestamp range	✅ contract-sync.worker.ts and payout.service.ts select by cycle identifier
Historical rows remain readable	✅ Nullable cycle + migration backfill; timestamp window kept as fallback
A migration is included and a test covers a two-cycle sequence	✅ 20260901000000_add_contribution_cycle + contribution-cycle.test.ts
npm test passes locally	✅ Verified locally

Closes #246

[drips-wave]

@sanntotal Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits