添加Swagger/OpenAPI依赖并更新用户账户管理相关的API文档注释，优化用户和管理员账户控制器的接口描述，移除不必要的字段和参数，调整数据库映射以简化用户账户管理逻辑。

src/main/java/com/gameplatform/server/model/dto/account/AccountCreateRequest.java

@@ -1,20 +1,32 @@
 package com.gameplatform.server.model.dto.account;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.*;
 
+@Schema(description = "账户创建请求")
 public class AccountCreateRequest {
-    @NotBlank
+    @Schema(description = "用户类型", example = "AGENT", allowableValues = {"ADMIN", "AGENT"})
+    @NotBlank(message = "userType 不能为空")
+    @Pattern(regexp = "^(ADMIN|AGENT)$", message = "userType 只能是 ADMIN 或 AGENT")
     private String userType; // ADMIN | AGENT
-    @NotBlank
-    @Size(min = 3, max = 64)
+
+    @Schema(description = "用户名", example = "newuser", minLength = 3, maxLength = 64)
+    @NotBlank(message = "username 不能为空")
+    @Size(min = 3, max = 64, message = "username 长度必须在 3-64 字符之间")
+    @Pattern(regexp = "^[a-zA-Z0-9_]+$", message = "username 只能包含字母、数字、下划线")
     private String username;
 
-    private String status = "ENABLED"; // ENABLED | DISABLED
-    @NotBlank
-    @Size(min = 6, max = 128)
+    @Schema(description = "密码", example = "123456", minLength = 6, maxLength = 128)
+    @NotBlank(message = "password 不能为空")
+    @Size(min = 6, max = 128, message = "password 长度必须在 6-128 字符之间")
     private String password;
+
+    @Schema(description = "账户状态", example = "ENABLED", allowableValues = {"ENABLED", "DISABLED"}, defaultValue = "ENABLED")
+    private String status;
+
+    @Schema(description = "积分余额", example = "1000", minimum = "0", defaultValue = "0")
     @Min(0)
-    private Long pointsBalance = 0L; // for AGENT
+    private Long pointsBalance; // for AGENT
 
     public String getUserType() { return userType; }
     public void setUserType(String userType) { this.userType = userType; }

src/main/java/com/gameplatform/server/model/dto/account/AccountResponse.java

@@ -1,15 +1,30 @@
 package com.gameplatform.server.model.dto.account;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import java.time.LocalDateTime;
 
+@Schema(description = "账户响应")
 public class AccountResponse {
+    @Schema(description = "账户ID", example = "1")
     private Long id;
+
+    @Schema(description = "用户类型", example = "AGENT", allowableValues = {"ADMIN", "AGENT"})
     private String userType;
+
+    @Schema(description = "用户名", example = "newuser")
     private String username;
 
+    @Schema(description = "账户状态", example = "ENABLED", allowableValues = {"ENABLED", "DISABLED"})
     private String status;
+
+    @Schema(description = "积分余额", example = "1000")
     private Long pointsBalance;
+
+    @Schema(description = "创建时间", example = "2025-08-24T18:30:00.000")
     private LocalDateTime createdAt;
+
+    @Schema(description = "更新时间", example = "2025-08-24T18:30:00.000")
     private LocalDateTime updatedAt;
 
     public Long getId() { return id; }

src/main/java/com/gameplatform/server/model/dto/account/AccountUpdateRequest.java

@@ -1,10 +1,13 @@
 package com.gameplatform.server.model.dto.account;
 
-import jakarta.validation.constraints.Size;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.Pattern;
 
+@Schema(description = "账户更新请求")
 public class AccountUpdateRequest {
-
-    private String status; // ENABLED | DISABLED
+    @Schema(description = "账户状态", example = "ENABLED", allowableValues = {"ENABLED", "DISABLED"})
+    @Pattern(regexp = "^(ENABLED|DISABLED)$", message = "status 只能是 ENABLED 或 DISABLED")
+    private String status;
 
 
     public String getStatus() { return status; }

src/main/java/com/gameplatform/server/model/dto/account/ResetPasswordRequest.java

@@ -1,12 +1,17 @@
 package com.gameplatform.server.model.dto.account;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.Size;
 
+@Schema(description = "重置密码请求")
 public class ResetPasswordRequest {
-    @NotBlank
-    @Size(min = 6, max = 128)
+    @Schema(description = "新密码", example = "NewPassword123!", minLength = 6, maxLength = 128)
+    @NotBlank(message = "newPassword 不能为空")
+    @Size(min = 6, max = 128, message = "newPassword 长度必须在 6-128 字符之间")
     private String newPassword;
+    
+    @Schema(description = "是否强制登出", example = "true", defaultValue = "true")
     private Boolean forceLogout = Boolean.TRUE;
 
     public String getNewPassword() { return newPassword; }

src/main/java/com/gameplatform/server/model/entity/account/UserAccount.java

@@ -6,9 +6,7 @@ public class UserAccount {
     private Long id;
     private String userType; // ADMIN | AGENT
     private String username; // 登录名（admin/agent 共用）
-
     private String passwordHash; // BCrypt 或 PLAIN:xxx（初始化用）
-
     private String status; // ENABLED / DISABLED
     private Long pointsBalance; // 仅 AGENT 使用
     private LocalDateTime createdAt;
@@ -20,10 +18,8 @@ public class UserAccount {
     public void setUserType(String userType) { this.userType = userType; }
     public String getUsername() { return username; }
     public void setUsername(String username) { this.username = username; }
-
     public String getPasswordHash() { return passwordHash; }
     public void setPasswordHash(String passwordHash) { this.passwordHash = passwordHash; }
-
     public String getStatus() { return status; }
     public void setStatus(String status) { this.status = status; }
     public Long getPointsBalance() { return pointsBalance; }

src/main/java/com/gameplatform/server/model/entity/admin/Announcement.java

@@ -0,0 +1,34 @@
+package com.gameplatform.server.model.entity.admin;
+
+import java.time.LocalDateTime;
+
+public class Announcement {
+    private Long id;
+    private String title;
+    private String content;
+    private Boolean enabled;
+    private String jumpUrl;
+    private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
+
+    public Long getId() { return id; }
+    public void setId(Long id) { this.id = id; }
+
+    public String getTitle() { return title; }
+    public void setTitle(String title) { this.title = title; }
+
+    public String getContent() { return content; }
+    public void setContent(String content) { this.content = content; }
+
+    public Boolean getEnabled() { return enabled; }
+    public void setEnabled(Boolean enabled) { this.enabled = enabled; }
+
+    public String getJumpUrl() { return jumpUrl; }
+    public void setJumpUrl(String jumpUrl) { this.jumpUrl = jumpUrl; }
+
+    public LocalDateTime getCreatedAt() { return createdAt; }
+    public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; }
+
+    public LocalDateTime getUpdatedAt() { return updatedAt; }
+    public void setUpdatedAt(LocalDateTime updatedAt) { this.updatedAt = updatedAt; }
+}

src/main/java/com/gameplatform/server/model/entity/admin/OperationLog.java

@@ -0,0 +1,42 @@
+package com.gameplatform.server.model.entity.admin;
+
+import java.time.LocalDateTime;
+
+public class OperationLog {
+    private Long id;
+    private String actorType; // admin | agent | system | user
+    private Long actorId;
+    private String codeNo;
+    private String op;
+    private String detail; // JSON字符串
+    private String clientIp;
+    private String userAgent;
+    private LocalDateTime createdAt;
+
+    public Long getId() { return id; }
+    public void setId(Long id) { this.id = id; }
+
+    public String getActorType() { return actorType; }
+    public void setActorType(String actorType) { this.actorType = actorType; }
+
+    public Long getActorId() { return actorId; }
+    public void setActorId(Long actorId) { this.actorId = actorId; }
+
+    public String getCodeNo() { return codeNo; }
+    public void setCodeNo(String codeNo) { this.codeNo = codeNo; }
+
+    public String getOp() { return op; }
+    public void setOp(String op) { this.op = op; }
+
+    public String getDetail() { return detail; }
+    public void setDetail(String detail) { this.detail = detail; }
+
+    public String getClientIp() { return clientIp; }
+    public void setClientIp(String clientIp) { this.clientIp = clientIp; }
+
+    public String getUserAgent() { return userAgent; }
+    public void setUserAgent(String userAgent) { this.userAgent = userAgent; }
+
+    public LocalDateTime getCreatedAt() { return createdAt; }
+    public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; }
+}

src/main/java/com/gameplatform/server/model/entity/agent/AgentPointsTx.java

@@ -0,0 +1,46 @@
+package com.gameplatform.server.model.entity.agent;
+
+import java.time.LocalDateTime;
+
+public class AgentPointsTx {
+    private Long id;
+    private Long accountId;
+    private String type; // ADD | DEDUCT
+    private Long beforePoints;
+    private Long deltaPoints;
+    private Long afterPoints;
+    private String reason; // create_links | manual | refund_no_rollback | other
+    private Long refId;
+    private Long operatorId;
+    private LocalDateTime createdAt;
+
+    public Long getId() { return id; }
+    public void setId(Long id) { this.id = id; }
+
+    public Long getAccountId() { return accountId; }
+    public void setAccountId(Long accountId) { this.accountId = accountId; }
+
+    public String getType() { return type; }
+    public void setType(String type) { this.type = type; }
+
+    public Long getBeforePoints() { return beforePoints; }
+    public void setBeforePoints(Long beforePoints) { this.beforePoints = beforePoints; }
+
+    public Long getDeltaPoints() { return deltaPoints; }
+    public void setDeltaPoints(Long deltaPoints) { this.deltaPoints = deltaPoints; }
+
+    public Long getAfterPoints() { return afterPoints; }
+    public void setAfterPoints(Long afterPoints) { this.afterPoints = afterPoints; }
+
+    public String getReason() { return reason; }
+    public void setReason(String reason) { this.reason = reason; }
+
+    public Long getRefId() { return refId; }
+    public void setRefId(Long refId) { this.refId = refId; }
+
+    public Long getOperatorId() { return operatorId; }
+    public void setOperatorId(Long operatorId) { this.operatorId = operatorId; }
+
+    public LocalDateTime getCreatedAt() { return createdAt; }
+    public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; }
+}

src/main/java/com/gameplatform/server/model/entity/agent/LinkBatch.java

@@ -0,0 +1,38 @@
+package com.gameplatform.server.model.entity.agent;
+
+import java.time.LocalDateTime;
+
+public class LinkBatch {
+    private Long id;
+    private Long agentId;
+    private Integer quantity;
+    private Integer times;
+    private Integer batchSize;
+    private Long deductPoints;
+    private Long operatorId;
+    private LocalDateTime createdAt;
+
+    public Long getId() { return id; }
+    public void setId(Long id) { this.id = id; }
+
+    public Long getAgentId() { return agentId; }
+    public void setAgentId(Long agentId) { this.agentId = agentId; }
+
+    public Integer getQuantity() { return quantity; }
+    public void setQuantity(Integer quantity) { this.quantity = quantity; }
+
+    public Integer getTimes() { return times; }
+    public void setTimes(Integer times) { this.times = times; }
+
+    public Integer getBatchSize() { return batchSize; }
+    public void setBatchSize(Integer batchSize) { this.batchSize = batchSize; }
+
+    public Long getDeductPoints() { return deductPoints; }
+    public void setDeductPoints(Long deductPoints) { this.deductPoints = deductPoints; }
+
+    public Long getOperatorId() { return operatorId; }
+    public void setOperatorId(Long operatorId) { this.operatorId = operatorId; }
+
+    public LocalDateTime getCreatedAt() { return createdAt; }
+    public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; }
+}

src/main/java/com/gameplatform/server/model/entity/agent/LinkTask.java

@@ -0,0 +1,62 @@
+package com.gameplatform.server.model.entity.agent;
+
+import java.time.LocalDateTime;
+
+public class LinkTask {
+    private Long id;
+    private Long batchId;
+    private Long agentId;
+    private String codeNo;
+    private String tokenHash;
+    private LocalDateTime expireAt;
+    private String status; // NEW | USING | LOGGED_IN | REFUNDED | EXPIRED
+    private String region; // Q | V
+    private String machineId;
+    private LocalDateTime loginAt;
+    private LocalDateTime refundAt;
+    private LocalDateTime revokedAt;
+    private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
+
+    public Long getId() { return id; }
+    public void setId(Long id) { this.id = id; }
+
+    public Long getBatchId() { return batchId; }
+    public void setBatchId(Long batchId) { this.batchId = batchId; }
+
+    public Long getAgentId() { return agentId; }
+    public void setAgentId(Long agentId) { this.agentId = agentId; }
+
+    public String getCodeNo() { return codeNo; }
+    public void setCodeNo(String codeNo) { this.codeNo = codeNo; }
+
+    public String getTokenHash() { return tokenHash; }
+    public void setTokenHash(String tokenHash) { this.tokenHash = tokenHash; }
+
+    public LocalDateTime getExpireAt() { return expireAt; }
+    public void setExpireAt(LocalDateTime expireAt) { this.expireAt = expireAt; }
+
+    public String getStatus() { return status; }
+    public void setStatus(String status) { this.status = status; }
+
+    public String getRegion() { return region; }
+    public void setRegion(String region) { this.region = region; }
+
+    public String getMachineId() { return machineId; }
+    public void setMachineId(String machineId) { this.machineId = machineId; }
+
+    public LocalDateTime getLoginAt() { return loginAt; }
+    public void setLoginAt(LocalDateTime loginAt) { this.loginAt = loginAt; }
+
+    public LocalDateTime getRefundAt() { return refundAt; }
+    public void setRefundAt(LocalDateTime refundAt) { this.refundAt = refundAt; }
+
+    public LocalDateTime getRevokedAt() { return revokedAt; }
+    public void setRevokedAt(LocalDateTime revokedAt) { this.revokedAt = revokedAt; }
+
+    public LocalDateTime getCreatedAt() { return createdAt; }
+    public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; }
+
+    public LocalDateTime getUpdatedAt() { return updatedAt; }
+    public void setUpdatedAt(LocalDateTime updatedAt) { this.updatedAt = updatedAt; }
+}