[CLAUDE] App+Infra+Api+FE: Attachment upload E2E

Foundation file-storage:
- IFileStorage interface (Application) — SaveAsync/OpenReadAsync/
  DeleteAsync/Exists. Future swap cho S3/Azure Blob không đổi caller.
- LocalFileStorage (Infrastructure) — resolve Uploads:RootPath từ
  config, path-traversal guard (resolved full path phải stay in root),
  tự tạo directory khi save.
- DI: singleton (stateless).
- Config: dev "uploads", prod "C:\inetpub\solution-erp\uploads".

CQRS:
- UploadContractAttachmentCommand: validate size <=20MB + MIME whitelist
  (pdf, doc/docx, xls/xlsx, png/jpg/jpeg/webp). Sanitize filename
  (strip path components + invalid FS chars + leading dots). Storage
  path: contracts/{contractId}/{attId}_{safeFileName}.
- DownloadContractAttachmentQuery: trả Stream + FileName + ContentType.
- DeleteContractAttachmentCommand: best-effort file delete sau DB remove
  (orphan cleanup job có thể sweep sau).

Api:
- POST /api/contracts/{id}/attachments — multipart/form-data, field
  'file' + form fields 'purpose' + 'note'. RequestSizeLimit 25MB
  (validator enforces 20MB).
- GET /api/contracts/{id}/attachments/{attId}/download — File() stream.
- DELETE /api/contracts/{id}/attachments/{attId}.

FE ContractAttachmentsSection (both apps, identical):
- Drag-drop zone với dragging highlight (brand-500 border + brand-50 bg)
- Purpose selector (DraftExport / ScannedSigned / SealedCopy / Other)
- List có icon per MIME (FileText/Image/File), filename, metadata
  (purpose · size · createdAt), download button (fetch blob + trigger
  browser save với auth header), delete button (confirm dialog)
- Empty state hint về use-case ("bản scan HĐ đã ký ở phase In ký…")

Integrated vào cả 2 ContractDetailPage — ngay dưới phần comments,
trước sidebar lịch sử duyệt.

Unblock E2E workflow: users giờ có thể upload bản scan ký (DangInKy),
scan đóng dấu (DangDongDau) — phase transitions có bằng chứng thật.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/Backend/SolutionErp.Api/Controllers/ContractsController.cs

@@ -66,6 +66,41 @@ public class ContractsController(IMediator mediator) : ControllerBase
         await mediator.Send(new DeleteContractCommand(id), ct);
         return NoContent();
     }
+
+    // ==================== Attachments ====================
+
+    // Multipart upload: file + purpose + optional note
+    [HttpPost("{id:guid}/attachments")]
+    [RequestSizeLimit(25_000_000)] // ~24 MB ceiling (validator enforces 20 MB)
+    public async Task<ActionResult<ContractAttachmentDto>> UploadAttachment(
+        Guid id,
+        IFormFile file,
+        [FromForm] AttachmentPurpose purpose = AttachmentPurpose.Other,
+        [FromForm] string? note = null,
+        CancellationToken ct = default)
+    {
+        if (file is null || file.Length == 0)
+            return BadRequest(new { detail = "Chưa chọn file." });
+
+        await using var stream = file.OpenReadStream();
+        var dto = await mediator.Send(new UploadContractAttachmentCommand(
+            id, file.FileName, file.ContentType, file.Length, stream, purpose, note), ct);
+        return Ok(dto);
+    }
+
+    [HttpGet("{id:guid}/attachments/{attId:guid}/download")]
+    public async Task<IActionResult> DownloadAttachment(Guid id, Guid attId, CancellationToken ct)
+    {
+        var file = await mediator.Send(new DownloadContractAttachmentQuery(id, attId), ct);
+        return File(file.Content, file.ContentType, file.FileName);
+    }
+
+    [HttpDelete("{id:guid}/attachments/{attId:guid}")]
+    public async Task<IActionResult> DeleteAttachment(Guid id, Guid attId, CancellationToken ct)
+    {
+        await mediator.Send(new DeleteContractAttachmentCommand(id, attId), ct);
+        return NoContent();
+    }
 }
 
 public record TransitionContractBody(ContractPhase TargetPhase, ApprovalDecision Decision, string? Comment);

