feat(docs): migrate and reorganize frontend guides for BP panel and file uploads
- Deleted outdated documentation files for BP panel list sorting and Filestore frontend guide. - Created new documentation files for BP panel list sorting and Filestore frontend guide in the client directory. - Updated the structure and content to enhance clarity and accessibility for frontend integration with file upload and profile image APIs. - Ensured consistency in documentation style and improved examples for better developer experience.
This commit is contained in:
AmirReza Jamali
@@ -0,0 +1,276 @@
|
||||
# Frontend Guide: File Upload + Profile Image APIs
|
||||
|
||||
This is a simple reference for frontend integration with file upload, file retrieval, and setting profile image.
|
||||
|
||||
## Base URLs
|
||||
|
||||
- Admin APIs: `/admin/v1`
|
||||
- Customer/Public APIs: `/api/v1`
|
||||
|
||||
All protected endpoints require:
|
||||
|
||||
- `Authorization: Bearer <access_token>`
|
||||
|
||||
---
|
||||
|
||||
## 1) Login (Admin)
|
||||
|
||||
Use this when you want to update admin user profile image.
|
||||
|
||||
### Request
|
||||
|
||||
- `POST /admin/v1/profile/login`
|
||||
- `Content-Type: application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "Admin1234"
|
||||
}
|
||||
```
|
||||
|
||||
### Response (success)
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Login successful",
|
||||
"data": {
|
||||
"user": {
|
||||
"id": "65bc1234567890abcdef1234",
|
||||
"profile_image": null
|
||||
},
|
||||
"access_token": "<jwt>",
|
||||
"refresh_token": "<jwt>",
|
||||
"expires_at": 1776783486
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2) Upload File (GridFS)
|
||||
|
||||
Use multipart form upload.
|
||||
|
||||
### Admin route
|
||||
|
||||
- `POST /admin/v1/files/upload`
|
||||
|
||||
### Customer route
|
||||
|
||||
- `POST /api/v1/files/upload`
|
||||
|
||||
### Form fields
|
||||
|
||||
- `file` (required, File)
|
||||
- `category` (optional, string), example: `profile_images`
|
||||
- `tags` (optional, repeatable), example: `user`, `profile`
|
||||
- `description` (optional, string)
|
||||
|
||||
### Response (success)
|
||||
|
||||
```json
|
||||
{
|
||||
"file_id": "69e7899c2053abd3fa5433e0",
|
||||
"filename": "avatar.png",
|
||||
"content_type": "image/png",
|
||||
"size": 123456,
|
||||
"message": "File uploaded successfully"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3) Get File Info
|
||||
|
||||
- `GET /admin/v1/files/{file_id}/info`
|
||||
- `GET /api/v1/files/{file_id}/info`
|
||||
|
||||
### Response (success)
|
||||
|
||||
```json
|
||||
{
|
||||
"file_id": "69e7899c2053abd3fa5433e0",
|
||||
"filename": "avatar.png",
|
||||
"content_type": "image/png",
|
||||
"size": 123456,
|
||||
"uploaded_by": "65bc1234567890abcdef1234",
|
||||
"uploaded_at": "2026-04-21T14:28:44.787Z",
|
||||
"category": "profile_images",
|
||||
"tags": ["user", "profile"],
|
||||
"description": "sample profile photo"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4) Download File
|
||||
|
||||
- `GET /admin/v1/files/{file_id}/download`
|
||||
- `GET /api/v1/files/{file_id}/download`
|
||||
|
||||
Returns file binary stream.
|
||||
|
||||
Useful for image URL:
|
||||
|
||||
- `http://localhost:8080/admin/v1/files/<file_id>/download`
|
||||
- or `http://localhost:8080/api/v1/files/<file_id>/download`
|
||||
|
||||
---
|
||||
|
||||
## 5) Set Admin User Profile Image
|
||||
|
||||
Upload does not update user profile automatically.
|
||||
After upload, call profile update endpoint with the download URL.
|
||||
|
||||
### Request
|
||||
|
||||
- `PUT /admin/v1/profile`
|
||||
- `Content-Type: application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"profile_image": "http://localhost:8080/admin/v1/files/69e7899c2053abd3fa5433e0/download"
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
- Success: standard success envelope with updated user data
|
||||
- Failure example:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Bad Request",
|
||||
"error": {
|
||||
"code": "BAD_REQUEST",
|
||||
"message": "failed to update user"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6) Verify Profile
|
||||
|
||||
- `GET /admin/v1/profile`
|
||||
|
||||
Check:
|
||||
|
||||
- `data.profile_image` is now populated with file URL.
|
||||
|
||||
---
|
||||
|
||||
## Common Errors
|
||||
|
||||
- `401 Unauthorized`: missing/expired token
|
||||
- `413 Request Entity Too Large`: file too big
|
||||
- `400 Unsupported file type` or validation error
|
||||
- `404 File not found`: wrong `file_id`
|
||||
|
||||
---
|
||||
|
||||
## Suggested Frontend Flow (Admin)
|
||||
|
||||
1. Login -> save `access_token`
|
||||
2. Upload image -> get `file_id`
|
||||
3. Build URL `.../admin/v1/files/{file_id}/download`
|
||||
4. Update profile with `profile_image` URL
|
||||
5. Refresh profile screen via `GET /admin/v1/profile`
|
||||
|
||||
---
|
||||
|
||||
## Customer: Company Documents Upload
|
||||
|
||||
Customers can upload company documents using customer auth token.
|
||||
|
||||
### Upload endpoint
|
||||
|
||||
- `POST /api/v1/files/upload`
|
||||
|
||||
### Recommended form-data for company docs
|
||||
|
||||
- `file`: actual document file
|
||||
- `category`: `company_documents`
|
||||
- `tags`: repeatable. Suggested:
|
||||
- `company`
|
||||
- `document`
|
||||
- `<doc_type>` (example: `tax_certificate`, `registration`, `license`)
|
||||
- `description`: human-readable note, example: `Company tax certificate 2026`
|
||||
|
||||
### Example curl
|
||||
|
||||
```bash
|
||||
CUSTOMER_TOKEN="<customer_access_token>"
|
||||
|
||||
curl -X POST "http://localhost:8080/api/v1/files/upload" \
|
||||
-H "Authorization: Bearer ${CUSTOMER_TOKEN}" \
|
||||
-F "file=@/absolute/path/to/company-doc.pdf" \
|
||||
-F "category=company_documents" \
|
||||
-F "tags=company" \
|
||||
-F "tags=document" \
|
||||
-F "tags=tax_certificate" \
|
||||
-F "description=Company tax certificate 2026"
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"file_id": "69e8abcd2053abd3fa5433e1",
|
||||
"filename": "company-doc.pdf",
|
||||
"content_type": "application/pdf",
|
||||
"size": 245632,
|
||||
"message": "File uploaded successfully"
|
||||
}
|
||||
```
|
||||
|
||||
### Fetch company docs list
|
||||
|
||||
Use list with category filter:
|
||||
|
||||
- `GET /api/v1/files?category=company_documents&limit=50&skip=0`
|
||||
|
||||
You can also filter by tags:
|
||||
|
||||
- `GET /api/v1/files?category=company_documents&tags=tax_certificate`
|
||||
|
||||
### Download company doc
|
||||
|
||||
- `GET /api/v1/files/{file_id}/download`
|
||||
|
||||
### Important current behavior
|
||||
|
||||
- Upload works for customers and stores `uploaded_by` as `customer_id`.
|
||||
- Company now supports `document_file_ids` for mapping GridFS files.
|
||||
|
||||
### Attach uploaded documents to company
|
||||
|
||||
Use admin company update endpoint after collecting uploaded `file_id` values:
|
||||
|
||||
- `PUT /admin/v1/companies/{company_id}`
|
||||
|
||||
Request body includes regular company fields plus `document_file_ids`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Opplens",
|
||||
"type": "private",
|
||||
"registration_number": "1234567890",
|
||||
"tax_id": "1234567890",
|
||||
"industry": "Technology",
|
||||
"document_file_ids": [
|
||||
"69e8abcd2053abd3fa5433e1",
|
||||
"69e8abcd2053abd3fa5433e2"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`document_file_ids` is also returned in:
|
||||
|
||||
- `GET /admin/v1/companies/{id}`
|
||||
- `GET /api/v1/companies` (customer "my company" profile)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user