TrueGrowth/openspec/specs/backup-restore/spec.md

backup-restore Specification

Purpose

TBD - created by archiving change add-complete-environment-backup-restore. Update Purpose after archive.

Requirements

Requirement: Complete Environment Backup

The system SHALL support a complete backup mode that captures all durable user-facing environment data needed to restore the app to the backed-up state.

Scenario: Complete backup includes durable domains

• GIVEN the user has projects, assets, tasks, workflows, prompts, knowledge base content, chats, playlists, skills, model preferences, and UI preferences
• WHEN the user creates a complete backup
• THEN the backup SHALL include every selected durable domain
• AND the manifest SHALL record v4 schema metadata, selected domains, per-domain stats, and backup mode

Requirement: Replace Restore

The system SHALL support replace restore for complete backups by clearing selected local domains before importing backup data.

Scenario: Replace restore mirrors the backup

• GIVEN the current browser has existing local data
• AND the user selects replace restore for a complete backup
• WHEN restore completes
• THEN selected domains SHALL match the backup content instead of being merged with previous local content
• AND the workspace SHALL reload and restore the backed-up current board when available

Requirement: Encrypted Secrets

The system SHALL export sensitive configuration only when the user explicitly includes secrets and provides a backup password.

Scenario: Secrets require password

• GIVEN settings contain API keys, provider profiles, or sync credentials
• WHEN the user creates a backup without enabling secrets
• THEN sensitive values SHALL NOT be written to normal backup JSON
• WHEN the user enables secrets and provides a password
• THEN sensitive values SHALL be written only to an encrypted secrets payload

Requirement: Full Task and Prompt Fidelity

The system SHALL include full terminal and archived generation history required by prompt history, media library, PPT, audio, and task queue views.

Scenario: Task and prompt data survives restore

• GIVEN completed or archived image, video, audio, PPT, text, and agent tasks exist
• WHEN the user backs up and restores data
• THEN restored task records SHALL be persisted to IndexedDB
• AND prompt preset settings SHALL include all supported prompt types, deleted prompt contents, and prompt overrides

Requirement: Backward Compatibility

The system SHALL continue importing existing v2 and v3 backups.

Scenario: Legacy backups import incrementally

• GIVEN a valid v2 or v3 backup without environment files
• WHEN the user imports it
• THEN existing prompt, project, asset, task, and knowledge base import behavior SHALL continue to work
• AND missing v4 environment data SHALL be reported as skipped, not as a fatal error

Requirement: Shared Backup Restore Core

系统 SHALL 提供一套由主应用与 sw-debug 共用的备份恢复核心逻辑，用于统一备份格式、导出筛选、导入恢复顺序与去重规则。

Scenario: Main App and sw-debug export the same data semantics

• GIVEN 主应用与 sw-debug 访问的是同一份项目、素材、任务、提示词与知识库数据
• WHEN 用户分别从主应用与 sw-debug 执行备份
• THEN 两边都必须产出兼容的 manifest 与 ZIP 目录结构
• AND 音频、任务结果、知识库、项目目录和素材元数据的导出语义必须一致

Scenario: Shared core fixes apply to both environments

• GIVEN 共享备份恢复核心修复了素材命名冲突或音频任务筛选问题
• WHEN 主应用或 sw-debug 执行备份恢复
• THEN 两边都必须同时继承同一修复行为
• AND 不允许再出现仅一端生效、另一端仍保留旧逻辑的情况

Requirement: Environment Adapter Boundary

系统 SHALL 将备份恢复中的环境相关能力限制在适配层，以隔离核心逻辑与平台依赖。

Scenario: Core stays independent from app-specific services

• GIVEN 共享备份恢复核心需要读取或写入数据
• WHEN 核心执行导出或导入
• THEN 核心只能通过适配接口访问项目、素材、任务、提示词、知识库与缓存能力
• AND 核心不得直接依赖主应用 UI、React 状态或 sw-debug DOM 节点

Requirement: Knowledge Base Parity

系统 SHALL 保证主应用与 sw-debug 在共享内核接入后，对知识库备份与恢复采用同一数据结构与导入顺序。

Scenario: Knowledge base backup is available in both environments

• GIVEN 知识库中存在目录、笔记、标签和图片
• WHEN 用户从主应用或 sw-debug 执行备份恢复
• THEN 两边都必须使用同一份知识库序列化结构
• AND 导入后笔记数量、目录映射和标签关联必须保持一致