chore: format backend via husky

feat: show placeholder when timeline empty

.github/workflows/deploy-docs.yml

@@ -1,7 +1,11 @@
 name: Deploy Documentation
 
 on:
-  push:
+  workflow_call:
+    inputs:
+      build-id:
+        required: false
+        type: string
   workflow_dispatch:
 
 permissions:
@@ -16,6 +20,9 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Log build
+        run: echo "Running documentation deployment from build ${{ inputs.build-id }}"
+
       - name: Setup Bun
         uses: oven-sh/setup-bun@v1
         with:

.github/workflows/deploy-staging.yml

@@ -5,10 +5,14 @@ on:
     branches: [main]
   workflow_dispatch:
 
+permissions:
+  contents: write
+
 jobs:
   build-and-deploy:
     runs-on: ubuntu-latest
     environment: Deploy
+    if: ${{ !github.event.repository.fork }}  # 只有非 fork 才执行
 
     steps:
       - uses: actions/checkout@v4
@@ -21,3 +25,11 @@ jobs:
           key: ${{ secrets.SSH_KEY }}
           script: bash /opt/openisle/deploy-staging.sh
 
+  deploy-docs:
+    needs: build-and-deploy
+    if: ${{ success() }}
+    uses: ./.github/workflows/deploy-docs.yml
+    secrets: inherit
+    with:
+      build-id: ${{ github.run_id }}
+

CONTRIBUTING.md

@@ -246,3 +246,9 @@ https://resend.com/emails 创建账号并登录
   `RESEND_FROM_EMAIL`： **noreply@域名**
   `RESEND_API_KEY`：**刚刚复制的 Key**
   ![image-20250906151218330](assets/contributing/image-20250906151218330.png)
+
+## 开源共建和API文档
+
+- API文档: https://docs.open-isle.com/openapi
+
+

README.md

@@ -4,6 +4,8 @@
   高效的开源社区前后端平台
   <br><br><br>
   <img alt="Image" src="https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/22752cfac5a04a9c90c41995b9f55fed.png" width="1200">
+    <br><br><br>
+  <a href="https://hellogithub.com/repository/nagisa77/OpenIsle" target="_blank"><img src="https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=8605546658d94cbab45182af2a02e4c8&claim_uid=p5GNFTtZl6HBAYQ" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></a>
 </p>
 
 ## 💡 简介

backend/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "plugins": ["prettier-plugin-java"]
+}

backend/src/main/java/com/openisle/config/CachingConfig.java

