add docs part 1
This commit is contained in:
355
docs/albums.md
Normal file
355
docs/albums.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user