File system & Handler

This module manages file operations within the Plantask system, including upload, deletion, renaming, and batch zipping. It integrates with the database and activity log to track file-related actions.

📁 FILE MANAGEMENT WORKFLOW (Pyramid + SQLAlchemy)

---

1. 📤 File Upload (Single)

▶ Entry Point:

Route: file_upload_page Method: POST Function: file_upload_page(request)

🔄 Flow:

1. Extract Form Data:

   • entity_type (task, microtask, project, profile_picture)

   • entity_id (ID to associate file with)

   • file (uploaded file)

   • view_name (optional, for logs)

2. Create FileUploadService instance

3. Call handle_upload(...) in the service

   • Saves file to disk

   • Creates DB record in File

   • Associates with corresponding entity via:

     • TasksFile

     • MicrotasksFile

     • Project.project_image_id

     • User.user_image_id

   • Logs activity in ActivityLog

4. Flash message + redirect based on entity_type → to the appropriate view (task, microtask, etc.)

---

2. 📤 File Upload (Multiple)

▶ Entry Point:

Route: multi_upload Method: POST Function: multi_upload(request)

🔄 Flow:

1. Get list of uploaded files from multi_files (POST)

2. Create FileUploadService instance

3. Call handle_multiple_uploads_as_file(...) (Not shown in your code, but presumably similar to handle_upload in structure)

4. Flash success/failure

5. Redirect to file_list_page

---

3. 📄 File Display

▶ Entry Point:

Route: file_list_page Method: GET Function: file_list_page(request)

🔄 Flow:

1. Queries all active files: File.active == True

2. Passes them to the template: templates/test_file_service.jinja2

---

4. ⬇ File Download (GET or POST)

▶ Option A:

Route: file_crud Method: GET Function: file_crud(request)

▶ Option B:

Route: download_file Method: POST Function: handle_download_file(request)

🔄 Flow (Both):

1. Extract file_id and check action == 'download'

2. Create FileUploadService instance

3. Call download_file(file_id)

   • Query File where active == True

   • Check file exists on disk

   • Return file path + name

4. Return FileResponse to trigger browser download

---

5. ❌ File Deletion (Soft Delete)

▶ Entry Point:

Route: delete_file_page Method: POST Function: delete_file_page(request)

🔄 Flow:

1. Extract file_id and view_name from POST

2. Create FileUploadService instance

3. Call delete_file(file_id, ...)

   • Sets File.active = False

   • Logs activity in ActivityLog

4. Flash message + redirect to file_list_page

---

🔧 SERVICE LOGIC: FileUploadService

✅ save_file_to_disk(file_storage)

• Saves to upload_dir

• Only allows certain extensions (ALLOWED_FILES)

• Returns metadata (filename, path, extension, URL)

---

✅ handle_upload(...)

• Uses save_file_to_disk

• Creates a File record

• Associates with entity (via TasksFile, ProfilePicture, etc.)

• Logs action via ActivityLog

• Returns upload result

---

✅ delete_file(...)

• Queries file by ID

• If found and active → sets active = False

• Logs deletion

• Commits transaction

---

✅ download_file(file_id)

• Looks up file by ID

• Ensures it's active and file exists

• Returns path and filename for download