@@ -40,6 +40,14 @@ public class CachingConfig {
     public static final String CATEGORY_CACHE_NAME="openisle_categories";
     // 在线人数缓存名
     public static final String ONLINE_CACHE_NAME="openisle_online";
+    // 注册验证码
+    public static final String VERIFY_CACHE_NAME="openisle_verify";
+    // 发帖频率限制
+    public static final String LIMIT_CACHE_NAME="openisle_limit";
+    // 用户访问统计
+    public static final String VISIT_CACHE_NAME="openisle_visit";
+    // 文章缓存
+    public static final String POST_CACHE_NAME="openisle_posts";
 
     /**
      * 自定义Redis的序列化器
@@ -59,7 +67,10 @@ public class CachingConfig {
         // Hibernate6Module 可以自动处理懒加载代理对象。
         // Tag对象的creator是FetchType.LAZY
         objectMapper.registerModule(new Hibernate6Module()
-                .disable(Hibernate6Module.Feature.USE_TRANSIENT_ANNOTATION));
+                .disable(Hibernate6Module.Feature.USE_TRANSIENT_ANNOTATION)
+                // 将 Hibernate 特有的集合类型转换为标准 Java 集合类型
+                // 避免序列化时出现 org.hibernate.collection.spi.PersistentSet 这样的类型信息
+                .configure(Hibernate6Module.Feature.REPLACE_PERSISTENT_COLLECTIONS, true));
         // service的时候带上类型信息
         // 启用类型信息，避免 LinkedHashMap 问题
         objectMapper.activateDefaultTyping(
@@ -86,8 +97,10 @@ public class CachingConfig {
         // 个别缓存单独设置 TTL 时间
         Map<String, RedisCacheConfiguration> cacheConfigs = new HashMap<>();
         RedisCacheConfiguration oneHourConfig = config.entryTtl(Duration.ofHours(1));
+        RedisCacheConfiguration tenMinutesConfig = config.entryTtl(Duration.ofMinutes(10));
         cacheConfigs.put(TAG_CACHE_NAME, oneHourConfig);
         cacheConfigs.put(CATEGORY_CACHE_NAME, oneHourConfig);
+        cacheConfigs.put(POST_CACHE_NAME, tenMinutesConfig);
 
         return RedisCacheManager.builder(connectionFactory)
                 .cacheDefaults(config)

backend/src/main/java/com/openisle/config/OpenApiConfig.java

@@ -5,13 +5,21 @@ import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.info.Info;
 import io.swagger.v3.oas.models.security.SecurityRequirement;
 import io.swagger.v3.oas.models.security.SecurityScheme;
+import io.swagger.v3.oas.models.servers.Server;
+
+import java.util.List;
+import java.util.stream.Collectors;
+import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
 @Configuration
+@RequiredArgsConstructor
 public class OpenApiConfig {
 
+    private final SpringDocProperties springDocProperties;
+
     @Value("${springdoc.info.title}")
     private String title;
 
@@ -30,19 +38,23 @@ public class OpenApiConfig {
     @Bean
     public OpenAPI openAPI() {
         SecurityScheme securityScheme = new SecurityScheme()
-			.type(SecurityScheme.Type.HTTP)
-			.scheme(scheme.toLowerCase())
-			.bearerFormat("JWT")
-			.in(SecurityScheme.In.HEADER)
-			.name(header);
+                        .type(SecurityScheme.Type.HTTP)
+                        .scheme(scheme.toLowerCase())
+                        .bearerFormat("JWT")
+                        .in(SecurityScheme.In.HEADER)
+                        .name(header);
+
+        List<Server> servers = springDocProperties.getServers().stream()
+                .map(s -> new Server().url(s.getUrl()).description(s.getDescription()))
+                .collect(Collectors.toList());
 
         return new OpenAPI()
+                .servers(servers)
                 .info(new Info()
-					.title(title)
-					.description(description)
-					.version(version))
-                .components(new Components()
-					.addSecuritySchemes("JWT", securityScheme))
+                        .title(title)
+                        .description(description)
+                        .version(version))
+                .components(new Components().addSecuritySchemes("JWT", securityScheme))
                 .addSecurityItem(new SecurityRequirement().addList("JWT"));
     }
 }

backend/src/main/java/com/openisle/config/RabbitMQConfig.java

@@ -1,6 +1,7 @@
 package com.openisle.config;
 
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.amqp.core.Binding;
 import org.springframework.amqp.core.BindingBuilder;
 import org.springframework.amqp.core.Queue;
@@ -23,6 +24,7 @@ import java.util.List;
 
 @Configuration
 @RequiredArgsConstructor
+@Slf4j
 public class RabbitMQConfig {
 
     public static final String EXCHANGE_NAME = "openisle-exchange";
@@ -38,7 +40,7 @@ public class RabbitMQConfig {
 
     @PostConstruct
     public void init() {
-        System.out.println("RabbitMQ配置初始化: 队列数量=" + queueCount + ", 持久化=" + queueDurable);
+        log.info("RabbitMQ配置初始化: 队列数量={}, 持久化={}", queueCount, queueDurable);
     }
 
     @Bean
@@ -51,7 +53,7 @@ public class RabbitMQConfig {
      */
     @Bean
     public List<Queue> shardedQueues() {
-        System.out.println("开始创建分片队列 Bean...");
+        log.info("开始创建分片队列 Bean...");
         
         List<Queue> queues = new ArrayList<>();
         for (int i = 0; i < queueCount; i++) {
@@ -61,7 +63,7 @@ public class RabbitMQConfig {
             queues.add(queue);
         }
         
-        System.out.println("分片队列 Bean 创建完成，总数: " + queues.size());
+        log.info("分片队列 Bean 创建完成，总数: {}", queues.size());
         return queues;
     }
 
@@ -70,7 +72,7 @@ public class RabbitMQConfig {
      */
     @Bean
     public List<Binding> shardedBindings(TopicExchange exchange, @Qualifier("shardedQueues") List<Queue> shardedQueues) {
-        System.out.println("开始创建分片绑定 Bean...");
+        log.info("开始创建分片绑定 Bean...");
         List<Binding> bindings = new ArrayList<>();
         if (shardedQueues != null) {
             for (Queue queue : shardedQueues) {
@@ -82,7 +84,7 @@ public class RabbitMQConfig {
             }
         }
         
-        System.out.println("分片绑定 Bean 创建完成，总数: " + bindings.size());
+        log.info("分片绑定 Bean 创建完成，总数: {}", bindings.size());
         return bindings;
     }
 
@@ -135,14 +137,14 @@ public class RabbitMQConfig {
                                                    @Qualifier("shardedBindings") List<Binding> shardedBindings,
                                                    Binding legacyBinding) {
         return args -> {
-            System.out.println("=== 开始主动声明 RabbitMQ 组件 ===");
+            log.info("=== 开始主动声明 RabbitMQ 组件 ===");
             
             try {
                 // 声明交换
                 rabbitAdmin.declareExchange(exchange);
                 
                 // 声明分片队列 - 检查存在性
-                System.out.println("开始检查并声明 " + shardedQueues.size() + " 个分片队列...");
+                log.info("开始检查并声明 {} 个分片队列...", shardedQueues.size());
                 int successCount = 0;
                 int skippedCount = 0;
                 
@@ -159,45 +161,44 @@ public class RabbitMQConfig {
                             skippedCount++;
                         }
                     } catch (Exception e) {
-                        System.err.println("队列声明失败: " + queueName + ", 错误: " + e.getMessage());
+                        log.error("队列声明失败: {}, 错误: {}", queueName, e.getMessage());
                     }
                 }
-                System.out.println("分片队列处理完成: 成功 " + successCount + ", 跳过 " + skippedCount + ", 总数 " + shardedQueues.size());
+                log.info("分片队列处理完成: 成功 {}, 跳过 {}, 总数 {}", successCount, skippedCount, shardedQueues.size());
                 
                 // 声明分片绑定
-                System.out.println("开始声明 " + shardedBindings.size() + " 个分片绑定...");
+                log.info("开始声明 {} 个分片绑定...", shardedBindings.size());
                 int bindingSuccessCount = 0;
                 for (Binding binding : shardedBindings) {
                     try {
                         rabbitAdmin.declareBinding(binding);
                         bindingSuccessCount++;
                     } catch (Exception e) {
-                        System.err.println("绑定声明失败: " + e.getMessage());
+                        log.error("绑定声明失败: {}", e.getMessage());
                     }
                 }
-                System.out.println("分片绑定声明完成: 成功 " + bindingSuccessCount + "/" + shardedBindings.size());
+                log.info("分片绑定声明完成: 成功 {}/{}", bindingSuccessCount, shardedBindings.size());
                 
                 // 声明遗留队列和绑定 - 检查存在性
                 try {
                     rabbitAdmin.declareQueue(legacyQueue);
                     rabbitAdmin.declareBinding(legacyBinding);
-                    System.out.println("遗留队列和绑定就绪: " + QUEUE_NAME + " (已存在或新创建)");
+                    log.info("遗留队列和绑定就绪: {} (已存在或新创建)", QUEUE_NAME);
                 } catch (org.springframework.amqp.AmqpIOException e) {
                     if (e.getMessage().contains("PRECONDITION_FAILED") && e.getMessage().contains("durable")) {
-                        System.out.println("遗留队列已存在但 durable 设置不匹配: " + QUEUE_NAME + ", 保持现有队列");
+                        log.warn("遗留队列已存在但 durable 设置不匹配: {}, 保持现有队列", QUEUE_NAME);
                     } else {
-                        System.err.println("遗留队列声明失败: " + QUEUE_NAME + ", 错误: " + e.getMessage());
+                        log.error("遗留队列声明失败: {}, 错误: {}", QUEUE_NAME, e.getMessage());
                     }
                 } catch (Exception e) {
-                    System.err.println("遗留队列声明失败: " + QUEUE_NAME + ", 错误: " + e.getMessage());
+                    log.error("遗留队列声明失败: {}, 错误: {}", QUEUE_NAME, e.getMessage());
                 }
                 
-                System.out.println("=== RabbitMQ 组件声明完成 ===");
-                System.out.println("请检查 RabbitMQ 管理界面确认队列已正确创建");
+                log.info("=== RabbitMQ 组件声明完成 ===");
+                log.info("请检查 RabbitMQ 管理界面确认队列已正确创建");
                 
             } catch (Exception e) {
-                System.err.println("RabbitMQ 组件声明过程中发生严重错误:");
-                e.printStackTrace();
+                log.error("RabbitMQ 组件声明过程中发生严重错误", e);
             }
         };
     }

backend/src/main/java/com/openisle/config/SecurityConfig.java

@@ -6,6 +6,7 @@ import com.openisle.repository.UserRepository;
 import lombok.RequiredArgsConstructor;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.http.HttpMethod;
 import org.springframework.security.authentication.AuthenticationManager;
 import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
@@ -26,6 +27,8 @@ import org.springframework.web.cors.CorsConfiguration;
 import org.springframework.web.cors.CorsConfigurationSource;
 import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
 import org.springframework.beans.factory.annotation.Value;
+
+import java.time.LocalDate;
 import java.util.List;
 
 import jakarta.servlet.FilterChain;
@@ -44,6 +47,8 @@ public class SecurityConfig {
     @Value("${app.website-url}")
     private String websiteUrl;
 
+    private final RedisTemplate redisTemplate;
+
     @Bean
     public PasswordEncoder passwordEncoder() {
         return new BCryptPasswordEncoder();
@@ -90,6 +95,9 @@ public class SecurityConfig {
                 "http://192.168.7.98",
                 "http://192.168.7.98:3000",
                 "https://petstore.swagger.io",
+                // 允许自建OpenAPI地址
+                "https://docs.open-isle.com",
+                "https://www.docs.open-isle.com",
                 websiteUrl,
                 websiteUrl.replace("://www.", "://")
         ));
@@ -205,7 +213,8 @@ public class SecurityConfig {
             protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
                 var auth = org.springframework.security.core.context.SecurityContextHolder.getContext().getAuthentication();
                 if (auth != null && auth.isAuthenticated() && !(auth instanceof org.springframework.security.authentication.AnonymousAuthenticationToken)) {
-                    userVisitService.recordVisit(auth.getName());
+                    String key = CachingConfig.VISIT_CACHE_NAME+":"+ LocalDate.now();
+                    redisTemplate.opsForSet().add(key, auth.getName());
                 }
                 filterChain.doFilter(request, response);
             }

backend/src/main/java/com/openisle/config/SpringDocProperties.java

@@ -0,0 +1,20 @@
+package com.openisle.config;
+
+import java.util.ArrayList;
+import java.util.List;
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+@Data
+@Component
+@ConfigurationProperties(prefix = "springdoc.api-docs")
+public class SpringDocProperties {
+    private List<ServerConfig> servers = new ArrayList<>();
+
+    @Data
+    public static class ServerConfig {
+        private String url;
+        private String description;
+    }
+}

backend/src/main/java/com/openisle/config/SystemUserInitializer.java

@@ -0,0 +1,36 @@
+package com.openisle.config;
+
+import com.openisle.model.Role;
+import com.openisle.model.User;
+import com.openisle.repository.UserRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.stereotype.Component;
+
+/**
+ * Ensure a dedicated "system" user exists for internal operations.
+ */
+@Component
+@RequiredArgsConstructor
+public class SystemUserInitializer implements CommandLineRunner {
+    private final UserRepository userRepository;
+    private final PasswordEncoder passwordEncoder;
+
+    @Override
+    public void run(String... args) {
+        userRepository.findByUsername("system").orElseGet(() -> {
+            User system = new User();
+            system.setUsername("system");
+            system.setEmail("system@openisle.local");
+            // todo(tim): raw password 采用环境变量
+            system.setPassword(passwordEncoder.encode("system"));
+            system.setRole(Role.USER);
+            system.setVerified(true);
+            system.setApproved(true);
+            system.setAvatar("https://openisle-1307107697.cos.ap-guangzhou.myqcloud.com/assert/image.png");
+            return userRepository.save(system);
+        });
+    }
+}
+

backend/src/main/java/com/openisle/controller/ActivityController.java

@@ -12,6 +12,12 @@ import com.openisle.service.UserService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.List;
 import java.util.stream.Collectors;
@@ -25,6 +31,9 @@ public class ActivityController {
     private final ActivityMapper activityMapper;
 
     @GetMapping
+    @Operation(summary = "List activities", description = "Retrieve all activities")
+    @ApiResponse(responseCode = "200", description = "List of activities",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ActivityDto.class))))
     public List<ActivityDto> list() {
         return activityService.list().stream()
                 .map(activityMapper::toDto)
@@ -32,6 +41,9 @@ public class ActivityController {
     }
 
     @GetMapping("/milk-tea")
+    @Operation(summary = "Milk tea info", description = "Get milk tea activity information")
+    @ApiResponse(responseCode = "200", description = "Milk tea info",
+            content = @Content(schema = @Schema(implementation = MilkTeaInfoDto.class)))
     public MilkTeaInfoDto milkTea() {
         Activity a = activityService.getByType(ActivityType.MILK_TEA);
         long count = activityService.countParticipants(a);
@@ -45,6 +57,10 @@ public class ActivityController {
     }
 
     @PostMapping("/milk-tea/redeem")
+    @Operation(summary = "Redeem milk tea", description = "Redeem milk tea activity reward")
+    @ApiResponse(responseCode = "200", description = "Redeem result",
+            content = @Content(schema = @Schema(implementation = java.util.Map.class)))
+    @SecurityRequirement(name = "JWT")
     public java.util.Map<String, String> redeemMilkTea(@RequestBody MilkTeaRedeemRequest req, Authentication auth) {
         User user = userService.findByIdentifier(auth.getName()).orElseThrow();
         Activity a = activityService.getByType(ActivityType.MILK_TEA);

backend/src/main/java/com/openisle/controller/AdminCommentController.java

@@ -3,6 +3,11 @@ package com.openisle.controller;
 import com.openisle.dto.CommentDto;
 import com.openisle.mapper.CommentMapper;
 import com.openisle.service.CommentService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
@@ -18,11 +23,19 @@ public class AdminCommentController {
     private final CommentMapper commentMapper;
 
     @PostMapping("/{id}/pin")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Pin comment", description = "Pin a comment by its id")
+    @ApiResponse(responseCode = "200", description = "Pinned comment",
+            content = @Content(schema = @Schema(implementation = CommentDto.class)))
     public CommentDto pin(@PathVariable Long id, Authentication auth) {
         return commentMapper.toDto(commentService.pinComment(auth.getName(), id));
     }
 
     @PostMapping("/{id}/unpin")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Unpin comment", description = "Remove pin from a comment")
+    @ApiResponse(responseCode = "200", description = "Unpinned comment",
+            content = @Content(schema = @Schema(implementation = CommentDto.class)))
     public CommentDto unpin(@PathVariable Long id, Authentication auth) {
         return commentMapper.toDto(commentService.unpinComment(auth.getName(), id));
     }

backend/src/main/java/com/openisle/controller/AdminConfigController.java

@@ -5,6 +5,11 @@ import com.openisle.service.AiUsageService;
 import com.openisle.service.PasswordValidator;
 import com.openisle.service.PostService;
 import com.openisle.service.RegisterModeService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
@@ -18,6 +23,10 @@ public class AdminConfigController {
     private final RegisterModeService registerModeService;
 
     @GetMapping
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Get configuration", description = "Retrieve application configuration settings")
+    @ApiResponse(responseCode = "200", description = "Current configuration",
+            content = @Content(schema = @Schema(implementation = ConfigDto.class)))
     public ConfigDto getConfig() {
         ConfigDto dto = new ConfigDto();
         dto.setPublishMode(postService.getPublishMode());
@@ -28,6 +37,10 @@ public class AdminConfigController {
     }
 
     @PostMapping
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Update configuration", description = "Update application configuration settings")
+    @ApiResponse(responseCode = "200", description = "Updated configuration",
+            content = @Content(schema = @Schema(implementation = ConfigDto.class)))
     public ConfigDto updateConfig(@RequestBody ConfigDto dto) {
         if (dto.getPublishMode() != null) {
             postService.setPublishMode(dto.getPublishMode());

backend/src/main/java/com/openisle/controller/AdminController.java

@@ -1,5 +1,10 @@
 package com.openisle.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
 import java.util.Map;
@@ -10,6 +15,10 @@ import java.util.Map;
 @RestController
 public class AdminController {
     @GetMapping("/api/admin/hello")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Admin greeting", description = "Returns a greeting for admin users")
+    @ApiResponse(responseCode = "200", description = "Greeting payload",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public Map<String, String> adminHello() {
         return Map.of("message", "Hello, Admin User");
     }

backend/src/main/java/com/openisle/controller/AdminPostController.java

@@ -3,6 +3,12 @@ package com.openisle.controller;
 import com.openisle.dto.PostSummaryDto;
 import com.openisle.mapper.PostMapper;
 import com.openisle.service.PostService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
@@ -20,6 +26,10 @@ public class AdminPostController {
     private final PostMapper postMapper;
 
     @GetMapping("/pending")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "List pending posts", description = "Retrieve posts awaiting approval")
+    @ApiResponse(responseCode = "200", description = "Pending posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))))
     public List<PostSummaryDto> pendingPosts() {
         return postService.listPendingPosts().stream()
                 .map(postMapper::toSummaryDto)
@@ -27,32 +37,56 @@ public class AdminPostController {
     }
 
     @PostMapping("/{id}/approve")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Approve post", description = "Approve a pending post")
+    @ApiResponse(responseCode = "200", description = "Approved post",
+            content = @Content(schema = @Schema(implementation = PostSummaryDto.class)))
     public PostSummaryDto approve(@PathVariable Long id) {
         return postMapper.toSummaryDto(postService.approvePost(id));
     }
 
     @PostMapping("/{id}/reject")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Reject post", description = "Reject a pending post")
+    @ApiResponse(responseCode = "200", description = "Rejected post",
+            content = @Content(schema = @Schema(implementation = PostSummaryDto.class)))
     public PostSummaryDto reject(@PathVariable Long id) {
         return postMapper.toSummaryDto(postService.rejectPost(id));
     }
 
     @PostMapping("/{id}/pin")
-    public PostSummaryDto pin(@PathVariable Long id) {
-        return postMapper.toSummaryDto(postService.pinPost(id));
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Pin post", description = "Pin a post to the top")
+    @ApiResponse(responseCode = "200", description = "Pinned post",
+            content = @Content(schema = @Schema(implementation = PostSummaryDto.class)))
+    public PostSummaryDto pin(@PathVariable Long id, org.springframework.security.core.Authentication auth) {
+        return postMapper.toSummaryDto(postService.pinPost(id, auth.getName()));
     }
 
     @PostMapping("/{id}/unpin")
-    public PostSummaryDto unpin(@PathVariable Long id) {
-        return postMapper.toSummaryDto(postService.unpinPost(id));
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Unpin post", description = "Remove a post from the top")
+    @ApiResponse(responseCode = "200", description = "Unpinned post",
+            content = @Content(schema = @Schema(implementation = PostSummaryDto.class)))
+    public PostSummaryDto unpin(@PathVariable Long id, org.springframework.security.core.Authentication auth) {
+        return postMapper.toSummaryDto(postService.unpinPost(id, auth.getName()));
     }
 
     @PostMapping("/{id}/rss-exclude")
-    public PostSummaryDto excludeFromRss(@PathVariable Long id) {
-        return postMapper.toSummaryDto(postService.excludeFromRss(id));
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Exclude from RSS", description = "Exclude a post from RSS feed")
+    @ApiResponse(responseCode = "200", description = "Updated post",
+            content = @Content(schema = @Schema(implementation = PostSummaryDto.class)))
+    public PostSummaryDto excludeFromRss(@PathVariable Long id, org.springframework.security.core.Authentication auth) {
+        return postMapper.toSummaryDto(postService.excludeFromRss(id, auth.getName()));
     }
 
     @PostMapping("/{id}/rss-include")
-    public PostSummaryDto includeInRss(@PathVariable Long id) {
-        return postMapper.toSummaryDto(postService.includeInRss(id));
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Include in RSS", description = "Include a post in the RSS feed")
+    @ApiResponse(responseCode = "200", description = "Updated post",
+            content = @Content(schema = @Schema(implementation = PostSummaryDto.class)))
+    public PostSummaryDto includeInRss(@PathVariable Long id, org.springframework.security.core.Authentication auth) {
+        return postMapper.toSummaryDto(postService.includeInRss(id, auth.getName()));
     }
 }

backend/src/main/java/com/openisle/controller/AdminTagController.java

@@ -5,6 +5,12 @@ import com.openisle.mapper.TagMapper;
 import com.openisle.model.Tag;
 import com.openisle.service.PostService;
 import com.openisle.service.TagService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
 
@@ -20,6 +26,10 @@ public class AdminTagController {
     private final TagMapper tagMapper;
 
     @GetMapping("/pending")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "List pending tags", description = "Retrieve tags awaiting approval")
+    @ApiResponse(responseCode = "200", description = "Pending tags",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = TagDto.class))))
     public List<TagDto> pendingTags() {
         return tagService.listPendingTags().stream()
                 .map(t -> tagMapper.toDto(t, postService.countPostsByTag(t.getId())))
@@ -27,6 +37,10 @@ public class AdminTagController {
     }
 
     @PostMapping("/{id}/approve")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Approve tag", description = "Approve a pending tag")
+    @ApiResponse(responseCode = "200", description = "Approved tag",
+            content = @Content(schema = @Schema(implementation = TagDto.class)))
     public TagDto approve(@PathVariable Long id) {
         Tag tag = tagService.approveTag(id);
         long count = postService.countPostsByTag(tag.getId());

backend/src/main/java/com/openisle/controller/AdminUserController.java

@@ -6,6 +6,9 @@ import com.openisle.model.User;
 import com.openisle.service.EmailSender;
 import com.openisle.repository.NotificationRepository;
 import com.openisle.repository.UserRepository;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
@@ -22,6 +25,9 @@ public class AdminUserController {
     private String websiteUrl;
 
     @PostMapping("/{id}/approve")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Approve user", description = "Approve a pending user registration")
+    @ApiResponse(responseCode = "200", description = "User approved")
     public ResponseEntity<?> approve(@PathVariable Long id) {
         User user = userRepository.findById(id).orElseThrow();
         user.setApproved(true);
@@ -33,6 +39,9 @@ public class AdminUserController {
     }
 
     @PostMapping("/{id}/reject")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Reject user", description = "Reject a pending user registration")
+    @ApiResponse(responseCode = "200", description = "User rejected")
     public ResponseEntity<?> reject(@PathVariable Long id) {
         User user = userRepository.findById(id).orElseThrow();
         user.setApproved(false);

backend/src/main/java/com/openisle/controller/AiController.java

@@ -9,6 +9,11 @@ import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.Map;
 
@@ -21,6 +26,10 @@ public class AiController {
     private final AiUsageService aiUsageService;
 
     @PostMapping("/format")
+    @Operation(summary = "Format markdown", description = "Format text via AI")
+    @ApiResponse(responseCode = "200", description = "Formatted content",
+            content = @Content(schema = @Schema(implementation = Map.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<Map<String, String>> format(@RequestBody Map<String, String> req,
                                                      Authentication auth) {
         String text = req.get("text");

backend/src/main/java/com/openisle/controller/AuthController.java

@@ -1,18 +1,27 @@
 package com.openisle.controller;
 
+import com.openisle.config.CachingConfig;
 import com.openisle.dto.*;
 import com.openisle.exception.FieldException;
 import com.openisle.model.RegisterMode;
 import com.openisle.model.User;
 import com.openisle.repository.UserRepository;
 import com.openisle.service.*;
+import com.openisle.util.VerifyType;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.Map;
 import java.util.Optional;
+import java.util.concurrent.TimeUnit;
 
 @RestController
 @RequestMapping("/api/auth")
@@ -43,6 +52,9 @@ public class AuthController {
     private boolean loginCaptchaEnabled;
 
     @PostMapping("/register")
+    @Operation(summary = "Register user", description = "Register a new user account")
+    @ApiResponse(responseCode = "200", description = "Registration result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> register(@RequestBody RegisterRequest req) {
         if (captchaEnabled && registerCaptchaEnabled && !captchaService.verify(req.getCaptcha())) {
             return ResponseEntity.badRequest().body(Map.of("error", "Invalid captcha"));
@@ -56,7 +68,8 @@ public class AuthController {
                 User user = userService.registerWithInvite(
                         req.getUsername(), req.getEmail(), req.getPassword());
                 inviteService.consume(req.getInviteToken(), user.getUsername());
-                emailService.sendEmail(user.getEmail(), "在网站填写验证码以验证", "您的验证码是 " + user.getVerificationCode());
+                // 发送确认邮件
+                userService.sendVerifyMail(user, VerifyType.REGISTER);
                 return ResponseEntity.ok(Map.of(
                         "token", jwtService.generateToken(user.getUsername()),
                         "reason_code", "INVITE_APPROVED"
@@ -70,7 +83,8 @@ public class AuthController {
         }
         User user = userService.register(
                 req.getUsername(), req.getEmail(), req.getPassword(), "", registerModeService.getRegisterMode());
-        emailService.sendEmail(user.getEmail(), "在网站填写验证码以验证", "您的验证码是 " + user.getVerificationCode());
+        // 发送确认邮件
+        userService.sendVerifyMail(user, VerifyType.REGISTER);
         if (!user.isApproved()) {
             notificationService.createRegisterRequestNotifications(user, user.getRegisterReason());
         }
@@ -78,14 +92,16 @@ public class AuthController {
     }
 
     @PostMapping("/verify")
+    @Operation(summary = "Verify account", description = "Verify registration code")
+    @ApiResponse(responseCode = "200", description = "Verification result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> verify(@RequestBody VerifyRequest req) {
-        boolean ok = userService.verifyCode(req.getUsername(), req.getCode());
+        Optional<User> userOpt = userService.findByUsername(req.getUsername());
+        if (userOpt.isEmpty()) {
+            return ResponseEntity.badRequest().body(Map.of("error", "Invalid credentials"));
+        }
+        boolean ok = userService.verifyCode(userOpt.get(), req.getCode(), VerifyType.REGISTER);
         if (ok) {
-            Optional<User> userOpt = userService.findByUsername(req.getUsername());
-            if (userOpt.isEmpty()) {
-                return ResponseEntity.badRequest().body(Map.of("error", "Invalid credentials"));
-            }
-
             User user = userOpt.get();
 
             if (user.isApproved()) {
@@ -106,6 +122,9 @@ public class AuthController {
     }
 
     @PostMapping("/login")
+    @Operation(summary = "Login", description = "Authenticate with username/email and password")
+    @ApiResponse(responseCode = "200", description = "Authentication result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> login(@RequestBody LoginRequest req) {
         if (captchaEnabled && loginCaptchaEnabled && !captchaService.verify(req.getCaptcha())) {
             return ResponseEntity.badRequest().body(Map.of("error", "Invalid captcha"));
@@ -122,7 +141,7 @@ public class AuthController {
         User user = userOpt.get();
         if (!user.isVerified()) {
             user = userService.register(user.getUsername(), user.getEmail(), user.getPassword(), user.getRegisterReason(), registerModeService.getRegisterMode());
-            emailService.sendEmail(user.getEmail(), "在网站填写验证码以验证", "您的验证码是 " + user.getVerificationCode());
+            userService.sendVerifyMail(user, VerifyType.REGISTER);
             return ResponseEntity.badRequest().body(Map.of(
                     "error", "User not verified",
                     "reason_code", "NOT_VERIFIED",
@@ -144,6 +163,9 @@ public class AuthController {
     }
 
     @PostMapping("/google")
+    @Operation(summary = "Login with Google", description = "Authenticate using Google account")
+    @ApiResponse(responseCode = "200", description = "Authentication result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> loginWithGoogle(@RequestBody GoogleLoginRequest req) {
         boolean viaInvite = req.getInviteToken() != null && !req.getInviteToken().isEmpty();
         InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(req.getInviteToken());
@@ -191,6 +213,9 @@ public class AuthController {
 
 
     @PostMapping("/reason")
+    @Operation(summary = "Submit register reason", description = "Submit registration reason for approval")
+    @ApiResponse(responseCode = "200", description = "Submission result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> reason(@RequestBody MakeReasonRequest req) {
         String username = jwtService.validateAndGetSubjectForReason(req.getToken());
         Optional<User> userOpt = userService.findByUsername(username);
@@ -219,6 +244,9 @@ public class AuthController {
     }
 
     @PostMapping("/github")
+    @Operation(summary = "Login with GitHub", description = "Authenticate using GitHub account")
+    @ApiResponse(responseCode = "200", description = "Authentication result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> loginWithGithub(@RequestBody GithubLoginRequest req) {
         boolean viaInvite = req.getInviteToken() != null && !req.getInviteToken().isEmpty();
         InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(req.getInviteToken());
@@ -267,6 +295,9 @@ public class AuthController {
     }
 
     @PostMapping("/discord")
+    @Operation(summary = "Login with Discord", description = "Authenticate using Discord account")
+    @ApiResponse(responseCode = "200", description = "Authentication result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> loginWithDiscord(@RequestBody DiscordLoginRequest req) {
         boolean viaInvite = req.getInviteToken() != null && !req.getInviteToken().isEmpty();
         InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(req.getInviteToken());
@@ -314,6 +345,9 @@ public class AuthController {
     }
       
     @PostMapping("/twitter")
+    @Operation(summary = "Login with Twitter", description = "Authenticate using Twitter account")
+    @ApiResponse(responseCode = "200", description = "Authentication result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> loginWithTwitter(@RequestBody TwitterLoginRequest req) {
         boolean viaInvite = req.getInviteToken() != null && !req.getInviteToken().isEmpty();
         InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(req.getInviteToken());
@@ -362,6 +396,9 @@ public class AuthController {
     }
 
     @PostMapping("/telegram")
+    @Operation(summary = "Login with Telegram", description = "Authenticate using Telegram data")
+    @ApiResponse(responseCode = "200", description = "Authentication result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> loginWithTelegram(@RequestBody TelegramLoginRequest req) {
         boolean viaInvite = req.getInviteToken() != null && !req.getInviteToken().isEmpty();
         InviteService.InviteValidateResult inviteValidateResult = inviteService.validate(req.getInviteToken());
@@ -407,24 +444,37 @@ public class AuthController {
     }
 
     @GetMapping("/check")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Check token", description = "Validate JWT token")
+    @ApiResponse(responseCode = "200", description = "Token valid",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> checkToken() {
         return ResponseEntity.ok(Map.of("valid", true));
     }
 
     @PostMapping("/forgot/send")
+    @Operation(summary = "Send reset code", description = "Send verification code for password reset")
+    @ApiResponse(responseCode = "200", description = "Sending result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> sendReset(@RequestBody ForgotPasswordRequest req) {
         Optional<User> userOpt = userService.findByEmail(req.getEmail());
         if (userOpt.isEmpty()) {
             return ResponseEntity.badRequest().body(Map.of("error", "User not found"));
         }
-        String code = userService.generatePasswordResetCode(req.getEmail());
-        emailService.sendEmail(req.getEmail(), "请填写验证码以重置密码", "您的验证码是" + code);
+        userService.sendVerifyMail(userOpt.get(), VerifyType.RESET_PASSWORD);
         return ResponseEntity.ok(Map.of("message", "Verification code sent"));
     }
 
     @PostMapping("/forgot/verify")
+    @Operation(summary = "Verify reset code", description = "Verify password reset code")
+    @ApiResponse(responseCode = "200", description = "Verification result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> verifyReset(@RequestBody VerifyForgotRequest req) {
-        boolean ok = userService.verifyPasswordResetCode(req.getEmail(), req.getCode());
+        Optional<User> userOpt = userService.findByEmail(req.getEmail());
+        if (userOpt.isEmpty()) {
+            return ResponseEntity.badRequest().body(Map.of("error", "User not found"));
+        }
+        boolean ok = userService.verifyCode(userOpt.get(), req.getCode(), VerifyType.RESET_PASSWORD);
         if (ok) {
             String username = userService.findByEmail(req.getEmail()).get().getUsername();
             return ResponseEntity.ok(Map.of("token", jwtService.generateResetToken(username)));
@@ -433,6 +483,9 @@ public class AuthController {
     }
 
     @PostMapping("/forgot/reset")
+    @Operation(summary = "Reset password", description = "Reset user password after verification")
+    @ApiResponse(responseCode = "200", description = "Reset result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> resetPassword(@RequestBody ResetPasswordRequest req) {
         String username = jwtService.validateAndGetSubjectForReset(req.getToken());
         try {

backend/src/main/java/com/openisle/controller/CategoryController.java

@@ -10,6 +10,11 @@ import com.openisle.service.CategoryService;
 import com.openisle.service.PostService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 
 import java.util.List;
 import java.util.Map;
@@ -25,6 +30,9 @@ public class CategoryController {
     private final CategoryMapper categoryMapper;
 
     @PostMapping
+    @Operation(summary = "Create category", description = "Create a new category")
+    @ApiResponse(responseCode = "200", description = "Created category",
+            content = @Content(schema = @Schema(implementation = CategoryDto.class)))
     public CategoryDto create(@RequestBody CategoryRequest req) {
         Category c = categoryService.createCategory(req.getName(), req.getDescription(), req.getIcon(), req.getSmallIcon());
         long count = postService.countPostsByCategory(c.getId());
@@ -32,6 +40,9 @@ public class CategoryController {
     }
 
     @PutMapping("/{id}")
+    @Operation(summary = "Update category", description = "Update an existing category")
+    @ApiResponse(responseCode = "200", description = "Updated category",
+            content = @Content(schema = @Schema(implementation = CategoryDto.class)))
     public CategoryDto update(@PathVariable Long id, @RequestBody CategoryRequest req) {
         Category c = categoryService.updateCategory(id, req.getName(), req.getDescription(), req.getIcon(), req.getSmallIcon());
         long count = postService.countPostsByCategory(c.getId());
@@ -39,11 +50,16 @@ public class CategoryController {
     }
 
     @DeleteMapping("/{id}")
+    @Operation(summary = "Delete category", description = "Remove a category by id")
+    @ApiResponse(responseCode = "200", description = "Category deleted")
     public void delete(@PathVariable Long id) {
         categoryService.deleteCategory(id);
     }
 
     @GetMapping
+    @Operation(summary = "List categories", description = "Get all categories")
+    @ApiResponse(responseCode = "200", description = "List of categories",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = CategoryDto.class))))
     public List<CategoryDto> list() {
         List<Category> all = categoryService.listCategories();
         List<Long> ids = all.stream().map(Category::getId).toList();
@@ -55,6 +71,9 @@ public class CategoryController {
     }
 
     @GetMapping("/{id}")
+    @Operation(summary = "Get category", description = "Get category by id")
+    @ApiResponse(responseCode = "200", description = "Category detail",
+            content = @Content(schema = @Schema(implementation = CategoryDto.class)))
     public CategoryDto get(@PathVariable Long id) {
         Category c = categoryService.getCategory(id);
         long count = postService.countPostsByCategory(c.getId());
@@ -62,6 +81,9 @@ public class CategoryController {
     }
 
     @GetMapping("/{id}/posts")
+    @Operation(summary = "List posts by category", description = "Get posts under a category")
+    @ApiResponse(responseCode = "200", description = "List of posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))))
     public List<PostSummaryDto> listPostsByCategory(@PathVariable Long id,
                                                     @RequestParam(value = "page", required = false) Integer page,
                                                     @RequestParam(value = "pageSize", required = false) Integer pageSize) {

backend/src/main/java/com/openisle/controller/ChannelController.java

@@ -8,6 +8,12 @@ import com.openisle.service.MessageService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.List;
 
@@ -26,16 +32,28 @@ public class ChannelController {
     }
 
     @GetMapping
+    @Operation(summary = "List channels", description = "List channels for the current user")
+    @ApiResponse(responseCode = "200", description = "Channels",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ChannelDto.class))))
+    @SecurityRequirement(name = "JWT")
     public List<ChannelDto> listChannels(Authentication auth) {
         return channelService.listChannels(getCurrentUserId(auth));
     }
 
     @PostMapping("/{channelId}/join")
+    @Operation(summary = "Join channel", description = "Join a channel")
+    @ApiResponse(responseCode = "200", description = "Joined channel",
+            content = @Content(schema = @Schema(implementation = ChannelDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ChannelDto joinChannel(@PathVariable Long channelId, Authentication auth) {
         return channelService.joinChannel(channelId, getCurrentUserId(auth));
     }
 
     @GetMapping("/unread-count")
+    @Operation(summary = "Unread count", description = "Get unread channel count")
+    @ApiResponse(responseCode = "200", description = "Unread count",
+            content = @Content(schema = @Schema(implementation = Long.class)))
+    @SecurityRequirement(name = "JWT")
     public long unreadCount(Authentication auth) {
         return messageService.getUnreadChannelCount(getCurrentUserId(auth));
     }

backend/src/main/java/com/openisle/controller/CommentController.java

@@ -1,20 +1,29 @@
 package com.openisle.controller;
 
+import com.openisle.dto.PostChangeLogDto;
+import com.openisle.dto.TimelineItemDto;
+import com.openisle.mapper.PostChangeLogMapper;
 import com.openisle.model.Comment;
 import com.openisle.dto.CommentDto;
 import com.openisle.dto.CommentRequest;
 import com.openisle.mapper.CommentMapper;
-import com.openisle.service.CaptchaService;
-import com.openisle.service.CommentService;
-import com.openisle.service.LevelService;
-import com.openisle.service.PointService;
+import com.openisle.model.CommentSort;
+import com.openisle.service.*;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
+import java.util.ArrayList;
+import java.util.Comparator;
 import java.util.List;
 import java.util.stream.Collectors;
 
@@ -28,6 +37,8 @@ public class CommentController {
     private final CaptchaService captchaService;
     private final CommentMapper commentMapper;
     private final PointService pointService;
+    private final PostChangeLogService changeLogService;
+    private final PostChangeLogMapper postChangeLogMapper;
 
     @Value("${app.captcha.enabled:false}")
     private boolean captchaEnabled;
@@ -36,6 +47,10 @@ public class CommentController {
     private boolean commentCaptchaEnabled;
 
     @PostMapping("/posts/{postId}/comments")
+    @Operation(summary = "Create comment", description = "Add a comment to a post")
+    @ApiResponse(responseCode = "200", description = "Created comment",
+            content = @Content(schema = @Schema(implementation = CommentDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<CommentDto> createComment(@PathVariable Long postId,
                                                     @RequestBody CommentRequest req,
                                                     Authentication auth) {
@@ -53,6 +68,10 @@ public class CommentController {
     }
 
     @PostMapping("/comments/{commentId}/replies")
+    @Operation(summary = "Reply to comment", description = "Reply to an existing comment")
+    @ApiResponse(responseCode = "200", description = "Reply created",
+            content = @Content(schema = @Schema(implementation = CommentDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<CommentDto> replyComment(@PathVariable Long commentId,
                                                    @RequestBody CommentRequest req,
                                                    Authentication auth) {
@@ -69,17 +88,51 @@ public class CommentController {
     }
 
     @GetMapping("/posts/{postId}/comments")
-    public List<CommentDto> listComments(@PathVariable Long postId,
-                                         @RequestParam(value = "sort", required = false, defaultValue = "OLDEST") com.openisle.model.CommentSort sort) {
+    @Operation(summary = "List comments", description = "List comments for a post")
+    @ApiResponse(responseCode = "200", description = "Comments",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = TimelineItemDto.class))))
+    public List<TimelineItemDto<?>> listComments(@PathVariable Long postId,
+                                         @RequestParam(value = "sort", required = false, defaultValue = "OLDEST") CommentSort sort) {
         log.debug("listComments called for post {} with sort {}", postId, sort);
-        List<CommentDto> list = commentService.getCommentsForPost(postId, sort).stream()
+        List<CommentDto> commentDtoList = commentService.getCommentsForPost(postId, sort).stream()
                 .map(commentMapper::toDtoWithReplies)
                 .collect(Collectors.toList());
-        log.debug("listComments returning {} comments", list.size());
-        return list;
+        List<PostChangeLogDto> postChangeLogDtoList = changeLogService.listLogs(postId).stream()
+                .map(postChangeLogMapper::toDto)
+                .collect(Collectors.toList());
+        List<TimelineItemDto<?>> itemDtoList = new ArrayList<>();
+
+        itemDtoList.addAll(commentDtoList.stream()
+                .map(c -> new TimelineItemDto<>(
+                        c.getId(),
+                        "comment",
+                        c.getCreatedAt(),
+                        c // payload 是 CommentDto
+                ))
+                .toList());
+
+        itemDtoList.addAll(postChangeLogDtoList.stream()
+                .map(l -> new TimelineItemDto<>(
+                        l.getId(),
+                        "log",
+                        l.getTime(), // 注意字段名不一样
+                        l // payload 是 PostChangeLogDto
+                ))
+                .toList());
+        // 排序
+        Comparator<TimelineItemDto<?>> comparator = Comparator.comparing(TimelineItemDto::getCreatedAt);
+        if (CommentSort.NEWEST.equals(sort)) {
+            comparator = comparator.reversed();
+        }
+        itemDtoList.sort(comparator);
+        log.debug("listComments returning {} comments", itemDtoList.size());
+        return itemDtoList;
     }
 
     @DeleteMapping("/comments/{id}")
+    @Operation(summary = "Delete comment", description = "Delete a comment")
+    @ApiResponse(responseCode = "200", description = "Deleted")
+    @SecurityRequirement(name = "JWT")
     public void deleteComment(@PathVariable Long id, Authentication auth) {
         log.debug("deleteComment called by user {} for comment {}", auth.getName(), id);
         commentService.deleteComment(auth.getName(), id);
@@ -87,12 +140,20 @@ public class CommentController {
     }
 
     @PostMapping("/comments/{id}/pin")
+    @Operation(summary = "Pin comment", description = "Pin a comment")
+    @ApiResponse(responseCode = "200", description = "Pinned comment",
+            content = @Content(schema = @Schema(implementation = CommentDto.class)))
+    @SecurityRequirement(name = "JWT")
     public CommentDto pinComment(@PathVariable Long id, Authentication auth) {
         log.debug("pinComment called by user {} for comment {}", auth.getName(), id);
         return commentMapper.toDto(commentService.pinComment(auth.getName(), id));
     }
 
     @PostMapping("/comments/{id}/unpin")
+    @Operation(summary = "Unpin comment", description = "Unpin a comment")
+    @ApiResponse(responseCode = "200", description = "Unpinned comment",
+            content = @Content(schema = @Schema(implementation = CommentDto.class)))
+    @SecurityRequirement(name = "JWT")
     public CommentDto unpinComment(@PathVariable Long id, Authentication auth) {
         log.debug("unpinComment called by user {} for comment {}", auth.getName(), id);
         return commentMapper.toDto(commentService.unpinComment(auth.getName(), id));

backend/src/main/java/com/openisle/controller/ConfigController.java

@@ -6,6 +6,10 @@ import org.springframework.beans.factory.annotation.Value;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 
 @RestController
 @RequestMapping("/api")
@@ -33,6 +37,9 @@ public class ConfigController {
     private final RegisterModeService registerModeService;
 
     @GetMapping("/config")
+    @Operation(summary = "Site config", description = "Get site configuration")
+    @ApiResponse(responseCode = "200", description = "Site configuration",
+            content = @Content(schema = @Schema(implementation = SiteConfigDto.class)))
     public SiteConfigDto getConfig() {
         SiteConfigDto resp = new SiteConfigDto();
         resp.setCaptchaEnabled(captchaEnabled);

backend/src/main/java/com/openisle/controller/DraftController.java

@@ -9,6 +9,11 @@ import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 @RestController
 @RequestMapping("/api/drafts")
@@ -18,12 +23,20 @@ public class DraftController {
     private final DraftMapper draftMapper;
 
     @PostMapping
+    @Operation(summary = "Save draft", description = "Save a draft for current user")
+    @ApiResponse(responseCode = "200", description = "Draft saved",
+            content = @Content(schema = @Schema(implementation = DraftDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<DraftDto> saveDraft(@RequestBody DraftRequest req, Authentication auth) {
         Draft draft = draftService.saveDraft(auth.getName(), req.getCategoryId(), req.getTitle(), req.getContent(), req.getTagIds());
         return ResponseEntity.ok(draftMapper.toDto(draft));
     }
 
     @GetMapping("/me")
+    @Operation(summary = "Get my draft", description = "Get current user's draft")
+    @ApiResponse(responseCode = "200", description = "Draft details",
+            content = @Content(schema = @Schema(implementation = DraftDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<DraftDto> getMyDraft(Authentication auth) {
         return draftService.getDraft(auth.getName())
                 .map(d -> ResponseEntity.ok(draftMapper.toDto(d)))
@@ -31,6 +44,9 @@ public class DraftController {
     }
 
     @DeleteMapping("/me")
+    @Operation(summary = "Delete my draft", description = "Delete current user's draft")
+    @ApiResponse(responseCode = "200", description = "Draft deleted")
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<?> deleteMyDraft(Authentication auth) {
         draftService.deleteDraft(auth.getName());
         return ResponseEntity.ok().build();

backend/src/main/java/com/openisle/controller/HelloController.java

@@ -1,5 +1,10 @@
 package com.openisle.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
 import java.util.Map;
@@ -7,6 +12,10 @@ import java.util.Map;
 @RestController
 public class HelloController {
     @GetMapping("/api/hello")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Hello endpoint", description = "Returns a greeting for authenticated users")
+    @ApiResponse(responseCode = "200", description = "Greeting payload",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public Map<String, String> hello() {
         return Map.of("message", "Hello, Authenticated User");
     }

backend/src/main/java/com/openisle/controller/InviteController.java

@@ -6,6 +6,11 @@ import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.Map;
 
@@ -16,6 +21,10 @@ public class InviteController {
     private final InviteService inviteService;
 
     @PostMapping("/generate")
+    @Operation(summary = "Generate invite", description = "Generate an invite token")
+    @ApiResponse(responseCode = "200", description = "Invite token",
+            content = @Content(schema = @Schema(implementation = Map.class)))
+    @SecurityRequirement(name = "JWT")
     public Map<String, String> generate(Authentication auth) {
         String token = inviteService.generate(auth.getName());
         return Map.of("token", token);

backend/src/main/java/com/openisle/controller/MedalController.java

@@ -7,6 +7,12 @@ import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.List;
 
@@ -17,11 +23,17 @@ public class MedalController {
     private final MedalService medalService;
 
     @GetMapping
+    @Operation(summary = "List medals", description = "List medals for user or globally")
+    @ApiResponse(responseCode = "200", description = "List of medals",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = MedalDto.class))))
     public List<MedalDto> getMedals(@RequestParam(value = "userId", required = false) Long userId) {
         return medalService.getMedals(userId);
     }
 
     @PostMapping("/select")
+    @Operation(summary = "Select medal", description = "Select a medal for current user")
+    @ApiResponse(responseCode = "200", description = "Medal selected")
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<Void> selectMedal(@RequestBody MedalSelectRequest req, Authentication auth) {
         try {
             medalService.selectMedal(auth.getName(), req.getType());

backend/src/main/java/com/openisle/controller/MessageController.java

@@ -18,6 +18,12 @@ import org.springframework.data.domain.Sort;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.List;
 
@@ -37,12 +43,20 @@ public class MessageController {
     }
 
     @GetMapping("/conversations")
+    @Operation(summary = "List conversations", description = "Get all conversations of current user")
+    @ApiResponse(responseCode = "200", description = "List of conversations",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ConversationDto.class))))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<List<ConversationDto>> getConversations(Authentication auth) {
         List<ConversationDto> conversations = messageService.getConversations(getCurrentUserId(auth));
         return ResponseEntity.ok(conversations);
     }
 
     @GetMapping("/conversations/{conversationId}")
+    @Operation(summary = "Get conversation", description = "Get messages of a conversation")
+    @ApiResponse(responseCode = "200", description = "Conversation detail",
+            content = @Content(schema = @Schema(implementation = ConversationDetailDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<ConversationDetailDto> getMessages(@PathVariable Long conversationId,
                                                                @RequestParam(defaultValue = "0") int page,
                                                                @RequestParam(defaultValue = "20") int size,
@@ -53,12 +67,20 @@ public class MessageController {
     }
 
     @PostMapping
+    @Operation(summary = "Send message", description = "Send a direct message to a user")
+    @ApiResponse(responseCode = "200", description = "Message sent",
+            content = @Content(schema = @Schema(implementation = MessageDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<MessageDto> sendMessage(@RequestBody MessageRequest req, Authentication auth) {
         Message message = messageService.sendMessage(getCurrentUserId(auth), req.getRecipientId(), req.getContent(), req.getReplyToId());
         return ResponseEntity.ok(messageService.toDto(message));
     }
 
     @PostMapping("/conversations/{conversationId}/messages")
+    @Operation(summary = "Send message to conversation", description = "Reply within a conversation")
+    @ApiResponse(responseCode = "200", description = "Message sent",
+            content = @Content(schema = @Schema(implementation = MessageDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<MessageDto> sendMessageToConversation(@PathVariable Long conversationId,
                                                                 @RequestBody ChannelMessageRequest req,
                                                                 Authentication auth) {
@@ -67,18 +89,29 @@ public class MessageController {
     }
 
     @PostMapping("/conversations/{conversationId}/read")
+    @Operation(summary = "Mark conversation read", description = "Mark messages in conversation as read")
+    @ApiResponse(responseCode = "200", description = "Marked as read")
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<Void> markAsRead(@PathVariable Long conversationId, Authentication auth) {
         messageService.markConversationAsRead(conversationId, getCurrentUserId(auth));
         return ResponseEntity.ok().build();
     }
 
     @PostMapping("/conversations")
+    @Operation(summary = "Find or create conversation", description = "Find existing or create new conversation with recipient")
+    @ApiResponse(responseCode = "200", description = "Conversation id",
+            content = @Content(schema = @Schema(implementation = CreateConversationResponse.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<CreateConversationResponse> findOrCreateConversation(@RequestBody CreateConversationRequest req, Authentication auth) {
         MessageConversation conversation = messageService.findOrCreateConversation(getCurrentUserId(auth), req.getRecipientId());
         return ResponseEntity.ok(new CreateConversationResponse(conversation.getId()));
     }
 
     @GetMapping("/unread-count")
+    @Operation(summary = "Unread message count", description = "Get unread message count for current user")
+    @ApiResponse(responseCode = "200", description = "Unread count",
+            content = @Content(schema = @Schema(implementation = Long.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<Long> getUnreadCount(Authentication auth) {
         return ResponseEntity.ok(messageService.getUnreadMessageCount(getCurrentUserId(auth)));
     }

backend/src/main/java/com/openisle/controller/NotificationController.java

@@ -10,6 +10,12 @@ import com.openisle.service.NotificationService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.List;
 import java.util.stream.Collectors;
@@ -23,6 +29,10 @@ public class NotificationController {
     private final NotificationMapper notificationMapper;
 
     @GetMapping
+    @Operation(summary = "List notifications", description = "Retrieve notifications for the current user")
+    @ApiResponse(responseCode = "200", description = "Notifications",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = NotificationDto.class))))
+    @SecurityRequirement(name = "JWT")
     public List<NotificationDto> list(@RequestParam(value = "page", defaultValue = "0") int page,
                                       @RequestParam(value = "size", defaultValue = "30") int size,
                                       Authentication auth) {
@@ -32,6 +42,10 @@ public class NotificationController {
     }
 
     @GetMapping("/unread")
+    @Operation(summary = "List unread notifications", description = "Retrieve unread notifications for the current user")
+    @ApiResponse(responseCode = "200", description = "Unread notifications",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = NotificationDto.class))))
+    @SecurityRequirement(name = "JWT")
     public List<NotificationDto> listUnread(@RequestParam(value = "page", defaultValue = "0") int page,
                                             @RequestParam(value = "size", defaultValue = "30") int size,
                                             Authentication auth) {
@@ -41,6 +55,10 @@ public class NotificationController {
     }
 
     @GetMapping("/unread-count")
+    @Operation(summary = "Unread count", description = "Get count of unread notifications")
+    @ApiResponse(responseCode = "200", description = "Unread count",
+            content = @Content(schema = @Schema(implementation = NotificationUnreadCountDto.class)))
+    @SecurityRequirement(name = "JWT")
     public NotificationUnreadCountDto unreadCount(Authentication auth) {
         long count = notificationService.countUnread(auth.getName());
         NotificationUnreadCountDto uc = new NotificationUnreadCountDto();
@@ -49,26 +67,43 @@ public class NotificationController {
     }
 
     @PostMapping("/read")
+    @Operation(summary = "Mark notifications read", description = "Mark notifications as read")
+    @ApiResponse(responseCode = "200", description = "Marked read")
+    @SecurityRequirement(name = "JWT")
     public void markRead(@RequestBody NotificationMarkReadRequest req, Authentication auth) {
         notificationService.markRead(auth.getName(), req.getIds());
     }
 
     @GetMapping("/prefs")
+    @Operation(summary = "List preferences", description = "List notification preferences")
+    @ApiResponse(responseCode = "200", description = "Preferences",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = NotificationPreferenceDto.class))))
+    @SecurityRequirement(name = "JWT")
     public List<NotificationPreferenceDto> prefs(Authentication auth) {
         return notificationService.listPreferences(auth.getName());
     }
 
     @PostMapping("/prefs")
+    @Operation(summary = "Update preference", description = "Update notification preference")
+    @ApiResponse(responseCode = "200", description = "Preference updated")
+    @SecurityRequirement(name = "JWT")
     public void updatePref(@RequestBody NotificationPreferenceUpdateRequest req, Authentication auth) {
         notificationService.updatePreference(auth.getName(), req.getType(), req.isEnabled());
     }
 
     @GetMapping("/email-prefs")
+    @Operation(summary = "List email preferences", description = "List email notification preferences")
+    @ApiResponse(responseCode = "200", description = "Email preferences",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = NotificationPreferenceDto.class))))
+    @SecurityRequirement(name = "JWT")
     public List<NotificationPreferenceDto> emailPrefs(Authentication auth) {
         return notificationService.listEmailPreferences(auth.getName());
     }
 
     @PostMapping("/email-prefs")
+    @Operation(summary = "Update email preference", description = "Update email notification preference")
+    @ApiResponse(responseCode = "200", description = "Email preference updated")
+    @SecurityRequirement(name = "JWT")
     public void updateEmailPref(@RequestBody NotificationPreferenceUpdateRequest req, Authentication auth) {
         notificationService.updateEmailPreference(auth.getName(), req.getType(), req.isEnabled());
     }

backend/src/main/java/com/openisle/controller/OnlineController.java

@@ -5,6 +5,10 @@ import lombok.RequiredArgsConstructor;
 import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.data.redis.core.StringRedisTemplate;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 
 import java.time.Duration;
 
@@ -22,11 +26,16 @@ public class OnlineController {
     private static final String ONLINE_KEY = CachingConfig.ONLINE_CACHE_NAME +":";
 
     @PostMapping("/heartbeat")
+    @Operation(summary = "Heartbeat", description = "Record user heartbeat")
+    @ApiResponse(responseCode = "200", description = "Heartbeat recorded")
     public void ping(@RequestParam String userId){
         redisTemplate.opsForValue().set(ONLINE_KEY+userId,"1", Duration.ofSeconds(150));
     }
 
     @GetMapping("/count")
+    @Operation(summary = "Online count", description = "Get current online user count")
+    @ApiResponse(responseCode = "200", description = "Online count",
+            content = @Content(schema = @Schema(implementation = Long.class)))
     public long count(){
         return redisTemplate.keys(ONLINE_KEY+"*").size();
     }

backend/src/main/java/com/openisle/controller/PointHistoryController.java

@@ -9,6 +9,12 @@ import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.List;
 import java.util.Map;
@@ -22,6 +28,10 @@ public class PointHistoryController {
     private final PointHistoryMapper pointHistoryMapper;
 
     @GetMapping
+    @Operation(summary = "Point history", description = "List point history for current user")
+    @ApiResponse(responseCode = "200", description = "List of point histories",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PointHistoryDto.class))))
+    @SecurityRequirement(name = "JWT")
     public List<PointHistoryDto> list(Authentication auth) {
         return pointService.listHistory(auth.getName()).stream()
                 .map(pointHistoryMapper::toDto)
@@ -29,6 +39,10 @@ public class PointHistoryController {
     }
 
     @GetMapping("/trend")
+    @Operation(summary = "Point trend", description = "Get point trend data for current user")
+    @ApiResponse(responseCode = "200", description = "Trend data",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = java.util.Map.class))))
+    @SecurityRequirement(name = "JWT")
     public List<Map<String, Object>> trend(Authentication auth,
                                           @RequestParam(value = "days", defaultValue = "30") int days) {
         return pointService.trend(auth.getName(), days);

backend/src/main/java/com/openisle/controller/PointMallController.java

@@ -9,6 +9,12 @@ import com.openisle.service.UserService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.List;
 import java.util.Map;
@@ -24,6 +30,9 @@ public class PointMallController {
     private final PointGoodMapper pointGoodMapper;
 
     @GetMapping
+    @Operation(summary = "List goods", description = "List all point goods")
+    @ApiResponse(responseCode = "200", description = "List of goods",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PointGoodDto.class))))
     public List<PointGoodDto> list() {
         return pointMallService.listGoods().stream()
                 .map(pointGoodMapper::toDto)
@@ -31,6 +40,10 @@ public class PointMallController {
     }
 
     @PostMapping("/redeem")
+    @Operation(summary = "Redeem good", description = "Redeem a point good")
+    @ApiResponse(responseCode = "200", description = "Remaining points",
+            content = @Content(schema = @Schema(implementation = java.util.Map.class)))
+    @SecurityRequirement(name = "JWT")
     public Map<String, Integer> redeem(@RequestBody PointRedeemRequest req, Authentication auth) {
         User user = userService.findByIdentifier(auth.getName()).orElseThrow();
         int point = pointMallService.redeem(user, req.getGoodId(), req.getContact());

backend/src/main/java/com/openisle/controller/PostChangeLogController.java

@@ -0,0 +1,33 @@
+package com.openisle.controller;
+
+import com.openisle.dto.PostChangeLogDto;
+import com.openisle.mapper.PostChangeLogMapper;
+import com.openisle.service.PostChangeLogService;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+@RestController
+@RequestMapping("/api/posts")
+@RequiredArgsConstructor
+public class PostChangeLogController {
+    private final PostChangeLogService changeLogService;
+    private final PostChangeLogMapper mapper;
+
+    @GetMapping("/{id}/change-logs")
+    @Operation(summary = "Post change logs", description = "List change logs for a post")
+    @ApiResponse(responseCode = "200", description = "Change logs",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostChangeLogDto.class))))
+    public List<PostChangeLogDto> listLogs(@PathVariable Long id) {
+        return changeLogService.listLogs(id).stream()
+                .map(mapper::toDto)
+                .collect(Collectors.toList());
+    }
+}

backend/src/main/java/com/openisle/controller/PostController.java

@@ -7,6 +7,12 @@ import com.openisle.dto.PollDto;
 import com.openisle.mapper.PostMapper;
 import com.openisle.model.Post;
 import com.openisle.service.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
@@ -21,6 +27,8 @@ import java.util.stream.Collectors;
 @RequiredArgsConstructor
 public class PostController {
     private final PostService postService;
+    private final CategoryService categoryService;
+    private final TagService tagService;
     private final LevelService levelService;
     private final CaptchaService captchaService;
     private final DraftService draftService;
@@ -35,6 +43,10 @@ public class PostController {
     private boolean postCaptchaEnabled;
 
     @PostMapping
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Create post", description = "Create a new post")
+    @ApiResponse(responseCode = "200", description = "Created post",
+            content = @Content(schema = @Schema(implementation = PostDetailDto.class)))
     public ResponseEntity<PostDetailDto> createPost(@RequestBody PostRequest req, Authentication auth) {
         if (captchaEnabled && postCaptchaEnabled && !captchaService.verify(req.getCaptcha())) {
             return ResponseEntity.badRequest().build();
@@ -53,6 +65,10 @@ public class PostController {
     }
 
     @PutMapping("/{id}")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Update post", description = "Update an existing post")
+    @ApiResponse(responseCode = "200", description = "Updated post",
+            content = @Content(schema = @Schema(implementation = PostDetailDto.class)))
     public ResponseEntity<PostDetailDto> updatePost(@PathVariable Long id, @RequestBody PostRequest req,
                                               Authentication auth) {
         Post post = postService.updatePost(id, auth.getName(), req.getCategoryId(),
@@ -61,21 +77,35 @@ public class PostController {
     }
 
     @DeleteMapping("/{id}")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Delete post", description = "Delete a post")
+    @ApiResponse(responseCode = "200", description = "Post deleted")
     public void deletePost(@PathVariable Long id, Authentication auth) {
         postService.deletePost(id, auth.getName());
     }
 
     @PostMapping("/{id}/close")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Close post", description = "Close a post to prevent further replies")
+    @ApiResponse(responseCode = "200", description = "Closed post",
+            content = @Content(schema = @Schema(implementation = PostSummaryDto.class)))
     public PostSummaryDto close(@PathVariable Long id, Authentication auth) {
         return postMapper.toSummaryDto(postService.closePost(id, auth.getName()));
     }
 
     @PostMapping("/{id}/reopen")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Reopen post", description = "Reopen a closed post")
+    @ApiResponse(responseCode = "200", description = "Reopened post",
+            content = @Content(schema = @Schema(implementation = PostSummaryDto.class)))
     public PostSummaryDto reopen(@PathVariable Long id, Authentication auth) {
         return postMapper.toSummaryDto(postService.reopenPost(id, auth.getName()));
     }
 
     @GetMapping("/{id}")
+    @Operation(summary = "Get post", description = "Get post details by id")
+    @ApiResponse(responseCode = "200", description = "Post detail",
+            content = @Content(schema = @Schema(implementation = PostDetailDto.class)))
     public ResponseEntity<PostDetailDto> getPost(@PathVariable Long id, Authentication auth) {
         String viewer = auth != null ? auth.getName() : null;
         Post post = postService.viewPost(id, viewer);
@@ -83,23 +113,35 @@ public class PostController {
     }
 
     @PostMapping("/{id}/lottery/join")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Join lottery", description = "Join a lottery for the post")
+    @ApiResponse(responseCode = "200", description = "Joined lottery")
     public ResponseEntity<Void> joinLottery(@PathVariable Long id, Authentication auth) {
         postService.joinLottery(id, auth.getName());
         return ResponseEntity.ok().build();
     }
 
     @GetMapping("/{id}/poll/progress")
+    @Operation(summary = "Poll progress", description = "Get poll progress for a post")
+    @ApiResponse(responseCode = "200", description = "Poll progress",
+            content = @Content(schema = @Schema(implementation = PollDto.class)))
     public ResponseEntity<PollDto> pollProgress(@PathVariable Long id) {
         return ResponseEntity.ok(postMapper.toSummaryDto(postService.getPoll(id)).getPoll());
     }
 
     @PostMapping("/{id}/poll/vote")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Vote poll", description = "Vote on a poll option")
+    @ApiResponse(responseCode = "200", description = "Vote recorded")
     public ResponseEntity<Void> vote(@PathVariable Long id, @RequestParam("option") List<Integer> option, Authentication auth) {
         postService.votePoll(id, auth.getName(), option);
         return ResponseEntity.ok().build();
     }
 
     @GetMapping
+    @Operation(summary = "List posts", description = "List posts by various filters")
+    @ApiResponse(responseCode = "200", description = "List of posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))))
     public List<PostSummaryDto> listPosts(@RequestParam(value = "categoryId", required = false) Long categoryId,
                                    @RequestParam(value = "categoryIds", required = false) List<Long> categoryIds,
                                    @RequestParam(value = "tagId", required = false) Long tagId,
@@ -107,36 +149,22 @@ public class PostController {
                                    @RequestParam(value = "page", required = false) Integer page,
                                    @RequestParam(value = "pageSize", required = false) Integer pageSize,
                                    Authentication auth) {
-        List<Long> ids = categoryIds;
-        if (categoryId != null) {
-            ids = java.util.List.of(categoryId);
-        }
-        List<Long> tids = tagIds;
-        if (tagId != null) {
-            tids = java.util.List.of(tagId);
-        }
 
-        if (auth != null) {
-            userVisitService.recordVisit(auth.getName());
-        }
+        List<Long> ids = categoryService.getSearchCategoryIds(categoryIds, categoryId);
+        List<Long> tids = tagService.getSearchTagIds(tagIds, tagId);
+// 只需要在请求的一开始统计一次
+//        if (auth != null) {
+//            userVisitService.recordVisit(auth.getName());
+//        }
 
-        boolean hasCategories = ids != null && !ids.isEmpty();
-        boolean hasTags = tids != null && !tids.isEmpty();
-
-        if (hasCategories && hasTags) {
-            return postService.listPostsByCategoriesAndTags(ids, tids, page, pageSize)
-                    .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
-        }
-        if (hasTags) {
-            return postService.listPostsByTags(tids, page, pageSize)
-                .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
-        }
-
-        return postService.listPostsByCategories(ids, page, pageSize)
-                .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
+        return postService.defaultListPosts(ids,tids,page, pageSize).stream()
+                .map(postMapper::toSummaryDto).collect(Collectors.toList());
     }
 
     @GetMapping("/ranking")
+    @Operation(summary = "Ranking posts", description = "List posts by view rankings")
+    @ApiResponse(responseCode = "200", description = "Ranked posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))))
     public List<PostSummaryDto> rankingPosts(@RequestParam(value = "categoryId", required = false) Long categoryId,
                                       @RequestParam(value = "categoryIds", required = false) List<Long> categoryIds,
                                       @RequestParam(value = "tagId", required = false) Long tagId,
@@ -144,24 +172,22 @@ public class PostController {
                                       @RequestParam(value = "page", required = false) Integer page,
                                       @RequestParam(value = "pageSize", required = false) Integer pageSize,
                                       Authentication auth) {
-        List<Long> ids = categoryIds;
-        if (categoryId != null) {
-            ids = java.util.List.of(categoryId);
-        }
-        List<Long> tids = tagIds;
-        if (tagId != null) {
-            tids = java.util.List.of(tagId);
-        }
 
-        if (auth != null) {
-            userVisitService.recordVisit(auth.getName());
-        }
+        List<Long> ids = categoryService.getSearchCategoryIds(categoryIds, categoryId);
+        List<Long> tids = tagService.getSearchTagIds(tagIds, tagId);
+// 只需要在请求的一开始统计一次
+//        if (auth != null) {
+//            userVisitService.recordVisit(auth.getName());
+//        }
 
         return postService.listPostsByViews(ids, tids, page, pageSize)
                 .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
     }
 
     @GetMapping("/latest-reply")
+    @Operation(summary = "Latest reply posts", description = "List posts by latest replies")
+    @ApiResponse(responseCode = "200", description = "Posts sorted by latest reply",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))))
     public List<PostSummaryDto> latestReplyPosts(@RequestParam(value = "categoryId", required = false) Long categoryId,
                                           @RequestParam(value = "categoryIds", required = false) List<Long> categoryIds,
                                           @RequestParam(value = "tagId", required = false) Long tagId,
@@ -169,24 +195,22 @@ public class PostController {
                                           @RequestParam(value = "page", required = false) Integer page,
                                           @RequestParam(value = "pageSize", required = false) Integer pageSize,
                                           Authentication auth) {
-        List<Long> ids = categoryIds;
-        if (categoryId != null) {
-            ids = java.util.List.of(categoryId);
-        }
-        List<Long> tids = tagIds;
-        if (tagId != null) {
-            tids = java.util.List.of(tagId);
-        }
 
-        if (auth != null) {
-            userVisitService.recordVisit(auth.getName());
-        }
+        List<Long> ids = categoryService.getSearchCategoryIds(categoryIds, categoryId);
+        List<Long> tids = tagService.getSearchTagIds(tagIds, tagId);
+// 只需要在请求的一开始统计一次
+//        if (auth != null) {
+//            userVisitService.recordVisit(auth.getName());
+//        }
 
-        return postService.listPostsByLatestReply(ids, tids, page, pageSize)
-                .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
+        List<Post> posts = postService.listPostsByLatestReply(ids, tids, page, pageSize);
+        return posts.stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
     }
 
     @GetMapping("/featured")
+    @Operation(summary = "Featured posts", description = "List featured posts")
+    @ApiResponse(responseCode = "200", description = "Featured posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))))
     public List<PostSummaryDto> featuredPosts(@RequestParam(value = "categoryId", required = false) Long categoryId,
                                        @RequestParam(value = "categoryIds", required = false) List<Long> categoryIds,
                                        @RequestParam(value = "tagId", required = false) Long tagId,
@@ -194,17 +218,13 @@ public class PostController {
                                        @RequestParam(value = "page", required = false) Integer page,
                                        @RequestParam(value = "pageSize", required = false) Integer pageSize,
                                        Authentication auth) {
-        List<Long> ids = categoryIds;
-        if (categoryId != null) {
-            ids = java.util.List.of(categoryId);
-        }
-        List<Long> tids = tagIds;
-        if (tagId != null) {
-            tids = java.util.List.of(tagId);
-        }
-        if (auth != null) {
-            userVisitService.recordVisit(auth.getName());
-        }
+
+        List<Long> ids = categoryService.getSearchCategoryIds(categoryIds, categoryId);
+        List<Long> tids = tagService.getSearchTagIds(tagIds, tagId);
+// 只需要在请求的一开始统计一次
+//        if (auth != null) {
+//            userVisitService.recordVisit(auth.getName());
+//        }
         return postService.listFeaturedPosts(ids, tids, page, pageSize)
                 .stream().map(postMapper::toSummaryDto).collect(Collectors.toList());
     }

backend/src/main/java/com/openisle/controller/PushSubscriptionController.java

@@ -7,6 +7,11 @@ import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 @RestController
 @RequestMapping("/api/push")
@@ -17,6 +22,9 @@ public class PushSubscriptionController {
     private String publicKey;
 
     @GetMapping("/public-key")
+    @Operation(summary = "Get public key", description = "Retrieve web push public key")
+    @ApiResponse(responseCode = "200", description = "Public key",
+            content = @Content(schema = @Schema(implementation = PushPublicKeyDto.class)))
     public PushPublicKeyDto getPublicKey() {
         PushPublicKeyDto r = new PushPublicKeyDto();
         r.setKey(publicKey);
@@ -24,6 +32,9 @@ public class PushSubscriptionController {
     }
 
     @PostMapping("/subscribe")
+    @Operation(summary = "Subscribe", description = "Subscribe to push notifications")
+    @ApiResponse(responseCode = "200", description = "Subscribed")
+    @SecurityRequirement(name = "JWT")
     public void subscribe(@RequestBody PushSubscriptionRequest req, Authentication auth) {
         pushSubscriptionService.saveSubscription(auth.getName(), req.getEndpoint(), req.getP256dh(), req.getAuth());
     }

backend/src/main/java/com/openisle/controller/ReactionController.java

@@ -12,6 +12,11 @@ import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 @RestController
 @RequestMapping("/api")
@@ -26,11 +31,18 @@ public class ReactionController {
      * Get all available reaction types.
      */
     @GetMapping("/reaction-types")
+    @Operation(summary = "List reaction types", description = "Get all available reaction types")
+    @ApiResponse(responseCode = "200", description = "Reaction types",
+            content = @Content(schema = @Schema(implementation = ReactionType[].class)))
     public ReactionType[] listReactionTypes() {
         return ReactionType.values();
     }
 
     @PostMapping("/posts/{postId}/reactions")
+    @Operation(summary = "React to post", description = "React to a post")
+    @ApiResponse(responseCode = "200", description = "Reaction result",
+            content = @Content(schema = @Schema(implementation = ReactionDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<ReactionDto> reactToPost(@PathVariable Long postId,
                                                    @RequestBody ReactionRequest req,
                                                    Authentication auth) {
@@ -46,6 +58,10 @@ public class ReactionController {
     }
 
     @PostMapping("/comments/{commentId}/reactions")
+    @Operation(summary = "React to comment", description = "React to a comment")
+    @ApiResponse(responseCode = "200", description = "Reaction result",
+            content = @Content(schema = @Schema(implementation = ReactionDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<ReactionDto> reactToComment(@PathVariable Long commentId,
                                                       @RequestBody ReactionRequest req,
                                                       Authentication auth) {
@@ -61,6 +77,10 @@ public class ReactionController {
     }
 
     @PostMapping("/messages/{messageId}/reactions")
+    @Operation(summary = "React to message", description = "React to a message")
+    @ApiResponse(responseCode = "200", description = "Reaction result",
+            content = @Content(schema = @Schema(implementation = ReactionDto.class)))
+    @SecurityRequirement(name = "JWT")
     public ResponseEntity<ReactionDto> reactToMessage(@PathVariable Long messageId,
                                                       @RequestBody ReactionRequest req,
                                                       Authentication auth) {

backend/src/main/java/com/openisle/controller/RssController.java

@@ -13,6 +13,10 @@ import org.jsoup.safety.Safelist;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 
 import com.vladsch.flexmark.ext.autolink.AutolinkExtension;
 import com.vladsch.flexmark.ext.tables.TablesExtension;
@@ -63,6 +67,8 @@ public class RssController {
     }
 
     @GetMapping(value = "/api/rss", produces = "application/rss+xml;charset=UTF-8")
+    @Operation(summary = "RSS feed", description = "Generate RSS feed for latest posts")
+    @ApiResponse(responseCode = "200", description = "RSS XML", content = @Content(schema = @Schema(implementation = String.class)))
     public String feed() {
         // 建议 20；你现在是 10，这里保留你的 10
         List<Post> posts = postService.listLatestRssPosts(10);

backend/src/main/java/com/openisle/controller/SearchController.java

@@ -11,6 +11,11 @@ import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 
 import java.util.List;
 import java.util.stream.Collectors;
@@ -24,6 +29,9 @@ public class SearchController {
     private final PostMapper postMapper;
 
     @GetMapping("/users")
+    @Operation(summary = "Search users", description = "Search users by keyword")
+    @ApiResponse(responseCode = "200", description = "List of users",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDto.class))))
     public List<UserDto> searchUsers(@RequestParam String keyword) {
         return searchService.searchUsers(keyword).stream()
                 .map(userMapper::toDto)
@@ -31,6 +39,9 @@ public class SearchController {
     }
 
     @GetMapping("/posts")
+    @Operation(summary = "Search posts", description = "Search posts by keyword")
+    @ApiResponse(responseCode = "200", description = "List of posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))))
     public List<PostSummaryDto> searchPosts(@RequestParam String keyword) {
         return searchService.searchPosts(keyword).stream()
                 .map(postMapper::toSummaryDto)
@@ -38,6 +49,9 @@ public class SearchController {
     }
 
     @GetMapping("/posts/content")
+    @Operation(summary = "Search posts by content", description = "Search posts by content keyword")
+    @ApiResponse(responseCode = "200", description = "List of posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))))
     public List<PostSummaryDto> searchPostsByContent(@RequestParam String keyword) {
         return searchService.searchPostsByContent(keyword).stream()
                 .map(postMapper::toSummaryDto)
@@ -45,6 +59,9 @@ public class SearchController {
     }
 
     @GetMapping("/posts/title")
+    @Operation(summary = "Search posts by title", description = "Search posts by title keyword")
+    @ApiResponse(responseCode = "200", description = "List of posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))))
     public List<PostSummaryDto> searchPostsByTitle(@RequestParam String keyword) {
         return searchService.searchPostsByTitle(keyword).stream()
                 .map(postMapper::toSummaryDto)
@@ -52,6 +69,9 @@ public class SearchController {
     }
 
     @GetMapping("/global")
+    @Operation(summary = "Global search", description = "Search users and posts globally")
+    @ApiResponse(responseCode = "200", description = "Search results",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = SearchResultDto.class))))
     public List<SearchResultDto> global(@RequestParam String keyword) {
         return searchService.globalSearch(keyword).stream()
                 .map(r -> {

backend/src/main/java/com/openisle/controller/SitemapController.java

@@ -10,6 +10,10 @@ import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 
 import java.util.List;
 
@@ -26,6 +30,9 @@ public class SitemapController {
     private String websiteUrl;
 
     @GetMapping(value = "/sitemap.xml", produces = MediaType.APPLICATION_XML_VALUE)
+    @Operation(summary = "Sitemap", description = "Generate sitemap xml")
+    @ApiResponse(responseCode = "200", description = "Sitemap xml",
+            content = @Content(schema = @Schema(implementation = String.class)))
     public ResponseEntity<String> sitemap() {
         List<Post> posts = postRepository.findByStatus(PostStatus.PUBLISHED);
 

backend/src/main/java/com/openisle/controller/StatController.java

@@ -8,6 +8,11 @@ import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 
 import java.time.LocalDate;
 import java.util.List;
@@ -21,6 +26,9 @@ public class StatController {
     private final StatService statService;
 
     @GetMapping("/dau")
+    @Operation(summary = "Daily active users", description = "Get daily active user count")
+    @ApiResponse(responseCode = "200", description = "DAU count",
+            content = @Content(schema = @Schema(implementation = java.util.Map.class)))
     public Map<String, Long> dau(@RequestParam(value = "date", required = false)
                                  @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate date) {
         long count = userVisitService.countDau(date);
@@ -28,6 +36,9 @@ public class StatController {
     }
 
     @GetMapping("/dau-range")
+    @Operation(summary = "DAU range", description = "Get daily active users over range of days")
+    @ApiResponse(responseCode = "200", description = "DAU data",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = java.util.Map.class))))
     public List<Map<String, Object>> dauRange(@RequestParam(value = "days", defaultValue = "30") int days) {
         if (days < 1) days = 1;
         LocalDate end = LocalDate.now();
@@ -42,6 +53,9 @@ public class StatController {
     }
 
     @GetMapping("/new-users-range")
+    @Operation(summary = "New users range", description = "Get new users over range of days")
+    @ApiResponse(responseCode = "200", description = "New user data",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = java.util.Map.class))))
     public List<Map<String, Object>> newUsersRange(@RequestParam(value = "days", defaultValue = "30") int days) {
         if (days < 1) days = 1;
         LocalDate end = LocalDate.now();
@@ -56,6 +70,9 @@ public class StatController {
     }
 
     @GetMapping("/posts-range")
+    @Operation(summary = "Posts range", description = "Get posts count over range of days")
+    @ApiResponse(responseCode = "200", description = "Post data",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = java.util.Map.class))))
     public List<Map<String, Object>> postsRange(@RequestParam(value = "days", defaultValue = "30") int days) {
         if (days < 1) days = 1;
         LocalDate end = LocalDate.now();
@@ -70,6 +87,9 @@ public class StatController {
     }
 
     @GetMapping("/comments-range")
+    @Operation(summary = "Comments range", description = "Get comments count over range of days")
+    @ApiResponse(responseCode = "200", description = "Comment data",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = java.util.Map.class))))
     public List<Map<String, Object>> commentsRange(@RequestParam(value = "days", defaultValue = "30") int days) {
         if (days < 1) days = 1;
         LocalDate end = LocalDate.now();

backend/src/main/java/com/openisle/controller/SubscriptionController.java

@@ -4,6 +4,9 @@ import com.openisle.service.SubscriptionService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 /** Endpoints for subscribing to posts, comments and users. */
 @RestController
@@ -13,31 +16,49 @@ public class SubscriptionController {
     private final SubscriptionService subscriptionService;
 
     @PostMapping("/posts/{postId}")
+    @Operation(summary = "Subscribe post", description = "Subscribe to a post")
+    @ApiResponse(responseCode = "200", description = "Subscribed")
+    @SecurityRequirement(name = "JWT")
     public void subscribePost(@PathVariable Long postId, Authentication auth) {
         subscriptionService.subscribePost(auth.getName(), postId);
     }
 
     @DeleteMapping("/posts/{postId}")
+    @Operation(summary = "Unsubscribe post", description = "Unsubscribe from a post")
+    @ApiResponse(responseCode = "200", description = "Unsubscribed")
+    @SecurityRequirement(name = "JWT")
     public void unsubscribePost(@PathVariable Long postId, Authentication auth) {
         subscriptionService.unsubscribePost(auth.getName(), postId);
     }
 
     @PostMapping("/comments/{commentId}")
+    @Operation(summary = "Subscribe comment", description = "Subscribe to a comment")
+    @ApiResponse(responseCode = "200", description = "Subscribed")
+    @SecurityRequirement(name = "JWT")
     public void subscribeComment(@PathVariable Long commentId, Authentication auth) {
         subscriptionService.subscribeComment(auth.getName(), commentId);
     }
 
     @DeleteMapping("/comments/{commentId}")
+    @Operation(summary = "Unsubscribe comment", description = "Unsubscribe from a comment")
+    @ApiResponse(responseCode = "200", description = "Unsubscribed")
+    @SecurityRequirement(name = "JWT")
     public void unsubscribeComment(@PathVariable Long commentId, Authentication auth) {
         subscriptionService.unsubscribeComment(auth.getName(), commentId);
     }
 
     @PostMapping("/users/{username}")
+    @Operation(summary = "Subscribe user", description = "Subscribe to a user")
+    @ApiResponse(responseCode = "200", description = "Subscribed")
+    @SecurityRequirement(name = "JWT")
     public void subscribeUser(@PathVariable String username, Authentication auth) {
         subscriptionService.subscribeUser(auth.getName(), username);
     }
 
     @DeleteMapping("/users/{username}")
+    @Operation(summary = "Unsubscribe user", description = "Unsubscribe from a user")
+    @ApiResponse(responseCode = "200", description = "Unsubscribed")
+    @SecurityRequirement(name = "JWT")
     public void unsubscribeUser(@PathVariable String username, Authentication auth) {
         subscriptionService.unsubscribeUser(auth.getName(), username);
     }

backend/src/main/java/com/openisle/controller/TagController.java

@@ -13,6 +13,12 @@ import com.openisle.service.PostService;
 import com.openisle.service.TagService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 
 import java.util.List;
 import java.util.Map;
@@ -29,6 +35,10 @@ public class TagController {
     private final TagMapper tagMapper;
 
     @PostMapping
+    @Operation(summary = "Create tag", description = "Create a new tag")
+    @ApiResponse(responseCode = "200", description = "Created tag",
+            content = @Content(schema = @Schema(implementation = TagDto.class)))
+    @SecurityRequirement(name = "JWT")
     public TagDto create(@RequestBody TagRequest req, org.springframework.security.core.Authentication auth) {
         boolean approved = true;
         if (postService.getPublishMode() == PublishMode.REVIEW && auth != null) {
@@ -49,6 +59,9 @@ public class TagController {
     }
 
     @PutMapping("/{id}")
+    @Operation(summary = "Update tag", description = "Update an existing tag")
+    @ApiResponse(responseCode = "200", description = "Updated tag",
+            content = @Content(schema = @Schema(implementation = TagDto.class)))
     public TagDto update(@PathVariable Long id, @RequestBody TagRequest req) {
         Tag tag = tagService.updateTag(id, req.getName(), req.getDescription(), req.getIcon(), req.getSmallIcon());
         long count = postService.countPostsByTag(tag.getId());
@@ -56,11 +69,16 @@ public class TagController {
     }
 
     @DeleteMapping("/{id}")
+    @Operation(summary = "Delete tag", description = "Delete a tag by id")
+    @ApiResponse(responseCode = "200", description = "Tag deleted")
     public void delete(@PathVariable Long id) {
         tagService.deleteTag(id);
     }
 
     @GetMapping
+    @Operation(summary = "List tags", description = "List tags with optional keyword")
+    @ApiResponse(responseCode = "200", description = "List of tags",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = TagDto.class))))
     public List<TagDto> list(@RequestParam(value = "keyword", required = false) String keyword,
                              @RequestParam(value = "limit", required = false) Integer limit) {
         List<Tag> tags = tagService.searchTags(keyword);
@@ -77,6 +95,9 @@ public class TagController {
     }
 
     @GetMapping("/{id}")
+    @Operation(summary = "Get tag", description = "Get tag by id")
+    @ApiResponse(responseCode = "200", description = "Tag detail",
+            content = @Content(schema = @Schema(implementation = TagDto.class)))
     public TagDto get(@PathVariable Long id) {
         Tag tag = tagService.getTag(id);
         long count = postService.countPostsByTag(tag.getId());
@@ -84,6 +105,9 @@ public class TagController {
     }
 
     @GetMapping("/{id}/posts")
+    @Operation(summary = "List posts by tag", description = "Get posts with specific tag")
+    @ApiResponse(responseCode = "200", description = "List of posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostSummaryDto.class))))
     public List<PostSummaryDto> listPostsByTag(@PathVariable Long id,
                                                @RequestParam(value = "page", required = false) Integer page,
                                                @RequestParam(value = "pageSize", required = false) Integer pageSize) {

backend/src/main/java/com/openisle/controller/UploadController.java

@@ -6,6 +6,10 @@ import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
 import org.springframework.web.multipart.MultipartFile;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
 
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
@@ -27,6 +31,9 @@ public class UploadController {
     private long maxUploadSize;
 
     @PostMapping
+    @Operation(summary = "Upload file", description = "Upload image file")
+    @ApiResponse(responseCode = "200", description = "Upload result",
+            content = @Content(schema = @Schema(implementation = java.util.Map.class)))
     public ResponseEntity<?> upload(@RequestParam("file") MultipartFile file) {
         if (checkImageType && (file.getContentType() == null || !file.getContentType().startsWith("image/"))) {
             return ResponseEntity.badRequest().body(Map.of("code", 1, "msg", "File is not an image"));
@@ -48,6 +55,9 @@ public class UploadController {
     }
 
     @PostMapping("/url")
+    @Operation(summary = "Upload from URL", description = "Upload image from remote URL")
+    @ApiResponse(responseCode = "200", description = "Upload result",
+            content = @Content(schema = @Schema(implementation = java.util.Map.class)))
     public ResponseEntity<?> uploadUrl(@RequestBody Map<String, String> body) {
         String link = body.get("url");
         if (link == null || link.isBlank()) {
@@ -76,6 +86,9 @@ public class UploadController {
     }
 
     @GetMapping("/presign")
+    @Operation(summary = "Presign upload", description = "Get presigned upload URL")
+    @ApiResponse(responseCode = "200", description = "Presigned URL",
+            content = @Content(schema = @Schema(implementation = java.util.Map.class)))
     public java.util.Map<String, String> presign(@RequestParam("filename") String filename) {
         return imageUploader.presignUpload(filename);
     }

backend/src/main/java/com/openisle/controller/UserController.java

@@ -6,6 +6,12 @@ import com.openisle.mapper.TagMapper;
 import com.openisle.mapper.UserMapper;
 import com.openisle.model.User;
 import com.openisle.service.*;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.RequiredArgsConstructor;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
@@ -48,12 +54,20 @@ public class UserController {
     private int defaultTagsLimit;
 
     @GetMapping("/me")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Current user", description = "Get current authenticated user information")
+    @ApiResponse(responseCode = "200", description = "User detail",
+            content = @Content(schema = @Schema(implementation = UserDto.class)))
     public ResponseEntity<UserDto> me(Authentication auth) {
         User user = userService.findByUsername(auth.getName()).orElseThrow();
         return ResponseEntity.ok(userMapper.toDto(user, auth));
     }
 
     @PostMapping("/me/avatar")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Upload avatar", description = "Upload avatar for current user")
+    @ApiResponse(responseCode = "200", description = "Upload result",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> uploadAvatar(@RequestParam("file") MultipartFile file,
                                           Authentication auth) {
         if (checkImageType && (file.getContentType() == null || !file.getContentType().startsWith("image/"))) {
@@ -73,6 +87,10 @@ public class UserController {
     }
 
     @PutMapping("/me")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Update profile", description = "Update current user's profile")
+    @ApiResponse(responseCode = "200", description = "Updated profile",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public ResponseEntity<?> updateProfile(@RequestBody UpdateProfileDto dto,
                                            Authentication auth) {
         User user = userService.updateProfile(auth.getName(), dto.getUsername(), dto.getIntroduction());
@@ -82,13 +100,21 @@ public class UserController {
         ));
     }
 
+    // 这个方法似乎没有使用？
     @PostMapping("/me/signin")
+    @SecurityRequirement(name = "JWT")
+    @Operation(summary = "Daily sign in", description = "Sign in to receive rewards")
+    @ApiResponse(responseCode = "200", description = "Sign in reward",
+            content = @Content(schema = @Schema(implementation = Map.class)))
     public Map<String, Integer> signIn(Authentication auth) {
         int reward = levelService.awardForSignin(auth.getName());
         return Map.of("reward", reward);
     }
 
     @GetMapping("/{identifier}")
+    @Operation(summary = "Get user", description = "Get user by identifier")
+    @ApiResponse(responseCode = "200", description = "User detail",
+            content = @Content(schema = @Schema(implementation = UserDto.class)))
     public ResponseEntity<UserDto> getUser(@PathVariable("identifier") String identifier,
                                            Authentication auth) {
         User user = userService.findByIdentifier(identifier).orElseThrow(() -> new NotFoundException("User not found"));
@@ -96,6 +122,9 @@ public class UserController {
     }
 
     @GetMapping("/{identifier}/posts")
+    @Operation(summary = "User posts", description = "Get recent posts by user")
+    @ApiResponse(responseCode = "200", description = "User posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostMetaDto.class))))
     public java.util.List<PostMetaDto> userPosts(@PathVariable("identifier") String identifier,
                                                  @RequestParam(value = "limit", required = false) Integer limit) {
         int l = limit != null ? limit : defaultPostsLimit;
@@ -106,6 +135,9 @@ public class UserController {
     }
 
     @GetMapping("/{identifier}/subscribed-posts")
+    @Operation(summary = "Subscribed posts", description = "Get posts the user subscribed to")
+    @ApiResponse(responseCode = "200", description = "Subscribed posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostMetaDto.class))))
     public java.util.List<PostMetaDto> subscribedPosts(@PathVariable("identifier") String identifier,
                                                        @RequestParam(value = "limit", required = false) Integer limit) {
         int l = limit != null ? limit : defaultPostsLimit;
@@ -117,6 +149,9 @@ public class UserController {
     }
 
     @GetMapping("/{identifier}/replies")
+    @Operation(summary = "User replies", description = "Get recent replies by user")
+    @ApiResponse(responseCode = "200", description = "User replies",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = CommentInfoDto.class))))
     public java.util.List<CommentInfoDto> userReplies(@PathVariable("identifier") String identifier,
                                                       @RequestParam(value = "limit", required = false) Integer limit) {
         int l = limit != null ? limit : defaultRepliesLimit;
@@ -127,6 +162,9 @@ public class UserController {
     }
 
     @GetMapping("/{identifier}/hot-posts")
+    @Operation(summary = "User hot posts", description = "Get most reacted posts by user")
+    @ApiResponse(responseCode = "200", description = "Hot posts",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = PostMetaDto.class))))
     public java.util.List<PostMetaDto> hotPosts(@PathVariable("identifier") String identifier,
                                                 @RequestParam(value = "limit", required = false) Integer limit) {
         int l = limit != null ? limit : 10;
@@ -138,6 +176,9 @@ public class UserController {
     }
 
     @GetMapping("/{identifier}/hot-replies")
+    @Operation(summary = "User hot replies", description = "Get most reacted replies by user")
+    @ApiResponse(responseCode = "200", description = "Hot replies",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = CommentInfoDto.class))))
     public java.util.List<CommentInfoDto> hotReplies(@PathVariable("identifier") String identifier,
                                                      @RequestParam(value = "limit", required = false) Integer limit) {
         int l = limit != null ? limit : 10;
@@ -149,6 +190,9 @@ public class UserController {
     }
 
     @GetMapping("/{identifier}/hot-tags")
+    @Operation(summary = "User hot tags", description = "Get tags frequently used by user")
+    @ApiResponse(responseCode = "200", description = "Hot tags",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = TagDto.class))))
     public java.util.List<TagDto> hotTags(@PathVariable("identifier") String identifier,
                                           @RequestParam(value = "limit", required = false) Integer limit) {
         int l = limit != null ? limit : 10;
@@ -161,6 +205,9 @@ public class UserController {
     }
 
     @GetMapping("/{identifier}/tags")
+    @Operation(summary = "User tags", description = "Get recent tags used by user")
+    @ApiResponse(responseCode = "200", description = "User tags",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = TagDto.class))))
     public java.util.List<TagDto> userTags(@PathVariable("identifier") String identifier,
                                            @RequestParam(value = "limit", required = false) Integer limit) {
         int l = limit != null ? limit : defaultTagsLimit;
@@ -171,6 +218,9 @@ public class UserController {
     }
 
     @GetMapping("/{identifier}/following")
+    @Operation(summary = "Following users", description = "Get users that this user is following")
+    @ApiResponse(responseCode = "200", description = "Following list",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDto.class))))
     public java.util.List<UserDto> following(@PathVariable("identifier") String identifier) {
         User user = userService.findByIdentifier(identifier).orElseThrow();
         return subscriptionService.getSubscribedUsers(user.getUsername()).stream()
@@ -179,6 +229,9 @@ public class UserController {
     }
 
     @GetMapping("/{identifier}/followers")
+    @Operation(summary = "Followers", description = "Get followers of this user")
+    @ApiResponse(responseCode = "200", description = "Followers list",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDto.class))))
     public java.util.List<UserDto> followers(@PathVariable("identifier") String identifier) {
         User user = userService.findByIdentifier(identifier).orElseThrow();
         return subscriptionService.getSubscribers(user.getUsername()).stream()
@@ -187,6 +240,9 @@ public class UserController {
     }
 
     @GetMapping("/admins")
+    @Operation(summary = "Admin users", description = "List administrator users")
+    @ApiResponse(responseCode = "200", description = "Admin users",
+            content = @Content(array = @ArraySchema(schema = @Schema(implementation = UserDto.class))))
     public java.util.List<UserDto> admins() {
         return userService.getAdmins().stream()
                 .map(userMapper::toDto)
@@ -194,6 +250,9 @@ public class UserController {
     }
 
     @GetMapping("/{identifier}/all")
+    @Operation(summary = "User aggregate", description = "Get aggregate information for user")
+    @ApiResponse(responseCode = "200", description = "User aggregate",
+            content = @Content(schema = @Schema(implementation = UserAggregateDto.class)))
     public ResponseEntity<UserAggregateDto> userAggregate(@PathVariable("identifier") String identifier,
                                                           @RequestParam(value = "postsLimit", required = false) Integer postsLimit,
                                                           @RequestParam(value = "repliesLimit", required = false) Integer repliesLimit,

backend/src/main/java/com/openisle/dto/PostChangeLogDto.java

@@ -0,0 +1,32 @@
+package com.openisle.dto;
+
+import com.openisle.model.PostChangeType;
+import lombok.Getter;
+import lombok.Setter;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+@Getter
+@Setter
+public class PostChangeLogDto {
+    private Long id;
+    private String username;
+    private String userAvatar;
+    private PostChangeType type;
+    private LocalDateTime time;
+    private String oldTitle;
+    private String newTitle;
+    private String oldContent;
+    private String newContent;
+    private CategoryDto oldCategory;
+    private CategoryDto newCategory;
+    private List<TagDto> oldTags;
+    private List<TagDto> newTags;
+    private Boolean oldClosed;
+    private Boolean newClosed;
+    private LocalDateTime oldPinnedAt;
+    private LocalDateTime newPinnedAt;
+    private Boolean oldFeatured;
+    private Boolean newFeatured;
+}

backend/src/main/java/com/openisle/dto/TimelineItemDto.java

@@ -0,0 +1,20 @@
+package com.openisle.dto;
+
+import lombok.*;
+
+import java.time.LocalDateTime;
+
+/**
+ * comment and change_log Dto
+ */
+@Getter
+@Setter
+@AllArgsConstructor
+@NoArgsConstructor
+public class TimelineItemDto<T> {
+
+    private Long id;
+    private String kind; // "comment" | "log"
+    private LocalDateTime createdAt;
+    private T payload; // 泛型，具体类型由外部决定
+}

backend/src/main/java/com/openisle/mapper/PostChangeLogMapper.java

@@ -0,0 +1,92 @@
+package com.openisle.mapper;
+
+import com.openisle.dto.CategoryDto;
+import com.openisle.dto.PostChangeLogDto;
+import com.openisle.dto.TagDto;
+import com.openisle.model.*;
+import com.openisle.repository.CategoryRepository;
+import com.openisle.repository.TagRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.stream.Collectors;
+
+@Component
+@RequiredArgsConstructor
+public class PostChangeLogMapper {
+
+    private final CategoryRepository categoryRepository;
+    private final TagRepository tagRepository;
+    private final CategoryMapper categoryMapper;
+    private final TagMapper tagMapper;
+
+    public PostChangeLogDto toDto(PostChangeLog log) {
+        PostChangeLogDto dto = new PostChangeLogDto();
+        dto.setId(log.getId());
+        if (log.getUser() != null) {
+            dto.setUsername(log.getUser().getUsername());
+            dto.setUserAvatar(log.getUser().getAvatar());
+        }
+        dto.setType(log.getType());
+        dto.setTime(log.getCreatedAt());
+        if (log instanceof PostTitleChangeLog t) {
+            dto.setOldTitle(t.getOldTitle());
+            dto.setNewTitle(t.getNewTitle());
+        } else if (log instanceof PostContentChangeLog c) {
+            dto.setOldContent(c.getOldContent());
+            dto.setNewContent(c.getNewContent());
+        } else if (log instanceof PostCategoryChangeLog cat) {
+            dto.setOldCategory(mapCategory(cat.getOldCategory()));
+            dto.setNewCategory(mapCategory(cat.getNewCategory()));
+        } else if (log instanceof PostTagChangeLog tag) {
+            dto.setOldTags(mapTags(tag.getOldTags()));
+            dto.setNewTags(mapTags(tag.getNewTags()));
+        } else if (log instanceof PostClosedChangeLog cl) {
+            dto.setOldClosed(cl.isOldClosed());
+            dto.setNewClosed(cl.isNewClosed());
+        } else if (log instanceof PostPinnedChangeLog p) {
+            dto.setOldPinnedAt(p.getOldPinnedAt());
+            dto.setNewPinnedAt(p.getNewPinnedAt());
+        } else if (log instanceof PostFeaturedChangeLog f) {
+            dto.setOldFeatured(f.isOldFeatured());
+            dto.setNewFeatured(f.isNewFeatured());
+        }
+        return dto;
+    }
+
+    private CategoryDto mapCategory(String name) {
+        if (name == null) {
+            return null;
+        }
+        return categoryRepository.findByName(name)
+                .map(categoryMapper::toDto)
+                .orElseGet(() -> {
+                    CategoryDto dto = new CategoryDto();
+                    dto.setName(name);
+                    return dto;
+                });
+    }
+
+    private List<TagDto> mapTags(String tags) {
+        if (tags == null || tags.isBlank()) {
+            return Collections.emptyList();
+        }
+        return Arrays.stream(tags.split(","))
+                .map(String::trim)
+                .map(this::mapTag)
+                .collect(Collectors.toList());
+    }
+
+    private TagDto mapTag(String name) {
+        return tagRepository.findByName(name)
+                .map(tagMapper::toDto)
+                .orElseGet(() -> {
+                    TagDto dto = new TagDto();
+                    dto.setName(name);
+                    return dto;
+                });
+    }
+}

backend/src/main/java/com/openisle/mapper/PostMapper.java

@@ -67,7 +67,6 @@ public class PostMapper {
         dto.setCategory(categoryMapper.toDto(post.getCategory()));
         dto.setTags(post.getTags().stream().map(tagMapper::toDto).collect(Collectors.toList()));
         dto.setViews(post.getViews());
-        dto.setCommentCount(commentService.countComments(post.getId()));
         dto.setStatus(post.getStatus());
         dto.setPinnedAt(post.getPinnedAt());
         dto.setRssExcluded(post.getRssExcluded() == null || post.getRssExcluded());
@@ -82,8 +81,12 @@ public class PostMapper {
         List<User> participants = commentService.getParticipants(post.getId(), 5);
         dto.setParticipants(participants.stream().map(userMapper::toAuthorDto).collect(Collectors.toList()));
 
-        LocalDateTime last = commentService.getLastCommentTime(post.getId());
-        dto.setLastReplyAt(last != null ? last : post.getCreatedAt());
+        LocalDateTime last = post.getLastReplyAt();
+        if (last == null) {
+            commentService.updatePostCommentStats(post);
+        }
+        dto.setCommentCount(post.getCommentCount());
+        dto.setLastReplyAt(post.getLastReplyAt());
         dto.setReward(0);
         dto.setSubscribed(false);
         dto.setType(post.getType());
@@ -96,8 +99,6 @@ public class PostMapper {
             l.setPointCost(lp.getPointCost());
             l.setStartTime(lp.getStartTime());
             l.setEndTime(lp.getEndTime());
-            l.setParticipants(lp.getParticipants().stream().map(userMapper::toAuthorDto).collect(Collectors.toList()));
-            l.setWinners(lp.getWinners().stream().map(userMapper::toAuthorDto).collect(Collectors.toList()));
             dto.setLottery(l);
         }
 
@@ -106,7 +107,6 @@ public class PostMapper {
             p.setOptions(pp.getOptions());
             p.setVotes(pp.getVotes());
             p.setEndTime(pp.getEndTime());
-            p.setParticipants(pp.getParticipants().stream().map(userMapper::toAuthorDto).collect(Collectors.toList()));
             Map<Integer, List<AuthorDto>> optionParticipants = pollVoteRepository.findByPostId(pp.getId()).stream()
                     .collect(Collectors.groupingBy(PollVote::getOptionIndex,
                             Collectors.mapping(v -> userMapper.toAuthorDto(v.getUser()), Collectors.toList())));

backend/src/main/java/com/openisle/model/Post.java

@@ -39,19 +39,19 @@ public class Post {
             columnDefinition = "DATETIME(6) DEFAULT CURRENT_TIMESTAMP(6)")
     private LocalDateTime createdAt;
 
-    @ManyToOne(optional = false, fetch = FetchType.LAZY)
+    @ManyToOne(optional = false, fetch = FetchType.EAGER)
     @JoinColumn(name = "author_id")
     private User author;
 
-    @ManyToOne(optional = false, fetch = FetchType.LAZY)
+    @ManyToOne(optional = false, fetch = FetchType.EAGER)
     @JoinColumn(name = "category_id")
     private Category category;
 
-    @ManyToMany(fetch = FetchType.LAZY)
+    @ManyToMany(fetch = FetchType.EAGER)
     @JoinTable(name = "post_tags",
             joinColumns = @JoinColumn(name = "post_id"),
             inverseJoinColumns = @JoinColumn(name = "tag_id"))
-    private java.util.Set<Tag> tags = new java.util.HashSet<>();
+    private Set<Tag> tags = new HashSet<>();
 
     @Column(nullable = false)
     private long views = 0;
@@ -72,4 +72,10 @@ public class Post {
 
     @Column(nullable = true)
     private Boolean rssExcluded = true;
+
+    @Column(nullable = false)
+    private long commentCount = 0;
+
+    @Column(nullable = true)
+    private LocalDateTime lastReplyAt;
 }

backend/src/main/java/com/openisle/model/PostCategoryChangeLog.java

@@ -0,0 +1,17 @@
+package com.openisle.model;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_category_change_logs")
+public class PostCategoryChangeLog extends PostChangeLog {
+    private String oldCategory;
+    private String newCategory;
+}

backend/src/main/java/com/openisle/model/PostChangeLog.java

@@ -0,0 +1,37 @@
+package com.openisle.model;
+
+import jakarta.persistence.*;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import org.hibernate.annotations.CreationTimestamp;
+
+import java.time.LocalDateTime;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_change_logs")
+@Inheritance(strategy = InheritanceType.JOINED)
+public abstract class PostChangeLog {
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @ManyToOne(fetch = FetchType.LAZY, optional = false)
+    @JoinColumn(name = "post_id")
+    private Post post;
+
+    @ManyToOne(fetch = FetchType.LAZY, optional = true)
+    @JoinColumn(name = "user_id")
+    private User user;
+
+    @CreationTimestamp
+    @Column(nullable = false, updatable = false)
+    private LocalDateTime createdAt;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    private PostChangeType type;
+}

backend/src/main/java/com/openisle/model/PostChangeType.java

@@ -0,0 +1,13 @@
+package com.openisle.model;
+
+public enum PostChangeType {
+    CONTENT,
+    TITLE,
+    CATEGORY,
+    TAG,
+    CLOSED,
+    PINNED,
+    FEATURED,
+    VOTE_RESULT,
+    LOTTERY_RESULT
+}

backend/src/main/java/com/openisle/model/PostClosedChangeLog.java

@@ -0,0 +1,17 @@
+package com.openisle.model;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_closed_change_logs")
+public class PostClosedChangeLog extends PostChangeLog {
+    private boolean oldClosed;
+    private boolean newClosed;
+}

backend/src/main/java/com/openisle/model/PostContentChangeLog.java

@@ -0,0 +1,21 @@
+package com.openisle.model;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_content_change_logs")
+public class PostContentChangeLog extends PostChangeLog {
+    @Column(name = "old_content", columnDefinition = "LONGTEXT")
+    private String oldContent;
+
+    @Column(name = "new_content", columnDefinition = "LONGTEXT")
+    private String newContent;
+}

backend/src/main/java/com/openisle/model/PostFeaturedChangeLog.java

@@ -0,0 +1,17 @@
+package com.openisle.model;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_featured_change_logs")
+public class PostFeaturedChangeLog extends PostChangeLog {
+    private boolean oldFeatured;
+    private boolean newFeatured;
+}

backend/src/main/java/com/openisle/model/PostLotteryResultChangeLog.java

@@ -0,0 +1,16 @@
+package com.openisle.model;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_lottery_result_change_logs")
+public class PostLotteryResultChangeLog extends PostChangeLog {
+}
+

backend/src/main/java/com/openisle/model/PostPinnedChangeLog.java

@@ -0,0 +1,19 @@
+package com.openisle.model;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import java.time.LocalDateTime;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_pinned_change_logs")
+public class PostPinnedChangeLog extends PostChangeLog {
+    private LocalDateTime oldPinnedAt;
+    private LocalDateTime newPinnedAt;
+}

backend/src/main/java/com/openisle/model/PostTagChangeLog.java

@@ -0,0 +1,21 @@
+package com.openisle.model;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_tag_change_logs")
+public class PostTagChangeLog extends PostChangeLog {
+    @Column(name = "old_tags")
+    private String oldTags;
+
+    @Column(name = "new_tags")
+    private String newTags;
+}

backend/src/main/java/com/openisle/model/PostTitleChangeLog.java

@@ -0,0 +1,17 @@
+package com.openisle.model;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_title_change_logs")
+public class PostTitleChangeLog extends PostChangeLog {
+    private String oldTitle;
+    private String newTitle;
+}

backend/src/main/java/com/openisle/model/PostVoteResultChangeLog.java

@@ -0,0 +1,16 @@
+package com.openisle.model;
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@Entity
+@Table(name = "post_vote_result_change_logs")
+public class PostVoteResultChangeLog extends PostChangeLog {
+}
+

backend/src/main/java/com/openisle/repository/CategoryRepository.java

@@ -4,7 +4,10 @@ import com.openisle.model.Category;
 import org.springframework.data.jpa.repository.JpaRepository;
 
 import java.util.List;
+import java.util.Optional;
 
 public interface CategoryRepository extends JpaRepository<Category, Long> {
     List<Category> findByNameContainingIgnoreCase(String keyword);
+
+    Optional<Category> findByName(String name);
 }

backend/src/main/java/com/openisle/repository/PointHistoryRepository.java

@@ -1,8 +1,9 @@
 package com.openisle.repository;
 
-import com.openisle.model.PointHistory;
-import com.openisle.model.User;
 import com.openisle.model.Comment;
+import com.openisle.model.PointHistory;
+import com.openisle.model.Post;
+import com.openisle.model.User;
 import org.springframework.data.jpa.repository.JpaRepository;
 
 import java.time.LocalDateTime;
@@ -10,9 +11,12 @@ import java.util.List;
 
 public interface PointHistoryRepository extends JpaRepository<PointHistory, Long> {
     List<PointHistory> findByUserOrderByIdDesc(User user);
+    List<PointHistory> findByUserOrderByIdAsc(User user);
     long countByUser(User user);
 
     List<PointHistory> findByUserAndCreatedAtAfterOrderByCreatedAtDesc(User user, LocalDateTime createdAt);
-    
+
     List<PointHistory> findByComment(Comment comment);
+
+    List<PointHistory> findByPost(Post post);
 }

backend/src/main/java/com/openisle/repository/PostChangeLogRepository.java

@@ -0,0 +1,13 @@
+package com.openisle.repository;
+
+import com.openisle.model.Post;
+import com.openisle.model.PostChangeLog;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+
+public interface PostChangeLogRepository extends JpaRepository<PostChangeLog, Long> {
+    List<PostChangeLog> findByPostOrderByCreatedAtAsc(Post post);
+
+    void deleteByPost(Post post);
+}

backend/src/main/java/com/openisle/repository/TagRepository.java

@@ -6,6 +6,7 @@ import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.domain.Pageable;
 
 import java.util.List;
+import java.util.Optional;
 
 public interface TagRepository extends JpaRepository<Tag, Long> {
     List<Tag> findByNameContainingIgnoreCase(String keyword);
@@ -15,4 +16,6 @@ public interface TagRepository extends JpaRepository<Tag, Long> {
 
     List<Tag> findByCreatorOrderByCreatedAtDesc(User creator, Pageable pageable);
     List<Tag> findByCreator(User creator);
+
+    Optional<Tag> findByName(String name);
 }

backend/src/main/java/com/openisle/scheduler/UserVisitScheduler.java

@@ -0,0 +1,48 @@
+package com.openisle.scheduler;
+
+import com.openisle.config.CachingConfig;
+import com.openisle.model.User;
+import com.openisle.model.UserVisit;
+import com.openisle.repository.UserRepository;
+import com.openisle.repository.UserVisitRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+import org.springframework.util.CollectionUtils;
+
+import java.time.LocalDate;
+import java.util.Set;
+
+/**
+ * 执行计划
+ * 将每天用户访问落库
+ * @author smallclover
+ * @since 2025-09-09
+ */
+@Component
+@RequiredArgsConstructor
+public class UserVisitScheduler {
+    private final RedisTemplate redisTemplate;
+    private final UserRepository userRepository;
+    private final UserVisitRepository userVisitRepository;
+
+    @Scheduled(cron = "0 5 0 * * ?") // 每天 00:05 执行
+    public void persistDailyVisits(){
+        LocalDate yesterday = LocalDate.now().minusDays(1);
+        String key = CachingConfig.VISIT_CACHE_NAME + ":" + yesterday;
+        Set<String> usernames = redisTemplate.opsForSet().members(key);
+        if (!CollectionUtils.isEmpty(usernames)) {
+            for(String username: usernames){
+                User user = userRepository.findByUsername(username).orElse(null);
+                if(user != null){
+                    UserVisit userVisit = new UserVisit();
+                    userVisit.setUser(user);
+                    userVisit.setVisitDate(yesterday);
+                    userVisitRepository.save(userVisit);
+                }
+            }
+            redisTemplate.delete(key);
+        }
+    }
+}

backend/src/main/java/com/openisle/service/CategoryService.java

@@ -62,4 +62,18 @@ public class CategoryService {
     public List<Category> listCategories() {
         return categoryRepository.findAll();
     }
+
+    /**
+     * 获取检索用的分类Id列表
+     * @param categoryIds
+     * @param categoryId
+     * @return
+     */
+    public List<Long> getSearchCategoryIds(List<Long> categoryIds, Long categoryId){
+        List<Long> ids = categoryIds;
+        if (categoryId != null) {
+            ids = List.of(categoryId);
+        }
+        return ids;
+    }
 }

backend/src/main/java/com/openisle/service/CommentService.java

@@ -1,5 +1,6 @@
 package com.openisle.service;
 
+import com.openisle.config.CachingConfig;
 import com.openisle.model.Comment;
 import com.openisle.model.Post;
 import com.openisle.model.User;
@@ -20,6 +21,8 @@ import com.openisle.model.Role;
 import com.openisle.exception.RateLimitException;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.cache.annotation.CacheEvict;
+import org.springframework.cache.annotation.Cacheable;
 import org.springframework.stereotype.Service;
 
 import java.util.List;
@@ -47,6 +50,10 @@ public class CommentService {
     private final PointService pointService;
     private final ImageUploader imageUploader;
 
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
     @Transactional
     public Comment addComment(String username, Long postId, String content) {
         log.debug("addComment called by user {} for post {}", username, postId);
@@ -69,6 +76,10 @@ public class CommentService {
         comment.setContent(content);
         comment = commentRepository.save(comment);
         log.debug("Comment {} saved for post {}", comment.getId(), postId);
+        
+        // Update post comment statistics
+        updatePostCommentStats(post);
+        
         imageUploader.addReferences(imageUploader.extractUrls(content));
         if (!author.getId().equals(post.getAuthor().getId())) {
             notificationService.createNotification(post.getAuthor(), NotificationType.COMMENT_REPLY, post, comment,
@@ -95,6 +106,10 @@ public class CommentService {
         return commentRepository.findLastCommentTimeOfUserByUserId(userId);
     }
 
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
     @Transactional
     public Comment addReply(String username, Long parentId, String content) {
         log.debug("addReply called by user {} for parent comment {}", username, parentId);
@@ -118,6 +133,10 @@ public class CommentService {
         comment.setContent(content);
         comment = commentRepository.save(comment);
         log.debug("Reply {} saved for parent {}", comment.getId(), parentId);
+        
+        // Update post comment statistics
+        updatePostCommentStats(parent.getPost());
+        
         imageUploader.addReferences(imageUploader.extractUrls(content));
         if (!author.getId().equals(parent.getAuthor().getId())) {
             notificationService.createNotification(parent.getAuthor(), NotificationType.COMMENT_REPLY, parent.getPost(),
@@ -228,6 +247,10 @@ public class CommentService {
         return count;
     }
 
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
     @Transactional
     public void deleteComment(String username, Long id) {
         log.debug("deleteComment called by user {} for comment {}", username, id);
@@ -243,6 +266,10 @@ public class CommentService {
         log.debug("deleteComment completed for comment {}", id);
     }
 
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
     @Transactional
     public void deleteCommentCascade(Comment comment) {
         log.debug("deleteCommentCascade called for comment {}", comment.getId());
@@ -263,9 +290,13 @@ public class CommentService {
         imageUploader.removeReferences(imageUploader.extractUrls(comment.getContent()));
 
         // 逻辑删除评论
+        Post post = comment.getPost();
         commentRepository.delete(comment);
         // 删除积分历史
         pointHistoryRepository.deleteAll(pointHistories);
+        
+        // Update post comment statistics
+        updatePostCommentStats(post);
 
         // 重新计算受影响用户的积分
         if (!usersToRecalculate.isEmpty()) {
@@ -311,4 +342,23 @@ public class CommentService {
         int replies = commentRepository.findByParentOrderByCreatedAtAsc(comment).size();
         return reactions + replies;
     }
+    
+    /**
+     * Update post comment statistics (comment count and last reply time)
+     */
+    public void updatePostCommentStats(Post post) {
+        long commentCount = commentRepository.countByPostId(post.getId());
+        post.setCommentCount(commentCount);
+
+        LocalDateTime lastReplyAt = commentRepository.findLastCommentTime(post);
+        if (lastReplyAt == null) {
+            post.setLastReplyAt(post.getCreatedAt());
+        } else {
+            post.setLastReplyAt(lastReplyAt);
+        }
+        postRepository.save(post);
+        
+        log.debug("Updated post {} stats: commentCount={}, lastReplyAt={}", 
+                post.getId(), commentCount, lastReplyAt);
+    }
 }

backend/src/main/java/com/openisle/service/PointService.java

@@ -225,17 +225,20 @@ public class PointService {
      */
     public int recalculateUserPoints(User user) {
         // 获取用户所有的积分历史记录（由于@Where注解，已删除的记录会被自动过滤）
-        List<PointHistory> histories = pointHistoryRepository.findByUserOrderByIdDesc(user);
-        
+        List<PointHistory> histories = pointHistoryRepository.findByUserOrderByIdAsc(user);
+
         int totalPoints = 0;
         for (PointHistory history : histories) {
             totalPoints += history.getAmount();
+            // 重新计算每条历史记录的余额
+            history.setBalance(totalPoints);
         }
-        
-        // 更新用户积分
+
+        // 批量更新历史记录及用户积分
+        pointHistoryRepository.saveAll(histories);
         user.setPoint(totalPoints);
         userRepository.save(user);
-        
+
         return totalPoints;
     }
 

backend/src/main/java/com/openisle/service/PostChangeLogService.java

@@ -0,0 +1,121 @@
+package com.openisle.service;
+
+import com.openisle.model.*;
+import com.openisle.repository.PostChangeLogRepository;
+import com.openisle.repository.PostRepository;
+import com.openisle.repository.UserRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+@Service
+@RequiredArgsConstructor
+public class PostChangeLogService {
+    private final PostChangeLogRepository logRepository;
+    private final PostRepository  postRepository;
+    private final UserRepository userRepository;
+
+    private User getSystemUser() {
+        return userRepository.findByUsername("system")
+                .orElseThrow(() -> new IllegalStateException("System user not found"));
+    }
+
+    public void recordContentChange(Post post, User user, String oldContent, String newContent) {
+        PostContentChangeLog log = new PostContentChangeLog();
+        log.setPost(post);
+        log.setUser(user);
+        log.setType(PostChangeType.CONTENT);
+        log.setOldContent(oldContent);
+        log.setNewContent(newContent);
+        logRepository.save(log);
+    }
+
+    public void recordTitleChange(Post post, User user, String oldTitle, String newTitle) {
+        PostTitleChangeLog log = new PostTitleChangeLog();
+        log.setPost(post);
+        log.setUser(user);
+        log.setType(PostChangeType.TITLE);
+        log.setOldTitle(oldTitle);
+        log.setNewTitle(newTitle);
+        logRepository.save(log);
+    }
+
+    public void recordCategoryChange(Post post, User user, String oldCategory, String newCategory) {
+        PostCategoryChangeLog log = new PostCategoryChangeLog();
+        log.setPost(post);
+        log.setUser(user);
+        log.setType(PostChangeType.CATEGORY);
+        log.setOldCategory(oldCategory);
+        log.setNewCategory(newCategory);
+        logRepository.save(log);
+    }
+
+    public void recordTagChange(Post post, User user, Set<Tag> oldTags, Set<Tag> newTags) {
+        PostTagChangeLog log = new PostTagChangeLog();
+        log.setPost(post);
+        log.setUser(user);
+        log.setType(PostChangeType.TAG);
+        log.setOldTags(oldTags.stream().map(Tag::getName).collect(Collectors.joining(",")));
+        log.setNewTags(newTags.stream().map(Tag::getName).collect(Collectors.joining(",")));
+        logRepository.save(log);
+    }
+
+    public void recordClosedChange(Post post, User user, boolean oldClosed, boolean newClosed) {
+        PostClosedChangeLog log = new PostClosedChangeLog();
+        log.setPost(post);
+        log.setUser(user);
+        log.setType(PostChangeType.CLOSED);
+        log.setOldClosed(oldClosed);
+        log.setNewClosed(newClosed);
+        logRepository.save(log);
+    }
+
+    public void recordPinnedChange(Post post, User user, java.time.LocalDateTime oldPinnedAt, java.time.LocalDateTime newPinnedAt) {
+        PostPinnedChangeLog log = new PostPinnedChangeLog();
+        log.setPost(post);
+        log.setUser(user);
+        log.setType(PostChangeType.PINNED);
+        log.setOldPinnedAt(oldPinnedAt);
+        log.setNewPinnedAt(newPinnedAt);
+        logRepository.save(log);
+    }
+
+    public void recordFeaturedChange(Post post, User user, boolean oldFeatured, boolean newFeatured) {
+        PostFeaturedChangeLog log = new PostFeaturedChangeLog();
+        log.setPost(post);
+        log.setUser(user);
+        log.setType(PostChangeType.FEATURED);
+        log.setOldFeatured(oldFeatured);
+        log.setNewFeatured(newFeatured);
+        logRepository.save(log);
+    }
+
+    public void recordVoteResult(Post post) {
+        PostVoteResultChangeLog log = new PostVoteResultChangeLog();
+        log.setPost(post);
+        log.setUser(getSystemUser());
+        log.setType(PostChangeType.VOTE_RESULT);
+        logRepository.save(log);
+    }
+
+    public void recordLotteryResult(Post post) {
+        PostLotteryResultChangeLog log = new PostLotteryResultChangeLog();
+        log.setPost(post);
+        log.setUser(getSystemUser());
+        log.setType(PostChangeType.LOTTERY_RESULT);
+        logRepository.save(log);
+    }
+
+    public void deleteLogsForPost(Post post) {
+        logRepository.deleteByPost(post);
+    }
+
+    public List<PostChangeLog> listLogs(Long postId) {
+        Post post = postRepository.findById(postId)
+                .orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
+        return logRepository.findByPostOrderByCreatedAtAsc(post);
+    }
+}

backend/src/main/java/com/openisle/service/PostService.java

@@ -1,38 +1,33 @@
 package com.openisle.service;
 
-import com.openisle.model.Post;
-import com.openisle.model.PostStatus;
-import com.openisle.model.PostType;
-import com.openisle.model.PublishMode;
-import com.openisle.model.User;
-import com.openisle.model.Category;
-import com.openisle.model.Comment;
-import com.openisle.model.NotificationType;
-import com.openisle.model.LotteryPost;
-import com.openisle.model.PollPost;
-import com.openisle.model.PollVote;
+import com.openisle.config.CachingConfig;
+import com.openisle.mapper.PostMapper;
+import com.openisle.model.*;
 import com.openisle.repository.PostRepository;
 import com.openisle.repository.LotteryPostRepository;
 import com.openisle.repository.PollPostRepository;
 import com.openisle.repository.UserRepository;
 import com.openisle.repository.CategoryRepository;
 import com.openisle.repository.TagRepository;
-import com.openisle.service.SubscriptionService;
-import com.openisle.service.CommentService;
 import com.openisle.repository.CommentRepository;
 import com.openisle.repository.ReactionRepository;
 import com.openisle.repository.PostSubscriptionRepository;
 import com.openisle.repository.NotificationRepository;
 import com.openisle.repository.PollVoteRepository;
-import com.openisle.model.Role;
+import com.openisle.repository.PointHistoryRepository;
 import com.openisle.exception.RateLimitException;
 import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.cache.annotation.CacheEvict;
+import org.springframework.cache.annotation.Cacheable;
 import org.springframework.context.ApplicationContext;
+import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.stereotype.Service;
 import org.springframework.scheduling.TaskScheduler;
 import com.openisle.service.EmailSender;
 
+import java.time.Duration;
 import java.time.ZoneId;
 import java.time.ZoneOffset;
 import java.util.*;
@@ -47,6 +42,8 @@ import java.time.LocalDateTime;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 import java.util.concurrent.ScheduledFuture;
+import java.util.stream.Collectors;
+
 import org.springframework.boot.context.event.ApplicationReadyEvent;
 import org.springframework.context.event.EventListener;
 
@@ -74,10 +71,14 @@ public class PostService {
     private final EmailSender emailSender;
     private final ApplicationContext applicationContext;
     private final PointService pointService;
+    private final PostChangeLogService postChangeLogService;
+    private final PointHistoryRepository pointHistoryRepository;
     private final ConcurrentMap<Long, ScheduledFuture<?>> scheduledFinalizations = new ConcurrentHashMap<>();
     @Value("${app.website-url:https://www.open-isle.com}")
     private String websiteUrl;
 
+    private final RedisTemplate redisTemplate;
+
     @org.springframework.beans.factory.annotation.Autowired
     public PostService(PostRepository postRepository,
                        UserRepository userRepository,
@@ -99,7 +100,10 @@ public class PostService {
                        EmailSender emailSender,
                        ApplicationContext applicationContext,
                        PointService pointService,
-                       @Value("${app.post.publish-mode:DIRECT}") PublishMode publishMode) {
+                       PostChangeLogService postChangeLogService,
+                       PointHistoryRepository pointHistoryRepository,
+                       @Value("${app.post.publish-mode:DIRECT}") PublishMode publishMode,
+                       RedisTemplate redisTemplate) {
         this.postRepository = postRepository;
         this.userRepository = userRepository;
         this.categoryRepository = categoryRepository;
@@ -120,7 +124,11 @@ public class PostService {
         this.emailSender = emailSender;
         this.applicationContext = applicationContext;
         this.pointService = pointService;
+        this.postChangeLogService = postChangeLogService;
+        this.pointHistoryRepository = pointHistoryRepository;
         this.publishMode = publishMode;
+
+        this.redisTemplate = redisTemplate;
     }
 
     @EventListener(ApplicationReadyEvent.class)
@@ -159,26 +167,37 @@ public class PostService {
         return postRepository.findByStatusAndRssExcludedFalseOrderByCreatedAtDesc(PostStatus.PUBLISHED, pageable);
     }
 
-    public Post excludeFromRss(Long id) {
+    public Post excludeFromRss(Long id, String username) {
         Post post = postRepository.findById(id).orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
+        User user = userRepository.findByUsername(username)
+                .orElseThrow(() -> new com.openisle.exception.NotFoundException("User not found"));
+        boolean oldFeatured = !Boolean.TRUE.equals(post.getRssExcluded());
         post.setRssExcluded(true);
-        return postRepository.save(post);
+        Post saved = postRepository.save(post);
+        postChangeLogService.recordFeaturedChange(saved, user, oldFeatured, false);
+        return saved;
     }
 
-    public Post includeInRss(Long id) {
+    public Post includeInRss(Long id, String username) {
         Post post = postRepository.findById(id).orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
+        User user = userRepository.findByUsername(username)
+                .orElseThrow(() -> new com.openisle.exception.NotFoundException("User not found"));
+        boolean oldFeatured = !Boolean.TRUE.equals(post.getRssExcluded());
         post.setRssExcluded(false);
-        post = postRepository.save(post);
-        notificationService.createNotification(post.getAuthor(), NotificationType.POST_FEATURED, post, null, null, null, null, null);
-        pointService.awardForFeatured(post.getAuthor().getUsername(), post.getId());
-        return post;
+        Post saved = postRepository.save(post);
+        postChangeLogService.recordFeaturedChange(saved, user, oldFeatured, true);
+        notificationService.createNotification(saved.getAuthor(), NotificationType.POST_FEATURED, saved, null, null, null, null, null);
+        pointService.awardForFeatured(saved.getAuthor().getUsername(), saved.getId());
+        return saved;
     }
-
+    @CacheEvict(
+        value = CachingConfig.POST_CACHE_NAME, allEntries = true
+    )
     public Post createPost(String username,
                            Long categoryId,
                            String title,
                            String content,
-                           java.util.List<Long> tagIds,
+                           List<Long> tagIds,
                            PostType type,
                            String prizeDescription,
                            String prizeIcon,
@@ -188,9 +207,9 @@ public class PostService {
                            LocalDateTime endTime,
                            java.util.List<String> options,
                            Boolean multiple) {
-        long recent = postRepository.countByAuthorAfter(username,
-                java.time.LocalDateTime.now().minusMinutes(5));
-        if (recent >= 1) {
+        // 限制访问次数
+        boolean limitResult = postRateLimit(username);
+        if (!limitResult) {
             throw new RateLimitException("Too many posts");
         }
         if (tagIds == null || tagIds.isEmpty()) {
@@ -287,6 +306,23 @@ public class PostService {
         return post;
     }
 
+    /**
+     * 限制发帖频率
+     * @param username
+     * @return
+     */
+    private boolean postRateLimit(String username){
+        String key = CachingConfig.LIMIT_CACHE_NAME +":posts:"+username;
+        String result = (String)redisTemplate.opsForValue().get(key);
+        //最近没有创建过文章
+        if(StringUtils.isEmpty(result)){
+            // 限制频率为5分钟
+            redisTemplate.opsForValue().set(key,"1", Duration.ofMinutes(5));
+            return true;
+        }
+        return false;
+    }
+
     public void joinLottery(Long postId, String username) {
         LotteryPost post = lotteryPostRepository.findById(postId)
                 .orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
@@ -355,6 +391,7 @@ public class PostService {
             for (User participant : pp.getParticipants()) {
                 notificationService.createNotification(participant, NotificationType.POLL_RESULT_PARTICIPANT, pp, null, null, null, null, null);
             }
+            postChangeLogService.recordVoteResult(pp);
         });
     }
 
@@ -389,6 +426,7 @@ public class PostService {
                 notificationService.createNotification(lp.getAuthor(), NotificationType.LOTTERY_DRAW, lp, null, null, null, null, null);
                 notificationService.sendCustomPush(lp.getAuthor(), "抽奖已开奖", String.format("%s/posts/%d", websiteUrl, lp.getId()));
             }
+            postChangeLogService.recordLotteryResult(lp);
         });
     }
 
@@ -470,6 +508,10 @@ public class PostService {
         return listPostsByLatestReply(null, null, page, pageSize);
     }
 
+    @Cacheable(
+            value = CachingConfig.POST_CACHE_NAME,
+            key = "new org.springframework.cache.interceptor.SimpleKey('latest_reply', #categoryIds, #tagIds, #page, #pageSize)"
+    )
     public List<Post> listPostsByLatestReply(java.util.List<Long> categoryIds,
                                              java.util.List<Long> tagIds,
                                              Integer page,
@@ -497,9 +539,9 @@ public class PostService {
                 posts = postRepository.findByCategoryInAndStatusOrderByCreatedAtDesc(categories, PostStatus.PUBLISHED);
             }
         } else {
-            java.util.List<com.openisle.model.Tag> tags = tagRepository.findAllById(tagIds);
+            List<Tag> tags = tagRepository.findAllById(tagIds);
             if (tags.isEmpty()) {
-                return java.util.List.of();
+                return new ArrayList<>();
             }
             posts = postRepository.findByAllTagsOrderByCreatedAtDesc(tags, PostStatus.PUBLISHED, tags.size());
         }
@@ -597,11 +639,43 @@ public class PostService {
         return paginate(sortByPinnedAndCreated(posts), page, pageSize);
     }
 
+    /**
+     * 默认的文章列表
+     * @param ids
+     * @param tids
+     * @param page
+     * @param pageSize
+     * @return
+     */
+    @Cacheable(
+            value = CachingConfig.POST_CACHE_NAME,
+            key = "new org.springframework.cache.interceptor.SimpleKey('default', #ids, #tids, #page, #pageSize)"
+    )
+    public List<Post> defaultListPosts(List<Long> ids, List<Long> tids, Integer page, Integer pageSize){
+        boolean hasCategories = !CollectionUtils.isEmpty(ids);
+        boolean hasTags = !CollectionUtils.isEmpty(tids);
+
+        if (hasCategories && hasTags) {
+            return listPostsByCategoriesAndTags(ids, tids, page, pageSize)
+                    .stream().collect(Collectors.toList());
+        }
+        if (hasTags) {
+            return listPostsByTags(tids, page, pageSize)
+                    .stream().collect(Collectors.toList());
+        }
+
+        return listPostsByCategories(ids, page, pageSize)
+                .stream().collect(Collectors.toList());
+    }
 
     public List<Post> listPendingPosts() {
         return postRepository.findByStatus(PostStatus.PENDING);
     }
 
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
     public Post approvePost(Long id) {
         Post post = postRepository.findById(id)
                 .orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
@@ -638,20 +712,42 @@ public class PostService {
         return post;
     }
 
-    public Post pinPost(Long id) {
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
+    public Post pinPost(Long id, String username) {
         Post post = postRepository.findById(id)
                 .orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
+        User user = userRepository.findByUsername(username)
+                .orElseThrow(() -> new com.openisle.exception.NotFoundException("User not found"));
+        java.time.LocalDateTime oldPinned = post.getPinnedAt();
         post.setPinnedAt(java.time.LocalDateTime.now());
-        return postRepository.save(post);
+        Post saved = postRepository.save(post);
+        postChangeLogService.recordPinnedChange(saved, user, oldPinned, saved.getPinnedAt());
+        return saved;
     }
 
-    public Post unpinPost(Long id) {
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
+    public Post unpinPost(Long id, String username) {
         Post post = postRepository.findById(id)
                 .orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
+        User user = userRepository.findByUsername(username)
+                .orElseThrow(() -> new com.openisle.exception.NotFoundException("User not found"));
+        java.time.LocalDateTime oldPinned = post.getPinnedAt();
         post.setPinnedAt(null);
-        return postRepository.save(post);
+        Post saved = postRepository.save(post);
+        postChangeLogService.recordPinnedChange(saved, user, oldPinned, null);
+        return saved;
     }
 
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
     public Post closePost(Long id, String username) {
         Post post = postRepository.findById(id)
                 .orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
@@ -660,10 +756,17 @@ public class PostService {
         if (!user.getId().equals(post.getAuthor().getId()) && user.getRole() != Role.ADMIN) {
             throw new IllegalArgumentException("Unauthorized");
         }
+        boolean oldClosed = post.isClosed();
         post.setClosed(true);
-        return postRepository.save(post);
+        Post saved = postRepository.save(post);
+        postChangeLogService.recordClosedChange(saved, user, oldClosed, true);
+        return saved;
     }
 
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
     public Post reopenPost(Long id, String username) {
         Post post = postRepository.findById(id)
                 .orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
@@ -672,11 +775,18 @@ public class PostService {
         if (!user.getId().equals(post.getAuthor().getId()) && user.getRole() != Role.ADMIN) {
             throw new IllegalArgumentException("Unauthorized");
         }
+        boolean oldClosed = post.isClosed();
         post.setClosed(false);
-        return postRepository.save(post);
+        Post saved = postRepository.save(post);
+        postChangeLogService.recordClosedChange(saved, user, oldClosed, false);
+        return saved;
     }
 
-    @org.springframework.transaction.annotation.Transactional
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
+    @Transactional
     public Post updatePost(Long id,
                            String username,
                            Long categoryId,
@@ -702,18 +812,38 @@ public class PostService {
         if (tags.isEmpty()) {
             throw new IllegalArgumentException("Tag not found");
         }
-        post.setTitle(title);
+        String oldTitle = post.getTitle();
         String oldContent = post.getContent();
+        Category oldCategory = post.getCategory();
+        java.util.Set<com.openisle.model.Tag> oldTags = new java.util.HashSet<>(post.getTags());
+        post.setTitle(title);
         post.setContent(content);
         post.setCategory(category);
         post.setTags(new java.util.HashSet<>(tags));
         Post updated = postRepository.save(post);
         imageUploader.adjustReferences(oldContent, content);
         notificationService.notifyMentions(content, user, updated, null);
+        if (!java.util.Objects.equals(oldTitle, title)) {
+            postChangeLogService.recordTitleChange(updated, user, oldTitle, title);
+        }
+        if (!java.util.Objects.equals(oldContent, content)) {
+            postChangeLogService.recordContentChange(updated, user, oldContent, content);
+        }
+        if (!java.util.Objects.equals(oldCategory.getId(), category.getId())) {
+            postChangeLogService.recordCategoryChange(updated, user, oldCategory.getName(), category.getName());
+        }
+        java.util.Set<com.openisle.model.Tag> newTags = new java.util.HashSet<>(tags);
+        if (!oldTags.equals(newTags)) {
+            postChangeLogService.recordTagChange(updated, user, oldTags, newTags);
+        }
         return updated;
     }
 
-    @org.springframework.transaction.annotation.Transactional
+    @CacheEvict(
+            value = CachingConfig.POST_CACHE_NAME,
+            allEntries = true
+    )
+    @Transactional
     public void deletePost(Long id, String username) {
         Post post = postRepository.findById(id)
                 .orElseThrow(() -> new com.openisle.exception.NotFoundException("Post not found"));
@@ -732,6 +862,25 @@ public class PostService {
         notificationRepository.deleteAll(notificationRepository.findByPost(post));
         postReadService.deleteByPost(post);
         imageUploader.removeReferences(imageUploader.extractUrls(post.getContent()));
+        List<PointHistory> pointHistories = pointHistoryRepository.findByPost(post);
+        Set<User> usersToRecalculate = pointHistories.stream()
+                .map(PointHistory::getUser)
+                .collect(Collectors.toSet());
+        if (!pointHistories.isEmpty()) {
+            LocalDateTime deletedAt = LocalDateTime.now();
+            for (PointHistory history : pointHistories) {
+                history.setDeletedAt(deletedAt);
+                history.setPost(null);
+            }
+            pointHistoryRepository.saveAll(pointHistories);
+        }
+        if (!usersToRecalculate.isEmpty()) {
+            for (User affected : usersToRecalculate) {
+                int newPoints = pointService.recalculateUserPoints(affected);
+                affected.setPoint(newPoints);
+            }
+            userRepository.saveAll(usersToRecalculate);
+        }
         if (post instanceof LotteryPost lp) {
             ScheduledFuture<?> future = scheduledFinalizations.remove(lp.getId());
             if (future != null) {
@@ -739,6 +888,7 @@ public class PostService {
             }
         }
         String title = post.getTitle();
+        postChangeLogService.deleteLogsForPost(post);
         postRepository.delete(post);
         if (adminDeleting) {
             notificationService.createNotification(author, NotificationType.POST_DELETED,
@@ -806,15 +956,17 @@ public class PostService {
                 .toList();
     }
 
-    private java.util.List<Post> paginate(java.util.List<Post> posts, Integer page, Integer pageSize) {
+    private List<Post> paginate(List<Post> posts, Integer page, Integer pageSize) {
         if (page == null || pageSize == null) {
             return posts;
         }
         int from = page * pageSize;
         if (from >= posts.size()) {
-            return java.util.List.of();
+            return new ArrayList<>();
         }
         int to = Math.min(from + pageSize, posts.size());
-        return posts.subList(from, to);
+        // 这里必须将list包装为arrayList类型，否则序列化会有问题
+        // list.sublist返回的是内部类
+        return new ArrayList<>(posts.subList(from, to));
     }
 }

backend/src/main/java/com/openisle/service/TagService.java

@@ -120,4 +120,18 @@ public class TagService {
                 .orElseThrow(() -> new com.openisle.exception.NotFoundException("User not found"));
         return tagRepository.findByCreator(user);
     }
+
+    /**
+     * 获取检索用的标签Id列表
+     * @param tagIds
+     * @param tagId
+     * @return
+     */
+    public List<Long> getSearchTagIds(List<Long> tagIds, Long tagId){
+        List<Long> ids = tagIds;
+        if (tagId != null) {
+            ids = List.of(tagId);
+        }
+        return ids;
+    }
 }

backend/src/main/java/com/openisle/service/UserService.java

@@ -1,5 +1,6 @@
 package com.openisle.service;
 
+import com.openisle.config.CachingConfig;
 import com.openisle.model.User;
 import com.openisle.model.Role;
 import com.openisle.service.PasswordValidator;
@@ -7,13 +8,18 @@ import com.openisle.service.UsernameValidator;
 import com.openisle.service.AvatarGenerator;
 import com.openisle.exception.FieldException;
 import com.openisle.repository.UserRepository;
+import com.openisle.util.VerifyType;
 import lombok.RequiredArgsConstructor;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
 import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.stereotype.Service;
 
+import java.util.Objects;
 import java.util.Optional;
 import java.util.Random;
+import java.util.concurrent.TimeUnit;
 
 @Service
 @RequiredArgsConstructor
@@ -25,6 +31,10 @@ public class UserService {
     private final ImageUploader imageUploader;
     private final AvatarGenerator avatarGenerator;
 
+    private final RedisTemplate redisTemplate;
+
+    private final EmailSender emailService;
+
     public User register(String username, String email, String password, String reason, com.openisle.model.RegisterMode mode) {
         usernameValidator.validate(username);
         passwordValidator.validate(password);
@@ -38,7 +48,7 @@ public class UserService {
             // 未验证 → 允许“重注册”：覆盖必要字段并重新发验证码
             u.setEmail(email);                              // 若不允许改邮箱可去掉
             u.setPassword(passwordEncoder.encode(password));
-            u.setVerificationCode(genCode());
+//            u.setVerificationCode(genCode());
             u.setRegisterReason(reason);
             u.setApproved(mode == com.openisle.model.RegisterMode.DIRECT);
             return userRepository.save(u);
@@ -54,7 +64,7 @@ public class UserService {
             // 未验证 → 允许“重注册”
             u.setUsername(username);                        // 若不允许改用户名可去掉
             u.setPassword(passwordEncoder.encode(password));
-            u.setVerificationCode(genCode());
+//            u.setVerificationCode(genCode());
             u.setRegisterReason(reason);
             u.setApproved(mode == com.openisle.model.RegisterMode.DIRECT);
             return userRepository.save(u);
@@ -67,7 +77,7 @@ public class UserService {
         user.setPassword(passwordEncoder.encode(password));
         user.setRole(Role.USER);
         user.setVerified(false);
-        user.setVerificationCode(genCode());
+//        user.setVerificationCode(genCode());
         user.setAvatar(avatarGenerator.generate(username));
         user.setRegisterReason(reason);
         user.setApproved(mode == com.openisle.model.RegisterMode.DIRECT);
@@ -77,7 +87,7 @@ public class UserService {
     public User registerWithInvite(String username, String email, String password) {
         User user = register(username, email, password, "", com.openisle.model.RegisterMode.DIRECT);
         user.setVerified(true);
-        user.setVerificationCode(genCode());
+//        user.setVerificationCode(genCode());
         return userRepository.save(user);
     }
 
@@ -85,16 +95,58 @@ public class UserService {
         return String.format("%06d", new Random().nextInt(1000000));
     }
 
-    public boolean verifyCode(String username, String code) {
-        Optional<User> userOpt = userRepository.findByUsername(username);
-        if (userOpt.isPresent() && code.equals(userOpt.get().getVerificationCode())) {
-            User user = userOpt.get();
-            user.setVerified(true);
-            user.setVerificationCode(null);
-            userRepository.save(user);
-            return true;
+    /**
+     * 将验证码存入缓存，并发送邮件
+     * @param user
+     */
+    public void sendVerifyMail(User user, VerifyType verifyType){
+        // 缓存验证码
+        String code = genCode();
+        String key;
+        String subject;
+        String content = "您的验证码是:" + code;
+        // 注册类型
+        if(verifyType.equals(VerifyType.REGISTER)){
+            key = CachingConfig.VERIFY_CACHE_NAME + ":register:code:" + user.getUsername();
+            subject = "在网站填写验证码以验证(有效期为5分钟)";
+        }else {
+            // 重置密码
+            key = CachingConfig.VERIFY_CACHE_NAME + ":reset_password:code:" + user.getUsername();
+            subject = "请填写验证码以重置密码(有效期为5分钟)";
         }
-        return false;
+
+        redisTemplate.opsForValue().set(key, code, 5, TimeUnit.MINUTES);// 五分钟后验证码过期
+        emailService.sendEmail(user.getEmail(), subject, content);
+    }
+
+    /**
+     * 验证code是否正确
+     * @param user
+     * @param code
+     * @param verifyType
+     * @return
+     */
+    public boolean verifyCode(User user, String code, VerifyType verifyType) {
+        // 生成key
+        String key1 = VerifyType.REGISTER.equals(verifyType)?":register:code:":":reset_password:code:";
+        String key = CachingConfig.VERIFY_CACHE_NAME + key1 + user.getUsername();
+        // 这里不能使用getAndDelete,需要6.x版本
+        String cachedCode = (String)redisTemplate.opsForValue().get(key);
+        // 如果校验code过期或者不存在
+        // 或者校验code不一致
+        if(Objects.isNull(cachedCode)
+                || !cachedCode.equals(code)){
+            return false;
+        }
+        // 注册模式需要设置已经确认
+        if(VerifyType.REGISTER.equals(verifyType)){
+            user.setVerified(true);
+            userRepository.save(user);
+        }
+        // 走到这里说明验证成功删除验证码
+        redisTemplate.delete(key);
+        return true;
+
     }
 
     public Optional<User> authenticate(String username, String password) {
@@ -165,26 +217,6 @@ public class UserService {
         return userRepository.save(user);
     }
 
-    public String generatePasswordResetCode(String email) {
-        User user = userRepository.findByEmail(email)
-                .orElseThrow(() -> new com.openisle.exception.NotFoundException("User not found"));
-        String code = genCode();
-        user.setPasswordResetCode(code);
-        userRepository.save(user);
-        return code;
-    }
-
-    public boolean verifyPasswordResetCode(String email, String code) {
-        Optional<User> userOpt = userRepository.findByEmail(email);
-        if (userOpt.isPresent() && code.equals(userOpt.get().getPasswordResetCode())) {
-            User user = userOpt.get();
-            user.setPasswordResetCode(null);
-            userRepository.save(user);
-            return true;
-        }
-        return false;
-    }
-
     public User updatePassword(String username, String newPassword) {
         passwordValidator.validate(newPassword);
         User user = userRepository.findByUsername(username)

backend/src/main/java/com/openisle/service/UserVisitService.java

@@ -1,15 +1,22 @@
 package com.openisle.service;
 
+import com.openisle.config.CachingConfig;
 import com.openisle.model.User;
 import com.openisle.model.UserVisit;
 import com.openisle.repository.UserRepository;
 import com.openisle.repository.UserVisitRepository;
 import lombok.RequiredArgsConstructor;
+import org.springframework.cache.annotation.CacheConfig;
+import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.stereotype.Service;
+import org.springframework.util.CollectionUtils;
 
+import java.time.Duration;
 import java.time.LocalDate;
+import java.time.LocalDateTime;
 import java.util.LinkedHashMap;
 import java.util.Map;
+import java.util.Set;
 
 @Service
 @RequiredArgsConstructor
@@ -17,6 +24,8 @@ public class UserVisitService {
     private final UserVisitRepository userVisitRepository;
     private final UserRepository userRepository;
 
+    private final RedisTemplate redisTemplate;
+
     public boolean recordVisit(String username) {
         User user = userRepository.findByUsername(username)
                 .orElseThrow(() -> new com.openisle.exception.NotFoundException("User not found"));
@@ -30,10 +39,36 @@ public class UserVisitService {
         });
     }
 
+    /**
+     * 统计访问次数，改为从缓存获取/数据库获取
+     * @param username
+     * @return
+     */
     public long countVisits(String username) {
         User user = userRepository.findByUsername(username)
                 .orElseThrow(() -> new com.openisle.exception.NotFoundException("User not found"));
-        return userVisitRepository.countByUser(user);
+
+        // 如果缓存存在就返回
+        String key1 = CachingConfig.VISIT_CACHE_NAME + ":" +LocalDate.now() + ":count:" + username;
+        Integer cached = (Integer) redisTemplate.opsForValue().get(key1);
+        if (cached != null){
+            return cached.longValue();
+        }
+
+        // Redis Set 检查今天是否访问
+        String todayKey = CachingConfig.VISIT_CACHE_NAME + ":" + LocalDate.now();
+        boolean todayVisited = redisTemplate.opsForSet().isMember(todayKey, username);
+
+        Long visitCount = userVisitRepository.countByUser(user);
+        if (todayVisited) visitCount += 1;
+
+        LocalDateTime now = LocalDateTime.now();
+        LocalDateTime endOfDay = now.toLocalDate().atTime(23, 59, 59);
+        long secondsUntilEndOfDay = Duration.between(now, endOfDay).getSeconds();
+
+        // 写入缓存，设置 TTL，当天剩余时间
+        redisTemplate.opsForValue().set(key1, visitCount, Duration.ofSeconds(secondsUntilEndOfDay));
+        return visitCount;
     }
 
     public long countDau(LocalDate date) {

backend/src/main/java/com/openisle/service/UsernameValidator.java

@@ -1,6 +1,7 @@
 package com.openisle.service;
 
 import com.openisle.exception.FieldException;
+import org.apache.commons.lang3.math.NumberUtils;
 import org.springframework.stereotype.Service;
 
 /**
@@ -17,6 +18,11 @@ public class UsernameValidator {
         if (username == null || username.isEmpty()) {
             throw new FieldException("username", "Username cannot be empty");
         }
+
+        if (NumberUtils.isDigits(username)) {
+            throw new FieldException("username", "Username cannot be pure number");
+        }
     }
+
 }
 

backend/src/main/java/com/openisle/util/VerifyType.java

@@ -0,0 +1,20 @@
+package com.openisle.util;
+
+/**
+ * 验证码类型
+ * @author smallclover
+ * @since  2025-09-08
+ */
+public enum VerifyType {
+    REGISTER(1),
+    RESET_PASSWORD(2);
+    private final int code;
+
+    VerifyType(int code) {
+        this.code = code;
+    }
+
+    public int getCode() {
+        return code;
+    }
+}

backend/src/main/resources/application.properties

@@ -108,6 +108,10 @@ rabbitmq.sharding.enabled=true
 # see https://springdoc.org/#springdoc-openapi-core-properties
 springdoc.api-docs.path=/api/v3/api-docs
 springdoc.api-docs.enabled=true
+springdoc.api-docs.servers[0].url=https://www.open-isle.com
+springdoc.api-docs.servers[0].description=Production Environment
+springdoc.api-docs.servers[1].url=https://www.staging.open-isle.com
+springdoc.api-docs.servers[1].description=Staging Environment
 springdoc.info.title=OpenIsle
 springdoc.info.description=OpenIsle Open API Documentation
 springdoc.info.version=0.0.1

backend/src/main/resources/db/migration/V5__add_comment_stats_to_posts.sql

@@ -0,0 +1,19 @@
+-- Add comment count and last reply time fields to posts table for performance optimization
+ALTER TABLE posts ADD COLUMN comment_count BIGINT NOT NULL DEFAULT 0;
+ALTER TABLE posts ADD COLUMN last_reply_at DATETIME(6) NULL;
+
+-- Add index on last_reply_at for sorting by latest reply
+CREATE INDEX idx_posts_last_reply_at ON posts(last_reply_at);
+
+-- Initialize comment_count and last_reply_at with existing data
+UPDATE posts p SET 
+    comment_count = (
+        SELECT COUNT(*) 
+        FROM comments c 
+        WHERE c.post_id = p.id AND c.deleted_at IS NULL
+    ),
+    last_reply_at = (
+        SELECT MAX(c.created_at) 
+        FROM comments c 
+        WHERE c.post_id = p.id AND c.deleted_at IS NULL
+    );

backend/src/test/java/com/openisle/controller/AuthControllerTest.java

@@ -4,6 +4,7 @@ import com.openisle.model.User;
 import com.openisle.service.*;
 import com.openisle.model.RegisterMode;
 import com.openisle.repository.UserRepository;
+import com.openisle.util.VerifyType;
 import org.junit.jupiter.api.Test;
 import org.mockito.Mockito;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -71,7 +72,9 @@ class AuthControllerTest {
 
     @Test
     void verifyCodeEndpoint() throws Exception {
-        Mockito.when(userService.verifyCode("u", "123")).thenReturn(true);
+        User user = new User();
+        user.setUsername("u");
+        Mockito.when(userService.verifyCode(user, "123", VerifyType.REGISTER)).thenReturn(true);
         Mockito.when(jwtService.generateReasonToken("u")).thenReturn("reason_token");
 
         mockMvc.perform(post("/api/auth/verify")

backend/src/test/java/com/openisle/controller/PostControllerTest.java

@@ -55,6 +55,10 @@ class PostControllerTest {
     private UserVisitService userVisitService;
     @MockBean
     private PostReadService postReadService;
+    @MockBean
+    private MedalService medalService;
+    @MockBean
+    private com.openisle.repository.PollVoteRepository pollVoteRepository;
 
     @Test
     void createAndGetPost() throws Exception {
@@ -63,9 +67,13 @@ class PostControllerTest {
         Category cat = new Category();
         cat.setId(1L);
         cat.setName("tech");
+        cat.setDescription("Technology category");
+        cat.setIcon("tech-icon");
         Tag tag = new Tag();
         tag.setId(1L);
         tag.setName("java");
+        tag.setDescription("Java programming language");
+        tag.setIcon("java-icon");
         Post post = new Post();
         post.setId(1L);
         post.setTitle("t");
@@ -111,9 +119,13 @@ class PostControllerTest {
         Category cat = new Category();
         cat.setId(1L);
         cat.setName("tech");
+        cat.setDescription("Technology category");
+        cat.setIcon("tech-icon");
         Tag tag = new Tag();
         tag.setId(1L);
         tag.setName("java");
+        tag.setDescription("Java programming language");
+        tag.setIcon("java-icon");
         Post post = new Post();
         post.setId(1L);
         post.setTitle("t2");
@@ -147,9 +159,13 @@ class PostControllerTest {
         Category cat = new Category();
         cat.setId(1L);
         cat.setName("tech");
+        cat.setDescription("Technology category");
+        cat.setIcon("tech-icon");
         Tag tag = new Tag();
         tag.setId(1L);
         tag.setName("java");
+        tag.setDescription("Java programming language");
+        tag.setIcon("java-icon");
         Post post = new Post();
         post.setId(2L);
         post.setTitle("hello");
@@ -197,9 +213,13 @@ class PostControllerTest {
         Category cat = new Category();
         cat.setId(1L);
         cat.setName("tech");
+        cat.setDescription("Technology category");
+        cat.setIcon("tech-icon");
         Tag tag = new Tag();
         tag.setId(1L);
         tag.setName("java");
+        tag.setDescription("Java programming language");
+        tag.setIcon("java-icon");
         Post post = new Post();
         post.setId(1L);
         post.setTitle("t");
@@ -262,6 +282,8 @@ class PostControllerTest {
         Category cat = new Category();
         cat.setId(1L);
         cat.setName("tech");
+        cat.setDescription("Technology category");
+        cat.setIcon("tech-icon");
         Post post = new Post();
         post.setId(1L);
         post.setTitle("t");

backend/src/test/java/com/openisle/service/PointServiceRecalculateUserPointsTest.java

@@ -0,0 +1,67 @@
+package com.openisle.service;
+
+import com.openisle.model.PointHistory;
+import com.openisle.model.PointHistoryType;
+import com.openisle.model.Role;
+import com.openisle.model.User;
+import com.openisle.repository.PointHistoryRepository;
+import com.openisle.repository.UserRepository;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
+import org.springframework.context.annotation.Import;
+
+import java.time.LocalDateTime;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+@DataJpaTest
+@Import(PointService.class)
+class PointServiceRecalculateUserPointsTest {
+
+    @Autowired
+    private PointService pointService;
+
+    @Autowired
+    private UserRepository userRepository;
+
+    @Autowired
+    private PointHistoryRepository pointHistoryRepository;
+
+    @Test
+    void recalculatesBalanceAfterDeletion() {
+        User user = new User();
+        user.setUsername("u");
+        user.setEmail("u@example.com");
+        user.setPassword("p");
+        user.setRole(Role.USER);
+        userRepository.save(user);
+
+        PointHistory h1 = new PointHistory();
+        h1.setUser(user);
+        h1.setType(PointHistoryType.POST);
+        h1.setAmount(30);
+        h1.setBalance(30);
+        h1.setCreatedAt(LocalDateTime.now().minusMinutes(2));
+        pointHistoryRepository.save(h1);
+
+        PointHistory h2 = new PointHistory();
+        h2.setUser(user);
+        h2.setType(PointHistoryType.COMMENT);
+        h2.setAmount(10);
+        h2.setBalance(40);
+        h2.setCreatedAt(LocalDateTime.now().minusMinutes(1));
+        pointHistoryRepository.save(h2);
+
+        user.setPoint(40);
+        userRepository.save(user);
+
+        pointHistoryRepository.delete(h1);
+
+        int total = pointService.recalculateUserPoints(user);
+
+        assertEquals(10, total);
+        assertEquals(10, userRepository.findById(user.getId()).orElseThrow().getPoint());
+        assertEquals(10, pointHistoryRepository.findById(h2.getId()).orElseThrow().getBalance());
+    }
+}

backend/src/test/java/com/openisle/service/PostCommentStatsTest.java

@@ -0,0 +1,90 @@
+package com.openisle.service;
+
+import com.openisle.model.*;
+import com.openisle.repository.*;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.TestPropertySource;
+import org.springframework.transaction.annotation.Transactional;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest
+@TestPropertySource(locations = "classpath:application.properties")
+@Transactional
+public class PostCommentStatsTest {
+
+    @Autowired
+    private PostRepository postRepository;
+
+    @Autowired
+    private UserRepository userRepository;
+
+    @Autowired
+    private CategoryRepository categoryRepository;
+
+    @Autowired
+    private TagRepository tagRepository;
+
+    @Autowired
+    private CommentService commentService;
+
+    @Test
+    public void testPostCommentStatsUpdate() {
+        // Create test user
+        User user = new User();
+        user.setUsername("testuser");
+        user.setEmail("test@example.com");
+        user.setPassword("hash");
+        user = userRepository.save(user);
+
+        // Create test category
+        Category category = new Category();
+        category.setName("Test Category");
+        category.setDescription("Test Category Description");
+        category.setIcon("test-icon");
+        category = categoryRepository.save(category);
+
+        // Create test tag
+        Tag tag = new Tag();
+        tag.setName("Test Tag");
+        tag.setDescription("Test Tag Description");
+        tag.setIcon("test-tag-icon");
+        tag = tagRepository.save(tag);
+
+        // Create test post
+        Post post = new Post();
+        post.setTitle("Test Post");
+        post.setContent("Test content");
+        post.setAuthor(user);
+        post.setCategory(category);
+        post.getTags().add(tag);
+        post.setStatus(PostStatus.PUBLISHED);
+        post.setCommentCount(0L);
+        post = postRepository.save(post);
+
+        // Verify initial state
+        assertEquals(0L, post.getCommentCount());
+        assertNull(post.getLastReplyAt());
+
+        // Add a comment
+        commentService.addComment("testuser", post.getId(), "Test comment");
+
+        // Refresh post from database
+        post = postRepository.findById(post.getId()).orElseThrow();
+
+        // Verify comment count and last reply time are updated
+        assertEquals(1L, post.getCommentCount());
+        assertNotNull(post.getLastReplyAt());
+
+        // Add another comment
+        commentService.addComment("testuser", post.getId(), "Another comment");
+
+        // Refresh post again
+        post = postRepository.findById(post.getId()).orElseThrow();
+
+        // Verify comment count is updated
+        assertEquals(2L, post.getCommentCount());
+    }
+}

backend/src/test/java/com/openisle/service/PostServiceTest.java

@@ -6,11 +6,15 @@ import com.openisle.exception.RateLimitException;
 import org.junit.jupiter.api.Test;
 import org.springframework.scheduling.TaskScheduler;
 import org.springframework.context.ApplicationContext;
+import org.springframework.data.redis.core.RedisTemplate;
 
 import static org.junit.jupiter.api.Assertions.*;
 
-import java.util.Optional;
+import java.time.LocalDateTime;
 import java.util.List;
+import java.util.Optional;
+
+import org.mockito.ArgumentCaptor;
 
 import static org.mockito.Mockito.*;
 
@@ -37,11 +41,15 @@ class PostServiceTest {
         EmailSender emailSender = mock(EmailSender.class);
         ApplicationContext context = mock(ApplicationContext.class);
         PointService pointService = mock(PointService.class);
+        PostChangeLogService postChangeLogService = mock(PostChangeLogService.class);
+        PointHistoryRepository pointHistoryRepository = mock(PointHistoryRepository.class);
+        RedisTemplate redisTemplate = mock(RedisTemplate.class);
 
         PostService service = new PostService(postRepo, userRepo, catRepo, tagRepo, lotteryRepo,
                 pollPostRepo, pollVoteRepo, notifService, subService, commentService, commentRepo,
                 reactionRepo, subRepo, notificationRepo, postReadService,
-                imageUploader, taskScheduler, emailSender, context, pointService, PublishMode.DIRECT);
+                imageUploader, taskScheduler, emailSender, context, pointService, postChangeLogService,
+                pointHistoryRepository, PublishMode.DIRECT, redisTemplate);
         when(context.getBean(PostService.class)).thenReturn(service);
 
         Post post = new Post();
@@ -57,11 +65,13 @@ class PostServiceTest {
         when(reactionRepo.findByPost(post)).thenReturn(List.of());
         when(subRepo.findByPost(post)).thenReturn(List.of());
         when(notificationRepo.findByPost(post)).thenReturn(List.of());
+        when(pointHistoryRepository.findByPost(post)).thenReturn(List.of());
 
         service.deletePost(1L, "alice");
 
         verify(postReadService).deleteByPost(post);
         verify(postRepo).delete(post);
+        verify(postChangeLogService).deleteLogsForPost(post);
     }
 
     @Test
@@ -86,11 +96,15 @@ class PostServiceTest {
         EmailSender emailSender = mock(EmailSender.class);
         ApplicationContext context = mock(ApplicationContext.class);
         PointService pointService = mock(PointService.class);
+        PostChangeLogService postChangeLogService = mock(PostChangeLogService.class);
+        PointHistoryRepository pointHistoryRepository = mock(PointHistoryRepository.class);
+        RedisTemplate redisTemplate = mock(RedisTemplate.class);
 
         PostService service = new PostService(postRepo, userRepo, catRepo, tagRepo, lotteryRepo,
                 pollPostRepo, pollVoteRepo, notifService, subService, commentService, commentRepo,
                 reactionRepo, subRepo, notificationRepo, postReadService,
-                imageUploader, taskScheduler, emailSender, context, pointService, PublishMode.DIRECT);
+                imageUploader, taskScheduler, emailSender, context, pointService, postChangeLogService,
+                pointHistoryRepository, PublishMode.DIRECT, redisTemplate);
         when(context.getBean(PostService.class)).thenReturn(service);
 
         Post post = new Post();
@@ -112,6 +126,7 @@ class PostServiceTest {
         when(reactionRepo.findByPost(post)).thenReturn(List.of());
         when(subRepo.findByPost(post)).thenReturn(List.of());
         when(notificationRepo.findByPost(post)).thenReturn(List.of());
+        when(pointHistoryRepository.findByPost(post)).thenReturn(List.of());
 
         service.deletePost(1L, "admin");
 
@@ -141,11 +156,15 @@ class PostServiceTest {
         EmailSender emailSender = mock(EmailSender.class);
         ApplicationContext context = mock(ApplicationContext.class);
         PointService pointService = mock(PointService.class);
+        PostChangeLogService postChangeLogService = mock(PostChangeLogService.class);
+        PointHistoryRepository pointHistoryRepository = mock(PointHistoryRepository.class);
+        RedisTemplate redisTemplate = mock(RedisTemplate.class);
 
         PostService service = new PostService(postRepo, userRepo, catRepo, tagRepo, lotteryRepo,
                 pollPostRepo, pollVoteRepo, notifService, subService, commentService, commentRepo,
                 reactionRepo, subRepo, notificationRepo, postReadService,
-                imageUploader, taskScheduler, emailSender, context, pointService, PublishMode.DIRECT);
+                imageUploader, taskScheduler, emailSender, context, pointService, postChangeLogService,
+                pointHistoryRepository, PublishMode.DIRECT, redisTemplate);
         when(context.getBean(PostService.class)).thenReturn(service);
 
         when(postRepo.countByAuthorAfter(eq("alice"), any())).thenReturn(1L);
@@ -155,6 +174,77 @@ class PostServiceTest {
                         null, null, null, null, null, null, null, null, null));
     }
 
+    @Test
+    void deletePostRemovesPointHistoriesAndRecalculatesPoints() {
+        PostRepository postRepo = mock(PostRepository.class);
+        UserRepository userRepo = mock(UserRepository.class);
+        CategoryRepository catRepo = mock(CategoryRepository.class);
+        TagRepository tagRepo = mock(TagRepository.class);
+        LotteryPostRepository lotteryRepo = mock(LotteryPostRepository.class);
+        PollPostRepository pollPostRepo = mock(PollPostRepository.class);
+        PollVoteRepository pollVoteRepo = mock(PollVoteRepository.class);
+        NotificationService notifService = mock(NotificationService.class);
+        SubscriptionService subService = mock(SubscriptionService.class);
+        CommentService commentService = mock(CommentService.class);
+        CommentRepository commentRepo = mock(CommentRepository.class);
+        ReactionRepository reactionRepo = mock(ReactionRepository.class);
+        PostSubscriptionRepository subRepo = mock(PostSubscriptionRepository.class);
+        NotificationRepository notificationRepo = mock(NotificationRepository.class);
+        PostReadService postReadService = mock(PostReadService.class);
+        ImageUploader imageUploader = mock(ImageUploader.class);
+        TaskScheduler taskScheduler = mock(TaskScheduler.class);
+        EmailSender emailSender = mock(EmailSender.class);
+        ApplicationContext context = mock(ApplicationContext.class);
+        PointService pointService = mock(PointService.class);
+        PostChangeLogService postChangeLogService = mock(PostChangeLogService.class);
+        PointHistoryRepository pointHistoryRepository = mock(PointHistoryRepository.class);
+        RedisTemplate redisTemplate = mock(RedisTemplate.class);
+
+        PostService service = new PostService(postRepo, userRepo, catRepo, tagRepo, lotteryRepo,
+                pollPostRepo, pollVoteRepo, notifService, subService, commentService, commentRepo,
+                reactionRepo, subRepo, notificationRepo, postReadService,
+                imageUploader, taskScheduler, emailSender, context, pointService, postChangeLogService,
+                pointHistoryRepository, PublishMode.DIRECT, redisTemplate);
+        when(context.getBean(PostService.class)).thenReturn(service);
+
+        Post post = new Post();
+        post.setId(10L);
+        User author = new User();
+        author.setId(20L);
+        author.setRole(Role.USER);
+        post.setAuthor(author);
+
+        User historyUser = new User();
+        historyUser.setId(30L);
+
+        PointHistory history = new PointHistory();
+        history.setUser(historyUser);
+        history.setPost(post);
+
+        when(postRepo.findById(10L)).thenReturn(Optional.of(post));
+        when(userRepo.findByUsername("author")).thenReturn(Optional.of(author));
+        when(commentRepo.findByPostAndParentIsNullOrderByCreatedAtAsc(post)).thenReturn(List.of());
+        when(reactionRepo.findByPost(post)).thenReturn(List.of());
+        when(subRepo.findByPost(post)).thenReturn(List.of());
+        when(notificationRepo.findByPost(post)).thenReturn(List.of());
+        when(pointHistoryRepository.findByPost(post)).thenReturn(List.of(history));
+        when(pointService.recalculateUserPoints(historyUser)).thenReturn(0);
+
+        service.deletePost(10L, "author");
+
+        ArgumentCaptor<List<PointHistory>> captor = ArgumentCaptor.forClass(List.class);
+        verify(pointHistoryRepository).saveAll(captor.capture());
+        List<PointHistory> savedHistories = captor.getValue();
+        assertEquals(1, savedHistories.size());
+        PointHistory savedHistory = savedHistories.get(0);
+        assertNull(savedHistory.getPost());
+        assertNotNull(savedHistory.getDeletedAt());
+        assertTrue(savedHistory.getDeletedAt().isBefore(LocalDateTime.now().plusSeconds(1)));
+
+        verify(pointService).recalculateUserPoints(historyUser);
+        verify(userRepo).saveAll(any());
+    }
+
     @Test
     void finalizeLotteryNotifiesAuthor() {
         PostRepository postRepo = mock(PostRepository.class);
@@ -177,11 +267,15 @@ class PostServiceTest {
         EmailSender emailSender = mock(EmailSender.class);
         ApplicationContext context = mock(ApplicationContext.class);
         PointService pointService = mock(PointService.class);
+        PostChangeLogService postChangeLogService = mock(PostChangeLogService.class);
+        PointHistoryRepository pointHistoryRepository = mock(PointHistoryRepository.class);
+        RedisTemplate redisTemplate = mock(RedisTemplate.class);
 
         PostService service = new PostService(postRepo, userRepo, catRepo, tagRepo, lotteryRepo,
                 pollPostRepo, pollVoteRepo, notifService, subService, commentService, commentRepo,
                 reactionRepo, subRepo, notificationRepo, postReadService,
-                imageUploader, taskScheduler, emailSender, context, pointService, PublishMode.DIRECT);
+                imageUploader, taskScheduler, emailSender, context, pointService, postChangeLogService,
+                pointHistoryRepository, PublishMode.DIRECT, redisTemplate);
         when(context.getBean(PostService.class)).thenReturn(service);
 
         User author = new User();

backend/src/test/resources/application.properties

@@ -4,7 +4,18 @@ spring.datasource.username=sa
 spring.datasource.password=
 spring.jpa.hibernate.ddl-auto=create-drop
 
+springdoc.info.title=openisle
+springdoc.info.description=Test API documentation
+springdoc.info.version=1.0.0
+springdoc.info.scheme=Bearer
+springdoc.info.header=Authorization
+
+
+rabbitmq.queue.durable=true
+rabbitmq.sharding.enabled=true
+
 resend.api.key=dummy
+resend.from.email=dummy@example.com
 cos.base-url=http://test.example.com
 cos.secret-id=dummy
 cos.secret-key=dummy
@@ -18,6 +29,7 @@ app.upload.max-size=1048576
 app.jwt.secret=TestSecret
 app.jwt.reason-secret=TestReasonSecret
 app.jwt.reset-secret=TestResetSecret
+app.jwt.invite-secret=TestInviteSecret
 app.jwt.expiration=3600000
 
 # Default publish mode for tests

docs/README.md

@@ -16,6 +16,6 @@ bun dev
 
 使用以下路由：
 
-- `docs/frontend/` 前端技术文档
-- `docs/backend/` 后端技术文档
-- `docs/openapi/` 后端 API 文档
+- `frontend/` 前端技术文档
+- `backend/` 后端技术文档
+- `openapi/` 后端 API 文档

docs/app/(home)/[[...slug]]/page.tsx

@@ -19,7 +19,7 @@ function DocsCategory({ url }: { url: string }) {
   );
 }
 
-export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
+export default async function Page(props: PageProps<'/[[...slug]]'>) {
   const params = await props.params;
   const page = source.getPage(params.slug);
   if (!page) notFound();
@@ -48,7 +48,7 @@ export async function generateStaticParams() {
 }
 
 export async function generateMetadata(
-  props: PageProps<'/docs/[[...slug]]'>
+  props: PageProps<'/[[...slug]]'>
 ): Promise<Metadata> {
   const params = await props.params;
   const page = source.getPage(params.slug);

docs/app/(home)/layout.tsx

@@ -28,7 +28,7 @@ function TabTitle({ children }: { children: React.ReactNode }) {
   return <span className="text-[11px]">{children}</span>;
 }
 
-export default function Layout({ children }: LayoutProps<'/docs'>) {
+export default function Layout({ children }: LayoutProps<'/'>) {
   return (
     // @ts-ignore
     <DocsLayout
@@ -40,7 +40,7 @@ export default function Layout({ children }: LayoutProps<'/docs'>) {
           {
             title: 'OpenIsle 前端',
             description: <TabTitle>前端开发文档</TabTitle>,
-            url: '/docs/frontend',
+            url: '/frontend',
             icon: (
               <TabIcon color="#4ca154">
                 <CompassIcon />
@@ -50,7 +50,7 @@ export default function Layout({ children }: LayoutProps<'/docs'>) {
           {
             title: 'OpenIsle 后端',
             description: <TabTitle>后端开发文档</TabTitle>,
-            url: '/docs/backend',
+            url: '/backend',
             icon: (
               <TabIcon color="#1f66f4">
                 <ServerIcon />
@@ -60,7 +60,7 @@ export default function Layout({ children }: LayoutProps<'/docs'>) {
           {
             title: 'OpenIsle API',
             description: <TabTitle>后端 API 文档</TabTitle>,
-            url: '/docs/openapi',
+            url: '/openapi',
             icon: (
               <TabIcon color="#677489">
                 <CodeXmlIcon />

docs/app/layout.tsx

@@ -6,7 +6,7 @@ const inter = Inter({
   subsets: ['latin'],
 });
 
-export default function Layout({ children }: LayoutProps<'/docs'>) {
+export default function Layout({ children }: LayoutProps<'/'>) {
   return (
     <html lang="zh" className={inter.className} suppressHydrationWarning>
       <body className="flex flex-col min-h-screen">

docs/content/docs/backend/index.mdx

@@ -40,4 +40,4 @@ backend/
 
 ## API 接口
 
-详细的 API 接口文档请查看 [API 文档](/docs/openapi)。
+详细的 API 接口文档请查看 [API 文档](/openapi)。

docs/content/docs/index.mdx

@@ -9,6 +9,6 @@ OpenIsle 是一个现代化的社区平台，提供完整的社交功能。
 
 ## 快速开始
 
-- [后端开发指南](/docs/backend) - 了解后端架构和开发
-- [前端开发指南](/docs/frontend) - 了解前端技术栈和组件
-- [API 文档](/docs/openapi) - 查看完整的 API 接口文档
+- [后端开发指南](/backend) - 了解后端架构和开发
+- [前端开发指南](/frontend) - 了解前端技术栈和组件
+- [API 文档](/openapi) - 查看完整的 API 接口文档

docs/lib/layout.shared.tsx

@@ -8,7 +8,7 @@ export function baseOptions(): BaseLayoutProps {
     githubUrl: 'https://github.com/nagisa77/OpenIsle',
     nav: {
       title: 'OpenIsle Docs',
-      url: '/docs',
+      url: '/',
     },
     searchToggle: {
       enabled: false,

docs/lib/source.ts

@@ -10,7 +10,7 @@ import * as ClientAdapters from './media-adapter.client';
 // See https://fumadocs.vercel.app/docs/headless/source-api for more info
 export const source = loader({
   // it assigns a URL to your pages
-  baseUrl: '/docs',
+  baseUrl: '/',
   source: docs.toFumadocsSource(),
   pageTree: {
     transformers: [transformerOpenAPI()],

frontend_nuxt/.env.dev.example

@@ -4,7 +4,9 @@ NUXT_PUBLIC_WEBSOCKET_URL=https://127.0.0.1:8082
 NUXT_PUBLIC_WEBSITE_BASE_URL=http://localhost:3000
 
 NUXT_PUBLIC_GOOGLE_CLIENT_ID=777830451304-nt8afkkap18gui4f9entcha99unal744.apps.googleusercontent.com
-NUXT_PUBLIC_GITHUB_CLIENT_ID=Ov23liVkO1NPAX5JyWxJ
+# NUXT_PUBLIC_GITHUB_CLIENT_ID=Ov23liVkO1NPAX5JyWxJ
+; 本地
+NUXT_PUBLIC_GITHUB_CLIENT_ID=Ov23liOlrZnPKRF7s7NN
 NUXT_PUBLIC_DISCORD_CLIENT_ID=1394985417044000779
 NUXT_PUBLIC_TWITTER_CLIENT_ID=ZTRTU05KSk9KTTJrTTdrVC1tc1E6MTpjaQ
 NUXT_PUBLIC_TELEGRAM_BOT_ID=8450237135

frontend_nuxt/assets/global.css

@@ -2,6 +2,8 @@
   --primary-color-hover: rgb(9, 95, 105);
   --primary-color: rgb(10, 110, 120);
   --primary-color-disabled: rgba(93, 152, 156, 0.5);
+  --secondary-color: rgb(255, 255, 255);
+  --secondary-color-hover: rgba(10, 111, 120, 0.184);
   --new-post-icon-color: rgba(10, 111, 120, 0.598);
   --header-height: 60px;
   --header-background-color: white;
@@ -17,8 +19,10 @@
   --background-color: white;
   --background-color-blur: rgba(255, 255, 255, 0.57);
   --menu-border-color: lightgray;
-  --normal-border-color: lightgray;
-  --menu-selected-background-color: rgba(242, 242, 242, 0.884);
+  --normal-border-color: rgba(211, 211, 211, 0.63);
+  --menu-selected-background-color: rgba(88, 241, 255, 0.166);
+  --normal-light-background-color: rgba(242, 242, 242, 0.884);
+  --menu-selected-background-color-hover: rgba(242, 242, 242, 0.884);
   --menu-text-color: rgb(99, 99, 99);
   --scroller-background-color: rgba(130, 175, 180, 0.5);
   /* --normal-background-color: rgb(241, 241, 241); */
@@ -58,6 +62,8 @@
   --menu-border-color: #555;
   --normal-border-color: #555;
   --menu-selected-background-color: rgba(255, 255, 255, 0.1);
+  --normal-light-background-color: rgba(255, 255, 255, 0.1);
+  --menu-selected-background-color-hover: rgba(17, 182, 197, 0.082);
   --menu-text-color: rgb(173, 173, 173);
   /* --normal-background-color: #000000; */
   --normal-background-color: #333;
@@ -162,7 +168,7 @@ body {
   padding-left: 1em;
   border-left: 4px solid #d0d7de;
   color: var(--blockquote-text-color);
-  background-color: var(--menu-selected-background-color);
+  background-color: var(--normal-light-background-color);
   padding-top: 1px;
   padding-bottom: 1px;
 }
@@ -235,8 +241,16 @@ body {
 }
 
 .info-content-text img {
-  max-width: 100%;
+  max-width: min(800px, 100%);
+  max-height: 600px;
   height: auto;
+  cursor: pointer;
+  box-shadow: 4px 12px 48px 0 rgba(0, 0, 0, 0.11);
+  transition: box-shadow 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.info-content-text img:hover {
+  box-shadow: 4px 12px 48px 0 rgba(0, 0, 0, 0.35);
 }
 
 .info-content-text table {
@@ -295,7 +309,7 @@ body {
 
 /* 鼠标悬停行高亮 */
 .info-content-text tbody tr:hover {
-  background-color: var(--menu-selected-background-color);
+  background-color: var(--normal-light-background-color);
   transition: background-color 0.2s ease;
 }
 
@@ -342,9 +356,41 @@ body {
     position: relative;
     min-width: 0;
   }
+
+  .d2h-file-name {
+    font-size: 14px !important;
+  }
+
+  .d2h-file-header {
+    height: auto !important;
+  }
+
+  .d2h-code-linenumber {
+    display: none !important;
+  }
+
+  .d2h-code-line {
+    padding-left: 10px !important;
+  }
+
+  /* .d2h-diff-table {
+    font-size: 6px !important;
+  }
+
+  .d2h-code-line ins {
+    height: 100%;
+    font-size: 13px !important;
+  } */
+
+  /* .d2h-code-line {
+    height: 12px;
+  }
+
+  .d2h-code-line-ctn {
+    font-size: 12px !important;
+  } */
 }
 
-/* Transition API */
 ::view-transition-old(root),
 ::view-transition-new(root) {
   animation: none;

frontend_nuxt/components/ArticleCategory.vue

@@ -35,6 +35,7 @@ const isImageIcon = (icon) => {
   display: flex;
   flex-direction: row;
   gap: 10px;
+  min-height: 25px;
 }
 
 .article-info-item {
@@ -63,5 +64,9 @@ const isImageIcon = (icon) => {
   .article-info-item {
     font-size: 10px;
   }
+
+  .article-category-container {
+    min-height: 20px;
+  }
 }
 </style>

frontend_nuxt/components/ArticleTags.vue

@@ -44,6 +44,7 @@ const isImageIcon = (icon) => {
   display: flex;
   flex-direction: row;
   gap: 10px;
+  min-height: 25px;
 }
 
 .article-info-item {
@@ -72,5 +73,9 @@ const isImageIcon = (icon) => {
   .article-info-item {
     font-size: 10px;
   }
+
+  .article-tags-container {
+    min-height: 20px;
+  }
 }
 </style>

frontend_nuxt/components/BaseTimeline.vue

@@ -100,7 +100,7 @@ export default {
 
 .timeline-content {
   flex: 1;
-  width: calc(100% - 32px);
+  width: calc(100% - 42px);
 }
 
 @media (max-width: 768px) {

frontend_nuxt/components/CommentEditor.vue

@@ -6,8 +6,15 @@
     </div>
     <div class="comment-bottom-container">
       <div class="comment-submit" :class="{ disabled: isDisabled }" @click="submit">
-        <template v-if="!loading"> 发布评论 </template>
-        <template v-else> <loading-four /> 发布中... </template>
+        <template v-if="!loading">
+          发布评论
+          <span class="shortcut-icon" v-if="!isMobile">
+            {{ isMac ? '⌘' : 'Ctrl' }} ⏎
+          </span>
+        </template>
+        <template v-else>
+          <loading-four /> 发布中...
+        </template>
       </div>
     </div>
   </div>
@@ -24,6 +31,7 @@ import {
 } from '~/utils/vditor'
 import '~/assets/global.css'
 import LoginOverlay from '~/components/LoginOverlay.vue'
+import { useIsMobile } from '~/utils/screen'
 
 export default {
   name: 'CommentEditor',
@@ -52,12 +60,22 @@ export default {
   },
   components: { LoginOverlay },
   setup(props, { emit }) {
+    const isMobile = useIsMobile()
     const vditorInstance = ref(null)
     const text = ref('')
     const editorId = ref(props.editorId)
     if (!editorId.value) {
       editorId.value = 'editor-' + useId()
     }
+
+    const isMac = ref(false)
+
+    if (navigator.userAgentData) {
+      isMac.value = navigator.userAgentData.platform === 'macOS'
+    } else {
+      isMac.value = /Mac|iPhone|iPad|iPod/.test(navigator.userAgent)
+    }
+
     const getEditorTheme = getEditorThemeUtil
     const getPreviewTheme = getPreviewThemeUtil
     const applyTheme = () => {
@@ -96,7 +114,27 @@ export default {
           applyTheme()
         },
       })
-      // applyTheme()
+      // 不是手机的情况下不添加快捷键
+      if(!isMobile.value){
+        // 添加快捷键监听 (Ctrl+Enter 或 Cmd+Enter)
+        const handleKeydown = (e) => {
+          if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') {
+            e.preventDefault()
+            submit()
+          }
+        }
+
+        const el = document.getElementById(editorId.value)
+        if (el) {
+          el.addEventListener('keydown', handleKeydown)
+        }
+
+        onUnmounted(() => {
+          if (el) {
+            el.removeEventListener('keydown', handleKeydown)
+          }
+        })
+      }
     })
 
     onUnmounted(() => {
@@ -134,7 +172,7 @@ export default {
       },
     )
 
-    return { submit, isDisabled, editorId }
+    return { submit, isDisabled, editorId, isMac, isMobile}
   },
 }
 </script>
@@ -174,10 +212,16 @@ export default {
 .comment-submit:hover {
   background-color: var(--primary-color-hover);
 }
-
-@media (max-width: 768px) {
-  .comment-editor-container {
-    margin-bottom: 10px;
-  }
+/** 评论按钮快捷键样式 */
+.shortcut-icon {
+  padding: 2px 6px;
+  border-radius: 6px;
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 1.2;
+  background-color: rgba(0, 0, 0, 0.25);
+}
+.comment-submit.disabled .shortcut-icon {
+  background-color: rgba(0, 0, 0, 0);
 }
 </style>

frontend_nuxt/components/CommentItem.vue

@@ -342,7 +342,7 @@ const copyCommentLink = () => {
 
 const handleContentClick = (e) => {
   handleMarkdownClick(e)
-  if (e.target.tagName === 'IMG') {
+  if (e.target.tagName === 'IMG' && !e.target.classList.contains('emoji')) {
     const container = e.target.parentNode
     const imgs = [...container.querySelectorAll('img')].map((i) => i.src)
     lightboxImgs.value = imgs

frontend_nuxt/components/MenuComponent.vue

@@ -314,6 +314,11 @@ const gotoTag = (t) => {
   border-radius: 10px;
   display: flex;
   align-items: center;
+  transition: background-color 0.5s ease;
+}
+
+.menu-item:hover {
+  background-color: var(--menu-selected-background-color-hover);
 }
 
 .menu-item.selected {
@@ -404,10 +409,11 @@ const gotoTag = (t) => {
   gap: 5px;
   border-radius: 8px;
   cursor: pointer;
+  transition: background-color 0.5s ease;
 }
 
 .section-item:hover {
-  background-color: var(--menu-selected-background-color);
+  background-color: var(--menu-selected-background-color-hover);
 }
 
 .section-item-text-count {