TTMusic/openspec/changes/playlist-backup/specs/playlist-remote-backup/spec.md

ADDED Requirements

Requirement: Upload backup to WebDAV

The system SHALL allow users to upload a playlist backup JSON file to a selected WebDAV account. The backup file SHALL be stored at the path /TTMusic/backups/ on the WebDAV server. The system SHALL create the directory if it does not exist.

Scenario: Successful WebDAV backup upload

• WHEN the user triggers "Backup to WebDAV" and selects a WebDAV account
• THEN the system SHALL generate a backup JSON from the current playlist database
• THEN the system SHALL create the /TTMusic/backups/ directory on the WebDAV server if absent
• THEN the system SHALL upload the file with name playlist_backup_YYYYMMDD_HHmmss.json
• THEN the system SHALL display a success toast with the backup file name

Scenario: WebDAV account selection

• WHEN the user triggers "Backup to WebDAV"
• AND multiple WebDAV accounts are configured
• THEN the system SHALL present a picker dialog listing only WebDAV-type accounts
• THEN the user SHALL select the target account before upload proceeds

Scenario: No WebDAV account configured

• WHEN the user triggers "Backup to WebDAV"
• AND no WebDAV accounts are configured
• THEN the system SHALL display a message prompting the user to add a WebDAV account first

Scenario: WebDAV upload failure

• WHEN a network error or authentication failure occurs during upload
• THEN the system SHALL display an error toast with the failure reason
• THEN no incomplete file SHALL remain on the server

Requirement: Download and restore backup from WebDAV

The system SHALL allow users to browse and download backup files from a WebDAV account's /TTMusic/backups/ directory and restore playlists from the selected file.

Scenario: Successful WebDAV restore

• WHEN the user triggers "Restore from WebDAV" and selects a WebDAV account
• THEN the system SHALL list all .json files in the /TTMusic/backups/ directory
• THEN the user SHALL select a backup file from the list
• THEN the system SHALL download and parse the file
• THEN the system SHALL import the playlists using the same conflict resolution logic as local import

Scenario: No backups found on WebDAV

• WHEN the /TTMusic/backups/ directory is empty or does not exist on the WebDAV server
• THEN the system SHALL display a message indicating no backups were found

Scenario: WebDAV download failure

• WHEN a network error occurs during backup file download
• THEN the system SHALL display an error toast with the failure reason
• THEN no data SHALL be imported

Requirement: Server auto-backup for VIP users

The system SHALL provide VIP users with automatic server backup functionality. When enabled, the system SHALL upload the playlist backup to the server API after playlist changes, using a 5-minute debounce window to merge consecutive changes into a single upload.

Scenario: VIP user enables auto-backup

• WHEN a VIP user toggles the auto-backup switch ON in backup settings
• THEN the system SHALL persist the preference
• THEN the system SHALL begin monitoring playlist changes (create, delete, update, add/remove songs)

Scenario: Auto-backup triggered by playlist change

• WHEN auto-backup is enabled and a playlist change occurs
• THEN the system SHALL start a 5-minute debounce timer
• WHEN additional changes occur within the 5-minute window
• THEN the system SHALL reset the timer
• WHEN the timer expires with no further changes
• THEN the system SHALL generate a backup JSON and upload it to POST /backup/playlist/upload with the user's token

Scenario: Non-VIP user attempts to enable auto-backup

• WHEN a non-VIP user attempts to toggle the auto-backup switch
• THEN the system SHALL display a prompt directing the user to the VIP subscription page
• THEN the auto-backup switch SHALL remain OFF

Scenario: VIP subscription expires while auto-backup is enabled

• WHEN a user's VIP subscription expires
• THEN the system SHALL disable auto-backup
• THEN the system SHALL display a notification informing the user that auto-backup has been disabled

Requirement: Restore from server backup

The system SHALL allow VIP users to download and restore their latest server backup or select from backup history.

Scenario: VIP user restores latest server backup

• WHEN a VIP user triggers "Restore from Server"
• THEN the system SHALL call GET /backup/playlist/list to retrieve backup history
• THEN the system SHALL display the list of available backups with timestamps
• THEN the user SHALL select a backup to restore
• THEN the system SHALL call GET /backup/playlist/download with the selected backup identifier
• THEN the system SHALL import playlists using the standard conflict resolution logic

Scenario: No server backups available

• WHEN a VIP user triggers "Restore from Server"
• AND no backups exist on the server
• THEN the system SHALL display a message indicating no server backups are available

Scenario: Non-VIP user attempts server restore

• WHEN a non-VIP user attempts to access "Restore from Server"
• THEN the system SHALL display a prompt directing the user to the VIP subscription page

Requirement: Server backup upload with authentication

All server backup API requests SHALL include the user's userToken for authentication. The system SHALL handle token expiry or invalid token responses by prompting the user to re-login.

Scenario: Successful authenticated upload

• WHEN the system uploads a backup to the server
• THEN the request SHALL include the userToken in the request parameters
• THEN the server SHALL respond with a success confirmation

Scenario: Token expired during upload

• WHEN the server returns an authentication error (invalid or expired token)
• THEN the system SHALL display a message prompting the user to re-login
• THEN the auto-backup timer SHALL be paused until the user re-authenticates

Requirement: Backup history display

The backup management page SHALL display a history of recent backups, showing the backup source (local/WebDAV/server), timestamp, and playlist count for each entry.

Scenario: View backup history

• WHEN the user opens the backup management page
• THEN the system SHALL display a list of recent backup operations
• THEN each entry SHALL show: backup type icon (local/WebDAV/server), date and time, and number of playlists in the backup

Scenario: Empty backup history

• WHEN the user has never performed a backup
• THEN the system SHALL display a placeholder message encouraging the user to create their first backup