docs: 完善AdminApi控制器注释和代码规范

.gitignore

@@ -3,3 +3,4 @@ bin/
 obj/
 **/bin/
 **/obj/
+.claude/

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

@@ -20,6 +20,7 @@ public sealed class FilesController(IFileStorageService fileStorageService) : Ba
     /// <summary>
     /// 上传图片或文件。
     /// </summary>
+    /// <returns>文件上传响应信息。</returns>
     [HttpPost("upload")]
     [RequestFormLimits(MultipartBodyLengthLimit = 30 * 1024 * 1024)]
     [ProducesResponseType(typeof(ApiResponse<FileUploadResponse>), StatusCodes.Status200OK)]

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

@@ -146,6 +146,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 获取商户详细资料（含证照、合同）。
     /// </summary>
+    /// <returns>创建的证照信息。</returns>
     [HttpGet("{merchantId:long}/detail")]
     [PermissionAuthorize("merchant:read")]
     [ProducesResponseType(typeof(ApiResponse<MerchantDetailDto>), StatusCodes.Status200OK)]
@@ -161,6 +162,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 上传商户证照信息（先通过文件上传接口获取 COS 地址）。
     /// </summary>
+    /// <returns>创建的证照信息。</returns>
     [HttpPost("{merchantId:long}/documents")]
     [PermissionAuthorize("merchant:update")]
     [ProducesResponseType(typeof(ApiResponse<MerchantDocumentDto>), StatusCodes.Status200OK)]
@@ -180,6 +182,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 商户证照列表。
     /// </summary>
+    /// <returns>商户证照列表。</returns>
     [HttpGet("{merchantId:long}/documents")]
     [PermissionAuthorize("merchant:read")]
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<MerchantDocumentDto>>), StatusCodes.Status200OK)]
@@ -195,6 +198,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 审核指定证照。
     /// </summary>
+    /// <returns>审核后的证照信息。</returns>
     [HttpPost("{merchantId:long}/documents/{documentId:long}/review")]
     [PermissionAuthorize("merchant:review")]
     [ProducesResponseType(typeof(ApiResponse<MerchantDocumentDto>), StatusCodes.Status200OK)]
@@ -215,6 +219,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 新增商户合同。
     /// </summary>
+    /// <returns>创建的合同信息。</returns>
     [HttpPost("{merchantId:long}/contracts")]
     [PermissionAuthorize("merchant:update")]
     [ProducesResponseType(typeof(ApiResponse<MerchantContractDto>), StatusCodes.Status200OK)]
@@ -234,6 +239,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 合同列表。
     /// </summary>
+    /// <returns>商户合同列表。</returns>
     [HttpGet("{merchantId:long}/contracts")]
     [PermissionAuthorize("merchant:read")]
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<MerchantContractDto>>), StatusCodes.Status200OK)]
@@ -249,6 +255,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 更新合同状态（生效/终止等）。
     /// </summary>
+    /// <returns>更新后的合同信息。</returns>
     [HttpPut("{merchantId:long}/contracts/{contractId:long}/status")]
     [PermissionAuthorize("merchant:update")]
     [ProducesResponseType(typeof(ApiResponse<MerchantContractDto>), StatusCodes.Status200OK)]
@@ -269,6 +276,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 审核商户（通过/驳回）。
     /// </summary>
+    /// <returns>审核后的商户信息。</returns>
     [HttpPost("{merchantId:long}/review")]
     [PermissionAuthorize("merchant:review")]
     [ProducesResponseType(typeof(ApiResponse<MerchantDto>), StatusCodes.Status200OK)]
@@ -285,6 +293,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 审核日志。
     /// </summary>
+    /// <returns>商户审核日志分页结果。</returns>
     [HttpGet("{merchantId:long}/audits")]
     [PermissionAuthorize("merchant:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<MerchantAuditLogDto>>), StatusCodes.Status200OK)]
@@ -304,6 +313,7 @@ public sealed class MerchantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 可选商户类目列表。
     /// </summary>
+    /// <returns>可选的商户类目列表。</returns>
     [HttpGet("categories")]
     [PermissionAuthorize("merchant:read")]
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<string>>), StatusCodes.Status200OK)]

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

