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

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)]