feat(restore): 恢复到指定目录（文件类型本机恢复 + 确认弹窗输入） (#86)

* feat(restore): 支持恢复到指定目录（文件类型本机恢复）

恢复此前只能覆盖原始源路径。新增「恢复到指定目录」：把文件备份还原到任意目录，
用于测试恢复、迁移、并排恢复而不覆盖现网数据。

- backup.TaskSpec +RestoreTargetPath；FileRunner.Restore 非空时把归档解压到该目录。
- model.RestoreRecord +TargetPath（持久化/审计）。
- RestoreService.Start 增加 targetPath 参数与校验：仅文件类型、需绝对路径、
  远程节点暂不支持（清晰报错）；executeLocally 透传到 spec。
- 恢复触发端点接受可选请求体 {targetPath}（无 body 时恢复到原始路径）。
- 测试：恢复到指定目录后文件落在该目录；相对路径被拒。

* feat(restore): 恢复确认弹窗支持指定恢复目录

文件类型 + 本机恢复时，恢复确认弹窗新增「恢复到指定目录」输入（可选、绝对路径、
留空=原位置），并实时反映在「恢复目标」摘要中；经 startRestoreFromBackup 透传 targetPath。

server/internal/backup/file_runner.go

@@ -185,6 +185,11 @@ func (r *FileRunner) Restore(_ context.Context, task TaskSpec, artifactPath stri
 		restoreSource = task.SourcePaths[0]
 	}
 	targetParent := filepath.Dir(filepath.Clean(strings.TrimSpace(restoreSource)))
+	// 恢复到指定位置：非空时归档解压到用户指定目录，而非原始源父目录。
+	if override := strings.TrimSpace(task.RestoreTargetPath); override != "" {
+		targetParent = filepath.Clean(override)
+		writer.WriteLine(fmt.Sprintf("恢复到指定目录：%s", targetParent))
+	}
 	if err := os.MkdirAll(targetParent, 0o755); err != nil {
 		return fmt.Errorf("create restore parent: %w", err)
 	}

server/internal/backup/types.go

@@ -42,6 +42,9 @@ type TaskSpec struct {
 	BaseManifest Manifest
 	// SelectedPaths 非空时仅恢复这些归档相对路径（及其子项），用于按需（选择性）恢复；仅文件类型生效。
 	SelectedPaths []string
+	// RestoreTargetPath 仅用于恢复：非空时，文件类型恢复将归档解压到该目录，
+	// 而非默认的原始源路径父目录。用于「恢复到指定位置」（迁移/测试/并排恢复）。
+	RestoreTargetPath string
 }
 
 type RunResult struct {

server/internal/http/backup_record_handler.go

@@ -151,11 +151,14 @@ func (h *BackupRecordHandler) Restore(c *gin.Context) {
 	if subject, exists := c.Get(contextUserSubjectKey); exists {
 		triggeredBy = strings.TrimSpace(fmt.Sprintf("%v", subject))
 	}
+	// 可选请求体：selectedPaths 按需（选择性）恢复；targetPath 恢复到指定目录（仅文件类型本机恢复）。
+	// 无 body 时为整体恢复到原始路径。
 	var body struct {
 		SelectedPaths []string `json:"selectedPaths"`
+		TargetPath    string   `json:"targetPath"`
 	}
-	_ = c.ShouldBindJSON(&body) // body 可选：无 body 为整体恢复，含 selectedPaths 为按需恢复
-	detail, err := h.restoreService.StartSelective(c.Request.Context(), id, body.SelectedPaths, triggeredBy)
+	_ = c.ShouldBindJSON(&body)
+	detail, err := h.restoreService.StartSelective(c.Request.Context(), id, body.SelectedPaths, strings.TrimSpace(body.TargetPath), triggeredBy)
 	if err != nil {
 		response.Error(c, err)
 		return

server/internal/model/restore_record.go

@@ -11,21 +11,23 @@ const (
 )
 
 type RestoreRecord struct {
-	ID              uint         `gorm:"primaryKey" json:"id"`
-	BackupRecordID  uint         `gorm:"column:backup_record_id;index;not null" json:"backupRecordId"`
-	BackupRecord    BackupRecord `json:"backupRecord,omitempty"`
-	TaskID          uint         `gorm:"column:task_id;index;not null" json:"taskId"`
-	Task            BackupTask   `json:"task,omitempty"`
-	NodeID          uint         `gorm:"column:node_id;index;default:0" json:"nodeId"`
-	Status          string       `gorm:"size:20;index;not null" json:"status"`
-	ErrorMessage    string       `gorm:"column:error_message;size:2000" json:"errorMessage"`
-	LogContent      string       `gorm:"column:log_content;type:text" json:"logContent"`
-	DurationSeconds int          `gorm:"column:duration_seconds;not null;default:0" json:"durationSeconds"`
-	StartedAt       time.Time    `gorm:"column:started_at;index;not null" json:"startedAt"`
-	CompletedAt     *time.Time   `gorm:"column:completed_at;index" json:"completedAt,omitempty"`
-	TriggeredBy     string       `gorm:"column:triggered_by;size:100" json:"triggeredBy"`
-	CreatedAt       time.Time    `json:"createdAt"`
-	UpdatedAt       time.Time    `json:"updatedAt"`
+	ID             uint         `gorm:"primaryKey" json:"id"`
+	BackupRecordID uint         `gorm:"column:backup_record_id;index;not null" json:"backupRecordId"`
+	BackupRecord   BackupRecord `json:"backupRecord,omitempty"`
+	TaskID         uint         `gorm:"column:task_id;index;not null" json:"taskId"`
+	Task           BackupTask   `json:"task,omitempty"`
+	NodeID         uint         `gorm:"column:node_id;index;default:0" json:"nodeId"`
+	// TargetPath 恢复到指定目录（仅文件类型本机恢复）；空 = 恢复到原始源路径。
+	TargetPath      string     `gorm:"column:target_path;size:500" json:"targetPath"`
+	Status          string     `gorm:"size:20;index;not null" json:"status"`
+	ErrorMessage    string     `gorm:"column:error_message;size:2000" json:"errorMessage"`
+	LogContent      string     `gorm:"column:log_content;type:text" json:"logContent"`
+	DurationSeconds int        `gorm:"column:duration_seconds;not null;default:0" json:"durationSeconds"`
+	StartedAt       time.Time  `gorm:"column:started_at;index;not null" json:"startedAt"`
+	CompletedAt     *time.Time `gorm:"column:completed_at;index" json:"completedAt,omitempty"`
+	TriggeredBy     string     `gorm:"column:triggered_by;size:100" json:"triggeredBy"`
+	CreatedAt       time.Time  `json:"createdAt"`
+	UpdatedAt       time.Time  `json:"updatedAt"`
 }
 
 func (RestoreRecord) TableName() string {

server/internal/service/restore_service.go

@@ -120,11 +120,13 @@ type RestoreRecordDetail struct {
 // 若任务绑定远程节点：入队 AgentCommand 后立即返回（状态为 running）
 // 若本地：异步执行并立即返回。
 func (s *RestoreService) Start(ctx context.Context, backupRecordID uint, triggeredBy string) (*RestoreRecordDetail, error) {
-	return s.StartSelective(ctx, backupRecordID, nil, triggeredBy)
+	return s.StartSelective(ctx, backupRecordID, nil, "", triggeredBy)
 }
 
-// StartSelective 启动恢复；selectedPaths 非空时仅恢复选中的文件/目录（按需恢复，仅本机文件备份）。
-func (s *RestoreService) StartSelective(ctx context.Context, backupRecordID uint, selectedPaths []string, triggeredBy string) (*RestoreRecordDetail, error) {
+// StartSelective 启动恢复。两个可选项均仅适用于本机文件备份：
+//   - selectedPaths 非空时仅恢复选中的文件/目录（及其子项），用于按需（选择性）恢复；
+//   - targetPath 非空时把归档恢复到该绝对目录而非原始源路径父目录（迁移/测试/并排恢复）。
+func (s *RestoreService) StartSelective(ctx context.Context, backupRecordID uint, selectedPaths []string, targetPath string, triggeredBy string) (*RestoreRecordDetail, error) {
 	record, err := s.records.FindByID(ctx, backupRecordID)
 	if err != nil {
 		return nil, apperror.Internal("BACKUP_RECORD_GET_FAILED", "无法获取备份记录", err)
@@ -153,10 +155,26 @@ func (s *RestoreService) StartSelective(ctx context.Context, backupRecordID uint
 
 	startedAt := s.now()
 	restoreNodeID := s.resolveRestoreNodeID(record, task)
+
+	// 恢复到指定目录：仅文件类型 + 本机执行支持；需为绝对路径。
+	targetPath = strings.TrimSpace(targetPath)
+	if targetPath != "" {
+		if task.Type != model.BackupTaskTypeFile {
+			return nil, apperror.BadRequest("RESTORE_TARGET_UNSUPPORTED", "仅文件类型备份支持恢复到指定目录", nil)
+		}
+		if !filepath.IsAbs(targetPath) {
+			return nil, apperror.BadRequest("RESTORE_TARGET_INVALID", "恢复目录必须是绝对路径", nil)
+		}
+		if s.isRemoteNode(ctx, restoreNodeID) {
+			return nil, apperror.BadRequest("RESTORE_TARGET_REMOTE_UNSUPPORTED", "远程节点恢复暂不支持指定目录，请在该节点本地操作", nil)
+		}
+	}
+
 	restore := &model.RestoreRecord{
 		BackupRecordID: backupRecordID,
 		TaskID:         record.TaskID,
 		NodeID:         restoreNodeID,
+		TargetPath:     targetPath,
 		Status:         model.RestoreRecordStatusRunning,
 		StartedAt:      startedAt,
 		TriggeredBy:    strings.TrimSpace(triggeredBy),
@@ -191,7 +209,7 @@ func (s *RestoreService) StartSelective(ctx context.Context, backupRecordID uint
 
 	// 本地节点：异步执行
 	run := func() {
-		s.executeLocally(context.Background(), restore.ID, task, record, selectedPaths)
+		s.executeLocally(context.Background(), restore.ID, task, record, selectedPaths, targetPath)
 	}
 	s.async(run)
 	return s.getDetail(ctx, restore.ID)
@@ -218,7 +236,7 @@ func (s *RestoreService) resolveRemoteNode(ctx context.Context, nodeID uint) *mo
 }
 
 // executeLocally 在 Master 本地执行恢复。
-func (s *RestoreService) executeLocally(ctx context.Context, restoreID uint, task *model.BackupTask, backupRecord *model.BackupRecord, selectedPaths []string) {
+func (s *RestoreService) executeLocally(ctx context.Context, restoreID uint, task *model.BackupTask, backupRecord *model.BackupRecord, selectedPaths []string, targetPath string) {
 	s.semaphore <- struct{}{}
 	defer func() { <-s.semaphore }()
 
@@ -247,6 +265,12 @@ func (s *RestoreService) executeLocally(ctx context.Context, restoreID uint, tas
 		spec.SelectedPaths = selectedPaths
 		logger.Infof("按需恢复：仅恢复选中的 %d 个路径", len(selectedPaths))
 	}
+	// 恢复到指定目录（已在 StartSelective 校验为文件类型+绝对路径+本机）；
+	// 应用于恢复链中的每个归档（全量铺底与差异覆盖均落到该目录）。
+	if targetPath != "" {
+		spec.RestoreTargetPath = targetPath
+		logger.Infof("恢复到指定目录：%s", targetPath)
+	}
 	runner, runnerErr := s.runnerRegistry.Runner(spec.Type)
 	if runnerErr != nil {
 		errMessage = runnerErr.Error()

server/internal/service/restore_service_test.go

@@ -269,6 +269,61 @@ func TestRestoreServiceStart_RejectsCorruptedBackup(t *testing.T) {
 	}
 }
 
+// TestRestoreServiceStart_RestoresToAlternatePath 验证恢复到指定目录：归档落在指定目录，
+// 且相对路径被拒绝。
+func TestRestoreServiceStart_RestoresToAlternatePath(t *testing.T) {
+	h := newRestoreTestHarness(t, false)
+	ctx := context.Background()
+
+	backupDetail, err := h.execution.RunTaskByIDSync(ctx, 1)
+	if err != nil {
+		t.Fatalf("RunTaskByIDSync: %v", err)
+	}
+	if backupDetail.Status != "success" {
+		t.Fatalf("expected backup success, got %s", backupDetail.Status)
+	}
+
+	altDir := filepath.Join(t.TempDir(), "restore-here")
+
+	// 相对路径应被拒绝（且不创建恢复记录）。
+	if _, relErr := h.service.StartSelective(ctx, backupDetail.ID, nil, "relative/path", "tester"); relErr == nil {
+		t.Fatal("relative target path should be rejected")
+	}
+
+	done := make(chan struct{})
+	h.service.async = func(job func()) {
+		go func() {
+			job()
+			close(done)
+		}()
+	}
+	detail, err := h.service.StartSelective(ctx, backupDetail.ID, nil, altDir, "tester")
+	if err != nil {
+		t.Fatalf("StartSelective(altDir): %v", err)
+	}
+	select {
+	case <-done:
+	case <-time.After(15 * time.Second):
+		t.Fatal("restore did not complete in time")
+	}
+
+	final, err := h.service.Get(ctx, detail.ID)
+	if err != nil {
+		t.Fatalf("Get: %v", err)
+	}
+	if final.Status != model.RestoreRecordStatusSuccess {
+		t.Fatalf("expected success, got %s (err=%s)", final.Status, final.ErrorMessage)
+	}
+	// 源目录 basename 为 "source"，归档解压到 altDir/source/index.html。
+	got, err := os.ReadFile(filepath.Join(altDir, "source", "index.html"))
+	if err != nil {
+		t.Fatalf("read restored file at alternate path: %v", err)
+	}
+	if string(got) != "hello-restore" {
+		t.Fatalf("unexpected restored content at alt path: %q", string(got))
+	}
+}
+
 func TestRestoreServiceStart_RemoteNodeEnqueuesCommand(t *testing.T) {
 	h := newRestoreTestHarness(t, true)
 	ctx := context.Background()