存储构建块提供文件存储抽象和本地文件系统实现。Files 平台模块在此基础之上构建上传/下载/管理操作。

IFileStorage 端口

public interface IFileStorage
{
    Task<string> SaveAsync(
        Stream stream,
        string contentType,
        string extension,
        CancellationToken ct = default);

    Task<Stream?> ReadAsync(
        string path,
        CancellationToken ct = default);

    Task DeleteAsync(
        string path,
        CancellationToken ct = default);
}

LocalFileStorage

默认实现将文件保存到本地目录：

public class LocalFileStorage : IFileStorage
{
    // 生成唯一路径：{basePath}/{year}/{month}/{guid}.{extension}
    // 返回相对路径存储到数据库
}

配置

{
  "Storage": {
    "BasePath": "./storage/files"
  }
}

文件命名约定

文件按日期组织以防止目录膨胀：

./storage/files/
├── 2026/
│   ├── 06/
│   │   ├── a1b2c3d4.pdf
│   │   ├── e5f6g7h8.png
│   │   └── i9j0k1l2.csv
│   └── 07/
│       └── ...

FileAssetService

Files 平台模块提供更高级别的文件管理：

操作	端点	描述
上传	`POST /api/files`	上传文件及元数据
下载	`GET /api/files/{id}`	按 asset ID 下载
删除	`DELETE /api/files/{id}`	软删除文件资源
列表	`GET /api/files`	分页文件列表

FileAsset 实体

public class FileAssetEntity : TenantSoftDeleteEntityBase
{
    public string FileName { get; set; }
    public string ContentType { get; set; }
    public long FileSizeBytes { get; set; }
    public string StoragePath { get; set; }
    public string? Description { get; set; }
}

模块集成

文件存储与其他模块集成：

Tickets — FileAssetTicketAttachmentAccessService 将文件资源关联到工单
Chat — FileAssetChatAttachmentAccessService 将文件资源关联到聊天消息
Webhooks — Webhook 载荷可引用文件附件

路线图：云存储适配器

计划的云存储实现：

适配器	目标
S3 Storage	AWS S3、MinIO、兼容提供商
Azure Blob	Azure Blob Storage
阿里云 OSS	阿里云对象存储

所有都将实现 IFileStorage — 可通过配置切换。