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/MULTI_TENANT.md
+++ b/marketing-agent/MULTI_TENANT.md
@@ -0,0 +1,260 @@
+# Multi-Tenant Architecture
+
+This document describes the multi-tenant implementation for the Telegram Marketing Intelligence Agent System.
+
+## Overview
+
+The system supports full multi-tenant isolation, allowing multiple organizations to use the same instance while keeping their data completely separated.
+
+## Architecture
+
+### Tenant Model
+
+Each tenant has:
+- **Basic Information**: Name, slug, domain
+- **Plan & Limits**: Subscription plan with resource limits
+- **Usage Tracking**: Real-time usage monitoring
+- **Billing**: Integrated billing and payment tracking
+- **Settings**: Customizable preferences per tenant
+- **Branding**: White-label support for enterprise plans
+- **Features**: Plan-based feature toggles
+- **Compliance**: GDPR and data retention settings
+
+### Data Isolation
+
+All data models include a `tenantId` field that ensures complete data isolation:
+- MongoDB models use compound indexes with tenantId
+- Sequelize models use foreign key references
+- All queries automatically filter by current tenant
+
+### Tenant Context
+
+The tenant context is determined through multiple methods:
+1. **Subdomain**: `acme.app.com` → tenant: acme
+2. **Custom Domain**: `app.acme.com` → tenant: acme
+3. **Header**: `X-Tenant-Id` for API access
+4. **URL Parameter**: `?tenant=acme` for multi-tenant admin
+5. **User Association**: From authenticated user's tenant
+
+## Implementation
+
+### 1. Tenant Middleware
+
+```javascript
+// Automatically adds tenant context to all requests
+app.use(tenantMiddleware);
+app.use(allowCrossTenant); // For superadmin access
+```
+
+### 2. Model Updates
+
+All models now include tenantId:
+```javascript
+const schema = new Schema({
+  tenantId: {
+    type: ObjectId,
+    ref: 'Tenant',
+    required: true,
+    index: true
+  },
+  // ... other fields
+});
+```
+
+### 3. API Routes
+
+#### Public Routes
+- `POST /api/v1/tenants/signup` - Create new tenant
+
+#### Tenant Routes (Authenticated)
+- `GET /api/v1/tenants/current` - Get current tenant
+- `PATCH /api/v1/tenants/current/settings` - Update settings
+- `PATCH /api/v1/tenants/current/branding` - Update branding
+- `GET /api/v1/tenants/current/usage` - Get usage statistics
+
+#### Superadmin Routes
+- `GET /api/v1/tenants` - List all tenants
+- `PATCH /api/v1/tenants/:id` - Update any tenant
+- `DELETE /api/v1/tenants/:id` - Delete tenant
+
+### 4. Frontend Components
+
+#### Tenant Settings
+- Location: `/dashboard/tenant/settings`
+- Features:
+  - General settings (timezone, language, currency)
+  - Security settings (2FA, SSO)
+  - Branding (logo, colors, custom CSS)
+  - Usage monitoring and limits
+  - Compliance configuration
+
+#### Tenant Management (Superadmin)
+- Location: `/dashboard/tenants`
+- Features:
+  - List all tenants with filtering
+  - Edit tenant plans and limits
+  - Suspend/activate tenants
+  - Login as tenant
+  - Delete tenants
+
+## Plans & Features
+
+### Free Plan
+- 5 users
+- 10 campaigns
+- 1,000 messages/month
+- Basic analytics
+- Community support
+
+### Starter Plan ($29/month)
+- 20 users
+- 50 campaigns
+- 10,000 messages/month
+- Automation
+- API access
+- Email support
+
+### Professional Plan ($99/month)
+- 100 users
+- 200 campaigns
+- 50,000 messages/month
+- A/B testing
+- Custom reports
+- Multi-language
+- Priority support
+
+### Enterprise Plan (Custom)
+- Unlimited everything
+- White-label branding
+- AI suggestions
+- SLA guarantee
+- Dedicated support
+
+## Resource Limits
+
+Each tenant has configurable limits:
+- `users`: Maximum number of users
+- `campaigns`: Maximum number of campaigns
+- `messagesPerMonth`: Monthly message limit
+- `telegramAccounts`: Number of Telegram accounts
+- `storage`: Storage quota in bytes
+- `apiCallsPerHour`: API rate limiting
+- `webhooks`: Number of webhooks
+- `customIntegrations`: Enable/disable custom integrations
+
+## Usage Tracking
+
+The system tracks usage in real-time:
+```javascript
+// Check limit before operation
+if (!tenant.checkLimit('campaigns')) {
+  throw new Error('Campaign limit exceeded');
+}
+
+// Increment usage after successful operation
+await tenant.incrementUsage('campaigns');
+
+// Monthly reset for message limits
+await tenant.resetMonthlyUsage();
+```
+
+## Security Considerations
+
+### Tenant Isolation
+- All database queries include tenant filtering
+- Compound indexes ensure query performance
+- Cross-tenant access blocked except for superadmin
+
+### Authentication
+- Users belong to a single tenant
+- Tenant context included in JWT tokens
+- API keys scoped to tenant
+
+### Compliance
+- Per-tenant GDPR settings
+- Configurable data retention
+- IP whitelisting support
+- Audit logging per tenant
+
+## Migration Guide
+
+### For Existing Installations
+
+1. **Backup your data** before migration
+
+2. **Run migration script**:
+   ```bash
+   node scripts/migrate-to-multitenant.js
+   ```
+
+3. **Update environment variables**:
+   ```env
+   DEFAULT_TENANT_SLUG=default
+   ENABLE_MULTI_TENANT=true
+   ```
+
+4. **Test tenant isolation**:
+   ```bash
+   npm run test:multitenant
+   ```
+
+### For New Installations
+
+Multi-tenancy is enabled by default. The first user signup creates a new tenant automatically.
+
+## Best Practices
+
+### Development
+1. Always include tenantId in queries
+2. Use tenant middleware for automatic filtering
+3. Test with multiple tenants in development
+4. Validate tenant limits before operations
+
+### Production
+1. Monitor tenant usage regularly
+2. Set up alerts for limit approaching
+3. Implement proper backup strategies per tenant
+4. Use custom domains for enterprise tenants
+
+### Performance
+1. Ensure all queries use tenant indexes
+2. Monitor slow queries per tenant
+3. Implement caching strategies
+4. Use read replicas for analytics
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Tenant not found" error**
+   - Check tenant slug/domain configuration
+   - Verify tenant status is active
+   - Check subdomain DNS settings
+
+2. **Data visible across tenants**
+   - Ensure tenantId is in all queries
+   - Check model indexes
+   - Verify middleware is applied
+
+3. **Performance degradation**
+   - Check compound index usage
+   - Monitor per-tenant query patterns
+   - Consider sharding large tenants
+
+### Debug Mode
+
+Enable tenant debug logging:
+```javascript
+// In development
+process.env.TENANT_DEBUG = 'true';
+```
+
+This logs all tenant resolution and filtering operations.
+
+## Future Enhancements
+
+1. **Tenant Sharding**: Distribute large tenants across databases
+2. **Tenant Templates**: Pre-configured tenant setups
+3. **Tenant Marketplace**: Share templates/workflows between tenants
+4. **Advanced Analytics**: Cross-tenant analytics for superadmin
+5. **Automated Scaling**: Dynamic resource allocation based on usage