[CLAUDE] App+Domain+Infra+Api+FE: Notifications module end-to-end

Domain:
- Notification entity + NotificationType enum (stable ints)
- Nullable RefId cho correlation (contract, user, ...)

Infrastructure:
- NotificationConfiguration: bảng Notifications, index theo (UserId, ReadAt)
- NotificationService: ghi vào DbContext, không SaveChanges (để caller quyết
  định unit-of-work — đảm bảo atomic với domain mutation)
- EF migration AddNotifications

Application:
- INotificationService (Notify + NotifyMany)
- CQRS: ListMyNotifications / GetMyUnreadCount / MarkRead / MarkAllRead

Api:
- NotificationsController: GET /api/notifications + unread-count + mark-read

Integration:
- ContractWorkflowService emit notification tới Drafter khi HĐ chuyển phase
  (skip nếu actor chính là Drafter). Title + type theo phase đích:
  DaPhatHanh → ContractPublished, TuChoi → ContractRejected, khác →
  ContractPhaseTransition.

FE:
- Both NotificationBell (admin + user) dùng /api/notifications thật
  (thay cho derived-from-inbox MVP trước đó). 30s refetch, click mark-read,
  'Đọc hết' bulk action.

Foundation sẵn cho SignalR push + email outbox sau này — chỉ cần mở rộng
NotificationService mà không đổi caller.

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

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

@@ -0,0 +1,35 @@
+using MediatR;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using SolutionErp.Application.Notifications;
+using SolutionErp.Application.Notifications.Dtos;
+
+namespace SolutionErp.Api.Controllers;
+
+[ApiController]
+[Route("api/notifications")]
+[Authorize]
+public class NotificationsController(IMediator mediator) : ControllerBase
+{
+    [HttpGet]
+    public async Task<ActionResult<IReadOnlyList<NotificationDto>>> List(
+        [FromQuery] bool unreadOnly = false,
+        [FromQuery] int limit = 50,
+        CancellationToken ct = default)
+        => Ok(await mediator.Send(new ListMyNotificationsQuery(unreadOnly, limit), ct));
+
+    [HttpGet("unread-count")]
+    public async Task<ActionResult<int>> UnreadCount(CancellationToken ct)
+        => Ok(await mediator.Send(new GetMyUnreadCountQuery(), ct));
+
+    [HttpPost("{id:guid}/read")]
+    public async Task<IActionResult> MarkRead(Guid id, CancellationToken ct)
+    {
+        await mediator.Send(new MarkNotificationReadCommand(id), ct);
+        return NoContent();
+    }
+
+    [HttpPost("read-all")]
+    public async Task<ActionResult<int>> MarkAllRead(CancellationToken ct)
+        => Ok(await mediator.Send(new MarkAllNotificationsReadCommand(), ct));
+}

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

@@ -3,6 +3,7 @@ using SolutionErp.Domain.Contracts;
 using SolutionErp.Domain.Forms;
 using SolutionErp.Domain.Identity;
 using SolutionErp.Domain.Master;
+using SolutionErp.Domain.Notifications;
 
 namespace SolutionErp.Application.Common.Interfaces;
 
@@ -20,6 +21,7 @@ public interface IApplicationDbContext
     DbSet<ContractComment> ContractComments { get; }
     DbSet<ContractAttachment> ContractAttachments { get; }
     DbSet<ContractCodeSequence> ContractCodeSequences { get; }
+    DbSet<Notification> Notifications { get; }
 
     Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
 }

src/Backend/SolutionErp.Application/Notifications/Dtos/NotificationDto.cs

@@ -0,0 +1,11 @@
+namespace SolutionErp.Application.Notifications.Dtos;
+
+public record NotificationDto(
+    Guid Id,
+    int Type,
+    string Title,
+    string? Description,
+    string? Href,
+    Guid? RefId,
+    DateTime CreatedAt,
+    DateTime? ReadAt);

src/Backend/SolutionErp.Application/Notifications/INotificationService.cs

