356 lines
14 KiB
Markdown
356 lines
14 KiB
Markdown
# Albums
|
|
|
|
This document describes album creation, management, sharing, and related functionality.
|
|
|
|
## Album Overview
|
|
|
|
Albums are collections of assets that can be:
|
|
- **Personal**: Created by you, only visible to you
|
|
- **Shared**: Shared with other users who can view/contribute
|
|
- **Local**: Device albums (not synced to server)
|
|
|
|
## Album Model
|
|
|
|
```
|
|
Album {
|
|
id: String // Unique identifier
|
|
name: String // Album name
|
|
description: String // Album description
|
|
ownerId: String // Owner user ID
|
|
ownerName: String // Owner display name
|
|
createdAt: DateTime // Creation time
|
|
updatedAt: DateTime // Last modified
|
|
thumbnailAssetId: String? // Cover image asset ID
|
|
assetCount: Integer // Number of assets
|
|
isShared: Boolean // Has shared users
|
|
isActivityEnabled: Boolean // Comments/likes enabled
|
|
order: AlbumAssetOrder // asc or desc
|
|
sharedUsers: List<User> // Users album is shared with
|
|
}
|
|
```
|
|
|
|
## Album List Screen
|
|
|
|
### Layout
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Albums [List/Grid] ⚙️ │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ [ 🔍 Search albums... ] │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ Sort by: Recent Activity ▼ [+ Create Album] │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ [Cover] │ │ [Cover] │ │ [Cover] │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ Summer 2024 │ │ Family │ │ Wedding │ │
|
|
│ │ 24 items │ │ 156 items │ │ 89 items │ │
|
|
│ │ [👤 Shared] │ │ │ │ [👤👤 Shared]│ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Sort Options
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| Recent Activity | Most recently modified first |
|
|
| Album Name | Alphabetical order |
|
|
| Most Items | Largest albums first |
|
|
| Oldest First | By creation date ascending |
|
|
|
|
### Filter Modes
|
|
| Mode | Shows |
|
|
|------|-------|
|
|
| All | All albums |
|
|
| My Albums | Albums you own |
|
|
| Shared | Albums shared with you |
|
|
| Local | On-device albums |
|
|
|
|
## Album API Endpoints
|
|
|
|
### List Albums
|
|
```
|
|
GET /albums?shared=true|false|null
|
|
|
|
Response:
|
|
[
|
|
{
|
|
"id": "album-uuid",
|
|
"albumName": "Summer 2024",
|
|
"description": "Beach vacation photos",
|
|
"ownerId": "user-uuid",
|
|
"owner": { user object },
|
|
"albumThumbnailAssetId": "asset-uuid",
|
|
"assetCount": 24,
|
|
"shared": true,
|
|
"albumUsers": [...],
|
|
"hasSharedLink": false,
|
|
"isActivityEnabled": true,
|
|
"order": "desc",
|
|
"createdAt": "2024-06-15T10:00:00Z",
|
|
"updatedAt": "2024-06-20T15:30:00Z"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Get Album Detail
|
|
```
|
|
GET /albums/{id}
|
|
|
|
Response: Full album object with assets
|
|
```
|
|
|
|
### Create Album
|
|
```
|
|
POST /albums
|
|
|
|
Body:
|
|
{
|
|
"albumName": "New Album",
|
|
"description": "Album description",
|
|
"assetIds": ["asset-1", "asset-2"],
|
|
"albumUsers": [
|
|
{ "userId": "user-uuid", "role": "editor" }
|
|
]
|
|
}
|
|
|
|
Response: Created album object
|
|
```
|
|
|
|
### Update Album
|
|
```
|
|
PATCH /albums/{id}
|
|
|
|
Body:
|
|
{
|
|
"albumName": "Updated Name",
|
|
"description": "New description",
|
|
"isActivityEnabled": true,
|
|
"order": "asc"
|
|
}
|
|
```
|
|
|
|
### Delete Album
|
|
```
|
|
DELETE /albums/{id}
|
|
```
|
|
|
|
## Album Detail Screen
|
|
|
|
### Layout
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ ← Summer 2024 [Select] [⋮] │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ Beach vacation with family │
|
|
│ 24 items • Shared with 3 people │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ June 2024 │
|
|
│ ┌─────┬─────┬─────┬─────┐ │
|
|
│ │ │ │ │ │ │
|
|
│ │ 📷 │ 📷 │ 🎥 │ 📷 │ │
|
|
│ │ │ │ │ │ │
|
|
│ └─────┴─────┴─────┴─────┘ │
|
|
│ ... │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ [+ Add Photos] [💬 Activity] │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Album Actions Menu
|
|
| Action | Description |
|
|
|--------|-------------|
|
|
| Edit Album | Change name/description |
|
|
| Add Photos | Select assets to add |
|
|
| Share | Share with users or create link |
|
|
| Album Options | Advanced settings |
|
|
| Delete Album | Remove album (owner only) |
|
|
| Leave Album | Leave shared album |
|
|
|
|
## Album Creation Flow
|
|
|
|
### Step 1: Select Assets
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ ← Add to Album [Create] │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ Selected: 5 │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ [Asset selection grid - same as timeline] │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Step 2: Enter Details
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ ← Create Album │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Album Name │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ Summer 2024 │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ Description (optional) │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ Beach vacation photos │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ [Share with users] (optional) │
|
|
│ │
|
|
│ [Create Album] │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Adding Assets to Album
|
|
|
|
### API Endpoint
|
|
```
|
|
PUT /albums/{id}/assets
|
|
|
|
Body:
|
|
{
|
|
"ids": ["asset-1", "asset-2", "asset-3"]
|
|
}
|
|
|
|
Response:
|
|
{
|
|
"successfullyAdded": 3,
|
|
"alreadyInAlbum": ["asset-4"]
|
|
}
|
|
```
|
|
|
|
## Removing Assets from Album
|
|
|
|
### API Endpoint
|
|
```
|
|
DELETE /albums/{id}/assets
|
|
|
|
Body:
|
|
{
|
|
"ids": ["asset-1", "asset-2"]
|
|
}
|
|
```
|
|
|
|
## Sharing Albums
|
|
|
|
### Share with Users
|
|
```
|
|
PUT /albums/{id}/users
|
|
|
|
Body:
|
|
{
|
|
"albumUsers": [
|
|
{ "userId": "user-1", "role": "editor" },
|
|
{ "userId": "user-2", "role": "viewer" }
|
|
]
|
|
}
|
|
```
|
|
|
|
### User Roles
|
|
| Role | Can View | Can Add | Can Remove | Can Edit |
|
|
|------|----------|---------|------------|----------|
|
|
| viewer | ✓ | | | |
|
|
| editor | ✓ | ✓ | Own assets | |
|
|
|
|
### Remove User from Album
|
|
```
|
|
DELETE /albums/{id}/user/{userId}
|
|
```
|
|
|
|
### Leave Album (for shared users)
|
|
```
|
|
DELETE /albums/{id}/user/me
|
|
```
|
|
|
|
## Album Options Screen
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ ← Album Options │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Sort Order │
|
|
│ [Newest first ▼] │
|
|
│ │
|
|
│ ───────────────────────────────────────────────────── │
|
|
│ │
|
|
│ Allow Activity [Toggle: ON] │
|
|
│ Enable comments and likes │
|
|
│ │
|
|
│ ───────────────────────────────────────────────────── │
|
|
│ │
|
|
│ Shared Users │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ 👤 John Doe (Editor) [X] │ │
|
|
│ │ 👤 Jane Smith (Viewer) [X] │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ [+ Add Users] │
|
|
│ │
|
|
│ ───────────────────────────────────────────────────── │
|
|
│ │
|
|
│ [Delete Album] (red, destructive) │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Local Albums
|
|
|
|
### Device Albums
|
|
- Albums from device photo gallery
|
|
- Read-only in the app
|
|
- Can be selected for backup
|
|
- Synced to server when enabled
|
|
|
|
### Local Album Model
|
|
```
|
|
LocalAlbum {
|
|
id: String // Device album ID
|
|
name: String // Album name
|
|
assetCount: Integer // Number of assets
|
|
modifiedAt: DateTime // Last modified
|
|
isAll: Boolean // Is "All Photos" album
|
|
thumbnailId: String? // Cover asset ID
|
|
}
|
|
```
|
|
|
|
## Album Sync
|
|
|
|
### Sync Album Feature
|
|
When enabled, uploaded assets are automatically added to matching remote albums:
|
|
|
|
1. Asset uploaded with album names in metadata
|
|
2. Server checks for existing albums with those names
|
|
3. Creates albums if they don't exist
|
|
4. Adds asset to matching albums
|
|
|
|
### API for Album Sync
|
|
```
|
|
POST /albums/{albumName}/assets
|
|
|
|
Body:
|
|
{
|
|
"assetIds": ["asset-1"]
|
|
}
|
|
```
|
|
|
|
## Album Search
|
|
|
|
### Local Search
|
|
- Filter album list by name
|
|
- Instant results as you type
|
|
|
|
### Quick Filter Chips
|
|
| Filter | Shows |
|
|
|--------|-------|
|
|
| All | All albums |
|
|
| Mine | Albums you created |
|
|
| Shared | Albums shared with you |
|
|
|
|
---
|
|
|
|
[Previous: Search](./search.md) | [Next: Library](./library.md)
|