chore: import codes
This commit is contained in:
@@ -0,0 +1,192 @@
|
||||
# Nuage module – Dashboard (Mes fichiers)
|
||||
|
||||
This guide explains how to add a **Mes fichiers** (My files) section to your client dashboard so that logged-in users can browse, download, and upload files/folders that have been shared with them by an admin.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Auth and dashboard set up as in [Client dashboard and user features](../../features/auth/README-dashboard.md).
|
||||
- Nuage module enabled (`ZEN_MODULE_NUAGE=true`).
|
||||
- **User–share link**: In the admin Nuage explorer, an admin must have created a share targeting a specific user (by their email/account). The share is stored in `zen_nuage_shares` with `user_id` set to the user.
|
||||
|
||||
## API for "my shares"
|
||||
|
||||
When a user is authenticated, you can load all active file/folder shares assigned to them with:
|
||||
|
||||
| Endpoint | Method | Auth | Description |
|
||||
|----------|--------|------|-------------|
|
||||
| `/zen/api/nuage/me` | GET | Session (user) | Returns all active shares assigned to the current user. |
|
||||
| `/zen/api/nuage/shared` | GET | Session (user) | Returns the contents of a shared folder (subfolders + files). |
|
||||
| `/zen/api/nuage/download` | GET | Session (user) | Returns a signed download URL for a file inside a share. |
|
||||
| `/zen/api/nuage/upload` | POST | Session (user) | Uploads a file into a shared folder (collaborator permission only). |
|
||||
|
||||
### GET `/zen/api/nuage/me`
|
||||
|
||||
**Example response (user has active shares):**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"shares": [
|
||||
{
|
||||
"id": 1,
|
||||
"token": "abc123...",
|
||||
"target_type": "folder",
|
||||
"target_id": "42",
|
||||
"target_name": "Contrats 2025",
|
||||
"permission": "reader",
|
||||
"expires_at": null
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"token": "def456...",
|
||||
"target_type": "file",
|
||||
"target_id": "17",
|
||||
"target_name": "Devis-2025-01.pdf",
|
||||
"permission": "collaborator",
|
||||
"expires_at": "2025-12-31T23:59:59.000Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**When the user has no active shares:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"shares": []
|
||||
}
|
||||
```
|
||||
|
||||
### GET `/zen/api/nuage/shared`
|
||||
|
||||
**Query parameters:**
|
||||
|
||||
- `shareId` *(required)* – The share `token` returned by `/nuage/me`.
|
||||
- `folder` *(optional)* – ID of a subfolder to navigate into.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"folders": [
|
||||
{ "id": "10", "name": "Sous-dossier", "created_at": "2025-03-01T10:00:00.000Z" }
|
||||
],
|
||||
"files": [
|
||||
{
|
||||
"id": "55",
|
||||
"display_name": "rapport.pdf",
|
||||
"mime_type": "application/pdf",
|
||||
"size": 204800
|
||||
}
|
||||
],
|
||||
"breadcrumb": [
|
||||
{ "id": "10", "name": "Sous-dossier" }
|
||||
],
|
||||
"permission": "reader"
|
||||
}
|
||||
```
|
||||
|
||||
### GET `/zen/api/nuage/download`
|
||||
|
||||
**Query parameters:**
|
||||
|
||||
- `fileId` *(required)* – ID of the file to download.
|
||||
- `shareId` *(required)* – The share `token`.
|
||||
|
||||
Returns a signed URL to download the file directly from storage.
|
||||
|
||||
### POST `/zen/api/nuage/upload`
|
||||
|
||||
Only available for shares with `permission: "collaborator"` targeting a folder.
|
||||
|
||||
**Form data fields:**
|
||||
|
||||
- `file` *(required)* – The file to upload.
|
||||
- `shareId` *(required)* – The share `token`.
|
||||
- `folderId` *(optional)* – ID of a subfolder to upload into (must be within the share scope).
|
||||
|
||||
All requests must send the session cookie (e.g. `fetch(..., { credentials: 'include' })`).
|
||||
|
||||
## Adding the Mes fichiers section to the dashboard
|
||||
|
||||
### 1. Protected page
|
||||
|
||||
Create a dashboard page that requires login and renders the Nuage section:
|
||||
|
||||
```js
|
||||
// app/dashboard/fichiers/page.js (Server Component)
|
||||
import { protect } from '@hykocx/zen/auth';
|
||||
import ClientNuageSection from '@hykocx/zen/nuage/dashboard';
|
||||
|
||||
export default async function DashboardFichiersPage() {
|
||||
await protect({ redirectTo: '/auth/login' });
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h1>Mes fichiers</h1>
|
||||
<ClientNuageSection
|
||||
apiBasePath="/zen/api"
|
||||
nuagePageBasePath="/zen/nuage"
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Props:**
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `apiBasePath` | `string` | `"/zen/api"` | Base path for the Zen API. |
|
||||
| `nuagePageBasePath` | `string` | `"/zen/nuage"` | Base path for the Nuage public pages (currently unused, reserved for future links). |
|
||||
| `emptyMessage` | `string` | `"Aucun document partagé pour le moment."` | Message shown when the user has no active shares. |
|
||||
| `newTab` | `boolean` | `false` | Open file download links in a new browser tab. |
|
||||
|
||||
### 2. Link in the dashboard layout
|
||||
|
||||
In your dashboard layout or nav, add a link to the Mes fichiers page:
|
||||
|
||||
```js
|
||||
<Link href="/dashboard/fichiers">Mes fichiers</Link>
|
||||
```
|
||||
|
||||
## Behaviour summary
|
||||
|
||||
- **Logged in, has active shares** → The section lists all files/folders shared with the user. Clicking a share opens a file browser with navigation, download, and (if `collaborator`) upload.
|
||||
- **Logged in, no active shares** → The section shows `emptyMessage`.
|
||||
- **Expired share** → The share is displayed as greyed out and cannot be opened.
|
||||
- **Not logged in** → The dashboard page should not be reachable if you use `protect()` and redirect to login.
|
||||
- **File preview** → Clicking a viewable file (image, PDF, video, audio, plain text) opens a full-screen viewer. Non-viewable files trigger a direct download.
|
||||
- **Sorting** → The file list can be sorted by name, date, or size (ascending/descending).
|
||||
- **Upload feedback** → When uploading as a collaborator, a per-file progress queue is displayed with a checkmark once each file completes.
|
||||
|
||||
## Share permissions
|
||||
|
||||
There are two permission levels for a share:
|
||||
|
||||
| Permission | Browse | Download | Upload |
|
||||
|------------|--------|----------|--------|
|
||||
| `reader` | Yes | Yes | No |
|
||||
| `collaborator` | Yes | Yes | Yes (folder shares only) |
|
||||
|
||||
The collaborator upload zone appears automatically when the share is a folder with `permission: "collaborator"`. Files can be dragged and dropped or selected via the file picker. An optional upload size limit (`upload_limit_bytes`) can be set by the admin on the share.
|
||||
|
||||
## Creating a share (admin side)
|
||||
|
||||
In the Zen admin Nuage explorer:
|
||||
|
||||
1. Navigate to the file or folder you want to share.
|
||||
2. Click the **Share** button (or the share icon).
|
||||
3. Search for the user by email and select them.
|
||||
4. Set the permission (`reader` or `collaborator`).
|
||||
5. Optionally set an expiry date and an upload size limit.
|
||||
6. Save. The user will immediately see the share in their dashboard under `GET /zen/api/nuage/me`.
|
||||
|
||||
## Security
|
||||
|
||||
- All four client-facing endpoints (`/nuage/me`, `/nuage/shared`, `/nuage/download`, `/nuage/upload`) require a valid session (`auth: 'user'`). No admin role needed.
|
||||
- A user can only access shares explicitly assigned to them (`zen_nuage_shares.user_id = session.user.id`).
|
||||
- File download and folder navigation are scoped to the share target — it is not possible to access files outside the shared scope (IDOR protection enforced server-side).
|
||||
- Upload is only allowed when `permission = 'collaborator'` and `target_type = 'folder'`.
|
||||
Reference in New Issue
Block a user