chore: add documentation comments and stylecop rules

src/Api/TakeoutSaaS.AdminApi/Controllers/TenantAnnouncementsController.cs

@@ -28,8 +28,13 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     [ProducesResponseType(typeof(ApiResponse<PagedResult<TenantAnnouncementDto>>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<PagedResult<TenantAnnouncementDto>>> Search(long tenantId, [FromQuery] SearchTenantAnnouncementsQuery query, CancellationToken cancellationToken)
     {
+        // 1. 绑定租户标识
         query = query with { TenantId = tenantId };
+
+        // 2. 查询公告列表
         var result = await mediator.Send(query, cancellationToken);
+
+        // 3. 返回分页结果
         return ApiResponse<PagedResult<TenantAnnouncementDto>>.Ok(result);
     }
 
@@ -42,7 +47,10 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     [ProducesResponseType(typeof(ApiResponse<TenantAnnouncementDto>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<TenantAnnouncementDto>> Detail(long tenantId, long announcementId, CancellationToken cancellationToken)
     {
+        // 1. 查询指定公告
         var result = await mediator.Send(new GetTenantAnnouncementQuery { TenantId = tenantId, AnnouncementId = announcementId }, cancellationToken);
+
+        // 2. 返回详情或 404
         return result is null
             ? ApiResponse<TenantAnnouncementDto>.Error(StatusCodes.Status404NotFound, "公告不存在")
             : ApiResponse<TenantAnnouncementDto>.Ok(result);
@@ -56,7 +64,10 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     [ProducesResponseType(typeof(ApiResponse<TenantAnnouncementDto>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<TenantAnnouncementDto>> Create(long tenantId, [FromBody, Required] CreateTenantAnnouncementCommand command, CancellationToken cancellationToken)
     {
+        // 1. 绑定租户标识
         command = command with { TenantId = tenantId };
+
+        // 2. 创建公告并返回
         var result = await mediator.Send(command, cancellationToken);
         return ApiResponse<TenantAnnouncementDto>.Ok(result);
     }
@@ -70,8 +81,13 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     [ProducesResponseType(typeof(ApiResponse<TenantAnnouncementDto>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<TenantAnnouncementDto>> Update(long tenantId, long announcementId, [FromBody, Required] UpdateTenantAnnouncementCommand command, CancellationToken cancellationToken)
     {
+        // 1. 绑定租户与公告标识
         command = command with { TenantId = tenantId, AnnouncementId = announcementId };
+
+        // 2. 执行更新
         var result = await mediator.Send(command, cancellationToken);
+
+        // 3. 返回更新结果或 404
         return result is null
             ? ApiResponse<TenantAnnouncementDto>.Error(StatusCodes.Status404NotFound, "公告不存在")
             : ApiResponse<TenantAnnouncementDto>.Ok(result);
@@ -85,7 +101,10 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
     public async Task<ApiResponse<bool>> Delete(long tenantId, long announcementId, CancellationToken cancellationToken)
     {
+        // 1. 删除公告
         var result = await mediator.Send(new DeleteTenantAnnouncementCommand { TenantId = tenantId, AnnouncementId = announcementId }, cancellationToken);
+
+        // 2. 返回执行结果
         return ApiResponse<bool>.Ok(result);
     }
 
@@ -98,7 +117,10 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     [ProducesResponseType(typeof(ApiResponse<TenantAnnouncementDto>), StatusCodes.Status404NotFound)]
     public async Task<ApiResponse<TenantAnnouncementDto>> MarkRead(long tenantId, long announcementId, CancellationToken cancellationToken)
     {
+        // 1. 标记公告已读
         var result = await mediator.Send(new MarkTenantAnnouncementReadCommand { TenantId = tenantId, AnnouncementId = announcementId }, cancellationToken);
+
+        // 2. 返回结果或 404
         return result is null
             ? ApiResponse<TenantAnnouncementDto>.Error(StatusCodes.Status404NotFound, "公告不存在")
             : ApiResponse<TenantAnnouncementDto>.Ok(result);