@@ -24,6 +24,7 @@ public sealed class OrdersController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 创建订单。
     /// </summary>
+    /// <returns>创建的订单信息。</returns>
     [HttpPost]
     [PermissionAuthorize("order:create")]
     [ProducesResponseType(typeof(ApiResponse<OrderDto>), StatusCodes.Status200OK)]
@@ -39,6 +40,7 @@ public sealed class OrdersController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 查询订单列表。
     /// </summary>
+    /// <returns>订单分页列表。</returns>
     [HttpGet]
     [PermissionAuthorize("order:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<OrderDto>>), StatusCodes.Status200OK)]
@@ -73,6 +75,7 @@ public sealed class OrdersController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 获取订单详情。
     /// </summary>
+    /// <returns>订单详情。</returns>
     [HttpGet("{orderId:long}")]
     [PermissionAuthorize("order:read")]
     [ProducesResponseType(typeof(ApiResponse<OrderDto>), StatusCodes.Status200OK)]
@@ -91,6 +94,7 @@ public sealed class OrdersController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 更新订单。
     /// </summary>
+    /// <returns>更新后的订单信息。</returns>
     [HttpPut("{orderId:long}")]
     [PermissionAuthorize("order:update")]
     [ProducesResponseType(typeof(ApiResponse<OrderDto>), StatusCodes.Status200OK)]
@@ -115,6 +119,7 @@ public sealed class OrdersController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 删除订单。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("{orderId:long}")]
     [PermissionAuthorize("order:delete")]
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]

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

@@ -23,6 +23,7 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 创建支付记录。
     /// </summary>
+    /// <returns>创建的支付记录信息。</returns>
     [HttpPost]
     [PermissionAuthorize("payment:create")]
     [ProducesResponseType(typeof(ApiResponse<PaymentDto>), StatusCodes.Status200OK)]
@@ -38,6 +39,7 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 查询支付记录列表。
     /// </summary>
+    /// <returns>支付记录分页列表。</returns>
     [HttpGet]
     [PermissionAuthorize("payment:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<PaymentDto>>), StatusCodes.Status200OK)]
@@ -68,6 +70,7 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 获取支付记录详情。
     /// </summary>
+    /// <returns>支付记录详情。</returns>
     [HttpGet("{paymentId:long}")]
     [PermissionAuthorize("payment:read")]
     [ProducesResponseType(typeof(ApiResponse<PaymentDto>), StatusCodes.Status200OK)]
@@ -86,6 +89,7 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 更新支付记录。
     /// </summary>
+    /// <returns>更新后的支付记录信息。</returns>
     [HttpPut("{paymentId:long}")]
     [PermissionAuthorize("payment:update")]
     [ProducesResponseType(typeof(ApiResponse<PaymentDto>), StatusCodes.Status200OK)]
@@ -110,6 +114,7 @@ public sealed class PaymentsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 删除支付记录。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("{paymentId:long}")]
     [PermissionAuthorize("payment:delete")]
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]

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

@@ -23,6 +23,7 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 创建商品。
     /// </summary>
+    /// <returns>创建的商品信息。</returns>
     [HttpPost]
     [PermissionAuthorize("product:create")]
     [ProducesResponseType(typeof(ApiResponse<ProductDto>), StatusCodes.Status200OK)]
@@ -38,6 +39,7 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 查询商品列表。
     /// </summary>
+    /// <returns>商品分页列表。</returns>
     [HttpGet]
     [PermissionAuthorize("product:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<ProductDto>>), StatusCodes.Status200OK)]
@@ -70,6 +72,7 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 获取商品详情。
     /// </summary>
+    /// <returns>商品详情。</returns>
     [HttpGet("{productId:long}")]
     [PermissionAuthorize("product:read")]
     [ProducesResponseType(typeof(ApiResponse<ProductDto>), StatusCodes.Status200OK)]
@@ -88,6 +91,7 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 更新商品。
     /// </summary>
+    /// <returns>更新后的商品信息。</returns>
     [HttpPut("{productId:long}")]
     [PermissionAuthorize("product:update")]
     [ProducesResponseType(typeof(ApiResponse<ProductDto>), StatusCodes.Status200OK)]
@@ -112,6 +116,7 @@ public sealed class ProductsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 删除商品。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("{productId:long}")]
     [PermissionAuthorize("product:delete")]
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]

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