@@ -0,0 +1,27 @@
+using SolutionErp.Domain.Notifications;
+
+namespace SolutionErp.Application.Notifications;
+
+// Abstraction for emitting notifications from domain handlers.
+// Implementation lives in Infrastructure and writes to DbContext (eventual SignalR
+// push + email will layer on the same method without changing callers).
+public interface INotificationService
+{
+    Task NotifyAsync(
+        Guid userId,
+        NotificationType type,
+        string title,
+        string? description = null,
+        string? href = null,
+        Guid? refId = null,
+        CancellationToken ct = default);
+
+    Task NotifyManyAsync(
+        IEnumerable<Guid> userIds,
+        NotificationType type,
+        string title,
+        string? description = null,
+        string? href = null,
+        Guid? refId = null,
+        CancellationToken ct = default);
+}

src/Backend/SolutionErp.Application/Notifications/NotificationFeatures.cs

@@ -0,0 +1,100 @@
+using MediatR;
+using Microsoft.EntityFrameworkCore;
+using SolutionErp.Application.Common.Exceptions;
+using SolutionErp.Application.Common.Interfaces;
+using SolutionErp.Application.Notifications.Dtos;
+using SolutionErp.Domain.Notifications;
+
+namespace SolutionErp.Application.Notifications;
+
+// ========== LIST current-user's notifications ==========
+
+public record ListMyNotificationsQuery(bool UnreadOnly, int Limit) : IRequest<IReadOnlyList<NotificationDto>>;
+
+public class ListMyNotificationsQueryHandler(
+    IApplicationDbContext db,
+    ICurrentUser currentUser) : IRequestHandler<ListMyNotificationsQuery, IReadOnlyList<NotificationDto>>
+{
+    public async Task<IReadOnlyList<NotificationDto>> Handle(ListMyNotificationsQuery request, CancellationToken ct)
+    {
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        var take = request.Limit is > 0 and <= 200 ? request.Limit : 50;
+
+        var q = db.Notifications.AsNoTracking().Where(n => n.UserId == userId);
+        if (request.UnreadOnly) q = q.Where(n => n.ReadAt == null);
+
+        return await q
+            .OrderByDescending(n => n.CreatedAt)
+            .Take(take)
+            .Select(n => new NotificationDto(
+                n.Id,
+                (int)n.Type,
+                n.Title,
+                n.Description,
+                n.Href,
+                n.RefId,
+                n.CreatedAt,
+                n.ReadAt))
+            .ToListAsync(ct);
+    }
+}
+
+// ========== UNREAD count ==========
+
+public record GetMyUnreadCountQuery : IRequest<int>;
+
+public class GetMyUnreadCountQueryHandler(
+    IApplicationDbContext db,
+    ICurrentUser currentUser) : IRequestHandler<GetMyUnreadCountQuery, int>
+{
+    public async Task<int> Handle(GetMyUnreadCountQuery request, CancellationToken ct)
+    {
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        return await db.Notifications.CountAsync(n => n.UserId == userId && n.ReadAt == null, ct);
+    }
+}
+
+// ========== MARK as read ==========
+
+public record MarkNotificationReadCommand(Guid Id) : IRequest;
+
+public class MarkNotificationReadCommandHandler(
+    IApplicationDbContext db,
+    ICurrentUser currentUser,
+    IDateTime clock) : IRequestHandler<MarkNotificationReadCommand>
+{
+    public async Task Handle(MarkNotificationReadCommand request, CancellationToken ct)
+    {
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        var entity = await db.Notifications.FirstOrDefaultAsync(n => n.Id == request.Id && n.UserId == userId, ct)
+            ?? throw new NotFoundException("Notification", request.Id);
+
+        if (entity.ReadAt == null)
+        {
+            entity.ReadAt = clock.UtcNow;
+            await db.SaveChangesAsync(ct);
+        }
+    }
+}
+
+// ========== MARK all as read ==========
+
+public record MarkAllNotificationsReadCommand : IRequest<int>;
+
+public class MarkAllNotificationsReadCommandHandler(
+    IApplicationDbContext db,
+    ICurrentUser currentUser,
+    IDateTime clock) : IRequestHandler<MarkAllNotificationsReadCommand, int>
+{
+    public async Task<int> Handle(MarkAllNotificationsReadCommand request, CancellationToken ct)
+    {
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        var now = clock.UtcNow;
+        var unread = await db.Notifications
+            .Where(n => n.UserId == userId && n.ReadAt == null)
+            .ToListAsync(ct);
+        foreach (var n in unread) n.ReadAt = now;
+        if (unread.Count > 0) await db.SaveChangesAsync(ct);
+        return unread.Count;
+    }
+}

