Create ANALYTICS.md
This commit is contained in:
NotII
329
ANALYTICS.md
Normal file
329
ANALYTICS.md
Normal file
@@ -0,0 +1,329 @@
|
||||
# Analytics System Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The analytics system provides comprehensive insights into store performance, sales trends, customer behavior, and order management. It supports both vendors and staff users (sub-users) with appropriate access controls and server-side rendering for optimal performance.
|
||||
|
||||
## Features
|
||||
|
||||
### 🔐 Multi-User Support
|
||||
- **Vendors**: Access their own store analytics automatically
|
||||
- **Staff/Sub-Users**: Access store analytics by providing a `storeId` parameter via URL or cookies
|
||||
- **Role-based Access**: Different permissions for different user types
|
||||
- **Server-side Rendering**: Initial data fetched server-side for better performance
|
||||
|
||||
### 📊 Analytics Dashboard
|
||||
- **Overview Metrics**: Total revenue, orders, customers, and products
|
||||
- **Revenue Trends**: Time-based revenue analysis with interactive charts
|
||||
- **Product Performance**: Top-selling products with stock status
|
||||
- **Customer Insights**: Customer segmentation and behavior analysis
|
||||
- **Order Analytics**: Order status distribution and processing times
|
||||
|
||||
### 🎯 Key Metrics
|
||||
- Total and monthly revenue
|
||||
- Order completion rates
|
||||
- Customer acquisition and retention
|
||||
- Product performance rankings
|
||||
- Average order processing times
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Authentication
|
||||
All endpoints require authentication using the new `protectStore` middleware:
|
||||
|
||||
```javascript
|
||||
// For vendors (automatic store access)
|
||||
GET /api/analytics/overview
|
||||
|
||||
// For staff users (requires storeId parameter)
|
||||
GET /api/analytics/overview?storeId=store_id_here
|
||||
```
|
||||
|
||||
### Available Endpoints
|
||||
|
||||
#### 1. Analytics Overview
|
||||
```http
|
||||
GET /api/analytics/overview
|
||||
```
|
||||
Returns comprehensive overview metrics including:
|
||||
- Order statistics (total, completed, pending, completion rate)
|
||||
- Revenue data (total, monthly, weekly, average order value)
|
||||
- Product count
|
||||
- Unique customer count
|
||||
- User type (vendor/staff)
|
||||
|
||||
#### 2. Revenue Trends
|
||||
```http
|
||||
GET /api/analytics/revenue-trends?period=30&storeId=optional
|
||||
```
|
||||
Returns daily revenue and order trends for the specified period.
|
||||
|
||||
#### 3. Product Performance
|
||||
```http
|
||||
GET /api/analytics/product-performance?storeId=optional
|
||||
```
|
||||
Returns top-performing products with sales metrics and stock status.
|
||||
|
||||
#### 4. Customer Insights
|
||||
```http
|
||||
GET /api/analytics/customer-insights?storeId=optional
|
||||
```
|
||||
Returns customer segmentation and top customer analysis.
|
||||
|
||||
#### 5. Order Analytics
|
||||
```http
|
||||
GET /api/analytics/order-analytics?period=30&storeId=optional
|
||||
```
|
||||
Returns order status distribution and processing time analysis.
|
||||
|
||||
## Frontend Implementation
|
||||
|
||||
### Server-Side Rendering
|
||||
The analytics page uses server-side rendering for optimal performance:
|
||||
|
||||
```typescript
|
||||
// app/dashboard/analytics/page.tsx
|
||||
export default async function AnalyticsPage({
|
||||
searchParams,
|
||||
}: {
|
||||
searchParams: { storeId?: string };
|
||||
}) {
|
||||
const storeId = searchParams.storeId;
|
||||
const initialData = await getAnalyticsOverviewServer(storeId);
|
||||
|
||||
return <AnalyticsDashboard initialData={initialData} />;
|
||||
}
|
||||
```
|
||||
|
||||
### Store Selection for Staff Users
|
||||
Staff users can select which store to view analytics for:
|
||||
|
||||
```typescript
|
||||
// URL-based store selection
|
||||
/dashboard/analytics?storeId=store_id_here
|
||||
|
||||
// StoreSelector component for easy store switching
|
||||
<StoreSelector />
|
||||
```
|
||||
|
||||
### Components
|
||||
|
||||
#### AnalyticsDashboard
|
||||
Main dashboard component with tabs for different analytics views.
|
||||
|
||||
**Props:**
|
||||
- `initialData`: Initial analytics overview data (server-side fetched)
|
||||
|
||||
**Features:**
|
||||
- Key metrics cards with trend indicators
|
||||
- Tabbed interface for different analytics views
|
||||
- Refresh functionality
|
||||
- User type indicator (Vendor/Staff View)
|
||||
|
||||
#### StoreSelector
|
||||
Client-side component for staff users to select stores.
|
||||
|
||||
**Features:**
|
||||
- Input field for store ID
|
||||
- URL-based navigation
|
||||
- Current store display
|
||||
- Error handling and validation
|
||||
|
||||
#### RevenueChart
|
||||
Displays revenue trends over time with interactive charts.
|
||||
|
||||
**Props:**
|
||||
- `timeRange`: Time period for analysis (7, 30, 90 days)
|
||||
|
||||
#### ProductPerformanceChart
|
||||
Shows top-performing products in a table format.
|
||||
|
||||
#### CustomerInsightsChart
|
||||
Displays customer segmentation and top customers.
|
||||
|
||||
#### OrderAnalyticsChart
|
||||
Shows order status distribution and daily trends.
|
||||
|
||||
**Props:**
|
||||
- `timeRange`: Time period for analysis
|
||||
|
||||
#### MetricsCard
|
||||
Reusable component for displaying individual metrics.
|
||||
|
||||
**Props:**
|
||||
- `title`: Metric title
|
||||
- `value`: Metric value
|
||||
- `description`: Metric description
|
||||
- `icon`: Lucide icon component
|
||||
- `trend`: Trend direction ("up", "down", "neutral")
|
||||
- `trendValue`: Trend description
|
||||
|
||||
## Sub-User (Staff) Support
|
||||
|
||||
### Authentication Flow
|
||||
1. Staff users authenticate using their staff credentials
|
||||
2. When accessing analytics, they must provide a `storeId` parameter
|
||||
3. The system verifies the store exists and grants access
|
||||
4. All analytics data is filtered by the specified store
|
||||
|
||||
### Access Methods
|
||||
Staff users can access store analytics in multiple ways:
|
||||
|
||||
1. **URL Parameter**: `/dashboard/analytics?storeId=store_id_here`
|
||||
2. **Store Selector**: Use the StoreSelector component to choose a store
|
||||
3. **Cookies**: Store ID can be stored in cookies for persistence
|
||||
|
||||
### Frontend Integration
|
||||
The analytics service automatically handles both user types:
|
||||
|
||||
```typescript
|
||||
// Server-side (for initial load)
|
||||
const data = await getAnalyticsOverviewServer(storeId);
|
||||
|
||||
// Client-side (for refreshes and updates)
|
||||
const data = await getAnalyticsOverviewWithStore();
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Analytics Access
|
||||
```typescript
|
||||
// Server-side rendering
|
||||
import { getAnalyticsOverviewServer } from '@/lib/server-api';
|
||||
const overview = await getAnalyticsOverviewServer(storeId);
|
||||
|
||||
// Client-side updates
|
||||
import { getAnalyticsOverviewWithStore } from '@/lib/services/analytics-service';
|
||||
const overview = await getAnalyticsOverviewWithStore();
|
||||
```
|
||||
|
||||
### Staff User with Specific Store
|
||||
```typescript
|
||||
// Navigate to analytics with store ID
|
||||
router.push(`/dashboard/analytics?storeId=${storeId}`);
|
||||
|
||||
// Or use the store selector component
|
||||
<StoreSelector />
|
||||
```
|
||||
|
||||
### Revenue Trends with Time Range
|
||||
```typescript
|
||||
import { getRevenueTrendsWithStore } from '@/lib/services/analytics-service';
|
||||
|
||||
// Get 30-day revenue trends
|
||||
const trends = await getRevenueTrendsWithStore('30');
|
||||
```
|
||||
|
||||
## Data Structure
|
||||
|
||||
### AnalyticsOverview
|
||||
```typescript
|
||||
interface AnalyticsOverview {
|
||||
orders: {
|
||||
total: number;
|
||||
completed: number;
|
||||
pending: number;
|
||||
completionRate: string;
|
||||
};
|
||||
revenue: {
|
||||
total: number;
|
||||
monthly: number;
|
||||
weekly: number;
|
||||
averageOrderValue: number;
|
||||
};
|
||||
products: {
|
||||
total: number;
|
||||
};
|
||||
customers: {
|
||||
unique: number;
|
||||
};
|
||||
userType?: 'vendor' | 'staff';
|
||||
}
|
||||
```
|
||||
|
||||
### RevenueData
|
||||
```typescript
|
||||
interface RevenueData {
|
||||
_id: {
|
||||
year: number;
|
||||
month: number;
|
||||
day: number;
|
||||
};
|
||||
revenue: number;
|
||||
orders: number;
|
||||
}
|
||||
```
|
||||
|
||||
### ProductPerformance
|
||||
```typescript
|
||||
interface ProductPerformance {
|
||||
productId: string;
|
||||
name: string;
|
||||
image: string;
|
||||
unitType: string;
|
||||
currentStock: number;
|
||||
stockStatus: string;
|
||||
totalSold: number;
|
||||
totalRevenue: number;
|
||||
orderCount: number;
|
||||
averagePrice: number;
|
||||
}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Access Control
|
||||
- Vendors can only access their own store data
|
||||
- Staff users must provide valid storeId parameter
|
||||
- All requests are authenticated and authorized
|
||||
- Store ownership is verified for staff access
|
||||
|
||||
### Data Privacy
|
||||
- Customer data is anonymized in analytics
|
||||
- No sensitive information is exposed
|
||||
- All data is filtered by store ownership
|
||||
|
||||
## Error Handling
|
||||
|
||||
The system provides comprehensive error handling:
|
||||
|
||||
- **401 Unauthorized**: Invalid or missing authentication → Redirect to login
|
||||
- **400 Bad Request**: Missing storeId for staff users → Show store selector
|
||||
- **403 Forbidden**: Access denied to specific store
|
||||
- **404 Not Found**: Store not found
|
||||
- **500 Server Error**: Internal server errors
|
||||
|
||||
All errors are displayed to users via toast notifications in the frontend.
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
- **Server-side data fetching** for initial load
|
||||
- **Client-side caching** for subsequent requests
|
||||
- **Efficient database queries** with proper indexing
|
||||
- **Pagination** for large datasets
|
||||
- **Real-time data refresh** capabilities
|
||||
- **Optimized rendering** with React Suspense
|
||||
|
||||
## Backend Implementation
|
||||
|
||||
### Middleware
|
||||
- `protectStore`: Handles both vendors and staff users
|
||||
- `protectVendorOnly`: Vendor-specific routes
|
||||
- `protectStaffOnly`: Staff-specific routes
|
||||
|
||||
### Database Queries
|
||||
- Uses `storeId` for consistent data filtering
|
||||
- Aggregation pipelines for complex analytics
|
||||
- Proper indexing for performance
|
||||
- Time-based filtering for trends
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- Real-time analytics updates
|
||||
- Export functionality for reports
|
||||
- Advanced filtering and date range selection
|
||||
- Custom dashboard configurations
|
||||
- Email reports and notifications
|
||||
- Comparative analytics (period-over-period)
|
||||
- Predictive analytics and forecasting
|
||||
- Multi-store comparison for staff users
|
||||
Reference in New Issue
Block a user