@@ -25,6 +25,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <remarks>
     /// 示例：GET /api/admin/v1/roles/templates
     /// </remarks>
+    /// <returns>角色模板列表。</returns>
     [HttpGet("templates")]
     [PermissionAuthorize("identity:role:read")]
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<RoleTemplateDto>>), StatusCodes.Status200OK)]
@@ -43,6 +44,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <remarks>
     /// 示例：GET /api/admin/v1/roles/templates/tenant-admin
     /// </remarks>
+    /// <returns>角色模板详情。</returns>
     [HttpGet("templates/{templateCode}")]
     [PermissionAuthorize("identity:role:read")]
     [ProducesResponseType(typeof(ApiResponse<RoleTemplateDto>), StatusCodes.Status200OK)]
@@ -61,6 +63,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 创建角色模板。
     /// </summary>
+    /// <returns>创建的角色模板信息。</returns>
     [HttpPost("templates")]
     [PermissionAuthorize("role-template:create")]
     [ProducesResponseType(typeof(ApiResponse<RoleTemplateDto>), StatusCodes.Status200OK)]
@@ -76,6 +79,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 更新角色模板。
     /// </summary>
+    /// <returns>更新后的角色模板信息。</returns>
     [HttpPut("templates/{templateCode}")]
     [PermissionAuthorize("role-template:update")]
     [ProducesResponseType(typeof(ApiResponse<RoleTemplateDto>), StatusCodes.Status200OK)]
@@ -100,6 +104,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 删除角色模板。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("templates/{templateCode}")]
     [PermissionAuthorize("role-template:delete")]
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
@@ -119,6 +124,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// 示例：POST /api/admin/v1/roles/templates/store-manager/copy
     /// Body: { "roleName": "新区店长" }
     /// </remarks>
+    /// <returns>创建的角色信息。</returns>
     [HttpPost("templates/{templateCode}/copy")]
     [PermissionAuthorize("identity:role:create")]
     [ProducesResponseType(typeof(ApiResponse<RoleDto>), StatusCodes.Status200OK)]
@@ -142,6 +148,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// 示例：POST /api/admin/v1/roles/templates/init
     /// Body: { "templateCodes": ["tenant-admin","store-manager","store-staff"] }
     /// </remarks>
+    /// <returns>创建的角色列表。</returns>
     [HttpPost("templates/init")]
     [PermissionAuthorize("identity:role:create")]
     [ProducesResponseType(typeof(ApiResponse<IReadOnlyList<RoleDto>>), StatusCodes.Status200OK)]
@@ -165,6 +172,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// GET /api/admin/v1/roles?keyword=ops&amp;page=1&amp;pageSize=20
     /// Header: Authorization: Bearer &lt;JWT&gt; + X-Tenant-Id
     /// </remarks>
+    /// <returns>角色分页结果。</returns>
     [HttpGet]
     [PermissionAuthorize("identity:role:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<RoleDto>>), StatusCodes.Status200OK)]
@@ -180,6 +188,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 创建角色。
     /// </summary>
+    /// <returns>创建的角色信息。</returns>
     [HttpPost]
     [PermissionAuthorize("identity:role:create")]
     [ProducesResponseType(typeof(ApiResponse<RoleDto>), StatusCodes.Status200OK)]
@@ -195,6 +204,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 更新角色。
     /// </summary>
+    /// <returns>更新后的角色信息。</returns>
     [HttpPut("{roleId:long}")]
     [PermissionAuthorize("identity:role:update")]
     [ProducesResponseType(typeof(ApiResponse<RoleDto>), StatusCodes.Status200OK)]
@@ -216,6 +226,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 删除角色。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("{roleId:long}")]
     [PermissionAuthorize("identity:role:delete")]
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
@@ -232,6 +243,7 @@ public sealed class RolesController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 绑定角色权限（覆盖式）。
     /// </summary>
+    /// <returns>是否绑定成功。</returns>
     [HttpPut("{roleId:long}/permissions")]
     [PermissionAuthorize("identity:role:bind-permission")]
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]

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