src/Backend/SolutionErp.Domain/Notifications/Notification.cs

@@ -0,0 +1,17 @@
+using SolutionErp.Domain.Common;
+
+namespace SolutionErp.Domain.Notifications;
+
+public class Notification : BaseEntity
+{
+    public Guid UserId { get; set; }
+    public NotificationType Type { get; set; }
+    public string Title { get; set; } = string.Empty;
+    public string? Description { get; set; }
+    public string? Href { get; set; }
+    public DateTime? ReadAt { get; set; }
+
+    // Optional correlation to source entity (contract, user, etc.). Interpretation
+    // depends on Type. Kept nullable to avoid a discriminated-union migration.
+    public Guid? RefId { get; set; }
+}

src/Backend/SolutionErp.Domain/Notifications/NotificationType.cs

@@ -0,0 +1,13 @@
+namespace SolutionErp.Domain.Notifications;
+
+// Stable ints — order matters for persistence + analytics. Don't renumber.
+public enum NotificationType
+{
+    ContractPhaseTransition = 1,
+    ContractCommentAdded = 2,
+    SlaWarning = 3,
+    SlaOverdue = 4,
+    ContractPublished = 5,
+    ContractRejected = 6,
+    Generic = 99,
+}

src/Backend/SolutionErp.Infrastructure/DependencyInjection.cs

@@ -5,6 +5,7 @@ using Microsoft.Extensions.DependencyInjection;
 using SolutionErp.Application.Common.Interfaces;
 using SolutionErp.Application.Contracts.Services;
 using SolutionErp.Application.Forms.Services;
+using SolutionErp.Application.Notifications;
 using SolutionErp.Application.Reports.Services;
 using SolutionErp.Domain.Identity;
 using SolutionErp.Infrastructure.Forms;
@@ -30,6 +31,7 @@ public static class DependencyInjection
         services.AddScoped<IContractCodeGenerator, ContractCodeGenerator>();
         services.AddScoped<IContractWorkflowService, ContractWorkflowService>();
         services.AddScoped<IContractExcelExporter, ContractExcelExporter>();
+        services.AddScoped<INotificationService, NotificationService>();
 
         // Phase 3 iteration 2 — SLA auto-approve background service
         services.AddHostedService<SlaExpiryJob>();

src/Backend/SolutionErp.Infrastructure/Persistence/ApplicationDbContext.cs

@@ -5,6 +5,7 @@ using SolutionErp.Domain.Contracts;
 using SolutionErp.Domain.Forms;
 using SolutionErp.Domain.Identity;
 using SolutionErp.Domain.Master;
+using SolutionErp.Domain.Notifications;
 
 namespace SolutionErp.Infrastructure.Persistence;
 
@@ -25,6 +26,7 @@ public class ApplicationDbContext
     public DbSet<ContractComment> ContractComments => Set<ContractComment>();
     public DbSet<ContractAttachment> ContractAttachments => Set<ContractAttachment>();
     public DbSet<ContractCodeSequence> ContractCodeSequences => Set<ContractCodeSequence>();
