feat: 为 Admin/Token/AdminAnalytics/User/UserProfile Controller 补全 OpenAPI 注解

- AdminController: 4 个 @RequestParam 补全 @Parameter
- TokenController: 调整 @Operation 注解顺序
- AdminAnalyticsController: 新增 @Tag + 6 个 @Operation
- UserController: 新增 @Tag + 7 个 @Operation + 2 个 @Parameter
- UserProfileController: 新增 @Tag + 7 个 @Operation

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

backend-single/src/main/java/com/emotion/controller/AdminAnalyticsController.java

@@ -9,6 +9,8 @@ import com.emotion.dto.response.analytics.AnalyticsTopEventItem;
 import com.emotion.dto.response.analytics.AnalyticsTrendItem;
 import com.emotion.dto.response.analytics.AnalyticsUserItem;
 import com.emotion.service.AnalyticsService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -19,36 +21,43 @@ import java.util.List;
 
 @RestController
 @RequestMapping("/admin/analytics")
+@Tag(name = "数据分析管理", description = "管理后台的数据分析看板接口")
 public class AdminAnalyticsController {
 
     @Autowired
     private AnalyticsService analyticsService;
 
+    @Operation(summary = "获取数据概览", description = "获取数据分析概览，包括关键指标和汇总统计")
     @GetMapping("/overview")
     public Result<AnalyticsOverviewResponse> overview(@Validated AnalyticsQueryRequest request) {
         return Result.success(analyticsService.getOverview(request));
     }
 
+    @Operation(summary = "获取趋势数据", description = "获取指定时间范围内的数据趋势")
     @GetMapping("/trend")
     public Result<List<AnalyticsTrendItem>> trend(@Validated AnalyticsQueryRequest request) {
         return Result.success(analyticsService.getTrend(request));
     }
 
+    @Operation(summary = "获取漏斗数据", description = "获取用户转化漏斗数据，分析各阶段转化率")
     @GetMapping("/funnel")
     public Result<List<AnalyticsFunnelItem>> funnel(@Validated AnalyticsQueryRequest request) {
         return Result.success(analyticsService.getFunnel(request));
     }
 
+    @Operation(summary = "获取用户偏好数据", description = "获取用户偏好设置和使用习惯统计")
     @GetMapping("/preferences")
     public Result<List<AnalyticsPreferenceItem>> preferences(@Validated AnalyticsQueryRequest request) {
         return Result.success(analyticsService.getPreferences(request));
     }
 
+    @Operation(summary = "获取热门事件排行", description = "获取热门事件排行榜，按访问次数倒序排列")
     @GetMapping("/top-events")
     public Result<List<AnalyticsTopEventItem>> topEvents(@Validated AnalyticsQueryRequest request) {
         return Result.success(analyticsService.getTopEvents(request));
     }
 
+    @Operation(summary = "获取用户活跃数据", description = "获取用户活跃度分析和行为统计数据")
     @GetMapping("/users")
     public Result<List<AnalyticsUserItem>> users(@Validated AnalyticsQueryRequest request) {
         return Result.success(analyticsService.getUsers(request));

backend-single/src/main/java/com/emotion/controller/AdminController.java

@@ -13,6 +13,7 @@ import com.emotion.dto.response.DashboardStatsResponse;
 import com.emotion.service.AdminService;
 import com.emotion.service.DashboardService;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.validation.annotation.Validated;
@@ -51,7 +52,9 @@ public class AdminController {
      */
     @Operation(summary = "根据ID获取管理员", description = "根据ID获取管理员详情")
     @GetMapping("/detail")
-    public Result<AdminResponse> getById(@RequestParam String id) {
+    public Result<AdminResponse> getById(
+            @Parameter(description = "管理员ID", required = true)
+            @RequestParam String id) {
         AdminResponse response = adminService.getAdminResponseById(id);
         if (response == null) {
             return Result.notFound("管理员不存在");
@@ -90,7 +93,9 @@ public class AdminController {
      */
     @Operation(summary = "删除管理员", description = "删除指定管理员")
     @DeleteMapping("/delete")
-    public Result<Void> delete(@RequestParam String id) {
+    public Result<Void> delete(
+            @Parameter(description = "管理员ID", required = true)
+            @RequestParam String id) {
         boolean deleted = adminService.removeById(id);
         if (!deleted) {
             return Result.error("删除失败");
@@ -164,6 +169,7 @@ public class AdminController {
     @Operation(summary = "获取用户增长趋势数据", description = "获取指定天数的用户增长趋势数据")
     @GetMapping("/dashboard/user-growth-trends")
     public Result<List<DashboardStatsResponse.UserGrowthTrend>> getUserGrowthTrends(
+            @Parameter(description = "查询天数", required = false)
             @RequestParam(defaultValue = "7") int days) {
         List<DashboardStatsResponse.UserGrowthTrend> trends = dashboardService.getUserGrowthTrends(days);
         return Result.success("获取成功", trends);
@@ -175,6 +181,7 @@ public class AdminController {
     @Operation(summary = "获取最近登录用户", description = "获取最近登录的用户列表")
     @GetMapping("/dashboard/recent-logins")
     public Result<List<DashboardStatsResponse.RecentLogin>> getRecentLogins(
+            @Parameter(description = "返回数量限制", required = false)
             @RequestParam(defaultValue = "10") int limit) {
         List<DashboardStatsResponse.RecentLogin> recentLogins = dashboardService.getRecentLogins(limit);
         return Result.success("获取成功", recentLogins);

backend-single/src/main/java/com/emotion/controller/TokenController.java

@@ -29,8 +29,8 @@ public class TokenController {
      * 通过请求头中的token获取用户信息
      * Token应该在请求头中以 "Authorization: Bearer {token}" 的形式传递
      */
-    @GetMapping("/user-info")
     @Operation(summary = "获取用户信息", description = "通过请求头中的token获取当前用户信息")
+    @GetMapping("/user-info")
     public Result<UserInfoResponse> getUserInfoByToken(HttpServletRequest request) {
         UserInfoResponse userInfo = tokenService.getUserInfoByToken(request);
         return Result.success(userInfo);

backend-single/src/main/java/com/emotion/controller/UserController.java

@@ -8,6 +8,9 @@ import com.emotion.dto.request.UserProfileUpdateRequest;
 import com.emotion.dto.request.UserUpdateRequest;
 import com.emotion.dto.response.UserResponse;
 import com.emotion.service.UserService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
@@ -22,6 +25,7 @@ import javax.validation.Valid;
  */
 @RestController
 @RequestMapping("/user")
+@Tag(name = "用户管理", description = "管理员对用户的增删改查功能")
 public class UserController {
 
     @Autowired
@@ -30,6 +34,7 @@ public class UserController {
     /**
      * 分页查询用户
      */
+    @Operation(summary = "分页查询用户", description = "分页查询用户列表")
     @GetMapping(value = "/page")
     public Result<PageResult<UserResponse>> getPage(@Validated UserPageRequest request) {
         PageResult<UserResponse> pageResult = userService.getPageWithResponse(request);
@@ -39,8 +44,11 @@ public class UserController {
     /**
      * 根据ID获取用户信息
      */
+    @Operation(summary = "根据ID获取用户信息", description = "根据ID获取用户详情")
     @GetMapping(value = "/detail")
-    public Result<UserResponse> getById(@RequestParam String id) {
+    public Result<UserResponse> getById(
+            @Parameter(description = "用户ID", required = true)
+            @RequestParam String id) {
         UserResponse user = userService.getUserResponseById(id);
         if (user == null) {
             return Result.notFound("用户不存在");
@@ -51,6 +59,7 @@ public class UserController {
     /**
      * 创建用户
      */
+    @Operation(summary = "创建用户", description = "创建新用户")
     @PostMapping(value = "/create")
     public Result<UserResponse> create(@Valid @RequestBody UserCreateRequest request) {
         UserResponse user = userService.createUserWithResponse(request);
@@ -60,6 +69,7 @@ public class UserController {
     /**
      * 更新用户
      */
+    @Operation(summary = "更新用户", description = "更新指定用户信息")
     @PutMapping(value = "/update")
     public Result<UserResponse> update(@Valid @RequestBody UserUpdateRequest request) {
         UserResponse updatedUser = userService.updateUserWithResponse(request);
@@ -72,8 +82,11 @@ public class UserController {
     /**
      * 删除用户
      */
+    @Operation(summary = "删除用户", description = "删除指定用户")
     @DeleteMapping(value = "/delete")
-    public Result<Void> delete(@RequestParam String id) {
+    public Result<Void> delete(
+            @Parameter(description = "用户ID", required = true)
+            @RequestParam String id) {
         boolean deleted = userService.deleteUser(id);
         if (!deleted) {
             return Result.error("删除失败");
@@ -84,6 +97,7 @@ public class UserController {
     /**
      * 获取当前用户个人资料
      */
+    @Operation(summary = "获取当前用户个人资料", description = "获取当前登录用户的个人资料")
     @GetMapping(value = "/profile")
     public Result<UserResponse> getCurrentUserProfile() {
         UserResponse user = userService.getCurrentUserProfileWithResponse();

backend-single/src/main/java/com/emotion/controller/UserProfileController.java

@@ -7,6 +7,9 @@ import com.emotion.dto.request.userprofile.UserProfilePageRequest;
 import com.emotion.dto.request.userprofile.UserProfileUpdateRequest;
 import com.emotion.dto.response.userprofile.UserProfileResponse;
 import com.emotion.service.UserProfileService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
@@ -22,6 +25,7 @@ import java.util.List;
  */
 @RestController
 @RequestMapping("/user-profile")
+@Tag(name = "用户档案管理", description = "用户生命档案的增删改查和查询功能")
 public class UserProfileController {
 
     @Autowired