@@ -23,6 +23,7 @@ public sealed class StoresController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 创建门店。
     /// </summary>
+    /// <returns>创建的门店信息。</returns>
     [HttpPost]
     [PermissionAuthorize("store:create")]
     [ProducesResponseType(typeof(ApiResponse<StoreDto>), StatusCodes.Status200OK)]
@@ -38,6 +39,7 @@ public sealed class StoresController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 查询门店列表。
     /// </summary>
+    /// <returns>门店分页列表。</returns>
     [HttpGet]
     [PermissionAuthorize("store:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<StoreDto>>), StatusCodes.Status200OK)]
@@ -68,6 +70,7 @@ public sealed class StoresController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 获取门店详情。
     /// </summary>
+    /// <returns>门店详情。</returns>
     [HttpGet("{storeId:long}")]
     [PermissionAuthorize("store:read")]
     [ProducesResponseType(typeof(ApiResponse<StoreDto>), StatusCodes.Status200OK)]
@@ -86,6 +89,7 @@ public sealed class StoresController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 更新门店。
     /// </summary>
+    /// <returns>更新后的门店信息。</returns>
     [HttpPut("{storeId:long}")]
     [PermissionAuthorize("store:update")]
     [ProducesResponseType(typeof(ApiResponse<StoreDto>), StatusCodes.Status200OK)]
@@ -110,6 +114,7 @@ public sealed class StoresController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 删除门店。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("{storeId:long}")]
     [PermissionAuthorize("store:delete")]
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]

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

@@ -25,6 +25,7 @@ public sealed class SystemParametersController(IMediator mediator) : BaseApiCont
     /// <summary>
     /// 创建系统参数。
     /// </summary>
+    /// <returns>创建的系统参数信息。</returns>
     [HttpPost]
     [PermissionAuthorize("system-parameter:create")]
     [ProducesResponseType(typeof(ApiResponse<SystemParameterDto>), StatusCodes.Status200OK)]
@@ -40,6 +41,7 @@ public sealed class SystemParametersController(IMediator mediator) : BaseApiCont
     /// <summary>
     /// 查询系统参数列表。
     /// </summary>