+    public DbSet<Notification> Notifications => Set<Notification>();
 
     protected override void OnModelCreating(ModelBuilder builder)
     {

src/Backend/SolutionErp.Infrastructure/Persistence/Configurations/NotificationConfiguration.cs

@@ -0,0 +1,21 @@
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Metadata.Builders;
+using SolutionErp.Domain.Notifications;
+
+namespace SolutionErp.Infrastructure.Persistence.Configurations;
+
+public class NotificationConfiguration : IEntityTypeConfiguration<Notification>
+{
+    public void Configure(EntityTypeBuilder<Notification> e)
+    {
+        e.ToTable("Notifications");
+        e.HasKey(x => x.Id);
+        e.Property(x => x.Type).HasConversion<int>();
+        e.Property(x => x.Title).HasMaxLength(300).IsRequired();
+        e.Property(x => x.Description).HasMaxLength(1000);
+        e.Property(x => x.Href).HasMaxLength(500);
+
+        e.HasIndex(x => new { x.UserId, x.ReadAt });
+        e.HasIndex(x => x.CreatedAt);
+    }
+}

src/Backend/SolutionErp.Infrastructure/Persistence/Migrations/20260421082148_AddNotifications.cs

@@ -0,0 +1,54 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace SolutionErp.Infrastructure.Persistence.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddNotifications : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.CreateTable(
+                name: "Notifications",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "uniqueidentifier", nullable: false),
+                    UserId = table.Column<Guid>(type: "uniqueidentifier", nullable: false),
+                    Type = table.Column<int>(type: "int", nullable: false),
+                    Title = table.Column<string>(type: "nvarchar(300)", maxLength: 300, nullable: false),
+                    Description = table.Column<string>(type: "nvarchar(1000)", maxLength: 1000, nullable: true),
+                    Href = table.Column<string>(type: "nvarchar(500)", maxLength: 500, nullable: true),
+                    ReadAt = table.Column<DateTime>(type: "datetime2", nullable: true),
+                    RefId = table.Column<Guid>(type: "uniqueidentifier", nullable: true),
+                    CreatedAt = table.Column<DateTime>(type: "datetime2", nullable: false),
+                    UpdatedAt = table.Column<DateTime>(type: "datetime2", nullable: true),
+                    CreatedBy = table.Column<Guid>(type: "uniqueidentifier", nullable: true),
+                    UpdatedBy = table.Column<Guid>(type: "uniqueidentifier", nullable: true)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_Notifications", x => x.Id);
+                });
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Notifications_CreatedAt",
+                table: "Notifications",
+                column: "CreatedAt");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Notifications_UserId_ReadAt",
+                table: "Notifications",
+                columns: new[] { "UserId", "ReadAt" });
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "Notifications");
+        }
+    }
+}

src/Backend/SolutionErp.Infrastructure/Persistence/Migrations/ApplicationDbContextModelSnapshot.cs

@@ -879,6 +879,58 @@ namespace SolutionErp.Infrastructure.Persistence.Migrations
                     b.ToTable("Suppliers", (string)null);
                 });
 
