604 lines
14 KiB
Markdown
604 lines
14 KiB
Markdown
# 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
|