Initial commit: Telegram Management System

Full-stack web application for Telegram management - Frontend: Vue 3 + Vben Admin - Backend: NestJS - Features: User management, group broadcast, statistics 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-04 15:37:50 +08:00
commit 237c7802e5
3674 changed files with 525172 additions and 0 deletions
--- a/marketing-agent/docs/QUICKSTART.md
+++ b/marketing-agent/docs/QUICKSTART.md
@@ -0,0 +1,243 @@
+# Quick Start Guide
+
+Get started with the Telegram Marketing Agent System in 5 minutes.
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- Node.js 18+ (for local development)
+- MongoDB and Redis (or use Docker)
+- Telegram account with API credentials
+
+## Installation
+
+### Option 1: Docker Compose (Recommended)
+
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/telegram-marketing-agent.git
+cd telegram-marketing-agent
+```
+
+2. Create environment file:
+```bash
+cp .env.example .env
+```
+
+3. Update `.env` with your configurations:
+```env
+# Telegram API
+TELEGRAM_API_ID=your_api_id
+TELEGRAM_API_HASH=your_api_hash
+
+# Claude API (optional)
+CLAUDE_API_KEY=your_claude_key
+
+# Database
+MONGODB_URI=mongodb://mongodb:27017/marketing_agent
+REDIS_URL=redis://redis:6379
+
+# Security
+JWT_SECRET=your-secret-key-change-this
+```
+
+4. Start all services:
+```bash
+docker-compose up -d
+```
+
+5. Access the application:
+- Frontend: http://localhost:8080
+- API Gateway: http://localhost:3000
+- API Docs: http://localhost:3000/api-docs
+
+### Option 2: Local Development
+
+1. Install dependencies for each service:
+```bash
+# API Gateway
+cd services/api-gateway
+npm install
+
+# Orchestrator
+cd ../orchestrator
+npm install
+
+# Continue for all services...
+```
+
+2. Start MongoDB and Redis:
+```bash
+# Using Docker
+docker run -d -p 27017:27017 --name mongodb mongo
+docker run -d -p 6379:6379 --name redis redis
+```
+
+3. Start services:
+```bash
+# In separate terminals
+cd services/api-gateway && npm start
+cd services/orchestrator && npm start
+cd services/gramjs-adapter && npm start
+# Continue for all services...
+```
+
+4. Start frontend:
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+## First Steps
+
+### 1. Login
+
+Default credentials:
+- Username: `admin`
+- Password: `password123`
+
+### 2. Connect Telegram Account
+
+1. Go to **Settings** → **Accounts**
+2. Click **Add Account**
+3. Enter your phone number
+4. Follow the verification process
+
+### 3. Import Users
+
+1. Go to **Users** → **Import**
+2. Download the sample CSV template
+3. Fill in user data
+4. Upload and import
+
+### 4. Create Your First Campaign
+
+1. Go to **Campaigns** → **Create New**
+2. Fill in campaign details:
+   - Name: "Welcome Campaign"
+   - Type: "Message"
+   - Target: Select imported users
+3. Create message:
+   - Use template or write custom
+   - Add personalization tags
+4. Review and save as draft
+
+### 5. Test Campaign
+
+1. Select a small test group
+2. Click **Test Campaign**
+3. Review test results
+4. Make adjustments if needed
+
+### 6. Execute Campaign
+
+1. Click **Execute Campaign**
+2. Monitor real-time progress
+3. View analytics dashboard
+
+## Common Tasks
+
+### Creating User Segments
+
+```javascript
+// API Example
+POST /api/v1/segments
+{
+  "name": "Active Users",
+  "criteria": [{
+    "field": "engagement.lastActivity",
+    "operator": "greater_than",
+    "value": "7d"
+  }]
+}
+```
+
+### Scheduling Recurring Campaigns
+
+1. Create campaign
+2. Go to **Schedules** → **Create Schedule**
+3. Select campaign and set recurrence:
+   - Daily at 10 AM
+   - Weekly on Mondays
+   - Monthly on 1st
+
+### Setting Up Webhooks
+
+```javascript
+// API Example
+POST /api/v1/webhooks
+{
+  "name": "Campaign Events",
+  "url": "https://your-server.com/webhooks",
+  "events": ["campaign.completed", "campaign.failed"]
+}
+```
+
+## Troubleshooting
+
+### Cannot Connect to Telegram
+
+1. Check API credentials in `.env`
+2. Ensure phone number format: `+1234567890`
+3. Check firewall/proxy settings
+4. View logs: `docker-compose logs gramjs-adapter`
+
+### Campaign Not Sending
+
+1. Check account connection status
+2. Verify rate limits aren't exceeded
+3. Check user permissions
+4. Review compliance settings
+
+### Performance Issues
+
+1. Check Redis connection
+2. Monitor resource usage
+3. Adjust rate limiting settings
+4. Scale services if needed
+
+## Best Practices
+
+1. **Test First**: Always test campaigns on small groups
+2. **Rate Limiting**: Respect Telegram's rate limits
+3. **Personalization**: Use tags for better engagement
+4. **Timing**: Schedule during user's active hours
+5. **Compliance**: Follow local regulations
+6. **Monitoring**: Set up alerts for failures
+
+## Next Steps
+
+- [Read Full Documentation](./README.md)
+- [API Documentation](./api/README.md)
+- [Advanced Features](./ADVANCED.md)
+- [Deployment Guide](./DEPLOYMENT.md)
+
+## Support
+
+- GitHub Issues: [Report bugs](https://github.com/yourusername/telegram-marketing-agent/issues)
+- Documentation: [Full docs](./docs)
+- Community: [Join Discord](https://discord.gg/yourinvite)
+
+## Quick API Reference
+
+### Authentication
+```bash
+curl -X POST http://localhost:3000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "admin", "password": "password123"}'
+```
+
+### List Campaigns
+```bash
+curl -X GET http://localhost:3000/api/v1/campaigns \
+  -H "Authorization: Bearer <token>"
+```
+
+### Execute Campaign
+```bash
+curl -X POST http://localhost:3000/api/v1/campaigns/<id>/execute \
+  -H "Authorization: Bearer <token>"
+```
+
+For more examples, visit the [API Examples](./api/examples.md) page.