src/Backend/SolutionErp.Api/appsettings.Production.json.example

@@ -50,5 +50,8 @@
   "RateLimit": {
     "AuthLoginPerMinute": 5,
     "GlobalPerMinute": 300
+  },
+  "Uploads": {
+    "RootPath": "C:\\inetpub\\solution-erp\\uploads"
   }
 }

src/Backend/SolutionErp.Api/appsettings.json

@@ -26,5 +26,8 @@
   "RateLimit": {
     "AuthLoginPerMinute": 5,
     "GlobalPerMinute": 300
+  },
+  "Uploads": {
+    "RootPath": "uploads"
   }
 }

src/Backend/SolutionErp.Application/Common/Interfaces/IFileStorage.cs

@@ -0,0 +1,18 @@
+namespace SolutionErp.Application.Common.Interfaces;
+
+// Abstraction over file storage. LocalFileStorage (Infrastructure) writes to
+// a configured root path today; future: S3/AzureBlob by swapping impl.
+public interface IFileStorage
+{
+    // Saves stream to relative path under root. Returns normalized relative path.
+    Task<string> SaveAsync(string relativePath, Stream content, CancellationToken ct = default);
+
+    // Opens a readable stream for downloading. Caller must dispose.
+    Task<Stream> OpenReadAsync(string relativePath, CancellationToken ct = default);
+
+    // Deletes a file if it exists. No-op if missing.
+    Task DeleteAsync(string relativePath, CancellationToken ct = default);
+
+    // True if file exists at relative path.
+    bool Exists(string relativePath);
+}

src/Backend/SolutionErp.Application/Contracts/ContractAttachmentFeatures.cs

