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:

```env
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:

```sql
-- 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](https://console.cloud.google.com/storage)
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:**
```env
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