# Backend CSA - Campaign & Content Management System

Backend API untuk Campaign & Content Management System dengan Firebase Cloud Messaging integration dan advanced analytics.

---

## 📋 Table of Contents

- [Features](#features)
- [Tech Stack](#tech-stack)
- [Database Schema](#database-schema)
- [API Endpoints](#api-endpoints)
- [Installation](#installation)
- [Environment Variables](#environment-variables)
- [Campaign Analytics](#campaign-analytics)
- [Project Structure](#project-structure)

---

## ✨ Features

### Content Management
- Multi-type content (splash, promo, article, banner, floating widget)
- Multi-corporation support (Walanja, Simaya, CIFO)
- File upload & management with MinIO
- CRUD operations for all content types

### Campaign Management
- Scheduled notification campaigns
- Firebase Cloud Messaging integration
- **Real-time delivery tracking per user**
- **Comprehensive analytics & reporting**
- Status management (pending, completed, failed, cancelled)
- Automatic campaign execution via cron jobs

### User Management
- User token management
- Activity tracking (Hotel, Room, Retail, CCTV visits)
- User-level notification delivery tracking

### Admin Features
- Admin account management
- API credential management
- System statistics & analytics

### Advanced Analytics
- Campaign performance metrics
- Delivery rate tracking
- Error analysis & breakdown
- Timeline visualization data
- Top performing campaigns
- User engagement metrics

---

## 🛠 Tech Stack

- **Runtime:** Node.js
- **Framework:** Express.js
- **Database:** MySQL (Prisma ORM)
- **Storage:** MinIO
- **Notifications:** Firebase Admin SDK
- **Authentication:** JWT + API Key
- **Logger:** Winston
- **Scheduler:** node-cron

---

## 🗄 Database Schema

### Core Models

#### **AppCampaign**
Campaign dengan tracking lengkap:
```prisma
model AppCampaign {
  UUID_ACP            String
  Title_ACP           String
  Content_ACP         String
  Date_ACP            DateTime
  Status_ACP          CampaignStatus
  
  // Analytics fields
  TargetUsers_ACP     Int?
  SentCount_ACP       Int?
  SuccessCount_ACP    Int?
  FailureCount_ACP    Int?
  DeliveryRate_ACP    Float?
  SentAt_ACP          DateTime?
  CompletedAt_ACP     DateTime?
  ErrorMessage_ACP    String?
}
```

#### **CampaignDelivery**
Per-user delivery tracking:
```prisma
model CampaignDelivery {
  UUID_CD             String
  Campaign_CD         String
  UserID_CD           String
  Token_CD            String
  Status_CD           DeliveryStatus
  SentAt_CD           DateTime?
  DeliveredAt_CD      DateTime?
  FailedAt_CD         DateTime?
  ErrorMessage_CD     String?
  ResponseData_CD     String?
}
```

#### **AppContent**
```prisma
model AppContent {
  UUID_APC            String
  Title_APC           String
  Content_APC         String
  Type_APC            ContentType
  CorpType_APC        CorpType
  Url_APC             String?
  Filename_APC        String?
  TargetUrl_APC       String?
}
```

#### **UsersToken**
```prisma
model UsersToken {
  UUID_UT             String
  UserID_UT           String
  Token_UT            String
  UsersActivity       UsersActivity[]
}
```

### Enums

```prisma
enum CampaignStatus {
  pending
  completed
  failed
  cancelled
}

enum DeliveryStatus {
  pending
  sent
  delivered
  failed
}

enum ContentType {
  splash
  promo
  article
  banner
  floatingWidget
}

enum CorpType {
  walanja
  simaya
  cifo
}

enum ActivityType {
  VisitHotel
  VisitRoom
  VisitRetail
  VisitCCTV
}
```

---

## 🔌 API Endpoints

### Authentication
All endpoints require `x-api-key` header (except `/api-management/test`)

### API Management
- `GET /api-management/test` - Test API connection
- `GET /api-management/test/secure` - Test secure API (requires API key)
- `POST /api-management/token` - Create new API token
- `DELETE /api-management/token` - Delete API token
- `GET /api-management/tokens` - Get all API tokens

### Content Management (CMS)
- `POST /cms/content` - Create content
- `GET /cms/content/:type/:corp` - Get contents by type & corp
- `PUT /cms/content/:id` - Update content
- `DELETE /cms/content/:id` - Delete content
- `GET /cms/stats` - Get CMS statistics with charts data

### Campaign Management
- `POST /campaign-management/setup` - Create campaign
- `GET /campaign-management/all` - Get all campaigns (filterable by status)
- `PUT /campaign-management/:id` - Update campaign
- `DELETE /campaign-management/:id` - Cancel campaign
- `POST /campaign-management/send` - Send notification to specific user
- `GET /campaign-management/analytics` - **Get campaign analytics & metrics**
- `GET /campaign-management/report/:id` - **Get detailed campaign report**

### User Management
- `POST /user-management/setup-token` - Setup user FCM token
- `GET /user-management/get-all` - Get all users
- `DELETE /user-management/delete` - Delete user

---

## 📊 Campaign Analytics

### Analytics Dashboard (`GET /campaign-management/analytics`)

Comprehensive analytics untuk monitoring campaign performance.

#### Response Structure:
```javascript
{
  summary: {
    campaigns: {
      total: 50,
      completed: 40,
      failed: 3,
      pending: 5,
      cancelled: 2,
      successRate: "93.02%",
      avgResponseTime: "5 minutes",
      upcomingCount: 5
    },
    delivery: {
      totalTargetUsers: 5000,
      totalSent: 5000,
      totalDelivered: 4750,
      totalFailed: 250,
      overallDeliveryRate: "95.00%",
      totalDeliveryRecords: 5000
    }
  },
  
  charts: {
    // Pie Chart: Campaign status distribution
    statusDistribution: {
      labels: ["completed", "failed", "pending", "cancelled"],
      data: [40, 3, 5, 2]
    },
    
    // Pie Chart: Delivery status
    deliveryStatusDistribution: {
      labels: ["delivered", "failed", "pending"],
      data: [4750, 250, 0]
    },
    
    // Line Chart: Campaign timeline (30 days)
    campaignTimeline: {
      "2025-11-01": { total: 5, completed: 4, failed: 1 }
    },
    
    // Line Chart: Delivery rate trend
    deliveryRateTrend: {
      labels: ["2025-11-01", "2025-11-02"],
      data: [95.5, 96.2]
    },
    
    // Stacked Bar: Status over time (7 days)
    statusOverTime: { ... }
  },
  
  // Top 10 best performing campaigns
  topPerforming: [
    {
      id: "uuid",
      title: "Campaign Title",
      targetUsers: 100,
      successCount: 98,
      deliveryRate: 98.00
    }
  ],
  
  upcoming: [...],
  recentActivity: [...]
}
```

### Individual Campaign Report (`GET /campaign-management/report/:id`)

Detailed report untuk campaign spesifik dengan per-user tracking.

#### Response Structure:
```javascript
{
  campaign: {
    id: "uuid",
    title: "Campaign Title",
    content: "Content",
    status: "completed",
    scheduledDate: "2025-11-20T10:00:00Z",
    errorMessage: null
  },
  
  metrics: {
    leadTime: "19 hours",              // Campaign preparation time
    executionTime: "5 minutes",         // Actual sending time
    avgDeliveryTime: "2 seconds",       // Avg time to deliver
    isScheduled: false,
    isOverdue: false
  },
  
  delivery: {
    targetUsers: 100,
    sentCount: 100,
    successCount: 95,
    failureCount: 5,
    deliveryRate: "95.00%",
    sentAt: "2025-11-20T10:00:00Z",
    completedAt: "2025-11-20T10:05:00Z",
    
    // Breakdown per status
    statusBreakdown: {
      pending: 0,
      sent: 0,
      delivered: 95,
      failed: 5
    },
    
    // Error analysis
    errorBreakdown: {
      "Invalid token": 3,
      "Token not registered": 2
    }
  },
  
  timeline: {
    created: "2025-11-19T15:00:00Z",
    scheduled: "2025-11-20T10:00:00Z",
    sent: "2025-11-20T10:00:00Z",
    completed: "2025-11-20T10:05:00Z"
  },
  
  // Per-user delivery records (max 100)
  deliveryRecords: {
    total: 100,
    records: [
      {
        UUID_CD: "uuid",
        UserID_CD: "user123",
        Status_CD: "delivered",
        SentAt_CD: "2025-11-20T10:00:01Z",
        DeliveredAt_CD: "2025-11-20T10:00:03Z",
        ErrorMessage_CD: null
      }
    ]
  }
}
```

#### Key Metrics:
- **Success Rate**: (Completed / Total Executed) × 100
- **Delivery Rate**: (Success Count / Sent Count) × 100
- **Lead Time**: Time between creation and scheduled date
- **Execution Time**: Time taken to send all notifications
- **Avg Delivery Time**: Average time from sent to delivered

---

## 🚀 Installation

### Prerequisites
- Node.js (v16+)
- MySQL Database
- MinIO Server
- Firebase Project with Admin SDK

### Setup

1. **Clone repository**
```bash
git clone <repository-url>
cd backend-csa
```

2. **Install dependencies**
```bash
npm install
```

3. **Configure environment**
Create `.env` file:
```env
DATABASE_URL="mysql://user:password@host:port/database?ssl-mode=REQUIRED"
DATABASE_URL_UTILITY="mysql://user:password@host:port/database?ssl-mode=REQUIRED"
X_API_KEY="your-api-key"
AI_API_KEY="your-ai-key"
MINIO_ENDPOINT="storage.example.com"
MINIO_ACCESS_KEY="admin"
MINIO_SECRET_KEY="secret"
JWT_SECRET_KEY="your-jwt-secret"
```

4. **Setup Firebase**
Place Firebase service account key at:
```
app/config/serviceAccountKey.json
```

5. **Run migrations**
```bash
npx prisma migrate deploy --schema=./prisma/schemas/schema.cms.prisma
npx prisma generate --schema=./prisma/schemas/schema.cms.prisma
```

6. **Start server**
```bash
npm start
# or for development
npm run dev
```

---

## 🌍 Environment Variables

| Variable | Description |
|----------|-------------|
| `DATABASE_URL` | MySQL connection string for CMS database |
| `DATABASE_URL_UTILITY` | MySQL connection string for utility database |
| `X_API_KEY` | Master API key for authentication |
| `AI_API_KEY` | OpenAI API key for AI features |
| `MINIO_ENDPOINT` | MinIO server endpoint |
| `MINIO_ACCESS_KEY` | MinIO access key |
| `MINIO_SECRET_KEY` | MinIO secret key |
| `JWT_SECRET_KEY` | JWT signing secret |

---

## 📁 Project Structure

```
backend-csa/
├── app/
│   ├── config/
│   │   └── serviceAccountKey.json    # Firebase config
│   ├── controllers/
│   │   ├── app.controller.js         # API management
│   │   ├── campaign.controller.js    # Campaign with analytics
│   │   ├── cms.controller.js         # Content management
│   │   ├── users.controller.js       # User management
│   │   └── ...
│   ├── middleware/
│   │   └── middleware.js             # Auth & validation
│   ├── routes/
│   │   ├── app.route.js
│   │   ├── campaign.route.js
│   │   ├── cms.route.js
│   │   ├── users.route.js
│   │   └── ...
│   ├── services/
│   │   ├── firebase.services.js      # FCM with tracking
│   │   ├── minio.services.js         # File storage
│   │   ├── cronjob.services.js       # Campaign scheduler
│   │   ├── logger.services.js        # Winston logger
│   │   └── ...
│   ├── res/
│   │   └── responses.js              # Response helpers
│   └── static/
│       └── prefix.js                 # Constants
├── prisma/
│   ├── schemas/
│   │   ├── schema.cms.prisma         # CMS database schema
│   │   └── schema.utility.prisma     # Utility database schema
│   ├── clients/                      # Generated Prisma clients
│   └── migrations/                   # Database migrations
├── backups/                          # Database backups
├── index.js                          # Entry point
├── package.json
└── README.md                         # This file
```

---

## 🔒 Security

- All endpoints protected with API key authentication
- JWT token validation for user-specific operations
- Input validation and sanitization
- SQL injection prevention via Prisma ORM
- File upload restrictions and validation

---

## 📝 API Response Format

### Success Response
```javascript
{
  success: true,
  message: "Operation successful",
  data: { ... }
}
```

### Error Response
```javascript
{
  success: false,
  message: "Error message",
  error: "Error details"
}
```

---

## 🎯 Usage Examples

### Create Campaign
```bash
POST /campaign-management/setup
Headers: { "x-api-key": "your-api-key" }
Body: {
  "title": "New Campaign",
  "content": "Campaign message",
  "date": "2025-11-30T10:00:00Z"
}
```

### Get Analytics
```bash
GET /campaign-management/analytics
Headers: { "x-api-key": "your-api-key" }
```

### Get Campaign Report
```bash
GET /campaign-management/report/campaign-uuid
Headers: { "x-api-key": "your-api-key" }
```

---

## 🔄 Campaign Flow

1. **Create** - Setup campaign with schedule
2. **Schedule** - Cron job monitors scheduled campaigns
3. **Execute** - Send notifications to all users
4. **Track** - Record delivery status per user
5. **Analyze** - View metrics and performance

---

## 📈 Analytics Features

### Campaign Metrics
- Total campaigns by status
- Success/failure rates
- Average response time
- Upcoming campaigns count

### Delivery Metrics
- Target users vs actual sent
- Delivery success rate
- Failed delivery analysis
- Per-user tracking

### Visualization Data
- Status distribution (pie chart)
- Campaign timeline (line chart)
- Delivery rate trend (line chart)
- Status over time (stacked bar)
- Top performers (bar chart)

---

## 🛠 Development

### Run Migrations
```bash
# Create migration
npx prisma migrate dev --schema=./prisma/schemas/schema.cms.prisma --name migration_name

# Apply migration
npx prisma migrate deploy --schema=./prisma/schemas/schema.cms.prisma

# Generate client
npx prisma generate --schema=./prisma/schemas/schema.cms.prisma
```

### View Database
```bash
npx prisma studio --schema=./prisma/schemas/schema.cms.prisma
```

---

## 📞 Support

For issues or questions, please contact the development team.

---

**Version:** 2.0.0  
**Last Updated:** November 25, 2025  
**License:** Private