media

type ErrContentMismatch struct {
	Ext      string
	Declared string
	Detected string
}

type ErrUnsupportedType struct{ Ext string }

type Filter struct {
	// Kind 非空时只返回该分类的附件。
	Kind Kind
	// UploaderID 非零时只返回该用户上传的附件。
	UploaderID int64
	// Q 非空时按原始文件名模糊筛选。
	Q string
}

type Handler struct {
	// contains filtered or unexported fields
}

type ImageInfo struct {
	Width  int
	Height int
}

type ImageProcessor interface {
	// Name 返回实现名，写入启动日志便于排查。
	Name() string
	// Process 解码图片（含 EXIF 方向纠正）并按 specs 生成缩略图。
	//
	// 返回的尺寸是**纠正方向之后**的，与缩略图和前台布局一致。
	Process(data []byte, specs []ThumbnailSpec) (ImageInfo, []Variant, error)
}

type Kind string

type LocalStorage struct {
	// contains filtered or unexported fields
}

type Media struct {
	bun.BaseModel `bun:"table:media,alias:m"`

	ID           int64       `bun:"id,pk,autoincrement" json:"id"`
	Filename     string      `bun:"filename,notnull"    json:"filename" doc:"存储用的随机化文件名"`
	OriginalName string      `bun:"original_name"       json:"originalName" doc:"上传时的原始文件名，仅作展示"`
	MIME         string      `bun:"mime,notnull"        json:"mime"`
	Kind         Kind        `bun:"kind,notnull"        json:"kind" enum:"image,video,audio,document,other"`
	Size         int64       `bun:"size"                json:"size" doc:"字节数"`
	Width        int         `bun:"width"               json:"width" doc:"图片宽度；非图片为 0"`
	Height       int         `bun:"height"              json:"height" doc:"图片高度；非图片为 0"`
	Driver       string      `bun:"driver,notnull"      json:"driver" doc:"写入时使用的存储驱动"`
	StorageKey   string      `bun:"storage_key,notnull" json:"storageKey" doc:"存储内的对象键"`
	URL          string      `bun:"url"                 json:"url" doc:"公开访问地址"`
	Thumbnails   []Thumbnail `bun:"thumbnails,type:jsonb" json:"thumbnails" doc:"按最长边生成的多档 WebP 缩略图"`
	Checksum     string      `bun:"checksum"            json:"checksum" doc:"原文件的 SHA-256"`
	UploaderID   int64       `bun:"uploader_id,notnull" json:"uploaderId"`
	Alt          string      `bun:"alt"                 json:"alt" doc:"无障碍替代文本"`
	Title        string      `bun:"title"               json:"title" doc:"标题"`
	CreatedAt    time.Time   `bun:"created_at,nullzero" json:"createdAt"`
	UpdatedAt    time.Time   `bun:"updated_at,nullzero" json:"updatedAt"`

	// Uploader 由存储层按需填充，不是数据库列。
	Uploader *UploaderView `bun:"-" json:"uploader,omitempty"`
}

type Module struct {
	// contains filtered or unexported fields
}

type S3Config struct {
	// Endpoint 是服务地址，可带协议（https://minio.example.com）也可只写 host:port。
	Endpoint string
	Bucket   string
	Region   string
	// PathStyle 为真时用 endpoint/bucket/key 形式寻址。自建 MinIO、Ceph 一般需要它；
	// 各家兼容程度不一，故不做自动探测，交由部署者显式指定。
	PathStyle bool
	UseSSL    bool
	// PublicURL 是对象的公开访问前缀（如 CDN 域名）；留空则由 endpoint 与 bucket 推导。
	PublicURL string
}

type S3Storage struct {
	// contains filtered or unexported fields
}

type Service struct {
	// contains filtered or unexported fields
}

type ServiceOptions struct {
	Store *Store
	// Settings 可为 nil：此时一律使用本地存储的默认配置。
	Settings *settings.Service
	// Images 可为 nil：缺省用纯 Go 实现。
	Images ImageProcessor
	// DataDir 是工作目录，本地存储写在它的 uploads 子目录下。
	DataDir string
	Logger  *slog.Logger
	// MaxUpload 是单个文件的字节上限，0 表示不额外限制（仍受路由层请求体上限约束）。
	MaxUpload int64
}

type Storage interface {
	// Driver 返回驱动名，随附件记录入库。
	Driver() string
	// Put 写入对象；size 为负表示长度未知。同名对象存在时覆盖。
	Put(ctx context.Context, key string, r io.Reader, size int64, contentType string) error
	// Delete 删除对象；对象不存在不算错误。
	Delete(ctx context.Context, key string) error
	// URL 返回对象的公开访问地址。
	URL(key string) string
}

type StorageSettings struct {
	Driver      string `json:"driver"`
	S3Endpoint  string `json:"s3Endpoint"`
	S3Bucket    string `json:"s3Bucket"`
	S3AccessKey string `json:"s3AccessKey"`
	S3SecretKey string `json:"s3SecretKey"`
	S3Region    string `json:"s3Region"`
	S3PathStyle bool   `json:"s3PathStyle"`
	S3UseSSL    bool   `json:"s3UseSsl"`
	S3PublicURL string `json:"s3PublicUrl"`
}

type Store struct {
	// contains filtered or unexported fields
}

type Thumbnail struct {
	Name   string `json:"name" doc:"档位名，如 thumb / medium / large"`
	Key    string `json:"key" doc:"存储内的对象键"`
	URL    string `json:"url" doc:"公开访问地址"`
	Width  int    `json:"width"`
	Height int    `json:"height"`
	Size   int64  `json:"size" doc:"字节数"`
}

type ThumbnailSpec struct {
	// Name 是档位名，写入缩略图记录并出现在文件名里。
	Name string
	// MaxEdge 是缩放后最长边的像素上限。
	MaxEdge int
}

type UploadParams struct {
	// OriginalName 是客户端给出的文件名，只用于取扩展名与展示，绝不参与路径拼接。
	OriginalName string
	// Size 是内容字节数的客户端声明值：用于超限预判与 S3 分片决策，落库以实际读到的字节数为准。
	Size    int64
	Content io.Reader
	Alt     string
	Title   string
	// UploaderID 是上传者的用户 ID。
	UploaderID int64
}

type UploaderView struct {
	ID          int64  `json:"id"`
	Username    string `json:"username"`
	DisplayName string `json:"displayName"`
	AvatarURL   string `json:"avatarUrl"`
}

type Variant struct {
	Name   string
	Width  int
	Height int
	// Ext 是编码格式对应的扩展名，如 .webp。
	Ext string
	// MIME 是编码格式的媒体类型。
	MIME string
	Data []byte
}