chore: format backend via husky

feat: show placeholder when timeline empty

.github/workflows/deploy-docs.yml

@@ -0,0 +1,47 @@
+name: Deploy Documentation
+
+on:
+  workflow_call:
+    inputs:
+      build-id:
+        required: false
+        type: string
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        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:
+          bun-version: latest
+
+      - name: Install Bun dependencies
+        run: bun install
+        working-directory: ./docs
+
+      - name: Generate API MDX
+        run: bun run generate
+        working-directory: ./docs
+
+      - name: Build documentation
+        run: bun run build
+        working-directory: ./docs
+
+      - name: Deploy to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: ./docs/out

.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 }}
+

.gitignore

@@ -21,6 +21,8 @@ dist
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+pnpm-lock.yaml
+pnpm-workspace.yaml
 
 # env
 *.env

CONTRIBUTING.md

@@ -70,7 +70,9 @@ SERVER_PORT=8082
 #### 配置 IDEA 参数
 
 - 设置 JDK 版本为 java 17
+
 - 设置 VM Option，最好运行在其他端口，非 `8080`，这里设置 `8081`
+    若上面在环境变量中设置了端口，那这里就不需要再额外设置
 
     ```shell
     -Dserver.port=8081
@@ -101,14 +103,27 @@ SERVER_PORT=8082
     ```
 
 3. 执行 [`db/init/init_script.sql`](backend/src/main/resources/db/init/init_script.sql) 脚本，导入基本的数据
-
+    管理员：**admin/123456**
+    普通用户1：**user1/123456**
+    普通用户2：**user2/123456**
+    
     ![初始化脚本](assets/contributing/resources_img.png)
 
-4. 处理完环境问题直接跑起来就能通了
+#### 配置 Redis
 
-    ![运行画面](assets/contributing/backend_img_4.png)
+填写环境变量 `.env` 中的 Redis 相关配置并启动 Redis
+
+```ini
+REDIS_HOST=<Redis 地址>
+REDIS_PORT=<Redis 端口>
+```
+
+处理完环境问题直接跑起来就能通了
+
+![运行画面](assets/contributing/backend_img_4.png)
 
 ### Docker 环境
+
 #### 配置环境变量
 
 ```shell
@@ -177,6 +192,8 @@ cd frontend_nuxt/
     cp .env.dev.example .env
     ```
 
+若依赖本机部署的后端，需要修改 `.env` 中的 `NUXT_PUBLIC_API_BASE_URL` 值与后端服务端口一致
+
 ### 安装依赖和运行
 
 前端安装依赖并启动服务。
@@ -193,7 +210,7 @@ npm run dev
 
 ## 其他配置
 
-配置第三方登录，这里以 GitHub 为例：
+### 配置第三方登录，这里以 GitHub 为例：
 
 - 修改 `application.properties` 配置
 
@@ -208,3 +225,30 @@ npm run dev
     ![github配置](assets/contributing/github_img.png)
 
     ![github配置2](assets/contributing/github_img_2.png)
