TTMusic/openspec/changes/playlist-backup/specs/playlist-export-import/spec.md

ADDED Requirements

Requirement: Backup JSON format definition

The system SHALL use a versioned JSON format for playlist backup files. The JSON structure SHALL contain the following top-level fields:

• version (number): Format version, currently 1
• exportTime (string): ISO 8601 timestamp of export
• appVersion (string): Application version at export time
• playlists (array): Array of playlist objects

Each playlist object SHALL contain: id, name, coverPath, description, createTime, updateTime, songCount, sortOrder, and a songs array. Each song entry SHALL contain: songFilePath, addTime, sortOrder.

Scenario: Valid backup file structure

• WHEN a backup file is generated
• THEN the file SHALL be valid JSON containing version, exportTime, appVersion, and playlists fields
• THEN each playlist entry SHALL include its complete metadata and associated songs array

Scenario: Empty playlist database

• WHEN the user has no playlists and triggers an export
• THEN the system SHALL generate a valid JSON file with an empty playlists array

Requirement: Export playlists to JSON file

The system SHALL allow users to export all playlists and their associated songs to a single JSON file saved to local storage. The system SHALL use the system DocumentViewPicker to let the user choose the save location. The exported file name SHALL follow the pattern playlist_backup_YYYYMMDD_HHmmss.json.

Scenario: Successful export to local storage

• WHEN the user triggers playlist export from the backup management UI
• THEN the system SHALL read all playlists and their songs from PlaylistTable
• THEN the system SHALL serialize the data to the defined JSON format
• THEN the system SHALL open a DocumentViewPicker for the user to choose a save location
• THEN the system SHALL write the JSON file to the chosen location
• THEN the system SHALL display a success toast with the file name

Scenario: Export with large dataset

• WHEN the database contains more than 100 playlists
• THEN the system SHALL query playlists in batches to avoid excessive memory usage
• THEN the export SHALL complete successfully without out-of-memory errors

Scenario: Export failure

• WHEN the user cancels the file picker or a write error occurs
• THEN the system SHALL display an error toast describing the failure
• THEN no partial file SHALL be left on disk

Requirement: Import playlists from JSON file

The system SHALL allow users to import playlists from a previously exported JSON backup file. The system SHALL use DocumentViewPicker to let the user select the backup file.

Scenario: Successful import with no conflicts

• WHEN the user selects a valid backup JSON file
• THEN the system SHALL parse and validate the JSON structure and version
• THEN the system SHALL create all playlists and song associations from the backup
• THEN the system SHALL display a success toast with the count of imported playlists

Scenario: Import with version validation

• WHEN the user selects a backup file with an unsupported version number
• THEN the system SHALL display an error message stating the file version is not compatible
• THEN no data SHALL be imported

Scenario: Import with malformed JSON

• WHEN the user selects a file that is not valid JSON or missing required fields
• THEN the system SHALL display an error message indicating the file format is invalid
• THEN no data SHALL be imported

Requirement: Import conflict resolution

When importing playlists, the system SHALL detect name conflicts with existing playlists and present the user with resolution options: "overwrite", "skip", or "rename" (append a numeric suffix).

Scenario: Conflicting playlist name — user chooses overwrite

• WHEN the imported backup contains a playlist with the same name as an existing local playlist
• AND the user selects "overwrite"
• THEN the system SHALL delete the existing playlist and its song associations
• THEN the system SHALL create the playlist from the backup data

Scenario: Conflicting playlist name — user chooses skip

• WHEN the imported backup contains a playlist with the same name as an existing local playlist
• AND the user selects "skip"
• THEN the system SHALL not modify the existing playlist
• THEN the system SHALL proceed to import the remaining playlists

Scenario: Conflicting playlist name — user chooses rename

• WHEN the imported backup contains a playlist with the same name as an existing local playlist
• AND the user selects "rename"
• THEN the system SHALL create the playlist with a suffixed name (e.g., "My Playlist (2)")
• THEN the system SHALL import all associated songs under the renamed playlist

Scenario: Multiple conflicts — apply to all

• WHEN multiple playlists in the backup conflict with existing playlists
• THEN the conflict resolution dialog SHALL provide an "apply to all" checkbox
• THEN choosing "apply to all" SHALL apply the selected resolution strategy to all remaining conflicts

Requirement: Backup management UI entry

The system SHALL provide a "Backup & Restore" entry in the Settings page that navigates to a dedicated backup management interface.

Scenario: Navigate to backup management

• WHEN the user taps "Backup & Restore" in Settings
• THEN the system SHALL navigate to the backup management page
• THEN the page SHALL display options for "Export to File", "Import from File", "Backup to WebDAV", and "Restore from WebDAV"