Initial TrueGrowth source import

openspec/specs/backup-restore/spec.md

@@ -0,0 +1,85 @@
+# 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** 导入后笔记数量、目录映射和标签关联必须保持一致
+