+
+### 配置 Resend 邮箱服务
+
+https://resend.com/emails 创建账号并登录
+
+- `Domains` -> `Add Domain`
+  ![image-20250906150459400](assets/contributing/image-20250906150459400.png)
+
+- 填写域名
+  ![image-20250906150541817](assets/contributing/image-20250906150541817.png)
+
+- 等待一段时间后解析成功，创建 key
+  `API Keys` -> `Create API Key`，输入名称，设置 `Permission` 为 `Sending access`
+  **Key 只能查看一次，务必保存下来**
+  ![image-20250906150811572](assets/contributing/image-20250906150811572.png)
+  ![image-20250906150924975](assets/contributing/image-20250906150924975.png)
+  ![image-20250906150944130](assets/contributing/image-20250906150944130.png)
+- 修改 `.env` 配置中的 `RESEND_API_KEY` 和 `RESEND_FROM_EMAIL`
+  `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/open-isle.env.example

@@ -13,8 +13,13 @@ JWT_RESET_SECRET=<jwt reset secret>
 JWT_INVITE_SECRET=<jwt invite secret>
 JWT_EXPIRATION=2592000000
 
+# === Redis ===
+REDIS_HOST=<Redis 地址>
+REDIS_PORT=<Redis 端口>
+
 # === Resend ===
 RESEND_API_KEY=<你的resend-api-key>
+RESEND_FROM_EMAIL=<你的 resend 发送邮箱>
 
 # === COS ===
 # COS_BASE_URL=https://<你的cos>.cos.ap-guangzhou.myqcloud.com

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

@@ -22,6 +22,8 @@ import org.springframework.data.redis.serializer.RedisSerializer;
 import org.springframework.data.redis.serializer.StringRedisSerializer;
 
 import java.time.Duration;
+import java.util.HashMap;
+import java.util.Map;
 
 /**
  * Redis 缓存配置类
@@ -36,6 +38,16 @@ public class CachingConfig {
     public static final String TAG_CACHE_NAME="openisle_tags";
     // 分类缓存名
     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的序列化器
@@ -55,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(
@@ -78,13 +93,18 @@ public class CachingConfig {
                 .serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer()))
                 .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(redisSerializer))
                 .disableCachingNullValues(); // 禁止缓存 null 值
-//        个别缓存单独设置TTL时间
-//        Map<String, RedisCacheConfiguration> cacheConfigs = new HashMap<>();
-//        cacheConfigs.put("openisle_tags", RedisCacheConfiguration.defaultCacheConfig().entryTtl(Duration.ZERO));
-//        cacheConfigs.put("openisle_categories", RedisCacheConfiguration.defaultCacheConfig().entryTtl(Duration.ZERO));
+
+        // 个别缓存单独设置 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)
+                .withInitialCacheConfigurations(cacheConfigs)
                 .build();
     }
 

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.", "://")
         ));
@@ -129,6 +137,8 @@ public class SecurityConfig {
                     .requestMatchers(HttpMethod.GET, "/api/sitemap.xml").permitAll()
                     .requestMatchers(HttpMethod.GET, "/api/channels").permitAll()
                     .requestMatchers(HttpMethod.GET, "/api/rss").permitAll()
+                    .requestMatchers(HttpMethod.GET, "/api/online/**").permitAll()
+                    .requestMatchers(HttpMethod.POST, "/api/online/**").permitAll()
                     .requestMatchers(HttpMethod.GET, "/api/point-goods").permitAll()
                     .requestMatchers(HttpMethod.POST, "/api/point-goods").permitAll()
                     .requestMatchers(HttpMethod.POST, "/api/categories/**").hasAuthority("ADMIN")
@@ -183,7 +193,8 @@ public class SecurityConfig {
                     }
                 } else if (!uri.startsWith("/api/auth") && !publicGet
                         && !uri.startsWith("/api/ws") && !uri.startsWith("/api/sockjs")
-                        && !uri.startsWith("/api/v3/api-docs")) {
+                        && !uri.startsWith("/api/v3/api-docs")
+                        && !uri.startsWith("/api/online")) {
                     response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
                     response.setContentType("application/json");
                     response.getWriter().write("{\"error\": \"Missing token\"}");
@@ -202,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

@@ -0,0 +1,42 @@
+package com.openisle.controller;
+
+import com.openisle.config.CachingConfig;
+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;
+
+/**
+ * @author smallclover
+ * @since 2025-09-05
+ * 统计在线人数
+ */
+@RestController
+@RequestMapping("/api/online")
+@RequiredArgsConstructor
+public class OnlineController {
+
+    private final RedisTemplate redisTemplate;
+    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/ResendEmailSender.java

@@ -18,6 +18,9 @@ public class ResendEmailSender extends EmailSender {
     @Value("${resend.api.key}")
     private String apiKey;
 
+    @Value("${resend.from.email}")
+    private String fromEmail;
+
     private final RestTemplate restTemplate = new RestTemplate();
 
     @Override
@@ -33,7 +36,7 @@ public class ResendEmailSender extends EmailSender {
         body.put("to", to);
         body.put("subject", subject);
         body.put("text", text);
-        body.put("from", "openisle <noreply@chenjiating.com>"); // todo(tim): use config
+        body.put("from", "openisle <" + fromEmail + ">");
 
         HttpEntity<Map<String, String>> entity = new HttpEntity<>(body, headers);
         restTemplate.exchange(url, HttpMethod.POST, entity, String.class);

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

@@ -12,7 +12,7 @@ spring.jpa.hibernate.ddl-auto=update
 # for redis
 spring.data.redis.host=${REDIS_HOST:localhost}
 spring.data.redis.port=${REDIS_PORT:6379}
-spring.data.redis.database=0
+spring.data.redis.database=${REDIS_DATABASE:0}
 
 # for jwt
 app.jwt.secret=${JWT_SECRET:jwt_sec}
@@ -56,8 +56,10 @@ app.captcha.comment-enabled=${CAPTCHA_COMMENT_ENABLED:false}
 # ========= Optional =========
 # for resend email send service, you can improve your service by yourself
 resend.api.key=${RESEND_API_KEY:}
+resend.from.email=${RESEND_FROM_EMAIL:}
 # your email services: ...
 
+
 # for tencent cloud image upload service, you can improve your service by yourself
 cos.base-url=${:https://example.com}
 cos.secret-id=${COS_SECRET_ID:}
@@ -106,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/init/init_script.sql

@@ -35,9 +35,9 @@ DELETE FROM `users`;
 -- 插入用户，两个普通用户，一个管理员
 -- username:admin/user1/user2 password:123321
 INSERT INTO `users` (`id`, `approved`, `avatar`, `created_at`, `display_medal`, `email`, `experience`, `introduction`, `password`, `password_reset_code`, `point`, `register_reason`, `role`, `username`, `verification_code`, `verified`) VALUES
-	(1, b'1', '', '2025-09-01 16:08:17.426430', 'PIONEER', 'adminmail@openisle.com', 70, NULL, '$2a$10$m.lLbT3wFtnzFMi7JqN17ecv/dzH704WzU1f/xvQ0nVz4XxTXPT0K', NULL, 110, '测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试', 'ADMIN', 'admin', NULL, b'1'),
-	(2, b'1', '', '2025-09-03 16:08:17.426430', 'PIONEER', 'usermail2@openisle.com', 70, NULL, '$2a$10$m.lLbT3wFtnzFMi7JqN17ecv/dzH704WzU1f/xvQ0nVz4XxTXPT0K', NULL, 110, '测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试', 'USER', 'user1', NULL, b'1'),
-	(3, b'1', '', '2025-09-02 17:21:21.617666', 'PIONEER', 'usermail1@openisle.com', 40, NULL, '$2a$10$m.lLbT3wFtnzFMi7JqN17ecv/dzH704WzU1f/xvQ0nVz4XxTXPT0K', NULL, 40, '测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试', 'USER', 'user2', NULL, b'1');
+	(1, b'1', '', '2025-09-01 16:08:17.426430', 'PIONEER', 'adminmail@openisle.com', 70, NULL, '$2a$10$dux.NXwW09cCsdZ05BgcnOtxVqqjcmnbj3.8xcxGl/iiIlv06y7Oe', NULL, 110, '测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试', 'ADMIN', 'admin', NULL, b'1'),
+	(2, b'1', '', '2025-09-03 16:08:17.426430', 'PIONEER', 'usermail2@openisle.com', 70, NULL, '$2a$10$dux.NXwW09cCsdZ05BgcnOtxVqqjcmnbj3.8xcxGl/iiIlv06y7Oe', NULL, 110, '测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试', 'USER', 'user1', NULL, b'1'),
+	(3, b'1', '', '2025-09-02 17:21:21.617666', 'PIONEER', 'usermail1@openisle.com', 40, NULL, '$2a$10$dux.NXwW09cCsdZ05BgcnOtxVqqjcmnbj3.8xcxGl/iiIlv06y7Oe', NULL, 40, '测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试测试', 'USER', 'user2', NULL, b'1');
 
 -- 创建 tags 表（如果不存在）
 CREATE TABLE IF NOT EXISTS `tags` (

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/.gitignore

@@ -0,0 +1,9 @@
+# generated content
+.contentlayer
+.content-collections
+.source
+.next/
+.vercel
+next-env.d.ts
+openapi.json
+openapi.yaml

docs/README.md

@@ -0,0 +1,21 @@
+# OpenIsle Documentation
+## 要求
+
+使用 [bun](https://bun.com/) 作为工具链的运行时，版本 1.2+。
+
+使用 [Fumadocs](https://fumadocs.dev/) 作为文档工具。
+
+## 开发调试
+
+```bash
+bun install
+bun dev
+```
+
+## 项目结构
+
+使用以下路由：
+
+- `frontend/` 前端技术文档
+- `backend/` 后端技术文档
+- `openapi/` 后端 API 文档

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

@@ -0,0 +1,61 @@
+import { source } from '@/lib/source';
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/page';
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { createRelativeLink } from 'fumadocs-ui/mdx';
+import { getMDXComponents } from '@/mdx-components';
+import { Card, Cards } from 'fumadocs-ui/components/card';
+import { getPageTreePeers } from 'fumadocs-core/server';
+
+function DocsCategory({ url }: { url: string }) {
+  return (
+    <Cards>
+      {getPageTreePeers(source.pageTree, url).map((peer) => (
+        <Card key={peer.url} title={peer.name} href={peer.url}>
+          <span className="font-mono">{peer.url}</span>
+        </Card>
+      ))}
+    </Cards>
+  );
+}
+
+export default async function Page(props: PageProps<'/[[...slug]]'>) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDXContent = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc} full={page.data.full}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody>
+        <MDXContent
+          components={getMDXComponents({
+            // this allows you to link to other pages with relative file paths
+            a: createRelativeLink(source, page),
+          })}
+        />
+        {page.data.full ? null : <DocsCategory url={page.url} />}
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(
+  props: PageProps<'/[[...slug]]'>
+): Promise<Metadata> {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}

docs/app/(home)/layout.tsx

@@ -0,0 +1,77 @@
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import { baseOptions } from '@/lib/layout.shared';
+import { source } from '@/lib/source';
+import { CodeXmlIcon, CompassIcon, ServerIcon } from 'lucide-react';
+
+function TabIcon({
+  color = 'var(--color-fd-foreground)',
+  children,
+}: {
+  color?: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div
+      className="[&_svg]:size-full rounded-lg size-full text-(--tab-color) max-md:bg-(--tab-color)/10 max-md:border max-md:p-1.5"
+      style={
+        {
+          '--tab-color': color,
+        } as React.CSSProperties
+      }
+    >
+      {children}
+    </div>
+  );
+}
+
+function TabTitle({ children }: { children: React.ReactNode }) {
+  return <span className="text-[11px]">{children}</span>;
+}
+
+export default function Layout({ children }: LayoutProps<'/'>) {
+  return (
+    // @ts-ignore
+    <DocsLayout
+      tree={source.pageTree}
+      sidebar={{
+        defaultOpenLevel: 1,
+        prefetch: true,
+        tabs: [
+          {
+            title: 'OpenIsle 前端',
+            description: <TabTitle>前端开发文档</TabTitle>,
+            url: '/frontend',
+            icon: (
+              <TabIcon color="#4ca154">
+                <CompassIcon />
+              </TabIcon>
+            ),
+          },
+          {
+            title: 'OpenIsle 后端',
+            description: <TabTitle>后端开发文档</TabTitle>,
+            url: '/backend',
+            icon: (
+              <TabIcon color="#1f66f4">
+                <ServerIcon />
+              </TabIcon>
+            ),
+          },
+          {
+            title: 'OpenIsle API',
+            description: <TabTitle>后端 API 文档</TabTitle>,
+            url: '/openapi',
+            icon: (
+              <TabIcon color="#677489">
+                <CodeXmlIcon />
+              </TabIcon>
+            ),
+          },
+        ],
+      }}
+      {...baseOptions()}
+    >
+      {children}
+    </DocsLayout>
+  );
+}

docs/app/global.css

@@ -0,0 +1,4 @@
+@import 'tailwindcss';
+@import 'fumadocs-ui/css/neutral.css';
+@import 'fumadocs-ui/css/preset.css';
+@import 'fumadocs-openapi/css/preset.css';

docs/app/layout.tsx

@@ -0,0 +1,17 @@
+import '@/app/global.css';
+import { Provider } from '@/app/provider';
+import { Inter } from 'next/font/google';
+
+const inter = Inter({
+  subsets: ['latin'],
+});
+
+export default function Layout({ children }: LayoutProps<'/'>) {
+  return (
+    <html lang="zh" className={inter.className} suppressHydrationWarning>
+      <body className="flex flex-col min-h-screen">
+        <Provider>{children}</Provider>
+      </body>
+    </html>
+  );
+}