为各服务接口补 /// 中文注释：swagger 恢复中文说明（admin 203 / user 93 / customer 12 / fishgame 4）

AdminSrc/AdminApi/AdminUser/AdminUserController.cs

@@ -32,6 +32,9 @@ namespace AdminApi.AdminUser
             _redisService = redisService;
         }
 
+        /// <summary>
+        /// 获取用户列表（管理员专用，增强版）
+        /// </summary>
         [HttpPost("GetUserList")]
         public async Task<PageResponse<UserListItemDto>> GetUserList(AdminUserListParam param)
         {
@@ -55,6 +58,9 @@ namespace AdminApi.AdminUser
             return this.ToPageResult(dtos, result.count);
         }
 
+        /// <summary>
+        /// 获取用户详情
+        /// </summary>
         [HttpGet("GetUserDetail")]
         public async Task<BaseResponse<UserEntity>> GetUserDetail(string userId)
         {
@@ -65,6 +71,9 @@ namespace AdminApi.AdminUser
             return this.ToResult(result);
         }
 
+        /// <summary>
+        /// 修改用户资产
+        /// </summary>
         [HttpPost("UpdateUserAssets")]
         public async Task<BaseResponse<string>> UpdateUserAssets(UpdateUserAssetsParam param)
         {
@@ -75,6 +84,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 获取用户统计数据
+        /// </summary>
         [HttpGet("GetUserStatistics")]
         public async Task<BaseResponse<UserStatisticsDto>> GetUserStatistics()
         {
@@ -82,6 +94,9 @@ namespace AdminApi.AdminUser
             return this.ToResult(MapToUserStatisticsDto(result));
         }
 
+        /// <summary>
+        /// 获取邮件统计数据
+        /// </summary>
         [HttpGet("GetEmailStatistics")]
         public async Task<BaseResponse<EmailStatisticsDto>> GetEmailStatistics()
         {
@@ -89,6 +104,9 @@ namespace AdminApi.AdminUser
             return this.ToResult(MapToEmailStatisticsDto(result));
         }
 
+        /// <summary>
+        /// 批量封号
+        /// </summary>
         [HttpPost("BatchBanUser")]
         public async Task<BaseResponse<string>> BatchBanUser(BatchBanUserParam param)
         {
@@ -99,6 +117,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 解封用户
+        /// </summary>
         [HttpGet("UnbanUser")]
         public async Task<BaseResponse<string>> UnbanUser(string userId)
         {
@@ -109,6 +130,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 批量发送邮件
+        /// </summary>
         [HttpPost("BatchSendEmail")]
         public async Task<BaseResponse<string>> BatchSendEmail(BatchSendEmailParam param)
         {
@@ -119,6 +143,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 注销用户
+        /// </summary>
         [HttpGet("CancelUser")]
         [Authorize]
         public async Task<BaseResponse<string>> CancelUser()
@@ -130,6 +157,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 删除用户
+        /// </summary>
         [HttpGet("DeleteUser")]
         [Authorize]
         public async Task<BaseResponse<string>> DeleteUser(string id)
@@ -141,6 +171,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 批量删除用户
+        /// </summary>
         [HttpPost("BatchDeleteUser")]
         [Authorize]
         public async Task<BaseResponse<string>> BatchDeleteUser([FromBody] BatchDeleteUserParam param)
@@ -152,6 +185,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 封号
+        /// </summary>
         [HttpPost("BanUser")]
         [Authorize]
         public async Task<BaseResponse<string>> BanUser([FromBody] BanUserParam param)
@@ -163,6 +199,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 更新用户信息
+        /// </summary>
         [HttpPost("UpdateUser")]
         [Authorize]
         public async Task<BaseResponse<string>> UpdateUser(UpdateUserDataParam param)
@@ -174,6 +213,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 发送邮件
+        /// </summary>
         [HttpPost("SendEmail")]
         [Authorize]
         public async Task<BaseResponse<string>> SendEmail(SendEmailParam param)
@@ -185,6 +227,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 分页查询邮件列表
+        /// </summary>
         [HttpPost("GetEmailList")]
         [Authorize]
         public async Task<PageResponse<EmailListItemDto>> GetEmailList([FromBody] EmailListQueryParam param)
@@ -216,6 +261,9 @@ namespace AdminApi.AdminUser
             return this.ToPageResult(dtos, (int)count);
         }
 
+        /// <summary>
+        /// 删除邮件
+        /// </summary>
         [HttpGet("DeleteEmail")]
         [Authorize]
         public async Task<BaseResponse<string>> DeleteEmail(string id)
@@ -227,6 +275,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.message ?? "删除失败");
         }
 
+        /// <summary>
+        /// 批量删除邮件
+        /// </summary>
         [HttpPost("BatchDeleteEmail")]
         [Authorize]
         public async Task<BaseResponse<string>> BatchDeleteEmail([FromBody] List<string> ids)
@@ -237,6 +288,9 @@ namespace AdminApi.AdminUser
             return this.ToResult($"删除完成：成功 {success} 条，失败 {fail} 条");
         }
 