+            modelBuilder.Entity("SolutionErp.Domain.Notifications.Notification", b =>
+                {
+                    b.Property<Guid>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("uniqueidentifier");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .HasColumnType("datetime2");
+
+                    b.Property<Guid?>("CreatedBy")
+                        .HasColumnType("uniqueidentifier");
+
+                    b.Property<string>("Description")
+                        .HasMaxLength(1000)
+                        .HasColumnType("nvarchar(1000)");
+
+                    b.Property<string>("Href")
+                        .HasMaxLength(500)
+                        .HasColumnType("nvarchar(500)");
+
+                    b.Property<DateTime?>("ReadAt")
+                        .HasColumnType("datetime2");
+
+                    b.Property<Guid?>("RefId")
+                        .HasColumnType("uniqueidentifier");
+
+                    b.Property<string>("Title")
+                        .IsRequired()
+                        .HasMaxLength(300)
+                        .HasColumnType("nvarchar(300)");
+
+                    b.Property<int>("Type")
+                        .HasColumnType("int");
+
+                    b.Property<DateTime?>("UpdatedAt")
+                        .HasColumnType("datetime2");
+
+                    b.Property<Guid?>("UpdatedBy")
+                        .HasColumnType("uniqueidentifier");
+
+                    b.Property<Guid>("UserId")
+                        .HasColumnType("uniqueidentifier");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("CreatedAt");
+
+                    b.HasIndex("UserId", "ReadAt");
+
+                    b.ToTable("Notifications", (string)null);
+                });
+
             modelBuilder.Entity("Microsoft.AspNetCore.Identity.IdentityRoleClaim<System.Guid>", b =>
                 {
                     b.HasOne("SolutionErp.Domain.Identity.Role", null)

src/Backend/SolutionErp.Infrastructure/Services/ContractWorkflowService.cs

@@ -2,15 +2,18 @@ using Microsoft.EntityFrameworkCore;
 using SolutionErp.Application.Common.Exceptions;
 using SolutionErp.Application.Common.Interfaces;
 using SolutionErp.Application.Contracts.Services;
+using SolutionErp.Application.Notifications;
 using SolutionErp.Domain.Contracts;
 using SolutionErp.Domain.Identity;
+using SolutionErp.Domain.Notifications;
 
 namespace SolutionErp.Infrastructure.Services;
 
 public class ContractWorkflowService(
     IApplicationDbContext db,
     IContractCodeGenerator codeGenerator,
-    IDateTime dateTime) : IContractWorkflowService
+    IDateTime dateTime,
+    INotificationService notifications) : IContractWorkflowService
 {
     // Map (from, to) → roles được phép chuyển. Xem docs/workflow-contract.md §5.
     // Admin luôn bypass (check trong Handler trước khi gọi service).
@@ -115,6 +118,31 @@ public class ContractWorkflowService(
             ApprovedAt = dateTime.UtcNow,
         });
 
+        // Notify the drafter (unless they are the actor or contract has no drafter)
+        if (contract.DrafterUserId is Guid drafterId && drafterId != actorUserId)
+        {
+            var title = targetPhase switch
+            {
+                ContractPhase.DaPhatHanh => $"HĐ {contract.MaHopDong ?? contract.TenHopDong} đã phát hành",
+                ContractPhase.TuChoi => $"HĐ {contract.TenHopDong ?? "của bạn"} bị từ chối",
+                _ => $"HĐ {contract.TenHopDong ?? contract.MaHopDong ?? ""} chuyển sang phase mới",
+            };
+            var type = targetPhase switch
+            {
+                ContractPhase.DaPhatHanh => NotificationType.ContractPublished,
+                ContractPhase.TuChoi => NotificationType.ContractRejected,
+                _ => NotificationType.ContractPhaseTransition,
+            };
+            await notifications.NotifyAsync(
+                drafterId,
+                type,
+                title,
+                description: $"{fromPhase} → {targetPhase}" + (string.IsNullOrWhiteSpace(comment) ? "" : $" · {comment}"),
+                href: $"/contracts/{contract.Id}",
+                refId: contract.Id,
+                ct: ct);
+        }
+
         await db.SaveChangesAsync(ct);
     }
 }

src/Backend/SolutionErp.Infrastructure/Services/NotificationService.cs

@@ -0,0 +1,59 @@
+using SolutionErp.Application.Common.Interfaces;
+using SolutionErp.Application.Notifications;
+using SolutionErp.Domain.Notifications;
+
+namespace SolutionErp.Infrastructure.Services;
+
+// MVP: writes directly to DbContext. Does NOT call SaveChanges — caller's unit of
+// work flushes both the domain mutation and the notification atomically.
+// Future: wrap with SignalR IHubContext push + Outbox for email dispatch.
+public class NotificationService(IApplicationDbContext db, IDateTime clock) : INotificationService
+{
+    public Task NotifyAsync(
+        Guid userId,
+        NotificationType type,
+        string title,
+        string? description = null,
+        string? href = null,
+        Guid? refId = null,
+        CancellationToken ct = default)
+    {
+        db.Notifications.Add(new Notification
+        {
+            UserId = userId,
+            Type = type,
+            Title = title,
+            Description = description,
+            Href = href,
+            RefId = refId,
+            CreatedAt = clock.UtcNow,
+        });
+        return Task.CompletedTask;
+    }
+
+    public Task NotifyManyAsync(
+        IEnumerable<Guid> userIds,
+        NotificationType type,
+        string title,
+        string? description = null,
+        string? href = null,
+        Guid? refId = null,
+        CancellationToken ct = default)
+    {
+        var now = clock.UtcNow;
+        foreach (var userId in userIds.Distinct())
+        {
+            db.Notifications.Add(new Notification
+            {
+                UserId = userId,
+                Type = type,
+                Title = title,
+                Description = description,
+                Href = href,
+                RefId = refId,
+                CreatedAt = now,
+            });
+        }
+        return Task.CompletedTask;
+    }
+}