init agent

Backend/.agent/workflowss/file-upload.md

@@ -0,0 +1,536 @@
+---
+description: How to handle file uploads (videos, attachments)
+---
+
+# File Upload Workflow
+
+Follow these steps to implement file upload functionality for videos and attachments.
+
+---
+
+## Prerequisites
+
+- MinIO/S3 configured and running
+- Multer installed: `npm install multer`
+- AWS SDK or MinIO client installed
+
+---
+
+## Step 1: Configure S3/MinIO Client
+
+Create `src/config/s3.config.js`:
+
+```javascript
+const { S3Client } = require('@aws-sdk/client-s3');
+const { Upload } = require('@aws-sdk/lib-storage');
+
+const s3Client = new S3Client({
+  endpoint: process.env.S3_ENDPOINT,
+  region: process.env.S3_REGION || 'us-east-1',
+  credentials: {
+    accessKeyId: process.env.S3_ACCESS_KEY,
+    secretAccessKey: process.env.S3_SECRET_KEY
+  },
+  forcePathStyle: true // Required for MinIO
+});
+
+module.exports = { s3Client };
+```
+
+---
+
+## Step 2: Create Upload Service
+
+Create `src/services/upload.service.js`:
+
+```javascript
+const { s3Client } = require('../config/s3.config');
+const { Upload } = require('@aws-sdk/lib-storage');
+const { DeleteObjectCommand } = require('@aws-sdk/client-s3');
+const { v4: uuidv4 } = require('uuid');
+const path = require('path');
+
+class UploadService {
+  async uploadFile(file, folder) {
+    const fileExt = path.extname(file.originalname);
+    const fileName = `${Date.now()}-${uuidv4()}${fileExt}`;
+    const key = `${folder}/${fileName}`;
+
+    const upload = new Upload({
+      client: s3Client,
+      params: {
+        Bucket: this.getBucket(folder),
+        Key: key,
+        Body: file.buffer,
+        ContentType: file.mimetype
+      }
+    });
+
+    await upload.done();
+
+    return {
+      key,
+      url: `${process.env.S3_ENDPOINT}/${this.getBucket(folder)}/${key}`,
+      fileName: file.originalname,
+      fileSize: file.size,
+      mimeType: file.mimetype
+    };
+  }
+
+  async deleteFile(key, folder) {
+    const command = new DeleteObjectCommand({
+      Bucket: this.getBucket(folder),
+      Key: key
+    });
+
+    await s3Client.send(command);
+  }
+
+  getBucket(folder) {
+    const bucketMap = {
+      videos: process.env.S3_BUCKET_VIDEOS,
+      documents: process.env.S3_BUCKET_DOCUMENTS,
+      images: process.env.S3_BUCKET_IMAGES,
+      attachments: process.env.S3_BUCKET_ATTACHMENTS
+    };
+
+    return bucketMap[folder] || process.env.S3_BUCKET_COURSES;
+  }
+
+  validateFileType(file, allowedTypes) {
+    return allowedTypes.includes(file.mimetype);
+  }
+
+  validateFileSize(file, maxSize) {
+    return file.size <= maxSize;
+  }
+}
+
+module.exports = new UploadService();
+```
+
+---
+
+## Step 3: Create Upload Middleware
+
+Create `src/middleware/upload.middleware.js`:
+
+```javascript
+const multer = require('multer');
+
+// File type validators
+const ALLOWED_VIDEO_TYPES = ['video/mp4', 'video/webm', 'video/quicktime'];
+const ALLOWED_DOCUMENT_TYPES = [
+  'application/pdf',
+  'application/msword',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'application/vnd.ms-excel',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+];
+const ALLOWED_IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/gif'];
+
+// File size limits
+const MAX_VIDEO_SIZE = 500 * 1024 * 1024; // 500 MB
+const MAX_ATTACHMENT_SIZE = 100 * 1024 * 1024; // 100 MB
+const MAX_IMAGE_SIZE = 10 * 1024 * 1024; // 10 MB
+
+// Multer configuration
+const storage = multer.memoryStorage();
+
+const fileFilter = (allowedTypes) => (req, file, cb) => {
+  if (allowedTypes.includes(file.mimetype)) {
+    cb(null, true);
+  } else {
+    cb(new Error('Invalid file type'), false);
+  }
+};
+
+// Upload configurations
+const uploadVideo = multer({
+  storage,
+  limits: { fileSize: MAX_VIDEO_SIZE },
+  fileFilter: fileFilter(ALLOWED_VIDEO_TYPES)
+}).single('video');
+
+const uploadAttachment = multer({
+  storage,
+  limits: { fileSize: MAX_ATTACHMENT_SIZE },
+  fileFilter: fileFilter([...ALLOWED_DOCUMENT_TYPES, ...ALLOWED_IMAGE_TYPES])
+}).single('file');
+
+const uploadAttachments = multer({
+  storage,
+  limits: { fileSize: MAX_ATTACHMENT_SIZE },
+  fileFilter: fileFilter([...ALLOWED_DOCUMENT_TYPES, ...ALLOWED_IMAGE_TYPES])
+}).array('attachments', 10); // Max 10 files
+
+const uploadImage = multer({
+  storage,
+  limits: { fileSize: MAX_IMAGE_SIZE },
+  fileFilter: fileFilter(ALLOWED_IMAGE_TYPES)
+}).single('image');
+
+module.exports = {
+  uploadVideo,
+  uploadAttachment,
+  uploadAttachments,
+  uploadImage,
+  ALLOWED_VIDEO_TYPES,
+  ALLOWED_DOCUMENT_TYPES,
+  ALLOWED_IMAGE_TYPES
+};
+```
+
+---
+
+## Step 4: Create Upload Controller
+
+Create `src/controllers/upload.controller.js`:
+
+```javascript
+const uploadService = require('../services/upload.service');
+
+class UploadController {
+  async uploadVideo(req, res) {
+    try {
+      if (!req.file) {
+        return res.status(400).json({
+          error: {
+            code: 'NO_FILE',
+            message: 'No video file provided'
+          }
+        });
+      }
+
+      const result = await uploadService.uploadFile(
+        req.file,
+        'videos'
+      );
+
+      return res.status(200).json({
+        video_url: result.url,
+        file_size: result.fileSize,
+        duration: null // Will be processed later
+      });
+    } catch (error) {
+      console.error('Upload video error:', error);
+      return res.status(500).json({
+        error: {
+          code: 'UPLOAD_FAILED',
+          message: 'Failed to upload video'
+        }
+      });
+    }
+  }
+
+  async uploadAttachment(req, res) {
+    try {
+      if (!req.file) {
+        return res.status(400).json({
+          error: {
+            code: 'NO_FILE',
+            message: 'No file provided'
+          }
+        });
+      }
+
+      const result = await uploadService.uploadFile(
+        req.file,
+        'attachments'
+      );
+
+      return res.status(200).json({
+        file_name: result.fileName,
+        file_path: result.key,
+        file_size: result.fileSize,
+        mime_type: result.mimeType,
+        download_url: result.url
+      });
+    } catch (error) {
+      console.error('Upload attachment error:', error);
+      return res.status(500).json({
+        error: {
+          code: 'UPLOAD_FAILED',
+          message: 'Failed to upload file'
+        }
+      });
+    }
+  }
+}
+
+module.exports = new UploadController();
+```
+
+---
+
+## Step 5: Create Upload Routes
+
+Create `src/routes/upload.routes.js`:
+
+```javascript
+const express = require('express');
+const router = express.Router();
+const uploadController = require('../controllers/upload.controller');
+const { authenticate, authorize } = require('../middleware/auth');
+const { uploadVideo, uploadAttachment } = require('../middleware/upload.middleware');
+
+// Video upload
+router.post(
+  '/video',
+  authenticate,
+  authorize(['INSTRUCTOR', 'ADMIN']),
+  (req, res, next) => {
+    uploadVideo(req, res, (err) => {
+      if (err) {
+        if (err.message === 'Invalid file type') {
+          return res.status(422).json({
+            error: {
+              code: 'INVALID_FILE_TYPE',
+              message: 'Only MP4, WebM, and QuickTime videos are allowed'
+            }
+          });
+        }
+        if (err.code === 'LIMIT_FILE_SIZE') {
+          return res.status(422).json({
+            error: {
+              code: 'FILE_TOO_LARGE',
+              message: 'Video file size exceeds 500 MB limit'
+            }
+          });
+        }
+        return res.status(500).json({
+          error: {
+            code: 'UPLOAD_ERROR',
+            message: err.message
+          }
+        });
+      }
+      next();
+    });
+  },
+  uploadController.uploadVideo
+);
+
+// Attachment upload
+router.post(
+  '/attachment',
+  authenticate,
+  authorize(['INSTRUCTOR', 'ADMIN']),
+  (req, res, next) => {
+    uploadAttachment(req, res, (err) => {
+      if (err) {
+        if (err.message === 'Invalid file type') {
+          return res.status(422).json({
+            error: {
+              code: 'INVALID_FILE_TYPE',
+              message: 'File type not allowed'
+            }
+          });
+        }
+        if (err.code === 'LIMIT_FILE_SIZE') {
+          return res.status(422).json({
+            error: {
+              code: 'FILE_TOO_LARGE',
+              message: 'File size exceeds 100 MB limit'
+            }
+          });
+        }
+        return res.status(500).json({
+          error: {
+            code: 'UPLOAD_ERROR',
+            message: err.message
+          }
+        });
+      }
+      next();
+    });
+  },
+  uploadController.uploadAttachment
+);
+
+module.exports = router;
+```
+
+---
+
+## Step 6: Integrate with Lesson Creation
+
+Update lesson controller to handle file uploads:
+
+```javascript
+async createLesson(req, res) {
+  try {
+    const { courseId, chapterId } = req.params;
+    
+    // Create lesson
+    const lesson = await lessonService.create({
+      ...req.body,
+      chapter_id: parseInt(chapterId)
+    });
+
+    // Handle video upload if present
+    if (req.files?.video) {
+      const videoResult = await uploadService.uploadFile(
+        req.files.video[0],
+        `courses/${courseId}/lessons/${lesson.id}`
+      );
+      
+      await lessonService.update(lesson.id, {
+        video_url: videoResult.url
+      });
+    }
+
+    // Handle attachments if present
+    if (req.files?.attachments) {
+      const attachments = await Promise.all(
+        req.files.attachments.map(async (file, index) => {
+          const result = await uploadService.uploadFile(
+            file,
+            `lessons/${lesson.id}/attachments`
+          );
+          
+          return {
+            lesson_id: lesson.id,
+            file_name: result.fileName,
+            file_path: result.key,
+            file_size: result.fileSize,
+            mime_type: result.mimeType,
+            description: req.body.descriptions?.[index] || {},
+            sort_order: index + 1
+          };
+        })
+      );
+
+      await prisma.attachment.createMany({
+        data: attachments
+      });
+    }
+
+    return res.status(201).json(lesson);
+  } catch (error) {
+    console.error('Create lesson error:', error);
+    return res.status(500).json({
+      error: {
+        code: 'INTERNAL_ERROR',
+        message: 'Failed to create lesson'
+      }
+    });
+  }
+}
+```
+
+---
+
+## Step 7: Test File Upload
+
+```bash
+# Upload video
+curl -X POST http://localhost:4000/api/upload/video \
+  -H "Authorization: Bearer <token>" \
+  -F "video=@/path/to/video.mp4"
+
+# Upload attachment
+curl -X POST http://localhost:4000/api/upload/attachment \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@/path/to/document.pdf"
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+1. **File Too Large**
+```json
+{
+  "error": {
+    "code": "FILE_TOO_LARGE",
+    "message": "File size exceeds maximum limit"
+  }
+}
+```
+
+2. **Invalid File Type**
+```json
+{
+  "error": {
+    "code": "INVALID_FILE_TYPE",
+    "message": "File type not allowed"
+  }
+}
+```
+
+3. **S3 Upload Failed**
+```json
+{
+  "error": {
+    "code": "UPLOAD_FAILED",
+    "message": "Failed to upload file to storage"
+  }
+}
+```
+
+---
+
+## Checklist
+
+- [ ] S3/MinIO client configured
+- [ ] Upload service created
+- [ ] Upload middleware configured
+- [ ] File type validation implemented
+- [ ] File size validation implemented
+- [ ] Upload routes created
+- [ ] Error handling implemented
+- [ ] File deletion implemented
+- [ ] Tests written
+- [ ] Manual testing done
+
+---
+
+## Best Practices
+
+1. **Validate Before Upload**: Check file type and size before uploading
+2. **Unique Filenames**: Use UUID to prevent filename conflicts
+3. **Organized Storage**: Use folder structure (courses/1/lessons/5/video.mp4)
+4. **Error Handling**: Provide clear error messages
+5. **Cleanup**: Delete files from S3 when deleting records
+6. **Security**: Validate file content, not just extension
+7. **Progress**: Consider upload progress for large files
+
+---
+
+## Advanced: Video Processing
+
+For video processing (transcoding, thumbnails):
+
+```javascript
+const ffmpeg = require('fluent-ffmpeg');
+
+async function processVideo(videoPath) {
+  // Generate thumbnail
+  await new Promise((resolve, reject) => {
+    ffmpeg(videoPath)
+      .screenshots({
+        timestamps: ['00:00:01'],
+        filename: 'thumbnail.jpg',
+        folder: './thumbnails'
+      })
+      .on('end', resolve)
+      .on('error', reject);
+  });
+
+  // Get video duration
+  const metadata = await new Promise((resolve, reject) => {
+    ffmpeg.ffprobe(videoPath, (err, metadata) => {
+      if (err) reject(err);
+      else resolve(metadata);
+    });
+  });
+
+  return {
+    duration: metadata.format.duration,
+    thumbnail: './thumbnails/thumbnail.jpg'
+  };
+}
+```