Files 上传会话与客户端直传

POST /api/files/upload-session HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9
Content-Type: application/json

{
  "ownerType": "user",
  "fileName": "invoice-2026-07.pdf",
  "contentType": "application/pdf",
  "size": 48231,
  "visibility": "private"
}

{
  "fileId": "019c64e67fc87db8b7ca748f5442f91a",
  "storageKey": "tenants/tenant-a/019c64e67fc87db8b7ca748f5442f91a",
  "presignedUrl": "https://storage.example/presigned-put-token"
}

public async Task<string> UploadInvoiceAsync(
    HttpClient api,
    HttpClient objectStorage,
    byte[] pdf,
    CancellationToken cancellationToken)
{
    // Files 只接收元数据。TenantId 与 OwnerId 来自 Bearer 身份。
    using var createResponse = await api.PostAsJsonAsync(
        "/api/files/upload-session",
        new
        {
            ownerType = "user",
            fileName = "invoice-2026-07.pdf",
            contentType = "application/pdf",
            size = pdf.LongLength,
            visibility = "private"
        },
        cancellationToken);

    createResponse.EnsureSuccessStatusCode();
    var session = await createResponse.Content
        .ReadFromJsonAsync<UploadSessionDto>(cancellationToken);

    // 预签名 URL 自带对象存储授权；不要把 API Bearer Token 转发给存储服务。
    using var put = new HttpRequestMessage(HttpMethod.Put, session!.PresignedUrl)
    {
        Content = new ByteArrayContent(pdf)
    };
    put.Content.Headers.ContentType = new("application/pdf");

    using var uploadResponse = await objectStorage.SendAsync(put, cancellationToken);
    uploadResponse.EnsureSuccessStatusCode();

    // 这里只返回 FileId。业务绑定必须等 finalize 成功。
    return session.FileId;
}

public sealed record UploadSessionDto(
    string FileId,
    string StorageKey,
    string PresignedUrl);

type UploadSession = {
  fileId: string;
  storageKey: string;
  presignedUrl: string;
};

export async function createAndPut(file: File): Promise<UploadSession> {
  // 会话请求只携带非可信元数据；认证上下文由 Cookie/Bearer 建立。
  const sessionResponse = await fetch("/api/files/upload-session", {
    method: "POST",
    credentials: "include",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      ownerType: "user",
      fileName: file.name,
      contentType: file.type || "application/octet-stream",
      size: file.size,
      visibility: "private",
    }),
  });

  if (!sessionResponse.ok)
    throw new Error(`create session failed: ${sessionResponse.status}`);

  const session = (await sessionResponse.json()) as UploadSession;
  // PUT 只发送对象存储允许的头，不把应用认证信息转发给预签名地址。
  const uploadResponse = await fetch(session.presignedUrl, {
    method: "PUT",
    headers: { "content-type": file.type || "application/octet-stream" },
    body: file,
  });

  // PUT 失败时不要 finalize；重新创建会话比重用未知过期 URL 更安全。
  if (!uploadResponse.ok)
    throw new Error(`object upload failed: ${uploadResponse.status}`);

  return session;
}

public sealed record FileUploadIntent(
    string TenantId,
    string SubjectId,
    string OwnerType,
    string FileName,
    string DeclaredContentType,
    long DeclaredSize);

public interface IFileUploadAdmissionPolicy
{
    // 返回批准后的规范 MIME、最大字节数与必须提供的 checksum 算法。
    // 策略失败必须发生在签发 URL 之前，避免产生未登记的存储能力。
    Task<Result<ApprovedUpload>> AuthorizeAsync(
        FileUploadIntent intent,
        CancellationToken cancellationToken);
}

public sealed record ApprovedUpload(
    string ContentType,
    long MaximumBytes,
    string ChecksumAlgorithm);