+        /// <summary>
+        /// 设置用户类型
+        /// </summary>
         [HttpPost("SetUserType")]
         public async Task<BaseResponse<string>> SetUserType(string userId, int userType)
         {
@@ -247,6 +301,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 批量设置用户类型
+        /// </summary>
         [HttpPost("BatchSetUserType")]
         public async Task<BaseResponse<string>> BatchSetUserType([FromBody] BatchSetUserTypeParam param)
         {
@@ -257,6 +314,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 设置屏蔽状态
+        /// </summary>
         [HttpPost("SetBlackUser")]
         public async Task<BaseResponse<string>> SetBlackUser(string userId, bool isBlack)
         {
@@ -267,6 +327,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 批量设置屏蔽状态
+        /// </summary>
         [HttpPost("BatchSetBlackUser")]
         public async Task<BaseResponse<string>> BatchSetBlackUser([FromBody] BatchSetBlackUserParam param)
         {
@@ -277,6 +340,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 更新用户因子
+        /// </summary>
         [HttpPost("UpdateUserFactor")]
         public async Task<BaseResponse<string>> UpdateUserFactor([FromBody] UpdateUserFactorFlatParam param)
         {
@@ -297,6 +363,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 获取屏蔽用户因子配置
+        /// </summary>
         [HttpGet("GetBlackFactorConfig")]
         public async Task<BaseResponse<PlayerFactorDto>> GetBlackFactorConfig()
         {
@@ -304,6 +373,9 @@ namespace AdminApi.AdminUser
             return this.ToResult(MapToPlayerFactorDto(result));
         }
 
+        /// <summary>
+        /// 重置用户因子为默认值
+        /// </summary>
         [HttpPost("ResetUserFactor")]
         public async Task<BaseResponse<string>> ResetUserFactor(string userId)
         {
@@ -314,6 +386,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 初始化用户密码为123456
+        /// </summary>
         [HttpGet("InitUserPassword")]
         public async Task<BaseResponse<string>> InitUserPassword([FromQuery] string userId)
         {
@@ -324,6 +399,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 初始化保险箱密码为123456
+        /// </summary>
         [HttpGet("InitSafeBoxPassword")]
         public async Task<BaseResponse<string>> InitSafeBoxPassword([FromQuery] string userId)
         {
@@ -334,6 +412,9 @@ namespace AdminApi.AdminUser
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 获取用户因子列表
+        /// </summary>
         [HttpPost("GetUserFactorList")]
         public async Task<PageResponse<UserFactorListItemDto>> GetUserFactorList([FromBody] UserFactorListParam param)
         {
@@ -491,6 +572,9 @@ namespace AdminApi.AdminUser
 
 
 
+        /// <summary>
+        /// 获取用户背包道具
+        /// </summary>
         [HttpGet("GetUserProps")]
         public async Task<BaseResponse<List<BaseProductCount>>> GetUserProps(string userId)
         {
@@ -498,6 +582,9 @@ namespace AdminApi.AdminUser
             return this.ToResult(result);
         }
 
+        /// <summary>
+        /// 添加用户背包道具
+        /// </summary>
         [HttpPost("AddUserProp")]
         public async Task<BaseResponse<string>> AddUserProp(string userId, string propNumber, int count)
         {
@@ -506,6 +593,9 @@ namespace AdminApi.AdminUser
             return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 修改用户道具数量（数量设为0则删除）
+        /// </summary>
         [HttpPost("UpdateUserPropCount")]
         public async Task<BaseResponse<string>> UpdateUserPropCount(string userId, string propNumber, int count)
         {
@@ -514,6 +604,9 @@ namespace AdminApi.AdminUser
             return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 删除用户道具
+        /// </summary>
         [HttpPost("DeleteUserProp")]
         public async Task<BaseResponse<string>> DeleteUserProp(string userId, string propNumber)
         {
@@ -522,6 +615,9 @@ namespace AdminApi.AdminUser
             return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 同步所有玩家的等级（根据经验值+充值重新计算）
+        /// </summary>
         [HttpGet("SyncAllUserLevel")]
         public async Task<BaseResponse<string>> SyncAllUserLevel()
         {

AdminSrc/AdminApi/BackgroundOperation/BackgroundOperationController.cs

@@ -23,6 +23,9 @@ namespace AdminApi.BackgroundOperation
             _operationService = operationService;
         }
 
+        /// <summary>
+        /// 充值操作（不消耗平台资金，直接操作）
+        /// </summary>
         [HttpPost("charge")]
         public async Task<BaseResponse<string>> Charge([FromBody] BackgroundOperationRequest request)
         {
@@ -40,6 +43,9 @@ namespace AdminApi.BackgroundOperation
                 : this.ToFailResult<string>(message);
         }
 
+        /// <summary>
+        /// 扣除操作（必须用户有足够余额）
+        /// </summary>
         [HttpPost("deduct")]
         public async Task<BaseResponse<string>> Deduct([FromBody] BackgroundOperationRequest request)
         {
@@ -57,6 +63,9 @@ namespace AdminApi.BackgroundOperation
                 : this.ToFailResult<string>(message);
         }
 
+        /// <summary>
+        /// 查询操作日志（支持筛选）
+        /// </summary>
         [HttpGet("logs")]
         public async Task<PageResponse<BackgroundOperationLog>> GetLogs(
             string? adminUserId = null,
@@ -71,6 +80,9 @@ namespace AdminApi.BackgroundOperation
             return this.ToPageResult(data, total);
         }
 
+        /// <summary>
+        /// 搜索用户（通过ID或用户名）
+        /// </summary>
         [HttpGet("search-user")]
         public async Task<BaseResponse<SearchUserResponse>> SearchUser(string keyword)
         {

AdminSrc/AdminApi/BeautifulNumber/BeautifulNumberController.cs

@@ -23,6 +23,9 @@ namespace AdminApi.BeautifulNumber
             _beautifulNumberService = beautifulNumberService;
         }
 
+        /// <summary>
+        /// 获取靓号列表
+        /// </summary>
         [HttpGet("list")]
         public async Task<PageResponse<BeautifulNumberDto>> GetList([FromQuery] BeautifulNumberListParam param)
         {
@@ -33,6 +36,9 @@ namespace AdminApi.BeautifulNumber
             return this.ToPageResult(dtos, (int)result.count);
         }
 
+        /// <summary>
+        /// 获取可购买的靓号列表
+        /// </summary>
         [HttpGet("available")]
         public async Task<PageResponse<BeautifulNumberDto>> GetAvailableList([FromQuery] BeautifulNumberListParam param)
         {
@@ -44,6 +50,9 @@ namespace AdminApi.BeautifulNumber
             return this.ToPageResult(dtos, (int)result.count);
         }
 
+        /// <summary>
+        /// 查询靓号信息
+        /// </summary>
         [HttpGet("check/{number}")]
         public async Task<BaseResponse<BeautifulNumberDto>> CheckNumber(string number)
         {
@@ -70,6 +79,9 @@ namespace AdminApi.BeautifulNumber
             };
         }
 
+        /// <summary>
+        /// 删除靓号
+        /// </summary>
         [HttpPost("delete")]
         public async Task<BaseResponse<string>> Delete([FromBody] DeleteBeautifulNumberParam param)
         {
@@ -80,6 +92,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 设置为普通号
+        /// </summary>
         [HttpPost("set-normal")]
         public async Task<BaseResponse<string>> SetToNormal([FromBody] DeleteBeautifulNumberParam param)
         {
@@ -90,6 +105,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 冻结靓号
+        /// </summary>
         [HttpPost("freeze")]
         public async Task<BaseResponse<string>> Freeze([FromBody] DeleteBeautifulNumberParam param)
         {
@@ -100,6 +118,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 解冻靓号
+        /// </summary>
         [HttpPost("unfreeze")]
         public async Task<BaseResponse<string>> Unfreeze([FromBody] DeleteBeautifulNumberParam param)
         {
@@ -110,6 +131,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 修改价格
+        /// </summary>
         [HttpPost("update-price")]
         public async Task<BaseResponse<string>> UpdatePrice([FromBody] UpdateBeautifulNumberPriceParam param)
         {
@@ -120,6 +144,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 修改靓号（等级和价格）
+        /// </summary>
         [HttpPost("update-number")]
         public async Task<BaseResponse<string>> UpdateNumber([FromBody] UpdateBeautifulNumberParam param)
         {
@@ -130,6 +157,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 获取靓号规则列表
+        /// </summary>
         [HttpGet("rules")]
         public async Task<BaseResponse<List<BeautifulNumberRuleDto>>> GetRules()
         {
@@ -152,6 +182,9 @@ namespace AdminApi.BeautifulNumber
             };
         }
 
+        /// <summary>
+        /// 更新靓号规则
+        /// </summary>
         [HttpPost("update-rules")]
         public async Task<BaseResponse<string>> UpdateRules([FromBody] List<UpdateBeautifulNumberRuleParam> paramList)
         {
@@ -175,6 +208,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 初始化靓号规则
+        /// </summary>
         [HttpPost("init-rules")]
         public async Task<BaseResponse<string>> InitRules()
         {
@@ -185,6 +221,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 添加规则
+        /// </summary>
         [HttpPost("add-rule")]
         public async Task<BaseResponse<string>> AddRule([FromBody] BeautifulNumberRule rule)
         {
@@ -195,6 +234,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 更新规则
+        /// </summary>
         [HttpPost("update-rule")]
         public async Task<BaseResponse<string>> UpdateRule([FromBody] BeautifulNumberRule rule)
         {
@@ -205,6 +247,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 删除规则
+        /// </summary>
         [HttpPost("delete-rule")]
         public async Task<BaseResponse<string>> DeleteRule([FromBody] DeleteBeautifulNumberRuleParam param)
         {
@@ -215,6 +260,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 赠送靓号给用户
+        /// </summary>
         [HttpPost("give-to-user")]
         public async Task<BaseResponse<string>> GiveToUser([FromBody] GiveBeautifulNumberParam param)
         {
@@ -225,6 +273,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 初始化靓号（已售出不删除）
+        /// </summary>
         [HttpPost("init-numbers")]
         public async Task<BaseResponse<string>> InitNumbers()
         {
@@ -235,6 +286,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 添加单个靓号
+        /// </summary>
         [HttpPost("add-number")]
         public async Task<BaseResponse<string>> AddNumber([FromBody] AddBeautifulNumberParam param)
         {
@@ -245,6 +299,9 @@ namespace AdminApi.BeautifulNumber
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 批量添加靓号
+        /// </summary>
         [HttpPost("batch-add-numbers")]
         public async Task<BaseResponse<BatchAddResult>> BatchAddNumbers([FromBody] BatchAddBeautifulNumbersParam param)
         {

AdminSrc/AdminApi/Controllers/ImageUploadController.cs

@@ -17,6 +17,9 @@ namespace AdminApi.Controllers
             _imageUploadService = imageUploadService;
         }
 
+        /// <summary>
+        /// 兼容现有前端的通用上传入口。有 name 时按编号覆盖，否则上传到临时目录。
+        /// </summary>
         [HttpPost("upload")]
         public async Task<IActionResult> UploadFile(IFormFile file, [FromQuery] string? name = null)
         {
@@ -29,6 +32,9 @@ namespace AdminApi.Controllers
                 : Json(this.ToFailResult<object>(result.errorMessage));
         }
 
+        /// <summary>
+        /// 上传公告等临时图片。业务数据保存成功后，由对应业务服务移动到正式目录。
+        /// </summary>
         [HttpPost("upload/temp")]
         public async Task<IActionResult> UploadTempFile(IFormFile file)
         {
@@ -38,6 +44,9 @@ namespace AdminApi.Controllers
                 : Json(this.ToFailResult<object>(result.errorMessage));
         }
 
+        /// <summary>
+        /// 上传道具、碎片等配置图片，按“编号.png”直接覆盖正式图片。
+        /// </summary>
         [HttpPost("upload/config")]
         public async Task<IActionResult> UploadConfigFile(IFormFile file, [FromQuery] string? number = null)
         {

AdminSrc/AdminApi/Controllers/OperationLogController.cs

@@ -28,6 +28,9 @@ namespace AdminApi.Controllers
             _logRepo = logRepo;
         }
 
+        /// <summary>
+        /// 分页查询操作日志
+        /// </summary>
         [HttpPost("list")]
         public async Task<PageResponse<OperationLogDto>> GetList([FromBody] OperationLogQueryParam param)
         {
@@ -38,6 +41,9 @@ namespace AdminApi.Controllers
             return this.ToPageResult(dtos, (int)count);
         }
 
+        /// <summary>
+        /// 获取所有管理员（下拉选择用）
+        /// </summary>
         [HttpGet("admins")]
         public async Task<BaseResponse<List<AdminOptionDto>>> GetAdmins()
         {
@@ -46,6 +52,9 @@ namespace AdminApi.Controllers
             return this.ToResult(result);
         }
 
+        /// <summary>
+        /// 获取所有模块（下拉选择用）
+        /// </summary>
         [HttpGet("modules")]
         public BaseResponse<List<ModuleOptionDto>> GetModules()
         {
@@ -55,6 +64,9 @@ namespace AdminApi.Controllers
             return this.ToResult(modules);
         }
 
+        /// <summary>
+        /// 删除操作日志
+        /// </summary>
         [HttpPost("Delete")]
         public async Task<BaseResponse<string>> Delete(string id)
         {
@@ -65,6 +77,9 @@ namespace AdminApi.Controllers
                 return this.ToFailResult<string>("删除失败");
         }
 
+        /// <summary>
+        /// 批量删除操作日志
+        /// </summary>
         [HttpPost("BatchDelete")]
         public async Task<BaseResponse<string>> BatchDelete([FromBody] List<string> ids)
         {

AdminSrc/AdminApi/Customer/CustomerController.cs

@@ -22,6 +22,9 @@ namespace AdminApi.Customer
             _customerService = customerService;
         }
 
+        /// <summary>
+        /// 获取客服列表
+        /// </summary>
         [HttpGet("list")]
         public async Task<PageResponse<CustomerDto>> GetCustomerList([FromQuery] GetCustomerListParam param)
         {
@@ -30,6 +33,9 @@ namespace AdminApi.Customer
             return this.ToPageResult(dtos, result.total);
         }
 
+        /// <summary>
+        /// 根据ID获取客服详情
+        /// </summary>
         [HttpGet("{id}")]
         public async Task<BaseResponse<CustomerDto>> GetCustomerById(string id)
         {
@@ -38,6 +44,9 @@ namespace AdminApi.Customer
             return this.ToResult(dto);
         }
 
+        /// <summary>
+        /// 添加新客服
+        /// </summary>
         [HttpPost]
         public async Task<BaseResponse<CustomerDto>> AddCustomer([FromBody] AddCustomerParam param)
         {
@@ -53,6 +62,9 @@ namespace AdminApi.Customer
             }
         }
 
+        /// <summary>
+        /// 更新客服信息
+        /// </summary>
         [HttpPut]
         public async Task<BaseResponse<string>> UpdateCustomer([FromBody] UpdateCustomerParam param)
         {
@@ -67,6 +79,9 @@ namespace AdminApi.Customer
             }
         }
 
+        /// <summary>
+        /// 删除客服
+        /// </summary>
         [HttpDelete("{id}")]
         public async Task<BaseResponse<string>> DeleteCustomer(string id)
         {
@@ -81,6 +96,9 @@ namespace AdminApi.Customer
             }
         }
 
+        /// <summary>
+        /// 获取会话列表
+        /// </summary>
         [HttpGet("conversations")]
         public async Task<PageResponse<ConversationDto>> GetConversationList([FromQuery] GetConversationListParam param)
         {
@@ -89,6 +107,9 @@ namespace AdminApi.Customer
             return this.ToPageResult(dtos, result.total);
         }
 
+        /// <summary>
+        /// 根据ID获取会话详情
+        /// </summary>
         [HttpGet("conversation/{id}")]
         public async Task<BaseResponse<ConversationDto>> GetConversationById(string id)
         {
@@ -97,6 +118,9 @@ namespace AdminApi.Customer
             return this.ToResult(dto);
         }
 
+        /// <summary>
+        /// 删除会话及全部关联聊天记录。
+        /// </summary>
         [HttpDelete("conversation/{id}")]
         public async Task<BaseResponse<string>> DeleteConversation(string id)
         {
@@ -106,6 +130,9 @@ namespace AdminApi.Customer
                 : this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 获取会话聊天记录
+        /// </summary>
         [HttpGet("chatlog/{conversationId}")]
         public async Task<BaseResponse<List<MessageDto>>> GetChatLog(string conversationId)
         {
@@ -121,6 +148,9 @@ namespace AdminApi.Customer
             }
         }
 
+        /// <summary>
+        /// 删除单条消息
+        /// </summary>
         [HttpDelete("message/{id}")]
         public async Task<BaseResponse<string>> DeleteMessage(string id)
         {
@@ -135,6 +165,9 @@ namespace AdminApi.Customer
             }
         }
 
+        /// <summary>
+        /// 删除会话所有消息
+        /// </summary>
         [HttpDelete("messages/{conversationId}")]
         public async Task<BaseResponse<string>> DeleteAllMessages(string conversationId)
         {
@@ -149,6 +182,9 @@ namespace AdminApi.Customer
             }
         }
 
+        /// <summary>
+        /// 批量删除消息
+        /// </summary>
         [HttpPost("messages/delete-batch")]
         public async Task<BaseResponse<string>> DeleteMessagesBatch([FromBody] DeleteMessagesBatchRequest param)
         {

AdminSrc/AdminApi/EmptyRoomRate/EmptyRoomRateConfigController.cs

@@ -19,6 +19,9 @@ namespace AdminApi.EmptyRoomRate
             _emptyRoomRateConfigService = emptyRoomRateConfigService;
         }
 
+        /// <summary>
+        /// 获取空房率配置列表
+        /// </summary>
         [HttpGet("list")]
         public async Task<PageResponse<EmptyRoomRateDto>> GetList(
             [FromQuery] int page = 1,
@@ -33,6 +36,9 @@ namespace AdminApi.EmptyRoomRate
             return this.ToPageResult(dtos, (int)result.count);
         }
 
+        /// <summary>
+        /// 新增空房率配置
+        /// </summary>
         [HttpPost("add")]
         public async Task<BaseResponse<string>> Add([FromBody] AddEmptyRoomRateParam param)
         {
@@ -42,6 +48,9 @@ namespace AdminApi.EmptyRoomRate
             return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 修改空房率配置
+        /// </summary>
         [HttpPost("update")]
         public async Task<BaseResponse<string>> Update([FromBody] UpdateEmptyRoomRateParam param)
         {
@@ -51,6 +60,9 @@ namespace AdminApi.EmptyRoomRate
             return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 删除空房率配置
+        /// </summary>
         [HttpPost("delete")]
         public async Task<BaseResponse<string>> Delete([FromBody] DeleteEmptyRoomRateParam param)
         {
@@ -107,4 +119,4 @@ namespace AdminApi.EmptyRoomRate
     {
         public string Id { get; set; }
     }
-}
+}

AdminSrc/AdminApi/Faq/FaqController.cs

@@ -20,6 +20,9 @@ namespace AdminApi.Faq
         }
 
 
+        /// <summary>
+        /// 获取所有板块
+        /// </summary>
         [HttpGet("Categories")]
         public async Task<BaseCommonResponse> GetCategories()
         {
@@ -35,6 +38,9 @@ namespace AdminApi.Faq
             };
         }
 
+        /// <summary>
+        /// 获取板块树形结构
+        /// </summary>
         [HttpGet("CategoryTree")]
         public async Task<BaseCommonResponse> GetCategoryTree()
         {
@@ -48,6 +54,9 @@ namespace AdminApi.Faq
             };
         }
 
+        /// <summary>
+        /// 获取板块详情
+        /// </summary>
         [HttpGet("CategoryDetail")]
         public async Task<BaseResponse<FaqCategoryDto>> GetCategoryDetail(string id)
         {
@@ -58,6 +67,9 @@ namespace AdminApi.Faq
             return this.ToResult(MapToCategoryDto(category));
         }
 
+        /// <summary>
+        /// 添加板块
+        /// </summary>
         [HttpPost("AddCategory")]
         public async Task<BaseResponse<string>> AddCategory([FromBody] FaqCategory category)
         {
@@ -68,6 +80,9 @@ namespace AdminApi.Faq
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 更新板块
+        /// </summary>
         [HttpPost("UpdateCategory")]
         public async Task<BaseResponse<string>> UpdateCategory([FromBody] FaqCategory category)
         {
@@ -78,6 +93,9 @@ namespace AdminApi.Faq
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 删除板块
+        /// </summary>
         [HttpPost("DeleteCategory")]
         public async Task<BaseResponse<string>> DeleteCategory(string id)
         {
@@ -89,6 +107,9 @@ namespace AdminApi.Faq
         }
 
 
+        /// <summary>
+        /// 获取板块下的问题列表
+        /// </summary>
         [HttpGet("Questions")]
         public async Task<BaseCommonResponse> GetQuestions(string categoryId)
         {
@@ -104,6 +125,9 @@ namespace AdminApi.Faq
             };
         }
 
+        /// <summary>
+        /// 分页查询问题
+        /// </summary>
         [HttpPost("QuestionList")]
         public async Task<BaseCommonResponse> GetQuestionList([FromBody] FaqQueryParam param)
         {
@@ -118,6 +142,9 @@ namespace AdminApi.Faq
             };
         }
 
+        /// <summary>
+        /// 获取问题详情
+        /// </summary>
         [HttpGet("QuestionDetail")]
         public async Task<BaseResponse<FaqQuestionDto>> GetQuestionDetail(string id)
         {
@@ -128,6 +155,9 @@ namespace AdminApi.Faq
             return this.ToResult(MapToQuestionDto(question));
         }
 
+        /// <summary>
+        /// 添加问题
+        /// </summary>
         [HttpPost("AddQuestion")]
         public async Task<BaseResponse<string>> AddQuestion([FromBody] FaqQuestion question)
         {
@@ -138,6 +168,9 @@ namespace AdminApi.Faq
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 更新问题
+        /// </summary>
         [HttpPost("UpdateQuestion")]
         public async Task<BaseResponse<string>> UpdateQuestion([FromBody] FaqQuestion question)
         {
@@ -148,6 +181,9 @@ namespace AdminApi.Faq
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 删除问题
+        /// </summary>
         [HttpPost("DeleteQuestion")]
         public async Task<BaseResponse<string>> DeleteQuestion(string id)
         {

AdminSrc/AdminApi/Feedbacks/FeedbackManageController.cs

@@ -24,6 +24,9 @@ namespace AdminApi.Feedbacks
             _feedbackRepo = feedbackRepo;
         }
 
+        /// <summary>
+        /// 分页查询反馈列表
+        /// </summary>
         [HttpPost("List")]
         public async Task<PageResponse<FeedbackDto>> GetList([FromBody] FeedbackQueryParam param)
         {
@@ -32,6 +35,9 @@ namespace AdminApi.Feedbacks
             return this.ToPageResult(dtos, (int)result.count);
         }
 
+        /// <summary>
+        /// 获取反馈详情
+        /// </summary>
         [HttpGet("Detail")]
         public async Task<BaseResponse<FeedbackDetailDto>> GetDetail(string id)
         {
@@ -42,6 +48,9 @@ namespace AdminApi.Feedbacks
             return this.ToResult(MapToDetailDto(feedback));
         }
 
+        /// <summary>
+        /// 回复反馈
+        /// </summary>
         [HttpPost("Reply")]
         public async Task<BaseResponse<string>> Reply([FromBody] ReplyFeedbackParam param)
         {
@@ -62,6 +71,9 @@ namespace AdminApi.Feedbacks
                 return this.ToFailResult<string>("回复失败");
         }
 
+        /// <summary>
+        /// 删除反馈
+        /// </summary>
         [HttpPost("Delete")]
         public async Task<BaseResponse<string>> Delete(string id)
         {

AdminSrc/AdminApi/GameConfigs/ActivityConfigController.cs

@@ -23,7 +23,13 @@ namespace AdminApi.GameConfigs
             _redisService = redisService;
         }
 
+        /// <summary>
+        /// 获取活动配置
+        /// </summary>
         [HttpGet]
+        /// <summary>
+        /// 获取活动配置
+        /// </summary>
         [HttpGet("Get")]
         public async Task<BaseResponse<ActivityConfig>> Get()
         {
@@ -34,6 +40,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<ActivityConfig>("配置不存在");
         }
 
+        /// <summary>
+        /// 更新活动配置
+        /// </summary>
         [HttpPost("Update")]
         public async Task<BaseResponse<string>> Update(ActivityConfig config)
         {
@@ -44,6 +53,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 删除活动配置
+        /// </summary>
         [HttpPost("Delete")]
         public async Task<BaseResponse<string>> Delete()
         {
@@ -54,6 +66,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新战令配置
+        /// </summary>
         [HttpPost("UpdateBattleOrder")]
         public async Task<BaseResponse<string>> UpdateBattleOrder(BattleOrderConfig config)
         {
@@ -66,6 +81,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新救济金配置
+        /// </summary>
         [HttpPost("UpdateRelief")]
         public async Task<BaseResponse<string>> UpdateRelief(ReliefConfig config)
         {
@@ -78,6 +96,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新签到池配置
+        /// </summary>
         [HttpPost("UpdateSign")]
         public async Task<BaseResponse<string>> UpdateSign(SignActivityConfig config)
         {
@@ -90,6 +111,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新金币商城配置
+        /// </summary>
         [HttpPost("UpdateGoldShop")]
         public async Task<BaseResponse<string>> UpdateGoldShop(List<GoldShopConfig> configs)
         {
@@ -102,6 +126,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新钻石商城配置
+        /// </summary>
         [HttpPost("UpdateDiamondShop")]
         public async Task<BaseResponse<string>> UpdateDiamondShop(List<DiamondShopConfig> configs)
         {
@@ -114,6 +141,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新注册配置
+        /// </summary>
         [HttpPost("UpdateRegister")]
         public async Task<BaseResponse<string>> UpdateRegister(RegisterConfig config)
         {
@@ -126,6 +156,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新捕鱼返金币活动配置
+        /// </summary>
         [HttpPost("UpdateFishingReturn")]
         public async Task<BaseResponse<string>> UpdateFishingReturn(FishingReturnConfig config)
         {
@@ -138,6 +171,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 获取捕鱼返金币活动配置
+        /// </summary>
         [HttpGet("GetFishingReturn")]
         public async Task<BaseResponse<FishingReturnConfig>> GetFishingReturn()
         {
@@ -148,6 +184,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<FishingReturnConfig>("配置不存在");
         }
 
+        /// <summary>
+        /// 保存指定板块到 activityconfig.json（将当前 MongoDB 配置写回初始化文件）
+        /// </summary>
         [HttpGet("SaveSection/{sectionName}")]
         public async Task<BaseResponse<string>> SaveSection(string sectionName)
         {
@@ -197,6 +236,9 @@ namespace AdminApi.GameConfigs
             }
         }
 
+        /// <summary>
+        /// 导出活动配置指定板块为 JSON 文件
+        /// </summary>
         [HttpGet("ExportSection/{sectionName}")]
         public async Task<IActionResult> ExportSection(string sectionName)
         {

AdminSrc/AdminApi/GameConfigs/AdminRoomController.cs

@@ -38,6 +38,9 @@ namespace AdminApi.GameConfigs
             _logger = logger;
         }
 
+        /// <summary>
+        /// 获取所有房间列表
+        /// </summary>
         [HttpGet("GetAllRooms")]
         public async Task<PageResponse<RedisGameRoom>> GetAllRooms(
             int pageIndex = 1, 
@@ -97,6 +100,9 @@ namespace AdminApi.GameConfigs
             return this.ToPageResult(pagedRooms, total);
         }
 
+        /// <summary>
+        /// 获取所有象棋房间列表
+        /// </summary>
         [HttpGet("GetAllChessRooms")]
         public async Task<PageResponse<ChessGameRoom>> GetAllChessRooms(
             int pageIndex = 1,
@@ -124,6 +130,9 @@ namespace AdminApi.GameConfigs
             return this.ToPageResult(pagedRooms, total);
         }
 
+        /// <summary>
+        /// 获取象棋房间详情
+        /// </summary>
         [HttpGet("GetChessRoomDetail")]
         public async Task<BaseResponse<ChessGameRoom>> GetChessRoomDetail(string roomId)
         {
@@ -134,6 +143,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult(room);
         }
 
+        /// <summary>
+        /// 清空象棋房间玩家
+        /// </summary>
         [HttpGet("ClearChessRoom")]
         public async Task<BaseResponse<string>> ClearChessRoom(string roomId)
         {
@@ -176,6 +188,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult($"已清空房间 {roomId} 的所有玩家（{playerCount} 人）");
         }
 
+        /// <summary>
+        /// 后台将指定玩家踢出象棋房间。
+        /// </summary>
         [HttpGet("KickChessPlayer")]
         public async Task<BaseResponse<string>> KickChessPlayer(string roomId, string userId)
         {
@@ -200,6 +215,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult("踢人指令已提交");
         }
 
+        /// <summary>
+        /// 获取象棋房间统计（房间为空时自动初始化）
+        /// </summary>
         [HttpGet("GetChessRoomStatistics")]
         public async Task<BaseResponse<ChessRoomStatistics>> GetChessRoomStatistics()
         {
@@ -226,6 +244,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult(stats);
         }
 
+        /// <summary>
+        /// 删除象棋房间
+        /// </summary>
         [HttpGet("DeleteChessRoom")]
         public async Task<BaseResponse<string>> DeleteChessRoom(string roomId)
         {
@@ -238,6 +259,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult("已删除房间 " + roomId);
         }
 
+        /// <summary>
+        /// 为象棋房间添加机器人
+        /// </summary>
         [HttpGet("AddChessRobot")]
         public async Task<BaseResponse<string>> AddChessRobot(string roomId, int count)
         {
@@ -256,6 +280,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult("添加成功");
         }
 
+        /// <summary>
+        /// 设置象棋房间机器人数量
+        /// </summary>
         [HttpGet("SetChessRobot")]
         public async Task<BaseResponse<string>> SetChessRobot(string roomId, int count)
         {
@@ -274,6 +301,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult("设置成功");
         }
 
+        /// <summary>
+        /// 获取房间详情
+        /// </summary>
         [HttpGet("GetRoomDetail")]
         public async Task<BaseResponse<RedisGameRoom>> GetRoomDetail(string roomId)
         {
@@ -284,6 +314,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult(room);
         }
 
+        /// <summary>
+        /// 获取用户实时房间数据（捕鱼，读Redis房间内该用户数据）
+        /// </summary>
         [HttpGet("GetUserRoomRealtime")]
         [ResponseCache(NoStore = true, Location = ResponseCacheLocation.None)]
         public async Task<BaseResponse<UserRoomRealtimeDto>> GetUserRoomRealtime(string userId)
@@ -383,6 +416,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult(dto);
         }
 
+        /// <summary>
+        /// 为房间添加机器人
+        /// </summary>
         [HttpGet("AddRobot")]
         public async Task<BaseResponse<string>> AddRobot(string roomId, int count)
         {
@@ -411,6 +447,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult($"已为房间 {roomId} 添加 {count} 个机器人");
         }
 
+        /// <summary>
+        /// 设置房间机器人数量
+        /// </summary>
         [HttpGet("SetRobotCount")]
         public async Task<BaseResponse<string>> SetRobotCount(string roomId, int count)
         {
@@ -439,6 +478,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult($"已将房间 {roomId} 的机器人数量设置为 {count}");
         }
 
+        /// <summary>
+        /// 一键重生成所有机器人编号（GUID UserId + 8位编号）
+        /// </summary>
         [HttpGet("RegenerateAllBotIds")]
         public async Task<BaseResponse<string>> RegenerateAllBotIds()
         {
@@ -469,6 +511,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult($"已刷新 {totalBots} 个机器人编号（涉及 {rooms.Count(r => r?.Players?.Any(p => p.IsBot) == true)} 个房间）");
         }
 
+        /// <summary>
+        /// 清空房间（踢出所有玩家，含结算通知）
+        /// </summary>
         [HttpGet("ClearRoom")]
         public async Task<BaseResponse<string>> ClearRoom(string roomId)
         {
@@ -536,6 +581,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult(msg);
         }
 
+        /// <summary>
+        /// 获取房间统计
+        /// </summary>
         [HttpGet("GetRoomStatistics")]
         public async Task<BaseResponse<RoomStatistics>> GetRoomStatistics()
         {
@@ -563,6 +611,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult(stats);
         }
 
+        /// <summary>
+        /// 修复所有象棋房间状态和密码（按 robotCount 规则修正）
+        /// </summary>
         [HttpGet("RepairChessRooms")]
         public async Task<BaseResponse<string>> RepairChessRooms()
         {
@@ -584,6 +635,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult($"已修复 {fixedCount} 个象棋房间");
         }
 
+        /// <summary>
+        /// 初始化房间
+        /// </summary>
         [HttpGet("InitRooms")]
         public async Task<BaseResponse<string>> InitRooms()
         {
@@ -625,6 +679,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult("房间初始化成功");
         }
 
+        /// <summary>
+        /// 清空并重新初始化所有象棋房间
+        /// </summary>
         [HttpGet("ReInitChessRooms")]
         public async Task<BaseResponse<string>> ReInitChessRooms()
         {

AdminSrc/AdminApi/GameConfigs/BotConfigController.cs

@@ -17,6 +17,9 @@ namespace AdminApi.GameConfigs
             _botRepo = botRepo;
         }
 
+        /// <summary>
+        /// 获取所有机器人配置
+        /// </summary>
         [HttpGet("GetAll")]
         public async Task<BaseResponse<List<BotProfileEntity>>> GetAll()
         {
@@ -24,6 +27,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult(list.ToList());
         }
 
+        /// <summary>
+        /// 添加机器人配置
+        /// </summary>
         [HttpPost("Add")]
         public async Task<BaseResponse<string>> Add(BotProfileEntity entity)
         {
@@ -34,6 +40,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult("添加成功");
         }
 
+        /// <summary>
+        /// 更新机器人配置
+        /// </summary>
         [HttpPost("Update")]
         public async Task<BaseResponse<string>> Update(BotProfileEntity entity)
         {
@@ -50,6 +59,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult("更新成功");
         }
 
+        /// <summary>
+        /// 删除机器人配置
+        /// </summary>
         [HttpPost("Delete")]
         public async Task<BaseResponse<string>> Delete([FromQuery] string id)
         {

AdminSrc/AdminApi/GameConfigs/GameConfigController.cs

@@ -54,6 +54,9 @@ namespace AdminApi.GameConfigs
 
 
 
+        /// <summary>
+        /// 一键初始化所有配置（GameConfig + ActivityConfig）
+        /// </summary>
         [HttpGet("init-all")]
         public async Task<BaseResponse<string>> InitAll([FromServices] IActivityConfigService activityConfigService)
         {
@@ -64,6 +67,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult("所有配置初始化成功");
         }
 
+        /// <summary>
+        /// 初始化游戏配置（仅 GameConfig）
+        /// </summary>
         [HttpGet("init-game")]
         public async Task<BaseResponse<string>> InitGame()
         {
@@ -71,6 +77,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult("游戏配置初始化成功");
         }
 
+        /// <summary>
+        /// 初始化指定板块（从gameconfig.json读取该板块数据，不影响其他配置）
+        /// </summary>
         [HttpGet("InitSection/{sectionName}")]
         public async Task<BaseResponse<string>> InitSection(string sectionName)
         {
@@ -135,6 +144,9 @@ namespace AdminApi.GameConfigs
             }
         }
 
+        /// <summary>
+        /// 保存指定板块到 gameconfig.json（将当前 MongoDB 配置写回初始化文件）
+        /// </summary>
         [HttpGet("SaveSection/{sectionName}")]
         public async Task<BaseResponse<string>> SaveSection(string sectionName)
         {
@@ -213,6 +225,9 @@ namespace AdminApi.GameConfigs
             }
         }
 
+        /// <summary>
+        /// 初始化活动配置（仅 ActivityConfig）
+        /// </summary>
         [HttpGet("init-activity")]
         public async Task<BaseResponse<string>> InitActivity([FromServices] IActivityConfigService activityConfigService)
         {
@@ -220,6 +235,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult("活动配置初始化成功");
         }
 
+        /// <summary>
+        /// 初始化活动配置单个板块（从 activityconfig.json 读取）
+        /// </summary>
         [HttpGet("InitActivitySection/{sectionName}")]
         public async Task<BaseResponse<string>> InitActivitySection(string sectionName, [FromServices] IActivityConfigService activityConfigService)
         {
@@ -3317,6 +3335,9 @@ namespace AdminApi.GameConfigs
             }
         }
 
+        /// <summary>
+        /// 获取游戏配置
+        /// </summary>
         [HttpGet]
 
         public async Task<BaseResponse<GameConfig>> Get()
@@ -3329,6 +3350,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult(res);
         }
 
+        /// <summary>
+        /// 获取所有鱼类型列表（用于下拉选择）
+        /// </summary>
         [HttpGet("FishTypeList")]
         public async Task<BaseResponse<List<FishTypeConfig>>> GetFishTypeList()
         {
@@ -3341,6 +3365,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult(res.FishTypeConfigs.OrderBy(f => f.FishNumber).ToList());
         }
 
+        /// <summary>
+        /// 获取道具列表（用于发送邮件选择道具）
+        /// </summary>
         [HttpGet("PropList")]
         public async Task<BaseResponse<List<BaseProductCount>>> GetPropList()
         {
@@ -3365,6 +3392,9 @@ namespace AdminApi.GameConfigs
             return this.ToResult(propList);
         }
 
+        /// <summary>
+        /// 添加和修改游戏配置
+        /// </summary>
         [HttpPost("Update")]
         public async Task<BaseResponse<string>> Update(GameConfig param)
         {
@@ -3378,6 +3408,9 @@ namespace AdminApi.GameConfigs
         }
 
 
+        /// <summary>
+        /// 更新鱼种配置
+        /// </summary>
         [HttpPost("UpdateFishType")]
         public async Task<BaseResponse<string>> UpdateFishType(List<FishTypeConfig> configs)
         {
@@ -3391,6 +3424,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新房间配置
+        /// </summary>
         [HttpPost("UpdateRoom")]
         public async Task<BaseResponse<string>> UpdateRoom(List<RoomConfig> configs)
         {
@@ -3403,6 +3439,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新出鱼配置
+        /// </summary>
         [HttpPost("UpdateRoomFish")]
         public async Task<BaseResponse<string>> UpdateRoomFish(List<RoomFishConfig> configs)
         {
@@ -3416,6 +3455,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新鱼阵配置
+        /// </summary>
         [HttpPost("UpdateFishArray")]
         public async Task<BaseResponse<string>> UpdateFishArray(List<FishArrayConfig> configs)
         {
@@ -3429,6 +3471,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新用户等级配置
+        /// </summary>
         [HttpPost("UpdateUserLevel")]
         public async Task<BaseResponse<string>> UpdateUserLevel(List<UserLevelConfig> configs)
         {
@@ -3441,6 +3486,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新道具配置
+        /// </summary>
         [HttpPost("UpdateProp")]
         public async Task<BaseResponse<string>> UpdateProp(List<PropInfConfig> configs)
         {
@@ -3454,6 +3502,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新道具碎片配置
+        /// </summary>
         [HttpPost("UpdatePropFragment")]
         public async Task<BaseResponse<string>> UpdatePropFragment(List<PropFragmentConfig> configs)
         {
@@ -3484,6 +3535,9 @@ namespace AdminApi.GameConfigs
             }
         }
 
+        /// <summary>
+        /// 更新VIP等级配置
+        /// </summary>
         [HttpPost("UpdateVipLevel")]
         public async Task<BaseResponse<string>> UpdateVipLevel(List<VipLevelConfig> configs)
         {
@@ -3498,6 +3552,9 @@ namespace AdminApi.GameConfigs
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 独立更新刮刮卡配置，避免页面提交并覆盖整份游戏配置。
+        /// </summary>
         [HttpPost("UpdateScratchCard")]
         public async Task<BaseResponse<string>> UpdateScratchCard(List<ScratchCardConfig> configs)
         {
@@ -3514,6 +3571,9 @@ namespace AdminApi.GameConfigs
             return res.isok ? this.ToResult(res.msg) : this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新Boss道具掉落配置
+        /// </summary>
         [HttpPost("UpdateBossDrop")]
         public async Task<BaseResponse<string>> UpdateBossDrop(BossDropConfig config)
         {
@@ -3528,6 +3588,9 @@ namespace AdminApi.GameConfigs
 
 
 
+        /// <summary>
+        /// 导出指定板块的配置为JSON文件，产品数据自动从PropConfig富化
+        /// </summary>
         [HttpGet("ExportSection/{sectionName}")]
         public async Task<IActionResult> ExportSection(string sectionName)
         {

AdminSrc/AdminApi/GameConfigs/TempSpawnFishController.cs

@@ -25,6 +25,9 @@ namespace AdminApi.GameConfigs
             _logger = logger;
         }
 
+        /// <summary>
+        /// 指定房间强制出指定鱼（临时/调试）。无鉴权、GET 直接调用。
+        /// </summary>
         [HttpGet("SpawnFish")]
         public async Task<BaseResponse<string>> SpawnFish(
             string roomId,
@@ -95,4 +98,4 @@ namespace AdminApi.GameConfigs
             }
         }
     }
-}
+}

AdminSrc/AdminApi/LoginLogs/UserLoginLogController.cs

@@ -22,6 +22,9 @@ namespace AdminApi.LoginLogs
             _logRepo = logRepo;
         }
 
+        /// <summary>
+        /// 分页查询登录日志
+        /// </summary>
         [HttpPost("List")]
         public async Task<PageResponse<UserLoginLogDto>> GetList([FromBody] UserLoginLogQueryParam param)
         {
@@ -45,6 +48,9 @@ namespace AdminApi.LoginLogs
             return this.ToPageResult(dtos, (int)result.count);
         }
 
+        /// <summary>
+        /// 获取登录日志详情
+        /// </summary>
         [HttpGet("Detail")]
         public async Task<BaseResponse<UserLoginLogDto>> GetDetail(string id)
         {
@@ -55,6 +61,9 @@ namespace AdminApi.LoginLogs
             return this.ToResult(MapToDto(log));
         }
 
+        /// <summary>
+        /// 删除登录日志
+        /// </summary>
         [HttpPost("Delete")]
         public async Task<BaseResponse<string>> Delete(string id)
         {
@@ -65,6 +74,9 @@ namespace AdminApi.LoginLogs
                 return this.ToFailResult<string>("删除失败");
         }
 
+        /// <summary>
+        /// 批量删除登录日志
+        /// </summary>
         [HttpPost("BatchDelete")]
         public async Task<BaseResponse<string>> BatchDelete([FromBody] List<string> ids)
         {

AdminSrc/AdminApi/Lottery/LotteryController.cs

@@ -19,6 +19,9 @@ namespace AdminApi.Lottery
             _gameConfigService = gameConfigService;
         }
 
+        /// <summary>
+        /// 获取奖池抽奖活动列表（基于 ActivityConfig 中的 LotteryActivityConfig）
+        /// </summary>
         [HttpGet("list")]
         public async Task<BaseResponse<List<LotteryActivityVm>>> List()
         {
@@ -47,6 +50,9 @@ namespace AdminApi.Lottery
             return this.ToResult(new List<LotteryActivityVm> { vm });
         }
 
+        /// <summary>
+        /// 获取奖池抽奖活动详情
+        /// </summary>
         [HttpGet("detail")]
         public async Task<BaseResponse<LotteryActivityVm>> Detail([FromQuery] string activityId)
         {
@@ -71,6 +77,9 @@ namespace AdminApi.Lottery
             return this.ToResult(vm);
         }
 
+        /// <summary>
+        /// 保存奖池抽奖活动配置（新增或更新）
+        /// </summary>
         [HttpPost("save")]
         public async Task<BaseResponse<string>> Save([FromBody] LotteryActivityVm param)
         {
@@ -135,6 +144,9 @@ namespace AdminApi.Lottery
             LotteryPrizeProductHelper.Enrich(new LotteryActivityConfig { Pools = pools }, gameConfig);
         }
 
+        /// <summary>
+        /// 切换奖池抽奖活动开启/关闭状态
+        /// </summary>
         [HttpPost("toggle")]
         public async Task<BaseResponse<string>> Toggle([FromBody] LotteryToggleParam param)
         {
@@ -151,6 +163,9 @@ namespace AdminApi.Lottery
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 从独立模板初始化完整奖池配置。只在管理员明确点击时执行，其他活动配置不变。
+        /// </summary>
         [HttpPost("initialize")]
         public async Task<BaseResponse<string>> Initialize()
         {
@@ -191,6 +206,9 @@ namespace AdminApi.Lottery
                 : this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 删除奖池抽奖活动配置（重置为默认空配置）
+        /// </summary>
         [HttpDelete("delete")]
         public async Task<BaseResponse<string>> Delete()
         {

AdminSrc/AdminApi/Notices/NoticeController.cs

@@ -19,6 +19,9 @@ public class NoticeController : BaseController
         _noticeService = noticeService;
     }
 
+    /// <summary>
+    /// 添加系统公告
+    /// </summary>
     [HttpPost("add")]
     public async Task<BaseResponse<string>> AddNotice([FromBody] AddNoticeParam param)
     {
@@ -28,6 +31,9 @@ public class NoticeController : BaseController
             : this.ToFailResult<string>(result.msg);
     }
 
+    /// <summary>
+    /// 修改系统公告
+    /// </summary>
     [HttpPost("update")]
     public async Task<BaseResponse<string>> UpdateNotice([FromBody] UpdateNoticeParam param)
     {
@@ -37,6 +43,9 @@ public class NoticeController : BaseController
             : this.ToFailResult<string>(result.msg);
     }
 
+    /// <summary>
+    /// 删除公告
+    /// </summary>
     [HttpGet("delete")]
     public async Task<BaseResponse<string>> DeleteNotice([FromQuery] string id)
     {
@@ -46,6 +55,9 @@ public class NoticeController : BaseController
             : this.ToFailResult<string>(result.msg);
     }
 
+    /// <summary>
+    /// 获取系统公告列表
+    /// </summary>
     [HttpPost("list")]
     public async Task<PageResponse<NoticeListItemDto>> GetNoticeList([FromBody] GetNoticeListParam param)
     {
@@ -63,6 +75,9 @@ public class NoticeController : BaseController
         return this.ToPageResult(dtos, (int)count);
     }
 
+    /// <summary>
+    /// 根据ID获取公告详情
+    /// </summary>
     [HttpGet("get")]
     [AllowAnonymous]
     public async Task<BaseResponse<NoticeDto>> GetNotice([FromQuery] string id)

AdminSrc/AdminApi/System/SystemController.cs

@@ -25,6 +25,9 @@ namespace AdminApi.System
         }
 
 
+        /// <summary>
+        /// 添加系统用户
+        /// </summary>
         [HttpPost("user/add")]
         
         public async Task<BaseResponse<string>> AddUser(AddUserParam param)
@@ -35,6 +38,9 @@ namespace AdminApi.System
             else
                 return this.ToFailResult<string>(result.msg);
         }
+        /// <summary>
+        /// 修改系统用户
+        /// </summary>
         [HttpPost("user/update")]
         
         public async Task<BaseResponse<string>> UpdateUser(UpdateUserParam param)
@@ -45,6 +51,9 @@ namespace AdminApi.System
             else
                 return this.ToFailResult<string>(result.msg);
         }
+        /// <summary>
+        /// 修改系统用户头像
+        /// </summary>
         [HttpGet("user/update/icon")]
         
         public async Task<BaseResponse<string>> UpdateUserIcon(string id, string icon)
@@ -55,6 +64,9 @@ namespace AdminApi.System
             else
                 return this.ToFailResult<string>(result.msg);
         }
+        /// <summary>
+        /// 修改系统用户状态
+        /// </summary>
         [HttpGet("user/update/state")]
         
         public async Task<BaseResponse<string>> UpdateUserState(string id, int state)
@@ -65,6 +77,9 @@ namespace AdminApi.System
             else
                 return this.ToFailResult<string>(result.msg);
         }
+        /// <summary>
+        /// 删除用户
+        /// </summary>
         [HttpGet("user/delete")]
         
         public async Task<BaseResponse<string>> DeleteUser(string id)
@@ -75,6 +90,9 @@ namespace AdminApi.System
             else
                 return this.ToFailResult<string>(result.msg);
         }
+        /// <summary>
+        /// 用户登陆
+        /// </summary>
         [HttpGet("user/login")]
         [AllowAnonymous]
         public async Task<BaseResponse<AdminUserToken>> UserLogin(string userName, string password)
@@ -85,6 +103,9 @@ namespace AdminApi.System
             else
                 return this.ToFailResult<AdminUserToken>(result.msg);
         }
+        /// <summary>
+        /// 获取系统用户列表
+        /// </summary>
         [HttpPost("user/list")]
         
         public async Task<PageResponse<SystemUserDto>> GetUserList(GetUserListParam param)
@@ -94,6 +115,9 @@ namespace AdminApi.System
             return this.ToPageResult(dtos, (int)result.count);
         }
 
+        /// <summary>
+        /// 获取当前登陆用户信息
+        /// </summary>
         [HttpGet("user/getuser")]
         
         public async Task<BaseResponse<SystemUserDto>> GetUser()
@@ -122,6 +146,9 @@ namespace AdminApi.System
             };
         }
 
+        /// <summary>
+        /// 获取用户菜单
+        /// </summary>
         [HttpGet("user/nav")]
 
         public async Task<ListResponse<SystemNavigationResponse>> GetUserNav()
@@ -136,6 +163,9 @@ namespace AdminApi.System
 
 
 
+        /// <summary>
+        /// 添加系统角色
+        /// </summary>
         [HttpPost("role/add")]
 
         public async Task<BaseResponse<string>> AddRole(AddRoleParam param)
@@ -146,6 +176,9 @@ namespace AdminApi.System
             else
                 return this.ToFailResult<string>(result.msg);
         }
+        /// <summary>
+        /// 修改角色
+        /// </summary>
         [HttpPost("role/update")]
 
         public async Task<BaseResponse<string>> UpdateRole(UpdateRoleParam param)
@@ -156,6 +189,9 @@ namespace AdminApi.System
             else
                 return this.ToFailResult<string>(result.msg);
         }
+        /// <summary>
+        /// 修改角色菜单
+        /// </summary>
         [HttpPost("role/updatenav")]
 
         public async Task<BaseResponse<string>> UpdateRoleNav(UpdateRoleNavParam param)
@@ -167,6 +203,9 @@ namespace AdminApi.System
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 删除角色
+        /// </summary>
         [HttpGet("role/delete")]
 
         public async Task<BaseResponse<string>> DeleteRole(string id)
@@ -178,6 +217,9 @@ namespace AdminApi.System
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 获取系统角色列表
+        /// </summary>
         [HttpGet("role/list")]
         public async Task<ListResponse<SystemUserRoleDto>> GetRoleList(int page, int limit)
         {
@@ -197,6 +239,9 @@ namespace AdminApi.System
                 NavIds = entity.NavIds ?? new List<string>()
             };
         }
+        /// <summary>
+        /// 获取角色
+        /// </summary>
         [HttpGet("role/get")]
 
         public async Task<BaseResponse<SystemUserRoleDto>> GetUserRole(string id)
@@ -208,6 +253,9 @@ namespace AdminApi.System
 
 
 
+        /// <summary>
+        /// 添加系统菜单
+        /// </summary>
         [HttpPost("nav/add")]
 
         public async Task<BaseResponse<string>> AddNav(AddNavParam param)
@@ -218,6 +266,9 @@ namespace AdminApi.System
             else
                 return this.ToFailResult<string>(result.msg);
         }
+        /// <summary>
+        /// 修改菜单
+        /// </summary>
         [HttpPost("nav/update")]
 
         public async Task<BaseResponse<string>> UpdateNav(UpdateNavParam param)
@@ -229,6 +280,9 @@ namespace AdminApi.System
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 删除菜单
+        /// </summary>
         [HttpGet("nav/delete")]
 
         public async Task<BaseResponse<string>> DeleteNav(string id)
@@ -241,6 +295,9 @@ namespace AdminApi.System
         }
 
       
+        /// <summary>
+        /// 获取菜单列表
+        /// </summary>
         [HttpGet("nav/list")]
 
         public async Task<ListResponse<SystemNavigationResponse>> GetNavList(string? id="")
@@ -272,6 +329,9 @@ namespace AdminApi.System
 
 
 
+        /// <summary>
+        /// 添加系统字典
+        /// </summary>
         [HttpPost("dic/add")]
 
         public async Task<BaseResponse<string>> AddDic(AddDicParam param)
@@ -282,6 +342,9 @@ namespace AdminApi.System
             else
                 return this.ToFailResult<string>(result.msg);
         }
+        /// <summary>
+        /// 修改字典
+        /// </summary>
         [HttpPost("dic/update")]
 
         public async Task<BaseResponse<string>> UpdateDic(UpdateDicParam param)
@@ -293,6 +356,9 @@ namespace AdminApi.System
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 删除字典
+        /// </summary>
         [HttpGet("dic/delete")]
 
         public async Task<BaseResponse<string>> DeleteDic(string id)
@@ -305,6 +371,9 @@ namespace AdminApi.System
         }
 
 
+        /// <summary>
+        /// 获取字典列表
+        /// </summary>
         [HttpGet("dic/list")]
 
         public async Task<ListResponse<SystemDicResponse>> GetDicList(string id="")
@@ -312,6 +381,9 @@ namespace AdminApi.System
             var result = await _systemService.GetDicList(id);
             return this.ToListResult(result);
         }
+        /// <summary>
+        /// 获取字典列表
+        /// </summary>
         [HttpGet("dic/list/code")]
 
         public async Task<ListResponse<SystemDicResponse>> GetDicListByCode(string code)
@@ -319,6 +391,9 @@ namespace AdminApi.System
             var result = await _systemService.GetDicListByCode(code);
             return this.ToListResult(result);
         }
+        /// <summary>
+        /// 获取字典对象
+        /// </summary>
         [HttpGet("dic/get/code")]
 
         public async Task<BaseResponse<SystemDic>> GetDictByCode(string code)

AdminSrc/AdminApi/Task/TaskController.cs

@@ -1,4 +1,4 @@
-using AdminService.Tasks;
+using AdminService.Tasks;
 using AdminService.Tasks.Param;
 using Common;
 using CommonDomain;
@@ -19,17 +19,26 @@ namespace AdminApi.Task
             _taskService = taskService;
         }
 
+        /// <summary>
+        /// 初始化任务
+        /// </summary>
         [HttpGet("Init")]
         public async Task<string> Init()
         {
             return await _taskService.InitDefaultTasks();
         }
 
+        /// <summary>
+        /// 发放任务
+        /// </summary>
         [HttpGet("DayTaskReward")]
         public async Task<string> DayTaskReward()
         {
             return await _taskService.DayTaskReward();
         }
+        /// <summary>
+        /// 添加任务
+        /// </summary>
         [HttpPost("AddTask")]
         public async Task<BaseResponse<string>> AddTask([FromBody] GameTask param)
         {
@@ -39,6 +48,9 @@ namespace AdminApi.Task
             else
                 return this.ToFailResult<string>(res.msg);
         }
+        /// <summary>
+        /// 删除任务
+        /// </summary>
         [HttpGet("DeleteTask")]
         public async Task<BaseResponse<string>> DeleteTask(string id)
         {
@@ -48,6 +60,9 @@ namespace AdminApi.Task
             else
                 return this.ToFailResult<string>(res.msg);
         }
+        /// <summary>
+        /// 更新任务状态
+        /// </summary>
         [HttpGet("UpdateTaskState")]
         public async Task<BaseResponse<string>> UpdateTaskState(string id, int state)
         {
@@ -58,6 +73,9 @@ namespace AdminApi.Task
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 更新任务
+        /// </summary>
         [HttpPost("UpdateTask")]
         public async Task<BaseResponse<string>> UpdateTask([FromBody] GameTask param)
         {
@@ -68,6 +86,9 @@ namespace AdminApi.Task
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 获取任务列表
+        /// </summary>
         [HttpPost("GetTaskList")]
         public async Task<PageResponse<GameTask>> GetTaskList(GetTaskListParam param)
         {

AdminSrc/AdminApi/UserAssetChanges/UserAssetChangeController.cs

@@ -29,6 +29,9 @@ namespace AdminApi.UserAssetChanges
             _userMongo = userMongo;
         }
 
+        /// <summary>
+        /// 分页查询用户资产变动记录
+        /// </summary>
         [HttpPost("list")]
         public async Task<PageResponse<UserAssetChangeDto>> GetList([FromBody] UserAssetChangeQueryParam param)
         {
@@ -115,6 +118,9 @@ namespace AdminApi.UserAssetChanges
             return this.ToPageResult(dtos, (int)result.count);
         }
 
+        /// <summary>
+        /// 获取所有事件来源（下拉选择用）
+        /// </summary>
         [HttpGet("sources")]
         public BaseResponse<List<SourceOptionDto>> GetSources()
         {

CustomerSrc/CustomerApi/Controllers/CustomerController.cs

@@ -18,6 +18,9 @@ public class CustomerController : BaseController
         _customerService = customerService;
     }
 
+    /// <summary>
+    /// 发起会话 - 用户点击客服入口时调用
+    /// </summary>
     [HttpPost("start")]
     public async Task<BaseResponse<ConversationEntity>> StartConversation([FromBody] StartConversationParam param)
     {
@@ -28,6 +31,9 @@ public class CustomerController : BaseController
             return this.ToFailResult<ConversationEntity>(result.msg);
     }
 
+    /// <summary>
+    /// 发送消息 - 在会话中发送文字或图片消息
+    /// </summary>
     [HttpPost("message")]
     public async Task<BaseResponse<string>> SendMessage([FromBody] SendMessageParam param)
     {
@@ -38,6 +44,9 @@ public class CustomerController : BaseController
             return this.ToFailResult<string>(result.msg);
     }
 
+    /// <summary>
+    /// 获取消息列表 - 获取指定会话的所有聊天记录
+    /// </summary>
     [HttpGet("messages/{conversationId}")]
     public async Task<ListResponse<MessageEntity>> GetMessages(string conversationId)
     {
@@ -48,6 +57,9 @@ public class CustomerController : BaseController
             return this.ToListFailResult<MessageEntity>(result.msg);
     }
 
+    /// <summary>
+    /// 获取会话列表 - 获取所有会话或指定客服的会话
+    /// </summary>
     [HttpGet("conversations")]
     public async Task<ListResponse<ConversationResponse>> GetConversations([FromQuery] string? customerId)
     {
@@ -58,6 +70,9 @@ public class CustomerController : BaseController
             return this.ToListFailResult<ConversationResponse>(result.msg);
     }
 
+    /// <summary>
+    /// 获取当前用户的会话列表 - 获取当前登录用户的所有会话及聊天记录
+    /// </summary>
     [HttpGet("my-conversations")]
     public async Task<ListResponse<ConversationResponse>> GetMyConversations()
     {
@@ -69,6 +84,9 @@ public class CustomerController : BaseController
             return this.ToListFailResult<ConversationResponse>(result.msg);
     }
 
+    /// <summary>
+    /// 结束会话 - 关闭指定的会话
+    /// </summary>
     [HttpPost("end")]
     public async Task<BaseResponse<string>> EndConversation([FromBody] EndConversationParam param)
     {
@@ -79,7 +97,9 @@ public class CustomerController : BaseController
             return this.ToFailResult<string>(result.msg);
     }
 
-
+    /// <summary>
+    /// 获取在线客服列表 - 获取当前所有在线的客服人员
+    /// </summary>
     [HttpGet("online")]
     public async Task<ListResponse<CustomerEntity>> GetOnlineCustomers()
     {
@@ -90,6 +110,9 @@ public class CustomerController : BaseController
             return this.ToListFailResult<CustomerEntity>(result.msg);
     }
 
+    /// <summary>
+    /// 更新客服状态 - 设置客服的在线/离线状态
+    /// </summary>
     [HttpPost("status")]
     public async Task<BaseResponse<string>> UpdateCustomerStatus([FromBody] UpdateStatusParam param)
     {
@@ -100,6 +123,9 @@ public class CustomerController : BaseController
             return this.ToFailResult<string>(result.msg);
     }
 
+    /// <summary>
+    /// 标记会话已读 - 客服点击会话时调用，更新该用户所有会话的最后读取时间
+    /// </summary>
     [HttpPost("mark-read")]
     public async Task<BaseResponse<string>> MarkAsRead([FromBody] MarkReadParam param)
     {
@@ -110,6 +136,9 @@ public class CustomerController : BaseController
             return this.ToFailResult<string>(result.msg);
     }
 
+    /// <summary>
+    /// 获取聊天记录 - 获取指定会话的所有消息
+    /// </summary>
     [HttpGet("chatlog/{conversationId}")]
     public async Task<ListResponse<MessageEntity>> GetChatLog(string conversationId)
     {

CustomerSrc/CustomerApi/Controllers/ImageUploadController.cs

@@ -12,6 +12,9 @@ namespace CustomerApi.Controllers
             public string Path { get; set; } = "";
         }
 
+        /// <summary>
+        /// 上传图片 - 客服聊天中的图片上传
+        /// </summary>
         [HttpPost("upload")]
         public async Task<BaseResponse<ImageUploadResponse>> UploadFile(IFormFile file)
         {

FishGameSrc/FishGameHost/Controllers/PlayerController.cs

@@ -16,6 +16,9 @@ public class PlayerController : ControllerBase
         _jwtTools = jwtTools;
     }
 
+    /// <summary>
+    /// 玩家登录 - 生成 JWT token 并返回玩家基础信息（调试用）
+    /// </summary>
     [HttpPost("login")]
     public IActionResult Login([FromBody] PlayerLoginRequest request)
     {

FishGameSrc/FishGameHost/Controllers/RoomController.cs

@@ -23,6 +23,9 @@ namespace FishGameHost.Controllers
             public string WebSocketUrl { get; set; } = "";
         }
 
+        /// <summary>
+        /// 快速加入 - 根据游戏类型和等级查找一个不满员的房间，直接返回 WS 地址和 roomId
+        /// </summary>
         [HttpGet("QuickJoin")]
         public BaseResponse<QuickJoinResult> QuickJoin(int gameType, int level)
         {
@@ -54,6 +57,9 @@ namespace FishGameHost.Controllers
             return instances[0];
         }
 
+        /// <summary>
+        /// 分配房间到目标游戏服务器 - 返回指定房间对应的对局服务 WS 地址
+        /// </summary>
         [HttpGet("Assign")]
         public BaseResponse<string> AssignRoom(string roomId)
         {

FishGameSrc/FishGameHost/Controllers/TimeController.cs

@@ -6,6 +6,9 @@ namespace FishGameHost.Controllers;
 [Route("fishapi/[controller]")]
 public class TimeController : ControllerBase
 {
+    /// <summary>
+    /// 获取 FishApi 当前服务器时间，用于比较不同容器的系统时钟。
+    /// </summary>
     [HttpGet("GetDateTime")]
     [ResponseCache(NoStore = true, Location = ResponseCacheLocation.None)]
     public IActionResult GetDateTime()

UserSrc/UserApi/BeautifulNumber/BeautifulNumberController.cs

@@ -24,6 +24,9 @@ namespace UserApi.BeautifulNumber
         }
 
 
+        /// <summary>
+        /// 获取可购买的靓号列表
+        /// </summary>
         [HttpGet("available")]
         public async Task<PageResponse<BeautifulNumberDto>> GetAvailableList([FromQuery] BeautifulNumberListParam param)
         {
@@ -35,6 +38,9 @@ namespace UserApi.BeautifulNumber
             return this.ToPageResult(dtos, result.Count);
         }
 
+        /// <summary>
+        /// 查询靓号信息
+        /// </summary>
         [HttpGet("check/{number}")]
         public async Task<BaseResponse<BeautifulNumberDto>> CheckNumber(string number)
         {

UserSrc/UserApi/Dict/DictController.cs

@@ -16,6 +16,9 @@ namespace UserApi.Dict
             _dicRepo = dicRepo;
         }
 
+        /// <summary>
+        /// 根据编码获取字典项
+        /// </summary>
         [HttpGet("GetByCode")]
         public async Task<BaseResponse<SystemDic>> GetByCode(string code)
         {
@@ -23,6 +26,9 @@ namespace UserApi.Dict
             return this.ToResult(dic);
         }
 
+        /// <summary>
+        /// 根据编码获取字典子项列表 - 返回该字典编码下所有子项（按 Order 排序）
+        /// </summary>
         [HttpGet("GetListByCode")]
         public async Task<BaseResponse<List<SystemDic>>> GetListByCode(string code)
         {

UserSrc/UserApi/Faq/FaqController.cs

@@ -16,6 +16,9 @@ namespace UserApi.Faq
             _faqService = faqService;
         }
 
+        /// <summary>
+        /// 获取板块树形结构
+        /// </summary>
         [HttpGet("CategoryTree")]
         public async Task<BaseCommonResponse> GetCategoryTree()
         {
@@ -32,6 +35,9 @@ namespace UserApi.Faq
 
 
 
+        /// <summary>
+        /// 获取板块下的问题列表
+        /// </summary>
         [HttpGet("Questions")]
         public async Task<BaseCommonResponse> GetQuestions(string categoryId)
         {
@@ -47,6 +53,9 @@ namespace UserApi.Faq
             };
         }
 
+        /// <summary>
+        /// 分页查询问题
+        /// </summary>
         [HttpPost("QuestionList")]
         public async Task<BaseCommonResponse> GetQuestionList([FromBody] FaqQueryParam param)
         {
@@ -61,6 +70,9 @@ namespace UserApi.Faq
             };
         }
 
+        /// <summary>
+        /// 获取问题详情
+        /// </summary>
         [HttpGet("QuestionDetail")]
         public async Task<BaseResponse<FaqQuestionDto>> GetQuestionDetail(string id)
         {

UserSrc/UserApi/GameConfigs/ActivityConfigController.cs

@@ -19,6 +19,9 @@ namespace UserApi.GameConfigs
             _gameConfigService = gameConfigService;
         }
 
+        /// <summary>
+        /// 获取活动配置 - 一次性返回全部活动配置（含战令、抽奖的商品信息补全）
+        /// </summary>
         [HttpGet]
         public async Task<BaseResponse<ActivityConfig>> Get()
         {
@@ -30,6 +33,9 @@ namespace UserApi.GameConfigs
             return this.ToResult(config ?? new ActivityConfig());
         }
 
+        /// <summary>
+        /// 钻石商城列表
+        /// </summary>
         [HttpGet("diamondShopList")]
         public async Task<ListResponse<DiamondShopConfig>> GetDiamondShopList()
         {
@@ -37,6 +43,9 @@ namespace UserApi.GameConfigs
             return this.ToListResult(config?.DiamondShopConfigs ?? new List<DiamondShopConfig>());
         }
 
+        /// <summary>
+        /// 金币商城列表
+        /// </summary>
         [HttpGet("goldShopList")]
         public async Task<ListResponse<GoldShopConfig>> GetGoldShopList()
         {
@@ -44,6 +53,9 @@ namespace UserApi.GameConfigs
             return this.ToListResult(config?.GoldShopConfigs ?? new List<GoldShopConfig>());
         }
 
+        /// <summary>
+        /// 签到配置
+        /// </summary>
         [HttpGet("signConfig")]
         public async Task<BaseResponse<SignActivityConfig>> GetSignConfig()
         {
@@ -51,6 +63,9 @@ namespace UserApi.GameConfigs
             return this.ToResult(config?.SignActivityConfig ?? new SignActivityConfig());
         }
 
+        /// <summary>
+        /// 救济金配置
+        /// </summary>
         [HttpGet("reliefConfig")]
         public async Task<BaseResponse<ReliefConfig>> GetReliefConfig()
         {
@@ -61,6 +76,9 @@ namespace UserApi.GameConfigs
                 return this.ToFailResult<ReliefConfig>("配置不存在");
         }
 
+        /// <summary>
+        /// 注册配置
+        /// </summary>
         [HttpGet("registerConfig")]
         public async Task<BaseResponse<RegisterConfig>> GetRegisterConfig()
         {
@@ -71,6 +89,9 @@ namespace UserApi.GameConfigs
                 return this.ToFailResult<RegisterConfig>("配置不存在");
         }
 
+        /// <summary>
+        /// 捕鱼返金币活动配置
+        /// </summary>
         [HttpGet("fishingReturnConfig")]
         public async Task<BaseResponse<FishingReturnConfig>> GetFishingReturnConfig()
         {
@@ -81,6 +102,9 @@ namespace UserApi.GameConfigs
                 return this.ToFailResult<FishingReturnConfig>("配置不存在");
         }
 
+        /// <summary>
+        /// 战令配置
+        /// </summary>
         [HttpGet("battleOrderConfig")]
         public async Task<BaseResponse<BattleOrderConfig>> GetBattleOrderConfig()
         {
@@ -94,6 +118,9 @@ namespace UserApi.GameConfigs
                 return this.ToFailResult<BattleOrderConfig>("配置不存在");
         }
 
+        /// <summary>
+        /// 奖池抽奖活动配置
+        /// </summary>
         [HttpGet("lotteryConfig")]
         public async Task<BaseResponse<LotteryActivityConfig>> GetLotteryConfig()
         {
@@ -107,6 +134,9 @@ namespace UserApi.GameConfigs
                 return this.ToFailResult<LotteryActivityConfig>("配置不存在");
         }
 
+        /// <summary>
+        /// 排行榜奖励配置
+        /// </summary>
         [HttpGet("rankingRewardConfig")]
         public async Task<BaseResponse<RankingRewardConfig>> GetRankingRewardConfig()
         {

UserSrc/UserApi/GameConfigs/GameConfigController.cs

@@ -1,4 +1,4 @@
-using AutoMapper;
+using AutoMapper;
 using ChessGameDomain;
 using Common;
 using CommonDomain;
@@ -25,6 +25,9 @@ namespace UserApi.GameConfigs
 
 
 
+        /// <summary>
+        /// 获取游戏配置
+        /// </summary>
         [HttpGet]
 
         public async Task<BaseResponse<GameConfig>> Get()

UserSrc/UserApi/Hall/HallController.cs

@@ -37,6 +37,9 @@ namespace UserApi.Hall
         }
 
 
+        /// <summary>
+        /// 存入保险箱
+        /// </summary>
         [HttpGet("SaveSafeBox")]
         public async Task<BaseResponse<string>> SaveSafeBox(int gold)
         {
@@ -47,6 +50,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 取出保险箱
+        /// </summary>
         [HttpGet("GetSafeBox")]
         public async Task<BaseResponse<string>> GetSafeBox(long gold, string password)
         {
@@ -57,6 +63,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 设置保险箱密码
+        /// </summary>
         [HttpGet("SetSafeBoxPassword")]
         public async Task<BaseResponse<string>> SetSafeBoxPassword(string password)
         {
@@ -68,6 +77,9 @@ namespace UserApi.Hall
         }
 
 
+        /// <summary>
+        /// 重设保险箱密码 - 通过短信验证码重置
+        /// </summary>
         [HttpGet("ResetSafeBoxPassword")]
         public async Task<BaseResponse<string>> ResetSafeBoxPassword(string password, string code)
         {
@@ -78,6 +90,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 领取救济金
+        /// </summary>
         [HttpGet("GetRelief")]
         public async Task<BaseResponse<string>> GetRelief()
         {
@@ -89,6 +104,9 @@ namespace UserApi.Hall
         }
 
 
+        /// <summary>
+        /// 合成碎片
+        /// </summary>
         [HttpGet("SynthesisFragment")]
         public async Task<BaseResponse<BaseProductCount>> SynthesisFragment(string propNumber)
         {
@@ -102,6 +120,9 @@ namespace UserApi.Hall
 
      
 
+        /// <summary>
+        /// 购买道具
+        /// </summary>
         [HttpGet("BuyProp")]
         public async Task<BaseResponse<string>> BuyProp(string propNumber, int count = 1)
         {
@@ -112,6 +133,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 使用VIP经验包
+        /// </summary>
         [HttpGet("UseVipExp")]
         public async Task<BaseResponse<string>> UseVipExp(int count = 1)
         {
@@ -122,6 +146,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 购买金币
+        /// </summary>
         [HttpGet("BuyGold")]
         public async Task<BaseResponse<string>> BuyGold(string number, int count = 1)
         {
@@ -134,6 +161,9 @@ namespace UserApi.Hall
 
 
 
+        /// <summary>
+        /// 购买钻石
+        /// </summary>
         [HttpGet("BuyDiamond")]
         public async Task<BaseResponse<string>> BuyDiamond(string number, int count = 1)
         {
@@ -144,6 +174,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 签到
+        /// </summary>
         [HttpGet("SignIn")]
         public async Task<BaseResponse<SignRewardResult>> SignIn()
         {
@@ -154,6 +187,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<SignRewardResult>(res.msg);
         }
 
+        /// <summary>
+        /// 获取签到状态 - 返回当前签到进度与可领取状态
+        /// </summary>
         [HttpGet("GetSignStatus")]
         public async Task<BaseResponse<SignStatusResult>> GetSignStatus()
         {
@@ -162,6 +198,9 @@ namespace UserApi.Hall
         }
 
 
+        /// <summary>
+        /// 切换使用的炮台
+        /// </summary>
         [HttpGet("ChangeCannon")]
         public async Task<BaseResponse<string>> ChangeCannon(string number)
         {
@@ -175,6 +214,9 @@ namespace UserApi.Hall
 
 
 
+        /// <summary>
+        /// 切换使用的翅膀
+        /// </summary>
         [HttpGet("ChangeWing")]
         public async Task<BaseResponse<string>> ChangeWing(string number)
         {
@@ -185,6 +227,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 切换使用的战神
+        /// </summary>
         [HttpGet("ChangeGodWar")]
         public async Task<BaseResponse<string>> ChangeGodWar(string number)
         {
@@ -195,6 +240,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 卸载当前使用的炮台并切换为默认基础炮台（不会删除已拥有的炮台）
+        /// </summary>
         [HttpGet("UnloadCannon")]
         public async Task<BaseResponse<string>> UnloadCannon(string number)
         {
@@ -205,6 +253,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 卸载当前使用的翅膀（不会删除已拥有的翅膀）
+        /// </summary>
         [HttpGet("UnloadWing")]
         public async Task<BaseResponse<string>> UnloadWing(string number)
         {
@@ -215,6 +266,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(res.msg);
         }
 
+        /// <summary>
+        /// 卸载当前使用的战神（不会删除已拥有的战神）
+        /// </summary>
         [HttpGet("UnloadGodWar")]
         public async Task<BaseResponse<string>> UnloadGodWar(string number)
         {
@@ -227,6 +281,9 @@ namespace UserApi.Hall
 
 
 
+        /// <summary>
+        /// 领取Vip每日礼包
+        /// </summary>
         [HttpGet("GetVipDayGift")]
         public async Task<BaseResponse<GiftResponse>> GetVipDayGift()
         {
@@ -238,6 +295,9 @@ namespace UserApi.Hall
         }
 
 
+        /// <summary>
+        /// 领取Vip权益
+        /// </summary>
         [HttpGet("GetVipGift")]
         public async Task<BaseResponse<GiftResponse>> GetVipGift(int vipLevel)
         {
@@ -251,6 +311,9 @@ namespace UserApi.Hall
 
 
        
+        /// <summary>
+        /// 获取用户任务列表
+        /// </summary>
         [HttpGet("GetUserTaskList")]
         [Authorize]
         public async Task<ListResponse<UserTaskDto>> GetUserTaskList(int taskType)
@@ -282,6 +345,9 @@ namespace UserApi.Hall
                 Exp = entity.Exp
             };
         }
+        /// <summary>
+        /// 领取任务奖励
+        /// </summary>
         [HttpGet("DistributeRewards")]
         public async Task<BaseResponse<string>> DistributeRewards(string id)
         {
@@ -292,6 +358,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 获取资产变动记录
+        /// </summary>
         [HttpPost("GetUserRewardList")]
         public async Task<PageResponse<UserRewardDto>> GetUserRewardList(GetUserRewardListParam param)
         {
@@ -368,6 +437,9 @@ namespace UserApi.Hall
 
 
 
+        /// <summary>
+        /// 获取用户战令信息
+        /// </summary>
         [HttpGet("GetBattleOrder")]
         public async Task<BaseResponse<BattleOrderResponse>> GetBattleOrder()
         {
@@ -375,6 +447,9 @@ namespace UserApi.Hall
             return this.ToResult(result);
         }
 
+        /// <summary>
+        /// 获取各等级奖励领取状态
+        /// </summary>
         [HttpGet("GetBattleOrderLevelStatus")]
         public async Task<BaseResponse<BattleOrderLevelStatusResponse>> GetBattleOrderLevelStatus()
         {
@@ -382,6 +457,9 @@ namespace UserApi.Hall
             return this.ToResult(result);
         }
 
+        /// <summary>
+        /// 一键领取战令奖励
+        /// </summary>
         [HttpGet("ReceiveAllBattleOrderRewards")]
         public async Task<ListResponse<GiftConfig>> ReceiveAllBattleOrderRewards()
         {
@@ -392,6 +470,9 @@ namespace UserApi.Hall
                 return this.ToListFailResult<GiftConfig>(result.message);
         }
 
+        /// <summary>
+        /// 领取指定等级战令奖励
+        /// </summary>
         [HttpGet("ReceiveBattleOrderLevelReward")]
         public async Task<ListResponse<GiftConfig>> ReceiveBattleOrderLevelReward( int level)
         {
@@ -402,6 +483,9 @@ namespace UserApi.Hall
                 return this.ToListFailResult<GiftConfig>(result.message);
         }
 
+        /// <summary>
+        /// 购买战令等级
+        /// </summary>
         [HttpGet("BuyBattleOrderLevel")]
         public async Task<BaseResponse<BuyBattleOrderLevelResponse>> BuyBattleOrderLevel(int levelCount)
         {
@@ -416,6 +500,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<BuyBattleOrderLevelResponse>(result.message);
         }
 
+        /// <summary>
+        /// 购买战令进阶
+        /// </summary>
         [HttpGet("BuyBattleOrderAdvance")]
         public async Task<BaseResponse<BuyBattleOrderAdvanceResponse>> BuyBattleOrderAdvance(int type)
         {
@@ -431,6 +518,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<BuyBattleOrderAdvanceResponse>(result.message);
         }
 
+        /// <summary>
+        /// 一键领取所有任务奖励
+        /// </summary>
         [HttpGet("ReceiveAllTaskRewards")]
         public async Task<BaseResponse<object>> ReceiveAllTaskRewards()
         {
@@ -441,6 +531,9 @@ namespace UserApi.Hall
                 return this.ToFailResult<object>(result.message);
         }
 
+        /// <summary>
+        /// 获取用户排行榜
+        /// </summary>
         [HttpGet("GetRanking")]
         public async Task<BaseResponse<RankingResponse>> GetRanking(int type = 1)
         {
@@ -457,6 +550,9 @@ namespace UserApi.Hall
             return this.ToResult(result);
         }
 
+        /// <summary>
+        /// 使用大喇叭发送全服广播
+        /// </summary>
         [HttpGet("SendBroadcast")]
         public async Task<BaseResponse<string>> SendBroadcast(string message)
         {
@@ -467,6 +563,9 @@ namespace UserApi.Hall
         }
 
 
+        /// <summary>
+        /// 获取象棋分区总数
+        /// </summary>
         [AllowAnonymous]
         [HttpGet("GetChessRoomPartitionCount")]
         public async Task<BaseResponse<int>> GetChessRoomPartitionCount([FromServices] UserService.GameConfigs.IGameConfigService gameConfigService)

UserSrc/UserApi/Login/LoginController.cs

@@ -1,4 +1,4 @@
-using Common;
+using Common;
 using Common.Utils;
 using Common.WX;
 using Common.WX.Response;
@@ -24,6 +24,10 @@ namespace UserApi.Login
             _userService = userService;
             _weiXinPayHelper = weiXinPayHelper;
         }
+
+        /// <summary>
+        /// 获取 access_token - 获取微信小程序的接口调用凭证
+        /// </summary>
         [HttpGet("GetAccessToken")]
         public async Task<BaseResponse<string>> GetAccessToken()
         {
@@ -36,6 +40,10 @@ namespace UserApi.Login
                 return this.ToResult(result.accessToken);
             }
         }
+
+        /// <summary>
+        /// 登录凭证校验 - 用微信登录 code(js_code) 换取用户的会话信息
+        /// </summary>
         [HttpGet("GetSessionToken")]
         public async Task<BaseResponse<AccessTokenResponse>> GetSessionToken(string js_code)
         {
@@ -47,6 +55,7 @@ namespace UserApi.Login
                 return this.ToResult(result.response);
             }
         }
+
         private string GetClientIp()
         {
             var forwarded = HttpContext.Request.Headers["X-Forwarded-For"].FirstOrDefault();
@@ -55,6 +64,9 @@ namespace UserApi.Login
             return HttpContext.Connection.RemoteIpAddress?.ToString() ?? "";
         }
 
+        /// <summary>
+        /// 注册用户通过微信账号
+        /// </summary>
         [HttpPost("registerWX")]
 
         public async Task<BaseResponse<UserToken>> RegisterWX(RegisterUserWeiXinParam param)
@@ -63,6 +75,10 @@ namespace UserApi.Login
             var result = await _userService.RegisterWeiXin(param, ip);
             return this.ToResult(result);
         }
+
+        /// <summary>
+        /// 注册用户通过短信和验证码
+        /// </summary>
         [HttpPost("register")]
 
         public async Task<BaseResponse<UserToken>> Register(RegisterUserParam param)
@@ -74,6 +90,10 @@ namespace UserApi.Login
             else
                 return this.ToFailResult<UserToken>(result.msg);
         }
+
+        /// <summary>
+        /// 发送短信验证码
+        /// </summary>
         [HttpGet("SendMobileCode")]
 
         public async Task<BaseResponse<string>> SendMobileCode(string mobile)
@@ -84,6 +104,10 @@ namespace UserApi.Login
             else
                 return this.ToFailResult<string>(result.msg);
         }
+
+        /// <summary>
+        /// 微信用户登陆
+        /// </summary>
         [HttpGet("LoginWx")]
         public async Task<BaseResponse<UserToken>> LoginWx(string openId)
         {
@@ -91,6 +115,10 @@ namespace UserApi.Login
             var result = await _userService.LoginWx(openId, ip);
             return this.ToResult(result);
         }
+
+        /// <summary>
+        /// 用户登陆 - 手机号 + 验证码登录
+        /// </summary>
         [HttpGet("Login")]
         public async Task<BaseResponse<UserToken>> Login(string mobile, string code)
         {
@@ -108,6 +136,10 @@ namespace UserApi.Login
             else
                 return this.ToFailResult<UserToken>(result.msg);
         }
+
+        /// <summary>
+        /// 密码登录 - 手机号 + 密码登录
+        /// </summary>
         [HttpGet("LoginByPassword")]
         public async Task<BaseResponse<UserToken>> LoginByPassword(string mobile, string password)
         {
@@ -125,6 +157,9 @@ namespace UserApi.Login
             return this.ToFailResult<UserToken>(result.msg);
         }
 
+        /// <summary>
+        /// 获取服务器时间 - 返回服务器本地时间与 UTC 时间，用于客户端校准
+        /// </summary>
         [HttpGet("GetDateTime")]
         public async Task<BaseResponse<DateTimeResponse>> GetDateTime()
         {
@@ -160,6 +195,10 @@ namespace UserApi.Login
                 Container = Environment.MachineName
             });
         }
+
+        /// <summary>
+        /// 修改密码 - 通过短信验证码重置密码
+        /// </summary>
         [HttpGet("ResetPassword")]
         public async Task<BaseResponse<string>> ResetPassword(string mobile, string password, string code)
         {

UserSrc/UserApi/Lottery/LotteryController.cs

@@ -25,6 +25,9 @@ namespace UserApi.Lottery
             _gameConfigService = gameConfigService;
         }
 
+        /// <summary>
+        /// 获取奖池抽奖活动配置（含用户已抽状态）
+        /// </summary>
         [HttpGet("Config")]
         public async Task<BaseResponse<LotteryConfigResponse>> GetConfig()
         {
@@ -42,6 +45,9 @@ namespace UserApi.Lottery
             });
         }
 
+        /// <summary>
+        /// 抽奖 - 进行一次奖池抽奖（poolType 指定奖池类型）
+        /// </summary>
         [HttpGet("Draw")]
         public async Task<BaseResponse<LotteryDrawResponse>> Draw([FromQuery] int poolType = 0)
         {
@@ -60,6 +66,9 @@ namespace UserApi.Lottery
             });
         }
 
+        /// <summary>
+        /// 获取用户抽奖状态
+        /// </summary>
         [HttpGet("UserStatus")]
         public async Task<BaseResponse<LotteryUserStatus>> UserStatus()
         {
@@ -67,6 +76,9 @@ namespace UserApi.Lottery
             return this.ToResult(status);
         }
 
+        /// <summary>
+        /// 获取用户已抽中的奖品列表
+        /// </summary>
         [HttpGet("DrawnPrizes")]
         public async Task<BaseResponse<List<string>>> DrawnPrizes()
         {

UserSrc/UserApi/Notices/NoticeController.cs

@@ -23,6 +23,9 @@ namespace UserApi.Notices
             _noticeService = noticeService;
         }
 
+        /// <summary>
+        /// 获取系统公告列表（分页）
+        /// </summary>
         [HttpPost("list")]
         public async Task<PageResponse<NoticeDto>> GetNoticeList(GetNoticeListParam param)
         {
@@ -41,6 +44,9 @@ namespace UserApi.Notices
             return this.ToPageResult(dtos, (int)result.count);
         }
 
+        /// <summary>
+        /// 根据ID获取公告详情
+        /// </summary>
         [HttpGet("get")]
         [AllowAnonymous]
         public async Task<BaseResponse<NoticeDto>> GetNotice(string id)
@@ -64,6 +70,9 @@ namespace UserApi.Notices
             return this.ToResult(dto);
         }
 
+        /// <summary>
+        /// 获取一个最新的公告
+        /// </summary>
         [HttpGet("get/newone")]
         [AllowAnonymous]
         public async Task<BaseResponse<NoticeDto>> GetNewOne()

UserSrc/UserApi/ScratchCard/ScratchCardController.cs

@@ -17,6 +17,9 @@ namespace UserApi.ScratchCard
             _scratchCardService = scratchCardService;
         }
 
+        /// <summary>
+        /// 使用刮刮卡抽奖
+        /// </summary>
         [HttpGet("draw")]
         public async Task<BaseResponse<ScratchCardResult>> Draw()
         {

UserSrc/UserApi/SummonCard/SummonCardController.cs

@@ -17,6 +17,9 @@ namespace UserApi.SummonCard
             _summonCardService = summonCardService;
         }
 
+        /// <summary>
+        /// 使用召唤卡
+        /// </summary>
         [HttpGet("use")]
         public async Task<BaseResponse<string>> Use()
         {

UserSrc/UserApi/User/FeedbackController.cs

@@ -23,6 +23,9 @@ namespace UserApi.User
             _feedbackService = feedbackService;
         }
 
+        /// <summary>
+        /// 提交反馈
+        /// </summary>
         [HttpPost("Submit")]
         public async Task<BaseResponse<string>> Submit([FromBody] AddFeedbackParam param)
         {
@@ -33,6 +36,9 @@ namespace UserApi.User
                 return this.ToFailResult<string>("提交失败");
         }
 
+        /// <summary>
+        /// 获取我的反馈列表
+        /// </summary>
         [HttpGet("MyList")]
         public async Task<PageResponse<FeedbackDto>> GetMyList(int pageIndex = 1, int pageSize = 10)
         {
@@ -54,6 +60,9 @@ namespace UserApi.User
             return this.ToPageResult(dtos, (int)result.count);
         }
 
+        /// <summary>
+        /// 获取反馈详情
+        /// </summary>
         [HttpGet("Detail")]
         public async Task<BaseResponse<FeedbackDetailDto>> GetDetail(string id)
         {

UserSrc/UserApi/User/ImageUploadController.cs

@@ -15,6 +15,9 @@ namespace UserApi.Controllers
             _imageUploadService = imageUploadService;
         }
 
+        /// <summary>
+        /// 文件上传
+        /// </summary>
         [HttpPost("upload")]
         public async Task<IActionResult> UploadFile(IFormFile file)
         {

UserSrc/UserApi/User/UserController.cs

@@ -25,6 +25,9 @@ namespace UserApi.User
             _userService = userService;
         }
 
+        /// <summary>
+        /// 实名认证
+        /// </summary>
         [HttpGet("RealNameAuth")]
         [Authorize]
         public async Task<BaseResponse<string>> RealNameAuth(string realName, string idCard)
@@ -36,6 +39,9 @@ namespace UserApi.User
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 修改名称
+        /// </summary>
         [HttpGet("UpdateUserName")]
         [Authorize]
         public async Task<BaseResponse<string>> UpdateUserName(string userName)
@@ -47,6 +53,9 @@ namespace UserApi.User
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 绑定微信
+        /// </summary>
         [HttpGet("BindWX")]
         [Authorize]
         public async Task<BaseResponse<string>> BindWX(string openId)
@@ -58,6 +67,9 @@ namespace UserApi.User
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 绑定手机号
+        /// </summary>
         [HttpGet("BindMobile")]
         [Authorize]
         public async Task<BaseResponse<string>> BindMobile(string mobile, string code)
@@ -69,6 +81,9 @@ namespace UserApi.User
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 更新头像
+        /// </summary>
         [HttpGet("UpdateAvatar")]
         [Authorize]
         public async Task<BaseResponse<string>> UpdateAvatar(string avatarUrl)
@@ -80,6 +95,9 @@ namespace UserApi.User
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 修改头像框
+        /// </summary>
         [HttpGet("UpdateAvatarFrame")]
         [Authorize]
         public async Task<BaseResponse<string>> UpdateAvatarFrame(string avatarFrame)
@@ -91,6 +109,9 @@ namespace UserApi.User
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 获取用户信息
+        /// </summary>
         [HttpGet("GetUser")]
         [Authorize]
         public async Task<BaseResponse<UserEntity>> GetUser(string userid)
@@ -101,6 +122,9 @@ namespace UserApi.User
             return this.ToResult(result);
         }
 
+        /// <summary>
+        /// 获取当前用户资产和背包
+        /// </summary>
         [HttpGet("GetUserAssets")]
         public async Task<BaseResponse<UserAssetsResponse>> GetUserAssets()
         {
@@ -113,6 +137,9 @@ namespace UserApi.User
             });
         }
 
+        /// <summary>
+        /// 获取用户列表（分页查询）
+        /// </summary>
         [HttpPost("GetUserList")]
         [Authorize]
         public async Task<PageResponse<UserListItemDto>> GetUserList(BaseListPageParam param)
@@ -130,6 +157,9 @@ namespace UserApi.User
             return this.ToPageResult(dtos, (int)result.count);
         }
 
+        /// <summary>
+        /// 发送邮件
+        /// </summary>
         [HttpPost("SendEmail")]
         [Authorize]
         public async Task<BaseResponse<string>> SendEmail(SendEmailParam param)
@@ -141,6 +171,9 @@ namespace UserApi.User
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 获取邮件详情（未读会变为已读）
+        /// </summary>
         [HttpGet("GetEmail")]
         [Authorize]
         public async Task<BaseResponse<EmailDto>> GetEmail(string id)
@@ -166,6 +199,9 @@ namespace UserApi.User
             return this.ToResult(dto);
         }
 
+        /// <summary>
+        /// 领取邮件奖励
+        /// </summary>
         [HttpGet("RewardEmail")]
         [Authorize]
         public async Task<BaseResponse<RewardEmailResponse>> RewardEmail(int type, string? id = "")
@@ -177,6 +213,9 @@ namespace UserApi.User
                 return this.ToFailResult<RewardEmailResponse>(result.msg);
         }
 
+        /// <summary>
+        /// 删除邮件
+        /// </summary>
         [HttpGet("DeleteEmail")]
         [Authorize]
         public async Task<BaseResponse<string>> DeleteEmail(int type, string? id = "")
@@ -188,6 +227,9 @@ namespace UserApi.User
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 一键阅读 - 把所有未读邮件标记为已读
+        /// </summary>
         [HttpGet("ReadEmailMore")]
         [Authorize]
         public async Task<BaseResponse<string>> ReadEmailMore()
@@ -199,6 +241,9 @@ namespace UserApi.User
                 return this.ToFailResult<string>(result.msg);
         }
 
+        /// <summary>
+        /// 获取未读邮件数量
+        /// </summary>
         [HttpGet("GetNoReadCount")]
         [Authorize]
         public async Task<BaseResponse<long>> GetNoReadCount()
@@ -207,6 +252,9 @@ namespace UserApi.User
             return this.ToResult(result);
         }
 
+        /// <summary>
+        /// 获取邮件列表（分页）
+        /// </summary>
         [HttpPost("GetEmailByPage")]
         [Authorize]
         public async Task<PageResponse<UserEmail>> GetEmailByPage(GetEmailPageParam param)
@@ -217,6 +265,9 @@ namespace UserApi.User
         }
 
 
+        /// <summary>
+        /// 获取捕鱼返利信息
+        /// </summary>
         [HttpGet("GetFishingReturnInfo")]
         [Authorize]
         public async Task<BaseResponse<FishingReturnDto>> GetFishingReturnInfo()
@@ -232,6 +283,9 @@ namespace UserApi.User
             return this.ToResult(dto);
         }
 
+        /// <summary>
+        /// 领取捕鱼返利金币
+        /// </summary>
         [HttpGet("ClaimFishingReturn")]
         [Authorize]
         public async Task<BaseResponse<ClaimFishingReturnDto>> ClaimFishingReturn()