@@ -0,0 +1,147 @@
+using FluentValidation;
+using MediatR;
+using Microsoft.EntityFrameworkCore;
+using SolutionErp.Application.Common.Exceptions;
+using SolutionErp.Application.Common.Interfaces;
+using SolutionErp.Application.Contracts.Dtos;
+using SolutionErp.Domain.Contracts;
+
+namespace SolutionErp.Application.Contracts;
+
+// ========== UPLOAD ==========
+// File payload is decoupled from the command so MediatR-style CQRS works with
+// multipart/form-data: the controller reads IFormFile, hands the Application
+// layer a bare Stream + metadata. Keeps Application free of ASP.NET types.
+
+public record UploadContractAttachmentCommand(
+    Guid ContractId,
+    string FileName,
+    string ContentType,
+    long FileSize,
+    Stream Content,
+    AttachmentPurpose Purpose,
+    string? Note) : IRequest<ContractAttachmentDto>;
+
+public class UploadContractAttachmentCommandValidator : AbstractValidator<UploadContractAttachmentCommand>
+{
+    // 20 MB default — configurable later via Uploads:MaxFileSize if needed
+    private const long MaxBytes = 20L * 1024 * 1024;
+
+    // MIME whitelist — contract scans (pdf/image) + editable sources (word/excel)
+    private static readonly HashSet<string> AllowedContentTypes = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document", // .docx
+        "application/msword",                                                      // .doc
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",       // .xlsx
+        "application/vnd.ms-excel",                                                // .xls
+        "image/png",
+        "image/jpeg",
+        "image/webp",
+    };
+
+    public UploadContractAttachmentCommandValidator()
+    {
+        RuleFor(x => x.ContractId).NotEmpty();
+        RuleFor(x => x.FileName).NotEmpty().MaximumLength(255);
+        RuleFor(x => x.FileSize).GreaterThan(0).LessThanOrEqualTo(MaxBytes)
+            .WithMessage("File vượt quá 20 MB.");
+        RuleFor(x => x.ContentType).Must(c => AllowedContentTypes.Contains(c))
+            .WithMessage("Định dạng file không được hỗ trợ. Cho phép: pdf, doc(x), xls(x), png, jpg, webp.");
+        RuleFor(x => x.Purpose).IsInEnum();
+        RuleFor(x => x.Note).MaximumLength(500);
+    }
+}
+
+public class UploadContractAttachmentCommandHandler(
+    IApplicationDbContext db,
+    IFileStorage storage) : IRequestHandler<UploadContractAttachmentCommand, ContractAttachmentDto>
+{
+    public async Task<ContractAttachmentDto> Handle(UploadContractAttachmentCommand request, CancellationToken ct)
+    {
+        var contract = await db.Contracts.FirstOrDefaultAsync(c => c.Id == request.ContractId, ct)
+            ?? throw new NotFoundException("Contract", request.ContractId);
+
+        var attId = Guid.NewGuid();
+        var safeName = SanitizeFileName(request.FileName);
+        // Store under contracts/{contractId}/{attId}_{safeName} to keep originals separate
+        var relativePath = $"contracts/{contract.Id}/{attId}_{safeName}";
+
+        await storage.SaveAsync(relativePath, request.Content, ct);
+
+        var entity = new ContractAttachment
+        {
+            Id = attId,
+            ContractId = contract.Id,
+            FileName = request.FileName, // keep original for display
+            StoragePath = relativePath,
+            FileSize = request.FileSize,
+            ContentType = request.ContentType,
+            Purpose = request.Purpose,
+            Note = request.Note,
+        };
+        db.ContractAttachments.Add(entity);
+        await db.SaveChangesAsync(ct);
+
+        return new ContractAttachmentDto(
+            entity.Id, entity.FileName, entity.StoragePath, entity.FileSize,
+            entity.ContentType, entity.Purpose, entity.Note, DateTime.UtcNow);
+    }
+
+    private static string SanitizeFileName(string name)
+    {
+        // Strip path components + replace chars that are invalid on filesystems
+        var baseName = Path.GetFileName(name);
+        foreach (var c in Path.GetInvalidFileNameChars())
+            baseName = baseName.Replace(c, '_');
+        // Also strip leading dots (hidden files) and collapse whitespace
+        baseName = baseName.TrimStart('.');
+        if (string.IsNullOrWhiteSpace(baseName)) baseName = "file";
+        return baseName.Length > 200 ? baseName[^200..] : baseName;
+    }
+}
+
+// ========== DOWNLOAD ==========
+
+public record DownloadContractAttachmentQuery(Guid ContractId, Guid AttachmentId) : IRequest<ContractAttachmentFile>;
+
+public record ContractAttachmentFile(Stream Content, string FileName, string ContentType);
+
+public class DownloadContractAttachmentQueryHandler(
+    IApplicationDbContext db,
+    IFileStorage storage) : IRequestHandler<DownloadContractAttachmentQuery, ContractAttachmentFile>
+{
+    public async Task<ContractAttachmentFile> Handle(DownloadContractAttachmentQuery request, CancellationToken ct)
+    {
+        var att = await db.ContractAttachments.AsNoTracking()
+            .FirstOrDefaultAsync(a => a.Id == request.AttachmentId && a.ContractId == request.ContractId, ct)
+            ?? throw new NotFoundException("Attachment", request.AttachmentId);
+
+        var stream = await storage.OpenReadAsync(att.StoragePath, ct);
+        return new ContractAttachmentFile(stream, att.FileName, att.ContentType);
+    }
+}
+
+// ========== DELETE ==========
+
+public record DeleteContractAttachmentCommand(Guid ContractId, Guid AttachmentId) : IRequest;
+
+public class DeleteContractAttachmentCommandHandler(
+    IApplicationDbContext db,
+    IFileStorage storage) : IRequestHandler<DeleteContractAttachmentCommand>
+{
+    public async Task Handle(DeleteContractAttachmentCommand request, CancellationToken ct)
+    {
+        var att = await db.ContractAttachments
+            .FirstOrDefaultAsync(a => a.Id == request.AttachmentId && a.ContractId == request.ContractId, ct)
+            ?? throw new NotFoundException("Attachment", request.AttachmentId);
+
+        db.ContractAttachments.Remove(att);
+        await db.SaveChangesAsync(ct);
+
+        // Best-effort file delete — if it fails, DB row is already gone (orphan
+        // cleanup job can sweep storage later). Don't block API response.
+        try { await storage.DeleteAsync(att.StoragePath, ct); }
+        catch { /* ignore */ }
+    }
+}

