Re_Backend/TESTING_GCS_UPLOADS.md

Testing GCS File Uploads from Frontend

✅ Pre-Testing Checklist

Before testing, ensure the following are configured:

1. Environment Variables (.env file)

Make sure your .env file has these values:

GCP_PROJECT_ID=re-platform-workflow-dealer
GCP_BUCKET_NAME=your-bucket-name-here
GCP_KEY_FILE=./credentials/re-platform-workflow-dealer-3d5738fcc1f9.json

Important:

• Replace your-bucket-name-here with your actual GCS bucket name
• Ensure the credentials file path is correct
• The credentials file should exist at the specified path

2. GCS Bucket Setup

• Bucket exists in GCP Console
• Service account has permissions (Storage Object Admin)
• Bucket is accessible (public or with proper IAM)

3. Backend Server

• Backend server is running
• Check backend logs for GCS initialization message:

  [GCS] Initialized successfully
  

🧪 Testing Steps

Test 1: Upload Document (Standalone)

1. Navigate to a Request Detail page

   • Open any existing workflow request
   • Go to the "Documents" tab

2. Upload a document

   • Click "Upload Document" or browse button
   • Select a file (PDF, DOCX, etc.)
   • Wait for upload to complete

3. Verify in Backend Logs:

   [GCS] File uploaded successfully
   

4. Check Database:

   • storage_url field should contain GCS URL like:

     https://storage.googleapis.com/BUCKET_NAME/requests/REQ-2025-12-0001/documents/...
     

5. Verify in GCS Console:

   • Go to GCS Console
   • Navigate to: requests/{requestNumber}/documents/
   • File should be there

Test 2: Upload Document During Workflow Creation

1. Create New Workflow

   • Go to "Create Request"
   • Fill in workflow details
   • In "Documents" step, upload files
   • Submit workflow

2. Verify:

   • Check backend logs for GCS upload
   • Check GCS bucket: requests/{requestNumber}/documents/
   • Files should be organized by request number

Test 3: Upload Work Note Attachment

1. Open Work Notes/Chat

   • Go to any request
   • Open the work notes/chat section

2. Attach File to Comment

   • Type a comment
   • Click attachment icon
   • Select a file
   • Send the comment

3. Verify:

   • Check backend logs
   • Check GCS bucket: requests/{requestNumber}/attachments/
   • File should appear in attachments folder

Test 4: Download/Preview Files

1. Download Document

   • Click download on any document
   • Should redirect to GCS URL or download from GCS

2. Preview Document

   • Click preview on any document
   • Should open from GCS URL

🔍 What to Check

Backend Logs

Success:

[GCS] Initialized successfully { projectId: '...', bucketName: '...' }
[GCS] File uploaded successfully { fileName: '...', gcsPath: '...' }

Error (Falls back to local):

[GCS] GCP configuration missing. File uploads will fail.
[GCS] GCS upload failed, falling back to local storage

Database Verification

Check the documents and work_note_attachments tables:

-- Check documents
SELECT document_id, file_name, storage_url, file_path 
FROM documents 
WHERE request_id = 'YOUR_REQUEST_ID';

-- Check attachments
SELECT attachment_id, file_name, storage_url, file_path 
FROM work_note_attachments 
WHERE note_id IN (
  SELECT note_id FROM work_notes WHERE request_id = 'YOUR_REQUEST_ID'
);

Expected:

• storage_url should contain GCS URL (if GCS configured)
• file_path should contain GCS path like requests/REQ-2025-12-0001/documents/...

GCS Console Verification

1. Go to GCS Console
2. Navigate to your bucket
3. Check folder structure:

   requests/
   ├── REQ-2025-12-0001/
   │   ├── documents/
   │   │   └── {timestamp}-{hash}-{filename}
   │   └── attachments/
   │       └── {timestamp}-{hash}-{filename}
   

🐛 Troubleshooting

Issue: Files not uploading to GCS

Check:

1. .env file has correct values
2. Credentials file exists at specified path
3. Service account has correct permissions
4. Bucket name is correct
5. Backend logs for errors

Solution:

• System will automatically fall back to local storage
• Fix configuration and restart backend
• Re-upload files

Issue: "GCP configuration missing" in logs

Cause: Missing or incorrect environment variables

Fix:

GCP_PROJECT_ID=re-platform-workflow-dealer
GCP_BUCKET_NAME=your-actual-bucket-name
GCP_KEY_FILE=./credentials/re-platform-workflow-dealer-3d5738fcc1f9.json

Issue: "Key file not found"

Cause: Credentials file path is incorrect

Fix:

• Verify file exists at: Re_Backend/credentials/re-platform-workflow-dealer-3d5738fcc1f9.json
• Update GCP_KEY_FILE path in .env if needed

Issue: Files upload but can't download/preview

Cause: Bucket permissions or CORS configuration

Fix:

• Check bucket IAM permissions
• Verify CORS is configured (see GCP_STORAGE_SETUP.md)
• Check if bucket is public or using signed URLs

✅ Success Indicators

• ✅ Backend logs show "GCS Initialized successfully"
• ✅ Files upload without errors
• ✅ Database storage_url contains GCS URLs
• ✅ Files visible in GCS Console under correct folder structure
• ✅ Downloads/previews work from GCS URLs
• ✅ Files organized by request number with documents/attachments separation

📝 Notes

• No Frontend Changes Required: The frontend uses the same API endpoints
• Automatic Fallback: If GCS is not configured, system uses local storage
• Backward Compatible: Existing local files continue to work
• Folder Structure: Files are automatically organized by request number