fix(backend): harden final MVP invariants

backend/internal/logic/files/service.go

@@ -1,24 +1,25 @@
 package files
 
 import (
+	"crypto/rand"
+	"encoding/hex"
 	"errors"
-	"fmt"
 	"io"
 	"os"
 	"path/filepath"
 	"strings"
-	"time"
 
 	"gorm.io/gorm"
 	"senlinai-agent/backend/internal/models"
 )
 
 type Service struct {
-	root       string
-	db         *gorm.DB
-	createTemp func(string, string) (stagedFile, error)
-	rename     func(string, string) error
-	remove     func(string) error
+	root          string
+	db            *gorm.DB
+	createTemp    func(string, string) (stagedFile, error)
+	publish       func(string, string) error
+	remove        func(string) error
+	newStorageKey func() (string, error)
 }
 
 type stagedFile interface {
@@ -29,6 +30,7 @@ type stagedFile interface {
 
 type StoredFile struct {
 	OriginalName string
+	StorageKey   string
 	RelativePath string
 	AbsolutePath string
 }
@@ -41,45 +43,73 @@ func NewService(root string, databases ...*gorm.DB) *Service {
 	}
 	return &Service{
 		root: root, db: database,
-		createTemp: func(directory, pattern string) (stagedFile, error) { return os.CreateTemp(directory, pattern) },
-		rename:     os.Rename,
-		remove:     os.Remove,
+		createTemp:    func(directory, pattern string) (stagedFile, error) { return os.CreateTemp(directory, pattern) },
+		publish:       os.Link,
+		remove:        os.Remove,
+		newStorageKey: randomStorageKey,
 	}
 }
 
-// Save 清理客户端文件名，并只返回供持久化的相对路径；绝对路径不得进入 API DTO。
-func (s *Service) Save(projectID uint, originalName string, content io.Reader) (StoredFile, error) {
+// Save 使用项目公开 identity 和随机 opaque key 定位文件；硬链接发布提供跨请求的排他创建语义。
+func (s *Service) Save(projectIdentity string, originalName string, content io.Reader) (StoredFile, error) {
 	cleanName := filepath.Base(strings.ReplaceAll(strings.TrimSpace(originalName), "\\", "/"))
 	if cleanName == "." || cleanName == "" {
 		cleanName = "upload.bin"
 	}
-	relative := filepath.ToSlash(filepath.Join("projects", fmt.Sprint(projectID), fmt.Sprintf("%d-%s", time.Now().UnixNano(), cleanName)))
-	absolute, err := s.absolutePath(relative)
+	projectSegment := filepath.Base(strings.ReplaceAll(strings.TrimSpace(projectIdentity), "\\", "/"))
+	if projectSegment == "." || projectSegment == "" || projectSegment != strings.TrimSpace(projectIdentity) {
+		return StoredFile{}, ErrSourcePathRequired
+	}
+	directoryRelative := filepath.ToSlash(filepath.Join("projects", projectSegment))
+	directoryAbsolute, err := s.absolutePath(directoryRelative)
 	if err != nil {
 		return StoredFile{}, err
 	}
-	if err := os.MkdirAll(filepath.Dir(absolute), 0o755); err != nil {
+	if err := os.MkdirAll(directoryAbsolute, 0o755); err != nil {
 		return StoredFile{}, err
 	}
-	// 临时文件与最终文件位于同一目录，Close 成功后再原子替换，避免暴露半写入内容。
-	file, err := s.createTemp(filepath.Dir(absolute), ".upload-*")
+	// 临时文件与最终文件位于同一目录，完整关闭后再排他发布，避免暴露半写入内容。
+	file, err := s.createTemp(directoryAbsolute, ".upload-*")
 	if err != nil {
 		return StoredFile{}, err
 	}
 	if _, err := io.Copy(file, content); err != nil {
 		_ = file.Close()
-		s.cleanupFailedSave(file.Name(), absolute)
+		s.cleanupOwnedFiles(file.Name())
 		return StoredFile{}, err
 	}
 	if err := file.Close(); err != nil {
-		s.cleanupFailedSave(file.Name(), absolute)
+		s.cleanupOwnedFiles(file.Name())
 		return StoredFile{}, err
 	}
-	if err := s.rename(file.Name(), absolute); err != nil {
-		s.cleanupFailedSave(file.Name(), absolute)
-		return StoredFile{}, err
+	for attempt := 0; attempt < storageKeyAttempts; attempt++ {
+		storageKey, err := s.newStorageKey()
+		if err != nil {
+			s.cleanupOwnedFiles(file.Name())
+			return StoredFile{}, err
+		}
+		relative := filepath.ToSlash(filepath.Join(directoryRelative, storageKey))
+		absolute, err := s.absolutePath(relative)
+		if err != nil {
+			s.cleanupOwnedFiles(file.Name())
+			return StoredFile{}, err
+		}
+		if err := s.publish(file.Name(), absolute); err != nil {
+			if errors.Is(err, os.ErrExist) {
+				continue
+			}
+			s.cleanupOwnedFiles(file.Name())
+			return StoredFile{}, err
+		}
+		if err := s.remove(file.Name()); err != nil {
+			// final path 由本次排他发布创建，因此这里只清理本次请求拥有的两个路径。
+			s.cleanupOwnedFiles(file.Name(), absolute)
+			return StoredFile{}, err
+		}
+		return StoredFile{OriginalName: cleanName, StorageKey: storageKey, RelativePath: relative, AbsolutePath: absolute}, nil
 	}
-	return StoredFile{OriginalName: cleanName, RelativePath: relative, AbsolutePath: absolute}, nil
+	s.cleanupOwnedFiles(file.Name())
+	return StoredFile{}, ErrStorageKeyCollision
 }
 
 // Remove 只依据 Service 生成的相对路径定位文件，并尽量移除直至存储根目录的空父目录。
@@ -133,9 +163,10 @@ func (s *Service) absolutePath(relativePath string) (string, error) {
 	return absolute, nil
 }
 
-func (s *Service) cleanupFailedSave(tempPath, finalPath string) {
-	_ = s.remove(tempPath)
-	_ = s.remove(finalPath)
+func (s *Service) cleanupOwnedFiles(paths ...string) {
+	for _, path := range paths {
+		_ = s.remove(path)
+	}
 }
 
 func (s *Service) database() *gorm.DB {
@@ -148,8 +179,19 @@ func (s *Service) database() *gorm.DB {
 var (
 	ErrSourceTitleRequired = errors.New("source title is required")
 	ErrSourcePathRequired  = errors.New("source file path is required")
+	ErrStorageKeyCollision = errors.New("unable to allocate unique storage key")
 )
 
+const storageKeyAttempts = 8
+
+func randomStorageKey() (string, error) {
+	buffer := make([]byte, 16)
+	if _, err := rand.Read(buffer); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(buffer), nil
+}
+
 // CreateSource 只持久化 Save 产生的相对路径，不接受 handler 自行拼接本地路径。
 func (s *Service) CreateSource(ownerID uint, project *models.SenlinAgentProject, title string, stored StoredFile) (*models.SenlinAgentSource, error) {
 	title = strings.TrimSpace(title)