+    /// <returns>分页的系统参数列表。</returns>
     [HttpGet]
     [PermissionAuthorize("system-parameter:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<SystemParameterDto>>), StatusCodes.Status200OK)]
@@ -70,6 +72,7 @@ public sealed class SystemParametersController(IMediator mediator) : BaseApiCont
     /// <summary>
     /// 获取系统参数详情。
     /// </summary>
+    /// <returns>系统参数详情。</returns>
     [HttpGet("{parameterId:long}")]
     [PermissionAuthorize("system-parameter:read")]
     [ProducesResponseType(typeof(ApiResponse<SystemParameterDto>), StatusCodes.Status200OK)]
@@ -88,6 +91,7 @@ public sealed class SystemParametersController(IMediator mediator) : BaseApiCont
     /// <summary>
     /// 更新系统参数。
     /// </summary>
+    /// <returns>更新后的系统参数信息。</returns>
     [HttpPut("{parameterId:long}")]
     [PermissionAuthorize("system-parameter:update")]
     [ProducesResponseType(typeof(ApiResponse<SystemParameterDto>), StatusCodes.Status200OK)]
@@ -112,6 +116,7 @@ public sealed class SystemParametersController(IMediator mediator) : BaseApiCont
     /// <summary>
     /// 删除系统参数。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("{parameterId:long}")]
     [PermissionAuthorize("system-parameter:delete")]
     [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]

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

@@ -22,6 +22,7 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     /// <summary>
     /// 分页查询公告。
     /// </summary>
+    /// <returns>租户公告分页结果。</returns>
     [HttpGet]
     [PermissionAuthorize("tenant-announcement:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<TenantAnnouncementDto>>), StatusCodes.Status200OK)]
@@ -40,6 +41,7 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     /// <summary>
     /// 公告详情。
     /// </summary>
+    /// <returns>租户公告详情。</returns>
     [HttpGet("{announcementId:long}")]
     [PermissionAuthorize("tenant-announcement:read")]
     [ProducesResponseType(typeof(ApiResponse<TenantAnnouncementDto>), StatusCodes.Status200OK)]
@@ -58,6 +60,7 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     /// <summary>
     /// 创建公告。
     /// </summary>
+    /// <returns>创建的公告信息。</returns>
     [HttpPost]
     [PermissionAuthorize("tenant-announcement:create")]
     [ProducesResponseType(typeof(ApiResponse<TenantAnnouncementDto>), StatusCodes.Status200OK)]
@@ -74,6 +77,7 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     /// <summary>
     /// 更新公告。
     /// </summary>
+    /// <returns>更新后的公告信息。</returns>
     [HttpPut("{announcementId:long}")]
     [PermissionAuthorize("tenant-announcement:update")]
     [ProducesResponseType(typeof(ApiResponse<TenantAnnouncementDto>), StatusCodes.Status200OK)]
@@ -95,6 +99,7 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     /// <summary>
     /// 删除公告。
     /// </summary>
+    /// <returns>删除结果。</returns>
     [HttpDelete("{announcementId:long}")]
     [PermissionAuthorize("tenant-announcement:delete")]
     [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
@@ -110,6 +115,7 @@ public sealed class TenantAnnouncementsController(IMediator mediator) : BaseApiC
     /// <summary>
     /// 标记公告已读。
     /// </summary>
+    /// <returns>标记已读后的公告信息。</returns>
     [HttpPost("{announcementId:long}/read")]
     [PermissionAuthorize("tenant-announcement:read")]
     [ProducesResponseType(typeof(ApiResponse<TenantAnnouncementDto>), StatusCodes.Status200OK)]

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

@@ -22,6 +22,7 @@ public sealed class TenantBillingsController(IMediator mediator) : BaseApiContro
     /// <summary>
     /// 分页查询账单。
     /// </summary>
+    /// <returns>租户账单分页结果。</returns>
     [HttpGet]
     [PermissionAuthorize("tenant-bill:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<TenantBillingDto>>), StatusCodes.Status200OK)]
@@ -40,6 +41,7 @@ public sealed class TenantBillingsController(IMediator mediator) : BaseApiContro
     /// <summary>
     /// 账单详情。
     /// </summary>
+    /// <returns>租户账单详情。</returns>
     [HttpGet("{billingId:long}")]
     [PermissionAuthorize("tenant-bill:read")]
     [ProducesResponseType(typeof(ApiResponse<TenantBillingDto>), StatusCodes.Status200OK)]
@@ -58,6 +60,7 @@ public sealed class TenantBillingsController(IMediator mediator) : BaseApiContro
     /// <summary>
     /// 创建账单。
     /// </summary>
+    /// <returns>创建的账单信息。</returns>
     [HttpPost]
     [PermissionAuthorize("tenant-bill:create")]
     [ProducesResponseType(typeof(ApiResponse<TenantBillingDto>), StatusCodes.Status200OK)]
@@ -74,6 +77,7 @@ public sealed class TenantBillingsController(IMediator mediator) : BaseApiContro
     /// <summary>
     /// 标记账单已支付。
     /// </summary>
+    /// <returns>标记支付后的账单信息。</returns>
     [HttpPost("{billingId:long}/pay")]
     [PermissionAuthorize("tenant-bill:pay")]
     [ProducesResponseType(typeof(ApiResponse<TenantBillingDto>), StatusCodes.Status200OK)]

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

@@ -21,6 +21,7 @@ public sealed class TenantNotificationsController(IMediator mediator) : BaseApiC
     /// <summary>
     /// 分页查询通知。
     /// </summary>
+    /// <returns>租户通知分页结果。</returns>
     [HttpGet]
     [PermissionAuthorize("tenant-notification:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<TenantNotificationDto>>), StatusCodes.Status200OK)]
@@ -39,6 +40,7 @@ public sealed class TenantNotificationsController(IMediator mediator) : BaseApiC
     /// <summary>
     /// 标记通知已读。
     /// </summary>
+    /// <returns>标记已读后的通知信息。</returns>
     [HttpPost("{notificationId:long}/read")]
     [PermissionAuthorize("tenant-notification:update")]
     [ProducesResponseType(typeof(ApiResponse<TenantNotificationDto>), StatusCodes.Status200OK)]

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

@@ -22,6 +22,7 @@ public sealed class TenantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 注册租户并初始化套餐。
     /// </summary>
+    /// <returns>注册的租户信息。</returns>
     [HttpPost]
     [PermissionAuthorize("tenant:create")]
     [ProducesResponseType(typeof(ApiResponse<TenantDto>), StatusCodes.Status200OK)]
@@ -37,6 +38,7 @@ public sealed class TenantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 分页查询租户。
     /// </summary>
+    /// <returns>租户分页结果。</returns>
     [HttpGet]
     [PermissionAuthorize("tenant:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<TenantDto>>), StatusCodes.Status200OK)]
@@ -52,6 +54,7 @@ public sealed class TenantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 查看租户详情。
     /// </summary>
+    /// <returns>租户详情。</returns>
     [HttpGet("{tenantId:long}")]
     [PermissionAuthorize("tenant:read")]
     [ProducesResponseType(typeof(ApiResponse<TenantDetailDto>), StatusCodes.Status200OK)]
@@ -67,6 +70,7 @@ public sealed class TenantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 提交或更新实名认证资料。
     /// </summary>
+    /// <returns>提交的实名认证信息。</returns>
     [HttpPost("{tenantId:long}/verification")]
     [PermissionAuthorize("tenant:review")]
     [ProducesResponseType(typeof(ApiResponse<TenantVerificationDto>), StatusCodes.Status200OK)]
@@ -88,6 +92,7 @@ public sealed class TenantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 审核租户。
     /// </summary>
+    /// <returns>审核后的租户信息。</returns>
     [HttpPost("{tenantId:long}/review")]
     [PermissionAuthorize("tenant:review")]
     [ProducesResponseType(typeof(ApiResponse<TenantDto>), StatusCodes.Status200OK)]
@@ -106,6 +111,7 @@ public sealed class TenantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 创建或续费租户订阅。
     /// </summary>
+    /// <returns>创建或续费的订阅信息。</returns>
     [HttpPost("{tenantId:long}/subscriptions")]
     [PermissionAuthorize("tenant:subscription")]
     [ProducesResponseType(typeof(ApiResponse<TenantSubscriptionDto>), StatusCodes.Status200OK)]
@@ -125,6 +131,7 @@ public sealed class TenantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 套餐升降配。
     /// </summary>
+    /// <returns>更新后的订阅信息。</returns>
     [HttpPut("{tenantId:long}/subscriptions/{subscriptionId:long}/plan")]
     [PermissionAuthorize("tenant:subscription")]
     [ProducesResponseType(typeof(ApiResponse<TenantSubscriptionDto>), StatusCodes.Status200OK)]
@@ -147,6 +154,7 @@ public sealed class TenantsController(IMediator mediator) : BaseApiController
     /// <summary>
     /// 查询审核日志。
     /// </summary>
+    /// <returns>租户审核日志分页结果。</returns>
     [HttpGet("{tenantId:long}/audits")]
     [PermissionAuthorize("tenant:read")]
     [ProducesResponseType(typeof(ApiResponse<PagedResult<TenantAuditLogDto>>), StatusCodes.Status200OK)]
@@ -168,6 +176,7 @@ public sealed class TenantsController(IMediator mediator) : BaseApiController
     /// 配额校验并占用额度（门店/账号/短信/配送）。
     /// </summary>
     /// <remarks>需在请求头携带 X-Tenant-Id 对应的租户。</remarks>
+    /// <returns>配额校验结果。</returns>
     [HttpPost("{tenantId:long}/quotas/check")]
     [PermissionAuthorize("tenant:quota:check")]
     [ProducesResponseType(typeof(ApiResponse<QuotaCheckResultDto>), StatusCodes.Status200OK)]