feat: implement campaign analytics rollups, trending, and impact metr…

docs/API.md

@@ -262,6 +262,33 @@ GET /campaigns/:id/stats
 Authorization: Bearer <access_token>
 ```
 
+#### Get Trending Campaigns
+
+```http
+GET /campaigns/trending?period=last24h&sortBy=trendScore&limit=10
+Authorization: Bearer <access_token>
+```
+
+Returns top campaigns by donation velocity, donor growth, or impact.
+
+#### Get Campaign Impact Metrics
+
+```http
+GET /campaigns/:id/impact-metrics
+Authorization: Bearer <access_token>
+```
+
+Returns comprehensive impact metrics: total donations, donor growth, distributions, beneficiaries reached, conversion rates.
+
+#### Get Campaign Historical Statistics
+
+```http
+GET /campaigns/:id/statistics/historical?granularity=hourly&startDate=2024-01-01&endDate=2024-01-31
+Authorization: Bearer <access_token>
+```
+
+Returns monthly or hourly rollup data for trend charts.
+
 ### Organizations
 
 #### Create Organization
@@ -538,6 +565,24 @@ Authorization: Bearer <access_token>
 }
 ```
 
+### Analytics
+
+#### Get Aggregated Campaign Analytics (Admin)
+
+```http
+GET /analytics/campaigns?page=1&limit=10&status=ACTIVE&sortBy=createdAt&sortOrder=desc
+Authorization: Bearer <admin_access_token>
+```
+
+Returns aggregated campaign metrics from rollup tables for admin dashboards.
+
+#### Get Campaign Analytics
+
+```http
+GET /analytics/campaign/:campaignId
+Authorization: Bearer <access_token>
+```
+
 ### Distributions
 
 #### Create Distribution

prisma/schema.prisma

@@ -794,6 +794,10 @@ enum JobType {
   DISTRIBUTION_PROCESSING
   REPORT_GENERATION
   CACHE_INVALIDATION
+  ANALYTICS_HOURLY
+  ANALYTICS_MONTHLY
+  ANALYTICS_REALTIME
+  ANALYTICS_TRENDING_REFRESH
 }
 
 model QueueJob {

src/config/index.ts

@@ -94,6 +94,19 @@ export const config = {
     // Notify donors when a campaign is suspended for a fraud-related reason.
     notifyDonorsOnFraudSuspension: process.env.MODERATION_NOTIFY_DONORS_ON_FRAUD !== 'false',
   },
+
+  analytics: {
+    // Cron patterns for rollup jobs (configurable via env vars)
+    hourlyRollupCron: process.env.ANALYTICS_HOURLY_CRON || '5 * * * *',
+    monthlyRollupCron: process.env.ANALYTICS_MONTHLY_CRON || '0 2 1 * *',
+    trendingRefreshCron: process.env.ANALYTICS_TRENDING_CRON || '*/15 * * * *',
+    // Feature flag to disable analytics worker
+    analyticsWorkerEnabled: process.env.ANALYTICS_WORKER_ENABLED !== 'false',
+    // Cache TTL for campaign stats in seconds
+    campaignStatsCacheTTL: parseInt(process.env.ANALYTICS_CACHE_TTL || '3600', 10),
+    // Number of trending campaigns to track
+    trendingCampaignsCount: parseInt(process.env.ANALYTICS_TRENDING_COUNT || '20', 10),
+  },
 };
 
 export default config;

src/controllers/analytics.controller.ts

@@ -1,4 +1,4 @@
-import { Response, NextFunction } from 'express';
+import { Request, Response, NextFunction } from 'express';
 import { AnalyticsService } from '../services/analytics.service';
 import { AuthRequest } from '../types';
 import { AppError } from '../middleware/error';
@@ -91,4 +91,85 @@ export class AnalyticsController {
       next(error);
     }
   }
