Ncp.Admin
├── Domain（領(lǐng)域?qū)樱?
│   ├── AggregatesModel（聚合模型）
│   └── DomainEvents（領(lǐng)域事件）
├── Infrastructure（基礎(chǔ)設(shè)施層）
│   ├── EntityConfigurations（實(shí)體配置）
│   └── Repositories（倉(cāng)儲(chǔ)實(shí)現(xiàn)）
└── Web（表現(xiàn)層）
    ├── Application（應(yīng)用服務(wù)層）
    │   ├── Commands（命令）
    │   ├── Queries（查詢）
    │   └── DomainEventHandlers（領(lǐng)域事件處理器）
    └── Endpoints（API端點(diǎn)）

/// <summary>
/// 部門ID（強(qiáng)類型ID）
/// </summary>
public partial record DeptId : IInt64StronglyTypedId;
/// <summary>
/// 部門聚合根
/// </summary>
public class Dept : Entity<DeptId>, IAggregateRoot
{
    public string Name { get; private set; } = string.Empty;
    public string Remark { get; private set; } = string.Empty;
    public DeptId ParentId { get; private set; } = default!;
    public int Status { get; private set; } = 1;
    protected Dept() { }
    // 業(yè)務(wù)方法：更新部門信息
    public void UpdateInfo(string name, string remark, DeptId parentId, int status)
    {
        Name = name;
        Remark = remark;
        ParentId = parentId;
        Status = status;
        UpdateTime = new UpdateTime(DateTimeOffset.UtcNow);
        // 發(fā)布領(lǐng)域事件
        AddDomainEvent(new DeptInfoChangedDomainEvent(this));
    }
    // 軟刪除
    public void SoftDelete()
    {
        if (IsDeleted)
        {
            throw new KnownException("部門已經(jīng)被刪除");
        }
        IsDeleted = true;
        UpdateTime = new UpdateTime(DateTimeOffset.UtcNow);
    }
}

/// <summary>
/// 創(chuàng)建部門命令
/// </summary>
public record CreateDeptCommand(string Name, string Remark, DeptId? ParentId, int Status) 
    : ICommand<DeptId>;
/// <summary>
/// 命令驗(yàn)證器
/// </summary>
public class CreateDeptCommandValidator : AbstractValidator<CreateDeptCommand>
{
    public CreateDeptCommandValidator(DeptQuery deptQuery)
    {
        RuleFor(d => d.Name).NotEmpty().WithMessage("部門名稱不能為空");
        RuleFor(d => d.Name)
            .MustAsync(async (n, ct) => !await deptQuery.DoesDeptExist(n, ct))
            .WithMessage(d => $"該部門已存在，Name={d.Name}");
        RuleFor(d => d.Status).InclusiveBetween(0, 1).WithMessage("狀態(tài)值必須為0或1");
    }
}
/// <summary>
/// 命令處理器
/// </summary>
public class CreateDeptCommandHandler(IDeptRepository deptRepository) 
    : ICommandHandler<CreateDeptCommand, DeptId>
{
    public async Task<DeptId> Handle(CreateDeptCommand request, CancellationToken cancellationToken)
    {
        var parentId = request.ParentId ?? new DeptId(0);
        var dept = new Dept(request.Name, request.Remark, parentId, request.Status);
        await deptRepository.AddAsync(dept, cancellationToken);
        // 注意：不需要手動(dòng)調(diào)用SaveChanges，框架會(huì)自動(dòng)處理
        return dept.Id;
    }
}

/// <summary>
/// 部門查詢服務(wù)
/// </summary>
public class DeptQuery(ApplicationDbContext applicationDbContext) : IQuery
{
    private DbSet<Dept> DeptSet { get; } = applicationDbContext.Depts;
    /// <summary>
    /// 獲取部門樹（使用投影優(yōu)化性能）
    /// </summary>
    public async Task<IEnumerable<DeptTreeDto>> GetDeptTreeAsync(
        bool includeInactive = false, 
        CancellationToken cancellationToken = default)
    {
        // 使用投影只選擇需要的字段，減少內(nèi)存占用
        var allDepts = await DeptSet.AsNoTracking()
            .WhereIf(!includeInactive, d => d.Status != 0)
            .Select(d => new DeptTreeNode
            {
                Id = d.Id,
                Name = d.Name,
                Remark = d.Remark,
                ParentId = d.ParentId,
                Status = d.Status,
                CreatedAt = d.CreatedAt
            })
            .ToListAsync(cancellationToken);
        // 在內(nèi)存中構(gòu)建樹形結(jié)構(gòu)
        return BuildTreeStructure(allDepts);
    }
}

/// <summary>
/// 部門信息變更領(lǐng)域事件
/// </summary>
public record DeptInfoChangedDomainEvent(Dept Dept) : IDomainEvent;

