113 lines
3.6 KiB
Markdown
113 lines
3.6 KiB
Markdown
# User Avatar — Design Spec
|
|
|
|
## Goal
|
|
|
|
Allow users to upload a profile avatar image (with client-side circular crop) that replaces initials everywhere in the app.
|
|
|
|
## Backend
|
|
|
|
### Entity Changes
|
|
|
|
**User** — add nullable field:
|
|
- `avatarFileName: ?string` (length 255) — UUID-based filename stored on disk
|
|
|
|
### Storage
|
|
|
|
- Directory: `var/uploads/avatars/`
|
|
- Parameter in `services.yaml`: `avatar_upload_dir`
|
|
|
|
### Endpoints
|
|
|
|
All under `/api/users/{id}/avatar`:
|
|
|
|
| Method | Description | Auth |
|
|
|--------|-------------|------|
|
|
| `POST` | Upload avatar (multipart file) | Owner or ROLE_ADMIN |
|
|
| `GET` | Serve avatar image (inline) | ROLE_USER or ROLE_CLIENT |
|
|
| `DELETE` | Remove avatar | Owner or ROLE_ADMIN |
|
|
|
|
**POST** accepts a single `file` field. Validates: image MIME (jpeg, png, webp, gif), max 5 MB. Stores with UUID filename, updates `avatarFileName`. Deletes previous file if exists.
|
|
|
|
**GET** returns the image with proper `Content-Type`. Returns 404 if no avatar.
|
|
|
|
**DELETE** removes file from disk, sets `avatarFileName` to null.
|
|
|
|
These are custom Symfony controllers (not API Platform resources) under `/api/` with `priority: 1`.
|
|
|
|
### Serialization
|
|
|
|
Add a virtual `avatarUrl` field to User serialization (group `user:read`):
|
|
- If `avatarFileName` is set: `/api/users/{id}/avatar`
|
|
- If null: `null`
|
|
|
|
This way the frontend knows if an avatar exists from any user payload.
|
|
|
|
### Migration
|
|
|
|
- Add `avatar_file_name` column (VARCHAR 255, nullable) to `user` table.
|
|
|
|
## Frontend
|
|
|
|
### New Components
|
|
|
|
**`UserAvatar.vue`** (`frontend/components/user/UserAvatar.vue`):
|
|
- Props: `user: { id: number, username: string, avatarUrl?: string | null }`, `size: 'xs' | 'sm' | 'md' | 'lg'`
|
|
- Sizes: xs=20px, sm=24px, md=32px, lg=48px
|
|
- If `avatarUrl`: `<img>` rounded-full, object-cover
|
|
- Else: initials badge (current bg-primary-500 style), 2 first chars of username uppercased
|
|
- Handles `@error` on img to fallback to initials (broken image)
|
|
|
|
**`AvatarCropper.vue`** (`frontend/components/user/AvatarCropper.vue`):
|
|
- Uses `vue-advanced-cropper` with `CircleStencil`
|
|
- Props: `imageFile: File`
|
|
- Emits: `crop(blob: Blob)`, `cancel`
|
|
- Fixed output size: 256x256px
|
|
- Modal overlay with crop area + confirm/cancel buttons
|
|
|
|
### New Page
|
|
|
|
**`/profile`** (`frontend/pages/profile.vue`):
|
|
- Shows current avatar (large) with "Change" button
|
|
- File input triggers AvatarCropper modal
|
|
- On confirm: POST blob to `/api/users/{id}/avatar`
|
|
- On success: refresh auth store user data
|
|
- "Remove avatar" button if avatar exists
|
|
- Accessible from "Mon profil" button in AppTopNav dropdown
|
|
|
|
### New Service
|
|
|
|
**`frontend/services/avatar.ts`**:
|
|
- `upload(userId: number, file: Blob): Promise<void>` — POST multipart
|
|
- `remove(userId: number): Promise<void>` — DELETE
|
|
- `getUrl(userId: number): string` — returns URL path
|
|
|
|
### DTO Update
|
|
|
|
**`UserData`** — add: `avatarUrl?: string | null`
|
|
|
|
### Replacement Points
|
|
|
|
Replace initials/icon with `<UserAvatar>` in:
|
|
|
|
| File | Current display | Size |
|
|
|------|----------------|------|
|
|
| `TaskCard.vue:48-53` | Initials badge (h-5 w-5) | xs |
|
|
| `archives.vue:50-55` | Initials badge (h-5 w-5) | xs |
|
|
| `AppTopNav.vue:13` | `mdi:account-circle-outline` icon | md |
|
|
| `AdminClientTicketTab.vue` | Username text for submitter | sm |
|
|
| `ClientTicketDetailModal.vue` | submittedBy display | sm |
|
|
|
|
### Auth Store
|
|
|
|
After avatar upload/delete, re-fetch current user data so `avatarUrl` updates everywhere reactively.
|
|
|
|
## Dependencies
|
|
|
|
- `vue-advanced-cropper` — npm install in frontend/
|
|
|
|
## Out of Scope
|
|
|
|
- Server-side image processing/resize
|
|
- Multiple image formats conversion
|
|
- Avatar for clients (entities), only users
|