feat: implement audit log pagination, bounded batch retention cleanup…

[Fatimasanusi]

Description

This PR resolves four backend and smart contract operational issues: replacing collision-prone reward shop identifiers with deterministic UUIDs and idempotency protection, implementing the admin moderation audit query API with canonical auth, adding bounded retention cleanup cron jobs for high-volume append-only tables, and providing the contract pause and recovery runbook.

Closes #542
Closes #557
Closes #561
Closes #562

---

Key Changes by Issue

1. #542 Reward Shop Collision Fix & Idempotency

• Deterministic ID Generation: Replaced Date.now() + Math.random with uuidv4() in RewardShopService.
• Idempotency Protection: Added optional idempotencyKey support in PurchaseItemDto and purchaseItem(). Retried requests with the same key return the existing record without deducting user points or inventory a second time.
• Backwards Compatibility: Legacy purchase-* records remain queryable via getPurchaseById(); added readable referenceId.
• Tests: Added tests for UUID v4 validation, idempotency retry guarantees, and legacy record retrieval.

2. #557 Admin Moderation Audit Query API

• Filter Contract & Pagination: Enhanced FilterAuditLogDto and AuditLogService.findAll() to filter by actor/userId, targetType, targetId, action, and date ranges, with bounded pagination (limit capped at 100) and deterministic ordering (timestamp DESC, id DESC).
• Canonical Authorization: Standardized AuditLogController and ModerationController on canonical JwtAuthGuard and RolesGuard (AdminRole.ADMIN, AdminRole.SUPERADMIN).
• Moderation Correlation: Added GET /admin/audit-logs/moderation/:reviewId and GET /moderation/:reviewId/decision-history to correlate moderation decisions with immutable audit log trails.
• Documentation & Tests: Added endpoint documentation in docs/api.md and test coverage in audit-log.controller.spec.ts and audit-log.service.spec.ts.

3. #561 Retention Jobs for High-Volume Append-Only Records

• Documented Retention Policy: Added docs/retention-policy.md documenting windows and separating user-facing history from operational telemetry:
  • analytics_events: 90 days (recent solve history retained; historical totals preserved via puzzle_stats_mv).
  • audit_logs: 90 days (compliance audit trail).
  • activity_logs: 30 days (operational debugging; user achievements stored in domain tables).
  • puzzle_access_logs: 14 days (short-term trend telemetry).
• Bounded Batch Deletion: Implemented @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT) batch cleanup in AnalyticService, AuditLogService, UserActivityLogService, and PuzzleAccessLogService.
• Concurrency & Observability: Uses FOR UPDATE SKIP LOCKED and ID batching to prevent table locking and race conditions across replicas. Emits structured logs with duration and deleted counts per run.
• Tests: Added batching and cutoff selection unit tests across all 4 services.

4. #562 Contract Pause & Recovery Operator Runbook

• Incident Response Guide: Created onchain/docs/pause-and-recovery-runbook.md and docs/pause-and-recovery-runbook.md.
• Decision Guide: Details scope, limits, and combinations for Game Contract Pause (stellar_hunts), NFT Contract Pause (stellar_hunts_nft), and Backend Maintenance Mode.
• Procedures: Provides exact stellar contract invoke and curl commands, expected returns, and halt verification steps.
• Recovery: Documents preconditions, step-by-step unpausing order, and reconciliation paths for interrupted submissions and in-flight NFT claims.

---

Verification

• Unit test suites updated for reward-shop, audit-log, analytic, user-activity-log, and puzzle-access-log.
• Math.random references removed from reward-shop.
• API documentation updated in docs/api.md.

[drips-wave]

@Fatimasanusi 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