/// <summary>
/// 部門信息變更領(lǐng)域事件處理器 - 用于更新用戶部門名稱
/// </summary>
public class DeptInfoChangedDomainEventHandlerForUpdateUserDeptName(
    IMediator mediator, 
    UserQuery userQuery) 
    : IDomainEventHandler<DeptInfoChangedDomainEvent>
{
    public async Task Handle(DeptInfoChangedDomainEvent domainEvent, CancellationToken cancellationToken)
    {
        var dept = domainEvent.Dept;
        var deptId = dept.Id;
        var newDeptName = dept.Name;
        // 查詢所有屬于該部門的用戶ID
        var userIds = await userQuery.GetUserIdsByDeptIdAsync(deptId, cancellationToken);
        // 通過(guò)Command更新每個(gè)用戶的部門名稱（而不是直接操作數(shù)據(jù)庫(kù)）
        foreach (var userId in userIds)
        {
            var command = new UpdateUserDeptNameCommand(userId, newDeptName);
            await mediator.Send(command, cancellationToken);
        }
    }
}

/// <summary>
/// 創(chuàng)建部門的API端點(diǎn)
/// </summary>
[Tags("Depts")]
public class CreateDeptEndpoint(IMediator mediator) 
    : Endpoint<CreateDeptRequest, ResponseData<CreateDeptResponse>>
{
    public override void Configure()
    {
        Post("/api/admin/dept");
        AuthSchemes(JwtBearerDefaults.AuthenticationScheme);
        Permissions(PermissionCodes.AllApiAccess, PermissionCodes.DeptCreate);
    }
    public override async Task HandleAsync(CreateDeptRequest req, CancellationToken ct)
    {
        var cmd = new CreateDeptCommand(req.Name, req.Remark, req.ParentId, req.Status);
        var deptId = await mediator.Send(cmd, ct);
        var response = new CreateDeptResponse(deptId, req.Name, req.Remark);
        await Send.OkAsync(response.AsResponseData(), cancellation: ct);
    }
}

// 定義強(qiáng)類型ID
public partial record DeptId : IInt64StronglyTypedId;
// 使用強(qiáng)類型ID
var deptId = new DeptId(123);
var parentId = request.ParentId ?? new DeptId(0);

/// <summary>
/// 部門倉(cāng)儲(chǔ)接口
/// </summary>
public interface IDeptRepository : IRepository<Dept, DeptId> { }
/// <summary>
/// 部門倉(cāng)儲(chǔ)實(shí)現(xiàn)
/// </summary>
public class DeptRepository(ApplicationDbContext context) 
    : RepositoryBase<Dept, DeptId, ApplicationDbContext>(context), 
      IDeptRepository { }

public class CreateDeptCommandValidator : AbstractValidator<CreateDeptCommand>
{
    public CreateDeptCommandValidator(DeptQuery deptQuery)
    {
        RuleFor(d => d.Name).NotEmpty().WithMessage("部門名稱不能為空");
        // 異步驗(yàn)證：檢查部門名稱是否已存在
        RuleFor(d => d.Name)
            .MustAsync(async (n, ct) => !await deptQuery.DoesDeptExist(n, ct))
            .WithMessage(d => $"該部門已存在，Name={d.Name}");
    }
}

// 在聚合根中
public void SoftDelete()
{
    if (IsDeleted)
    {
        throw new KnownException("部門已經(jīng)被刪除");
    }
    // ...
}
// 在命令處理器中
var dept = await deptRepository.GetAsync(request.DeptId, cancellationToken) 
    ?? throw new KnownException($"未找到部門，DeptId = {request.DeptId}");

[Collection(WebAppTestCollection.Name)]
public class DeptTests(WebAppFixture app) : AuthenticatedTestBase<WebAppFixture>(app)
{
    [Fact]
    public async Task CreateDept_WithValidData_ShouldSucceed()
    {
        // Arrange
        var client = await GetAuthenticatedClientAsync();
        var deptName = $"測(cè)試部門_{Guid.NewGuid():N}";
        try
        {
            // Act
            var request = new CreateDeptRequest(deptName, "測(cè)試備注", null, 1);
            var (response, result) = await client.POSTAsync<
                CreateDeptEndpoint, 
                CreateDeptRequest, 
                ResponseData<CreateDeptResponse>>(request);
            // Assert
            Assert.True(response.IsSuccessStatusCode);
            Assert.NotNull(result?.Data);
            Assert.Equal(deptName, result.Data.Name);
        }
        finally
        {
            await CleanupTestDataAsync();
        }
    }
}

# 僅需確保Docker環(huán)境運(yùn)行
docker version
# 直接運(yùn)行AppHost項(xiàng)目，Aspire會(huì)自動(dòng)管理所有依賴服務(wù)
cd src/Ncp.Admin.AppHost
dotnet run

# 安裝全局工具
dotnet tool install -g NetCorePal.Extensions.CodeAnalysis.Tools
# 生成可視化文件
cd src/Ncp.Admin.Web
netcorepal-codeanalysis generate --output architecture.html