src/Backend/SolutionErp.Infrastructure/DependencyInjection.cs

@@ -15,6 +15,7 @@ using SolutionErp.Infrastructure.Persistence;
 using SolutionErp.Infrastructure.Persistence.Interceptors;
 using SolutionErp.Infrastructure.Reports;
 using SolutionErp.Infrastructure.Services;
+using SolutionErp.Infrastructure.Storage;
 
 namespace SolutionErp.Infrastructure;
 
@@ -32,6 +33,7 @@ public static class DependencyInjection
         services.AddScoped<IContractWorkflowService, ContractWorkflowService>();
         services.AddScoped<IContractExcelExporter, ContractExcelExporter>();
         services.AddScoped<INotificationService, NotificationService>();
+        services.AddSingleton<IFileStorage, LocalFileStorage>();
 
         // Phase 3 iteration 2 — SLA auto-approve background service
         services.AddHostedService<SlaExpiryJob>();

src/Backend/SolutionErp.Infrastructure/Storage/LocalFileStorage.cs

@@ -0,0 +1,51 @@
+using Microsoft.Extensions.Configuration;
+using SolutionErp.Application.Common.Interfaces;
+
+namespace SolutionErp.Infrastructure.Storage;
+
+public class LocalFileStorage : IFileStorage
+{
+    private readonly string _root;
+
+    public LocalFileStorage(IConfiguration config)
+    {
+        var root = config["Uploads:RootPath"] ?? "uploads";
+        // Make absolute (relative paths resolve against ContentRoot)
+        _root = Path.GetFullPath(root);
+        Directory.CreateDirectory(_root);
+    }
+
+    private string Full(string rel)
+    {
+        var full = Path.GetFullPath(Path.Combine(_root, rel));
+        // Guard against path traversal — resolved full path must stay inside root
+        if (!full.StartsWith(_root, StringComparison.OrdinalIgnoreCase))
+            throw new UnauthorizedAccessException("Path traversal blocked.");
+        return full;
+    }
+
+    public async Task<string> SaveAsync(string relativePath, Stream content, CancellationToken ct = default)
+    {
+        var full = Full(relativePath);
+        Directory.CreateDirectory(Path.GetDirectoryName(full)!);
+        await using var fs = File.Create(full);
+        await content.CopyToAsync(fs, ct);
+        return relativePath.Replace('\\', '/');
+    }
+
+    public Task<Stream> OpenReadAsync(string relativePath, CancellationToken ct = default)
+    {
+        var full = Full(relativePath);
+        if (!File.Exists(full)) throw new FileNotFoundException(relativePath);
+        return Task.FromResult<Stream>(File.OpenRead(full));
+    }
+
+    public Task DeleteAsync(string relativePath, CancellationToken ct = default)
+    {
+        var full = Full(relativePath);
+        if (File.Exists(full)) File.Delete(full);
+        return Task.CompletedTask;
+    }
+
+    public bool Exists(string relativePath) => File.Exists(Full(relativePath));
+}