// Package storage 抽象附件二进制存储。MVP 默认 LocalFS；后续可加 S3。
package storage

import (
	"context"
	"io"
)

// PutResult 由 Put 返回，便于调用方一次拿到 path + sha256 + 实际写入字节数。
type PutResult struct {
	StoragePath string
	SHA256      string
	Size        int64
}

// Storage 是后端无关的存储接口。
type Storage interface {
	// Put 将 r 流式写入存储，返回相对 path、sha256 和实际字节数。
	// key 由调用方指定（例如 "yyyy/mm/<uuid>.<ext>"）；实现层校验并放入 base 之下。
	Put(ctx context.Context, key string, r io.Reader, mimeType string) (PutResult, error)

	// Get 返回 storagePath 对应的 ReadCloser。调用方负责关闭。
	Get(ctx context.Context, storagePath string) (io.ReadCloser, error)

	// Delete 删除文件。文件不存在视为成功（幂等）。
	Delete(ctx context.Context, storagePath string) error
}