## 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"