+
+  static async getTrendingCampaigns(req: Request, res: Response, next: NextFunction): Promise<void> {
+    try {
+      const period = (req.query.period as 'last24h' | 'last7d' | 'last30d') || 'last24h';
+      const sortBy = (req.query.sortBy as 'trendScore' | 'donationVelocity' | 'distributionImpact') || 'trendScore';
+      const limit = req.query.limit ? parseInt(req.query.limit as string) : 10;
+
+      const trending = await AnalyticsService.getTrendingCampaigns({ period, sortBy, limit });
+
+      res.status(200).json({
+        success: true,
+        data: trending,
+      });
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  static async getCampaignImpactMetrics(req: Request, res: Response, next: NextFunction): Promise<void> {
+    try {
+      const { id } = req.params;
+      const metrics = await AnalyticsService.getCampaignImpactMetrics(id);
+
+      res.status(200).json({
+        success: true,
+        data: metrics,
+      });
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  static async getCampaignHistoricalStats(req: Request, res: Response, next: NextFunction): Promise<void> {
+    try {
+      const { id } = req.params;
+      const granularity = (req.query.granularity as 'hourly' | 'monthly') || 'hourly';
+      const startDate = req.query.startDate ? new Date(req.query.startDate as string) : undefined;
+      const endDate = req.query.endDate ? new Date(req.query.endDate as string) : undefined;
+
+      const range = startDate && endDate ? { startDate, endDate } : undefined;
+
+      const stats = await AnalyticsService.getCampaignHistoricalStats(id, granularity, range);
+
+      res.status(200).json({
+        success: true,
+        data: stats,
+      });
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  static async getAggregatedCampaignAnalytics(req: AuthRequest, res: Response, next: NextFunction): Promise<void> {
+    try {
+      if (!req.user || req.user.role !== 'ADMIN') {
+        throw new AppError('Admin access required', 403);
+      }
+
+      const filters = {
+        status: req.query.status as string,
+        startDate: req.query.startDate ? new Date(req.query.startDate as string) : undefined,
+        endDate: req.query.endDate ? new Date(req.query.endDate as string) : undefined,
+      };
+
+      const pagination = {
+        page: req.query.page ? parseInt(req.query.page as string) : 1,
+        limit: req.query.limit ? parseInt(req.query.limit as string) : 10,
+        sortBy: req.query.sortBy as string || 'createdAt',
+        sortOrder: (req.query.sortOrder as 'asc' | 'desc') || 'desc',
+      };
+
+      const result = await AnalyticsService.getAggregatedCampaignAnalytics(filters, pagination);
+
+      res.status(200).json({
+        success: true,
+        ...result,
+      });
+    } catch (error) {
+      next(error);
+    }
+  }
 }

src/routes/analytics.routes.ts

@@ -65,4 +65,16 @@ router.post(
   AnalyticsController.generateReport
 );
 
+/**
+ * @route   GET /api/v1/analytics/campaigns
+ * @desc    Admin endpoint to query aggregated campaign metrics
+ * @access  Private (Admin)
+ */
+router.get(
+  '/campaigns',
+  authenticate,
+  analyticsLimiter,
+  AnalyticsController.getAggregatedCampaignAnalytics
+);
+
 export default router;

src/routes/campaign.routes.ts

@@ -1,6 +1,7 @@
 import { Router } from 'express';
 import { CampaignController } from '../controllers/campaign.controller';
 import { ModerationController } from '../controllers/moderation.controller';
+import { AnalyticsController } from '../controllers/analytics.controller';
 import { authenticate } from '../middleware/auth';
 import { campaignCreateLimiter, reportLimiter } from '../middleware/rateLimit';
 import { validate } from '../middleware/validation';
@@ -89,6 +90,35 @@ router.post('/', campaignCreateLimiter, validate(campaignSchema), CampaignContro
  */
 router.get('/', CampaignController.getCampaigns);
 
+/**
+ * @swagger
+ * /api/v1/campaigns/trending:
+ *   get:
+ *     summary: Get trending campaigns by donation velocity, donor growth, or impact
+ *     tags: [Campaigns]
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: query
+ *         name: period
+ *         schema:
+ *           type: string
+ *           enum: [last24h, last7d, last30d]
+ *       - in: query
+ *         name: sortBy
+ *         schema:
+ *           type: string
+ *           enum: [trendScore, donationVelocity, distributionImpact]
+ *       - in: query
+ *         name: limit
+ *         schema:
+ *           type: integer
+ *     responses:
+ *       200:
+ *         description: Trending campaigns retrieved successfully
+ */
+router.get('/trending', AnalyticsController.getTrendingCampaigns);
+
 /**
  * @swagger
  * /api/v1/campaigns/{id}:
@@ -283,6 +313,61 @@ router.post('/:campaignId/beneficiaries', CampaignController.assignBeneficiary);
  */
 router.get('/:id/stats', CampaignController.getCampaignStats);
 
+/**
+ * @swagger
+ * /api/v1/campaigns/{id}/impact-metrics:
+ *   get:
+ *     summary: Get campaign impact metrics from aggregated data
+ *     tags: [Campaigns]
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: Campaign impact metrics retrieved successfully
+ */
+router.get('/:id/impact-metrics', AnalyticsController.getCampaignImpactMetrics);
+
+/**
+ * @swagger
+ * /api/v1/campaigns/{id}/statistics/historical:
+ *   get:
+ *     summary: Get monthly or weekly rollup data for trend charts
+ *     tags: [Campaigns]
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - in: query
+ *         name: granularity
+ *         schema:
+ *           type: string
+ *           enum: [hourly, monthly]
+ *       - in: query
+ *         name: startDate
+ *         schema:
+ *           type: string
+ *           format: date-time
+ *       - in: query
+ *         name: endDate
+ *         schema:
+ *           type: string
+ *           format: date-time
+ *     responses:
+ *       200:
+ *         description: Historical statistics retrieved successfully
+ */
+router.get('/:id/statistics/historical', AnalyticsController.getCampaignHistoricalStats);
+
 /**
  * @swagger
  * /api/v1/campaigns/{id}/reports: