telegram-management-system/marketing-agent/frontend/README.md

# Telegram Marketing Agent - Frontend

Modern Vue 3 management interface for the Telegram Marketing Agent System.

## Features

- 🎯 **Campaign Management**: Create, manage, and monitor marketing campaigns
- 📊 **Real-time Analytics**: Track performance metrics and engagement rates
- 🧠 **A/B Testing**: Built-in experimentation framework
- 🤖 **AI Integration**: Claude-powered strategy generation and optimization
- 🔐 **Compliance Tools**: GDPR/CCPA compliance management
- 🌍 **Multi-language Support**: English and Chinese interfaces
- 🎨 **Modern UI**: Built with Element Plus and Tailwind CSS

## Tech Stack

- **Framework**: Vue 3 with Composition API
- **State Management**: Pinia
- **Routing**: Vue Router 4
- **UI Library**: Element Plus
- **Styling**: Tailwind CSS
- **Build Tool**: Vite
- **Charts**: Chart.js with vue-chartjs
- **HTTP Client**: Axios
- **Internationalization**: Vue I18n

## Getting Started

### Prerequisites

- Node.js 18+ and npm 8+
- Backend services running (see main README)

### Installation

```bash
# Install dependencies
npm install

# Start development server
npm run dev
```

The application will be available at http://localhost:3008

### Environment Configuration

The frontend proxies API requests to the backend. Configure the proxy in `vite.config.js`:

```javascript
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:3000', // API Gateway URL
      changeOrigin: true
    }
  }
}
```

## Project Structure

```
src/
├── api/              # API client modules
│   ├── index.js      # Axios configuration
│   └── modules/      # API endpoints by domain
├── assets/           # Static assets
├── components/       # Reusable components
├── locales/          # i18n translations
├── router/           # Vue Router configuration
├── stores/           # Pinia stores
├── utils/            # Utility functions
├── views/            # Page components
├── App.vue           # Root component
├── main.js           # Application entry
└── style.css         # Global styles
```

## Key Features

### Campaign Management

- Create campaigns with AI-powered strategy generation
- Multi-step message sequences with delays
- Target audience selection by groups and tags
- Real-time campaign status monitoring
- Campaign lifecycle management (start, pause, resume, cancel)

### Analytics Dashboard

- Key performance metrics with trend analysis
- Time-series charts for message and engagement data
- Campaign performance comparison
- Real-time activity feed
- Export reports in multiple formats

### A/B Testing

- Create experiments with multiple variants
- Statistical significance testing
- Real-time result monitoring
- Winner selection and rollout

### Compliance Management

- User consent tracking
- Data export/deletion requests
- Audit log viewing
- GDPR/CCPA compliance status

## Development

### Available Scripts

```bash
# Development server
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

# Lint and fix
npm run lint

# Format code
npm run format
```

### Code Style

- Use Composition API with `<script setup>`
- Prefer TypeScript-like prop definitions
- Use Tailwind for utility classes
- Use Element Plus components for consistency

### State Management

The application uses Pinia for state management:

```javascript
// stores/auth.js
export const useAuthStore = defineStore('auth', () => {
  const user = ref(null)
  const token = ref('')
  
  // Store logic...
})
```

### API Integration

All API calls go through the centralized API client:

```javascript
import api from '@/api'

// Example usage
const campaigns = await api.campaigns.getList({
  page: 1,
  pageSize: 20
})
```

## Building for Production

```bash
# Build the application
npm run build

# Files will be in dist/
# Serve with any static file server
```

### Nginx Configuration

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /var/www/marketing-agent;
    
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    location /api {
        proxy_pass http://api-gateway:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## Security Considerations

- All API requests require authentication
- JWT tokens stored in localStorage
- Automatic token refresh on 401 responses
- CORS configured for production domains
- Input validation on all forms
- XSS protection via Vue's template compilation

## Contributing

1. Follow the existing code style
2. Write meaningful commit messages
3. Add appropriate error handling
4. Update translations for new features
5. Test across different screen sizes

## License

See the main project LICENSE file.