fix: 简单调整按钮格式

Delete post change logs before removing posts

.github/ISSUE_TEMPLATE/新功能建议.md

@@ -0,0 +1,20 @@
+---
+name: 新功能建议
+about: 请为该项目提出一个想法
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**你的功能请求是否与某个问题相关？请描述。**
+请清晰、简洁地说明问题。例如：“我经常因为……而感到困扰。”
+
+**你期望的解决方案**
+请清晰、简洁地描述你希望发生的事情/功能如何工作。
+
+**你考虑过的替代方案**
+请清晰、简洁地说明你已考虑过的其他解决方案或功能。
+
+**其他上下文**
+在此添加与功能请求相关的其他信息或截图。

.github/ISSUE_TEMPLATE/错误-bug报告.md

@@ -0,0 +1,41 @@
+---
+name: 错误/Bug报告
+about: 创建报告以帮助我们改进
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**描述 Bug**
+对该 Bug 进行清晰简明的描述。
+
+**复现步骤**
+复现该问题的步骤：
+
+1. 进入 '...'
+2. 点击 '...'
+3. 下拉到 '...'
+4. 看到错误
+
+**预期行为**
+清晰简明地描述你期望发生的情况。
+
+**截图**
+如果适用，请添加截图以帮助解释问题。
+
+**桌面端（请完成以下信息）：**
+
+* 操作系统：\[例如 iOS]
+* 浏览器：\[例如 Chrome、Safari]
+* 版本：\[例如 22]
+
+**移动端（请完成以下信息）：**
+
+* 设备：\[例如 iPhone6]
+* 操作系统：\[例如 iOS8.1]
+* 浏览器：\[例如 系统自带浏览器、Safari]
+* 版本：\[例如 22]
+
+**附加上下文**
+在此添加与问题相关的其他上下文信息。

.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

@@ -1,7 +1,32 @@
+# IDE
 .idea
 target
-openisle.iml
+
+# log
+logs
+
+# deps
 node_modules
+
+# test & build
+coverage
+out/
+build
 dist
-open-isle.env
-logs
+*.tsbuildinfo
+
+# misc
+.DS_Store
+*.pem
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-lock.yaml
+pnpm-workspace.yaml
+
+# env
+*.env
+.env*.local
+
+# others
+openisle.iml

CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# OpenIsle Code of Conduct
+
+Like the technical community as a whole, the OpenIsle team and community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentorship, teaching, and connecting people.
+
+Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance.
+
+This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate.
+
+This code of conduct applies to all spaces managed by the OpenIsle project or . This includes IRC, the mailing lists, the issue tracker, DSF events, and any other forums created by the project team which the community uses for communication. In addition, violations of this code outside these spaces may affect a person's ability to participate within them.
+
+If you believe someone is violating the code of conduct, we ask that you report it by emailing [](mailto:). For more details please see our 
+
+- **Be friendly and patient.**
+- **Be welcoming.** We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
+- **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.
+- **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the OpenIsle community should be respectful when dealing with other members as well as with people outside the OpenIsle community.
+- **Be careful in the words that you choose.** We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to: 
+ - Violent threats or language directed against another person.
+ - Discriminatory jokes and language.
+ - Posting sexually explicit or violent material.
+ - Posting (or threatening to post) other people's personally identifying information ("doxing").
+ - Personal insults, especially those using racist or sexist terms.
+ - Unwelcome sexual attention.
+ - Advocating for, or encouraging, any of the above behavior.
+ - Repeated harassment of others. In general, if someone asks you to stop, then stop.
+- **When we disagree, try to understand why.** Disagreements, both social and technical, happen all the time and OpenIsle is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of OpenIsle comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
+
+Original text courtesy of the [Speak Up! project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html).
+
+## Questions?
+
+If you have questions, please see . If that doesn't answer your questions, feel free to [contact us](mailto:).

CONTRIBUTING.md

@@ -1,111 +1,202 @@
-#### **⚠️注意：仅想修改前端的朋友可不用部署后端服务**
+- [前置工作](#前置工作)
+- [启动后端服务](#启动后端服务)
+    - [本地 IDEA](#本地-idea)
+        - [配置环境变量](#配置环境变量)
+        - [配置 IDEA 参数](#配置-idea-参数)
+        - [配置 MySQL](#配置-mysql)
+    - [Docker 环境](#docker-环境)
+        - [配置环境变量](#配置环境变量-1)
+        - [构建并启动镜像](#构建并启动镜像)
+- [启动前端服务](#启动前端服务)
+    - [配置环境变量](#配置环境变量-2)
+    - [安装依赖和运行](#安装依赖和运行)
+- [其他配置](#其他配置)
 
-## 如何部署
+## 前置工作
 
-> Step1 先克隆仓库
+先克隆仓库：
 
 ```shell
 git clone https://github.com/nagisa77/OpenIsle.git
 cd OpenIsle
 ```
 
-> Step2 后端部署
+- 后端开发环境
+    - JDK 17+
+- 前端开发环境
+    - Node.JS 20+
+
+## 启动后端服务
+
+启动后端服务有多种方式，选择一种即可。
+
+> [!IMPORTANT]
+> 仅想修改前端的朋友可不用部署后端服务。转到 [启动前端服务](#启动前端服务) 章节。
+
+### 本地 IDEA
 
 ```shell
-cd backend
+cd backend/
 ```
 
-以IDEA编辑器为例，IDEA打开backend文件夹。
+IDEA 打开 `backend/` 文件夹。
 
-- 设置VM Option，最好运行在其他端口，非8080，这里设置8081
+#### 配置环境变量
 
-```shell
--Dserver.port=8081
+1. 生成环境变量文件
+
+    ```shell
+    cp open-isle.env.example open-isle.env
+    ```
+
+    `open-isle.env.example` 是环境变量模板，`open-isle.env` 才是真正读取的内容
+
+2. 修改环境变量，留下需要的，比如你要开发 Google 登录业务，就需要谷歌相关的变量，数据库是一定要的
+
+    ![环境变量](assets/contributing/backend_img_7.png)
+
+3. 应用环境文件，选择刚刚的 `open-isle.env`
+
+可以在 `open-isle.env` 按需填写个性化的配置，该文件不会被 Git 追踪。比如你想把服务跑在 `8082`（默认为 `8080`），那么直接改 `open-isle.env` 即可：
+
+```ini
+SERVER_PORT=8082
 ```
 
-![CleanShot 2025-08-04 at 11 .35.49.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/4cf210cfc6ea478a80dfc744c85ccdc4.png)
+另一种方式是修改 `.properities` 文件（但不建议），位于 `src/main/application.properties`，该配置同样来源于 `open-isle.env`，但修改 `.properties` 文件会被 Git 追踪。
 
-- 设置jdk版本为java 17
+![配置数据库](assets/contributing/backend_img_5.png)
 
-![CleanShot 2025-08-04 at 11 .38.03@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/392eeec753ae436ca12a78f750dfea2d.png)
+#### 配置 IDEA 参数
 
-- 本机配置MySQL服务（网上很多教程，忽略）
-- 设置环境变量.env 文件 或.properties 文件（二选一）
+- 设置 JDK 版本为 java 17
 
-1. 环境变量文件生成
+- 设置 VM Option，最好运行在其他端口，非 `8080`，这里设置 `8081`
+    若上面在环境变量中设置了端口，那这里就不需要再额外设置
 
-```shell
-cp open-isle.env.example open-isle.env
+    ```shell
+    -Dserver.port=8081
+    ```
+
+![配置1](assets/contributing/backend_img_3.png)
+
+![配置2](assets/contributing/backend_img_2.png)
+
+#### 配置 MySQL
+
+> [!TIP]
+> 如果不知道怎么配置数据库可以参考 [Docker 环境](#docker-环境) 章节
+
+1. 本机配置 MySQL 服务（网上很多教程，忽略）
+
+    + 可以用 Laragon，自带 MySQL 包括 Nodejs，版本建议 `6.x`，`7` 以后需要 Lisence
+    + [下载地址](https://github.com/leokhoa/laragon/releases)
+
+2. 填写环境变量
+
+    ![环境变量](assets/contributing/backend_img_6.png)
+
+    ```ini
+    MYSQL_URL=jdbc:mysql://<数据库地址>:<端口>/<数据库名>?useUnicode=yes&characterEncoding=UTF-8&useInformationSchema=true&useSSL=false&serverTimezone=UTC
+    MYSQL_USER=<数据库用户名>
+    MYSQL_PASSWORD=<数据库密码>
+    ```
+
+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)
+
+#### 配置 Redis
+
+填写环境变量 `.env` 中的 Redis 相关配置并启动 Redis
+
+```ini
+REDIS_HOST=<Redis 地址>
+REDIS_PORT=<Redis 端口>
 ```
 
-修改环境变量，留下需要的，比如你要开发Google登录业务，就需要谷歌相关的变量，数据库是一定要的
-
-![CleanShot 2025-08-04 at 11 .41.36@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/896c8363b6e64ea19d18c12ec4dae2b4.png)
-
-应用环境文件， 选择刚刚的`open-isle.env`
-
-![CleanShot 2025-08-04 at 11 .44.41.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/f588e37838014a6684c141605639b9fa.png)
-
-2. 直接修改 .properities 文件
-
-位置src/main/application.properties, 数据库需要修改标红处，其他按需修改
-
-![CleanShot 2025-08-04 at 11 .47.11@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/28c3104448a245419e0b06aee861abb4.png)
-
 处理完环境问题直接跑起来就能通了
 
-![CleanShot 2025-08-04 at 11 .49.01@2x.png](https://openisle-1307107697.cos.accelerate.myqcloud.com/dynamic_assert/2c945eae44b1477db09e80fc96b5e02d.png)
+![运行画面](assets/contributing/backend_img_4.png)
 
-> Step3 前端部署
+### Docker 环境
 
-**⚠️ 环境要求：Node.js 版本最低 20.0.0（因为 Nuxt 框架要求）**
-
-前端可以依赖本机部署的后端，也可以直接调用线上的后端接口
+#### 配置环境变量
 
 ```shell
-cd ../frontend_nuxt/
+cd docker/
 ```
 
-copy环境.env文件
+主要配置两个 `.env` 文件
+
+- `backend/open-isle.env`：后端环境变量，配置同上，见 [配置环境变量](#配置环境变量)。
+- `docker/.env`：Docker Compose 环境变量，主要配置 MySQL 相关
+    ```shell
+    cp .env.example .env
+    ```
+
+> [!TIP]
+> 使用单独的 `.env` 文件是为了兼容线上环境或已启用 MySQL 服务的情况，如果只是想快速体验或者启动统一的环境，则推荐使用本方式。
+
+在指定 `docker/.env` 后，`backend/open-isle.env` 中以下配置会被覆盖，这样就确保使用了同一份配置。
+
+```ini
+MYSQL_URL=
+MYSQL_USER=
+MYSQL_PASSWORD=
+```
+
+#### 构建并启动镜像
 
 ```shell
-cp .env.staging.example .env
+docker compose up -d
 ```
 
-1. 依赖本机部署的后端：打开本文件夹，修改.env 修改为瞄准本机后端端口
+如果想了解启动过程发生了什么可以查看日志
 
-```yaml
-; 本地部署后端
-NUXT_PUBLIC_API_BASE_URL=https://127.0.0.1:8081
-; 预发环境后端
-; NUXT_PUBLIC_API_BASE_URL=https://staging.open-isle.com
-; 生产环境后端
-; NUXT_PUBLIC_API_BASE_URL=https://www.open-isle.com
+```shell
+docker compose logs
 ```
 
-2. 依赖预发环境后台环境
+## 启动前端服务
 
-**(⚠️强烈推荐只部署前端的朋友使用该环境)**
+> [!IMPORTANT]
+> **⚠️ 环境要求：Node.js 版本最低 20.0.0（因为 Nuxt 框架要求）**
 
-```yaml
-; 本地部署后端
-; NUXT_PUBLIC_API_BASE_URL=https://127.0.0.1:8081
-; 预发环境后端
-NUXT_PUBLIC_API_BASE_URL=https://staging.open-isle.com
-; 生产环境后端
-; NUXT_PUBLIC_API_BASE_URL=https://www.open-isle.com
+```shell
+cd frontend_nuxt/
 ```
 
-4. 依赖线上后台环境
+### 配置环境变量
 
-```yaml
-; 本地部署后端
-; NUXT_PUBLIC_API_BASE_URL=https://127.0.0.1:8081
-; 预发环境后端
-; NUXT_PUBLIC_API_BASE_URL=https://staging.open-isle.com
-; 生产环境后端
-NUXT_PUBLIC_API_BASE_URL=https://www.open-isle.com
-```
+前端可以依赖本机部署的后端，也可以直接调用线上的后端接口。
+
+- 利用预发环境：**（⚠️ 强烈推荐只开发前端的朋友使用该环境）**
+
+    ```shell
+    cp .env.staging.example .env
+    ```
+
+- 利用生产环境
+
+    ```shell
+    cp .env.production.example .env
+    ```
+
+- 利用本地环境
+
+    ```shell
+    cp .env.dev.example .env
+    ```
+
+若依赖本机部署的后端，需要修改 `.env` 中的 `NUXT_PUBLIC_API_BASE_URL` 值与后端服务端口一致
+
+### 安装依赖和运行
+
+前端安装依赖并启动服务。
 
 ```shell
 # 安装依赖
@@ -115,4 +206,49 @@ npm install --verbose
 npm run dev
 ```
 
-如此一来，浏览器访问 http://127.0.0.1:3000 即可访问前端页面
+如此一来，浏览器访问 http://127.0.0.1:3000 即可访问前端页面。
+
+## 其他配置
+
+### 配置第三方登录，这里以 GitHub 为例：
+
+- 修改 `application.properties` 配置
+
+    ![后端配置](assets/contributing/backend_img.png)
+
+- 修改 `.env` 配置
+
+    ![前端](assets/contributing/fontend_img.png)
+
+- 配置第三方登录回调地址
+
+    ![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
+
+

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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/open-isle.env.example

@@ -1,5 +1,8 @@
+# === Spring Boot ===
+SERVER_PORT=8080
+
 # === Database ===
-MYSQL_URL=jdbc:mysql://<数据库地址>:<端口>/<数据库名>?useUnicode=yes&characterEncoding=UTF-8&useInformationSchema=true&useSSL=false&serverTimezone=UTC
+MYSQL_URL=jdbc:mysql://<数据库地址>:<数据库端口>/<数据库名>?useUnicode=yes&characterEncoding=UTF-8&useInformationSchema=true&useSSL=false&serverTimezone=UTC
 MYSQL_USER=<数据库用户名>
 MYSQL_PASSWORD=<数据库密码>
 
@@ -10,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
@@ -28,6 +36,7 @@ TWITTER_CLIENT_ID=<你的twitter-client-id>
 TWITTER_CLIENT_SECRET=<你的-twitter-client-secret>
 DISCORD_CLIENT_ID=<你的discord-client-id>
 DISCORD_CLIENT_SECRET=<你的discord-client-secret>
+TELEGRAM_BOT_TOKEN=<你的telegram-bot-token>
 
 # === OPENAI ===
 OPENAI_API_KEY=<你的openai-api-key>
@@ -36,4 +45,10 @@ OPENAI_API_KEY=<你的openai-api-key>
 WEBPUSH_PUBLIC_KEY=<你的webpush-public-key>
 WEBPUSH_PRIVATE_KEY=<你的webpush-private-key>
 
+# === RabbitMQ ===
+RABBITMQ_HOST=<你的rabbitmq_host>
+RABBITMQ_PORT=<你的rabbitmq_port>
+RABBITMQ_USERNAME=<你的rabbitmq_username>
+RABBITMQ_PASSWORD=<你的rabbitmq_password>
+
 # LOG_LEVEL=DEBUG

backend/pom.xml

@@ -26,9 +26,22 @@
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-web</artifactId>
     </dependency>
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-amqp</artifactId>
+    </dependency>
     <dependency>
       <groupId>org.springframework.boot</groupId>
-      <artifactId>spring-boot-starter-websocket</artifactId>
+      <artifactId>spring-boot-starter-data-redis</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.datatype</groupId>
+      <artifactId>jackson-datatype-jsr310</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.datatype</groupId>
+      <artifactId>jackson-datatype-hibernate6</artifactId>
+      <version>2.20.0</version>
     </dependency>
     <dependency>
       <groupId>org.slf4j</groupId>
@@ -114,6 +127,11 @@
       <artifactId>bcprov-jdk15on</artifactId>
       <version>1.70</version>
     </dependency>
+    <dependency>
+      <groupId>org.springdoc</groupId>
+      <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
+      <version>2.2.0</version>
+    </dependency>
   </dependencies>
 
   <build>
@@ -141,6 +159,26 @@
           </annotationProcessorPaths>
         </configuration>
       </plugin>
+
+      <plugin>
+        <!-- https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md -->
+        <groupId>org.springdoc</groupId>
+        <artifactId>springdoc-openapi-maven-plugin</artifactId>
+        <version>1.4</version>
+        <executions>
+          <execution>
+            <goals>
+              <goal>generate</goal>
+            </goals>
+          </execution>
+        </executions>
+        <configuration>
+          <!-- 此处为硬编码，应优化为 env 的配置 -->
+          <apiDocsUrl>http://localhost:8080/api/v3/api-docs</apiDocsUrl>
+          <outputFileName>openapi.json</outputFileName>
+          <outputDir>${project.build.directory}</outputDir>
+        </configuration>
+      </plugin>
     </plugins>
   </build>
 </project>

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

@@ -0,0 +1,129 @@
+package com.openisle.config;
+
+import com.fasterxml.jackson.annotation.JsonAutoDetect;
+import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import com.fasterxml.jackson.annotation.PropertyAccessor;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.jsontype.impl.LaissezFaireSubTypeValidator;
+import com.fasterxml.jackson.datatype.hibernate6.Hibernate6Module;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import org.springframework.cache.CacheManager;
+import org.springframework.cache.annotation.EnableCaching;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+import org.springframework.data.redis.cache.RedisCacheConfiguration;
+import org.springframework.data.redis.cache.RedisCacheManager;
+import org.springframework.data.redis.connection.RedisConnectionFactory;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer;
+import org.springframework.data.redis.serializer.RedisSerializationContext;
+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 缓存配置类
+ * @author smallclover
+ * @since 2025-09-04
+ */
+@Configuration
+@EnableCaching
+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的序列化器
+     * @return
+     */
+    @Bean()
+    @Primary
+    public RedisSerializer<Object> redisSerializer() {
+        // 注册 JavaTimeModule 來支持 Java 8 的日期和时间 API,否则回报一下错误，同时还要引入jsr310
+
+        // org.springframework.data.redis.serializer.SerializationException: Could not write JSON: Java 8 date/time type `java.time.LocalDateTime` not supported by default:
+        // add Module "com.fasterxml.jackson.datatype:jackson-datatype-jsr310" to enable handling
+        // (through reference chain: java.util.ArrayList[0]->com.openisle.dto.TagDto["createdAt"])
+        // 设置可见性，允许序列化所有元素
+        ObjectMapper objectMapper = new ObjectMapper();
+        objectMapper.registerModule(new JavaTimeModule());
+        // Hibernate6Module 可以自动处理懒加载代理对象。
+        // Tag对象的creator是FetchType.LAZY
+        objectMapper.registerModule(new Hibernate6Module()
+                .disable(Hibernate6Module.Feature.USE_TRANSIENT_ANNOTATION)
+                // 将 Hibernate 特有的集合类型转换为标准 Java 集合类型
+                // 避免序列化时出现 org.hibernate.collection.spi.PersistentSet 这样的类型信息
+                .configure(Hibernate6Module.Feature.REPLACE_PERSISTENT_COLLECTIONS, true));
+        // service的时候带上类型信息
+        // 启用类型信息，避免 LinkedHashMap 问题
+        objectMapper.activateDefaultTyping(
+                LaissezFaireSubTypeValidator.instance,
+                ObjectMapper.DefaultTyping.NON_FINAL,
+                JsonTypeInfo.As.PROPERTY
+        );
+        objectMapper.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.ANY);
+        return new GenericJackson2JsonRedisSerializer(objectMapper);
+    }
+
+    /**
+     * 配置 Spring Cache 使用 RedisCacheManager
+     */
+    @Bean
+    public CacheManager cacheManager(RedisConnectionFactory connectionFactory, RedisSerializer<Object> redisSerializer) {
+
+        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
+                .entryTtl(Duration.ZERO) // 默认缓存不过期
+                .serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer()))
+                .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(redisSerializer))
+                .disableCachingNullValues(); // 禁止缓存 null 值
+
+        // 个别缓存单独设置 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();
+    }
+
+    /**
+     * 配置 RedisTemplate，支持直接操作 Redis
+     */
+    @Bean
+    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory,  RedisSerializer<Object> redisSerializer) {
+        RedisTemplate<String, Object> template = new RedisTemplate<>();
+        template.setConnectionFactory(connectionFactory);
+
+        // key 和 hashKey 使用 String 序列化
+        template.setKeySerializer(new StringRedisSerializer());
+        template.setHashKeySerializer(new StringRedisSerializer());
+
+        // value 和 hashValue 使用 JSON 序列化
+        template.setValueSerializer(redisSerializer);
+        template.setHashValueSerializer(redisSerializer);
+
+        return template;
+    }
+}

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

@@ -0,0 +1,60 @@
+package com.openisle.config;
+
+import io.swagger.v3.oas.models.Components;
+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;
+
+    @Value("${springdoc.info.description}")
+    private String description;
+
+    @Value("${springdoc.info.version}")
+    private String version;
+
+    @Value("${springdoc.info.scheme}")
+    private String scheme;
+
+    @Value("${springdoc.info.header}")
+    private String header;
+
+    @Bean
+    public OpenAPI openAPI() {
+        SecurityScheme securityScheme = new SecurityScheme()
+                        .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))
+                .addSecurityItem(new SecurityRequirement().addList("JWT"));
+    }
+}

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

@@ -0,0 +1,205 @@
+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;
+import org.springframework.amqp.core.TopicExchange;
+import org.springframework.amqp.rabbit.connection.ConnectionFactory;
+import org.springframework.amqp.rabbit.core.RabbitTemplate;
+import org.springframework.amqp.support.converter.Jackson2JsonMessageConverter;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.springframework.amqp.rabbit.core.RabbitAdmin;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.context.annotation.DependsOn;
+
+import jakarta.annotation.PostConstruct;
+import java.util.ArrayList;
+import java.util.List;
+
+@Configuration
+@RequiredArgsConstructor
+@Slf4j
+public class RabbitMQConfig {
+
+    public static final String EXCHANGE_NAME = "openisle-exchange";
+    // 保持向后兼容的常量
+    public static final String QUEUE_NAME = "notifications-queue";
+    public static final String ROUTING_KEY = "notifications.routingkey";
+    
+    // 硬编码为16以匹配ShardingStrategy中的十六进制分片逻辑
+    private final int queueCount = 16;
+    
+    @Value("${rabbitmq.queue.durable}")
+    private boolean queueDurable;
+
+    @PostConstruct
+    public void init() {
+        log.info("RabbitMQ配置初始化: 队列数量={}, 持久化={}", queueCount, queueDurable);
+    }
+
+    @Bean
+    public TopicExchange exchange() {
+        return new TopicExchange(EXCHANGE_NAME);
+    }
+
+    /**
+     * 创建所有分片队列, 使用十六进制后缀 (0-f)
+     */
+    @Bean
+    public List<Queue> shardedQueues() {
+        log.info("开始创建分片队列 Bean...");
+        
+        List<Queue> queues = new ArrayList<>();
+        for (int i = 0; i < queueCount; i++) {
+            String shardKey = Integer.toHexString(i);
+            String queueName = "notifications-queue-" + shardKey;
+            Queue queue = new Queue(queueName, queueDurable);
+            queues.add(queue);
+        }
+        
+        log.info("分片队列 Bean 创建完成，总数: {}", queues.size());
+        return queues;
+    }
+
+    /**
+     * 创建所有分片绑定, 使用十六进制路由键 (notifications.shard.0 - notifications.shard.f)
+     */
+    @Bean
+    public List<Binding> shardedBindings(TopicExchange exchange, @Qualifier("shardedQueues") List<Queue> shardedQueues) {
+        log.info("开始创建分片绑定 Bean...");
+        List<Binding> bindings = new ArrayList<>();
+        if (shardedQueues != null) {
+            for (Queue queue : shardedQueues) {
+                String queueName = queue.getName();
+                String shardKey = queueName.substring("notifications-queue-".length());
+                String routingKey = "notifications.shard." + shardKey;
+                Binding binding = BindingBuilder.bind(queue).to(exchange).with(routingKey);
+                bindings.add(binding);
+            }
+        }
+        
+        log.info("分片绑定 Bean 创建完成，总数: {}", bindings.size());
+        return bindings;
+    }
+
+    /**
+     * 保持向后兼容的单队列配置（可选）
+     */
+    @Bean
+    public Queue legacyQueue() {
+        return new Queue(QUEUE_NAME, queueDurable);
+    }
+
+    /**
+     * 保持向后兼容的单队列绑定（可选）
+     */
+    @Bean
+    public Binding legacyBinding(Queue legacyQueue, TopicExchange exchange) {
+        return BindingBuilder.bind(legacyQueue).to(exchange).with(ROUTING_KEY);
+    }
+
+    @Bean
+    public Jackson2JsonMessageConverter messageConverter() {
+        ObjectMapper objectMapper = new ObjectMapper();
+        objectMapper.registerModule(new com.fasterxml.jackson.datatype.jsr310.JavaTimeModule());
+        objectMapper.disable(com.fasterxml.jackson.databind.SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
+        return new Jackson2JsonMessageConverter(objectMapper);
+    }
+
+    @Bean
+    public RabbitAdmin rabbitAdmin(ConnectionFactory connectionFactory) {
+        return new RabbitAdmin(connectionFactory);
+    }
+
+    @Bean
+    public RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory) {
+        RabbitTemplate template = new RabbitTemplate(connectionFactory);
+        template.setMessageConverter(messageConverter());
+        return template;
+    }
+
+    /**
+     * 使用 CommandLineRunner 确保在应用完全启动后声明队列到 RabbitMQ
+     * 这样可以确保 RabbitAdmin 和所有 Bean 都已正确初始化
+     */
+    @Bean
+    @DependsOn({"rabbitAdmin", "shardedQueues", "exchange"})
+    public CommandLineRunner queueDeclarationRunner(RabbitAdmin rabbitAdmin,
+                                                   @Qualifier("shardedQueues") List<Queue> shardedQueues,
+                                                   TopicExchange exchange,
+                                                   Queue legacyQueue,
+                                                   @Qualifier("shardedBindings") List<Binding> shardedBindings,
+                                                   Binding legacyBinding) {
+        return args -> {
+            log.info("=== 开始主动声明 RabbitMQ 组件 ===");
+            
+            try {
+                // 声明交换
+                rabbitAdmin.declareExchange(exchange);
+                
+                // 声明分片队列 - 检查存在性
+                log.info("开始检查并声明 {} 个分片队列...", shardedQueues.size());
+                int successCount = 0;
+                int skippedCount = 0;
+                
+                for (Queue queue : shardedQueues) {
+                    String queueName = queue.getName();
+                    try {
+                        // 使用 declareQueue 的返回值判断队列是否已存在
+                        // 如果队列已存在且配置匹配，declareQueue 会返回现有队列信息
+                        // 如果不匹配或不存在，会创建新队列
+                        rabbitAdmin.declareQueue(queue);
+                        successCount++;
+                    } catch (org.springframework.amqp.AmqpIOException e) {
+                        if (e.getMessage().contains("PRECONDITION_FAILED") && e.getMessage().contains("durable")) {
+                            skippedCount++;
+                        }
+                    } catch (Exception e) {
+                        log.error("队列声明失败: {}, 错误: {}", queueName, e.getMessage());
+                    }
+                }
+                log.info("分片队列处理完成: 成功 {}, 跳过 {}, 总数 {}", successCount, skippedCount, shardedQueues.size());
+                
+                // 声明分片绑定
+                log.info("开始声明 {} 个分片绑定...", shardedBindings.size());
+                int bindingSuccessCount = 0;
+                for (Binding binding : shardedBindings) {
+                    try {
+                        rabbitAdmin.declareBinding(binding);
+                        bindingSuccessCount++;
+                    } catch (Exception e) {
+                        log.error("绑定声明失败: {}", e.getMessage());
+                    }
+                }
+                log.info("分片绑定声明完成: 成功 {}/{}", bindingSuccessCount, shardedBindings.size());
+                
+                // 声明遗留队列和绑定 - 检查存在性
+                try {
+                    rabbitAdmin.declareQueue(legacyQueue);
+                    rabbitAdmin.declareBinding(legacyBinding);
+                    log.info("遗留队列和绑定就绪: {} (已存在或新创建)", QUEUE_NAME);
+                } catch (org.springframework.amqp.AmqpIOException e) {
+                    if (e.getMessage().contains("PRECONDITION_FAILED") && e.getMessage().contains("durable")) {
+                        log.warn("遗留队列已存在但 durable 设置不匹配: {}, 保持现有队列", QUEUE_NAME);
+                    } else {
+                        log.error("遗留队列声明失败: {}, 错误: {}", QUEUE_NAME, e.getMessage());
+                    }
+                } catch (Exception e) {
+                    log.error("遗留队列声明失败: {}, 错误: {}", QUEUE_NAME, e.getMessage());
+                }
+                
+                log.info("=== RabbitMQ 组件声明完成 ===");
+                log.info("请检查 RabbitMQ 管理界面确认队列已正确创建");
+                
+            } catch (Exception e) {
+                log.error("RabbitMQ 组件声明过程中发生严重错误", e);
+            }
+        };
+    }
+}

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

@@ -0,0 +1,35 @@
+package com.openisle.config;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.InitializingBean;
+import org.springframework.data.redis.connection.RedisConnectionFactory;
+import org.springframework.data.redis.connection.lettuce.LettuceConnectionFactory;
+import org.springframework.stereotype.Component;
+
+/**
+ * Logs a message when a Redis connection is successfully established.
+ */
+@Component
+@Slf4j
+public class RedisConnectionLogger implements InitializingBean {
+
+    private final RedisConnectionFactory connectionFactory;
+
+    public RedisConnectionLogger(RedisConnectionFactory connectionFactory) {
+        this.connectionFactory = connectionFactory;
+    }
+
+    @Override
+    public void afterPropertiesSet() {
+        try (var connection = connectionFactory.getConnection()) {
+            connection.ping();
+            if (connectionFactory instanceof LettuceConnectionFactory lettuce) {
+                log.info("Redis connection established at {}:{}", lettuce.getHostName(), lettuce.getPort());
+            } else {
+                log.info("Redis connection established");
+            }
+        } catch (Exception e) {
+            log.error("Failed to connect to Redis", 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();
@@ -74,10 +79,14 @@ public class SecurityConfig {
         CorsConfiguration cfg = new CorsConfiguration();
         cfg.setAllowedOrigins(List.of(
                 "http://127.0.0.1:8080",
+                "http://127.0.0.1:8081",
+                "http://127.0.0.1:8082",
                 "http://127.0.0.1:3000",
                 "http://127.0.0.1:3001",
                 "http://127.0.0.1",
                 "http://localhost:8080",
+                "http://localhost:8081",
+                "http://localhost:8082",
                 "http://localhost:3000",
                 "http://localhost:3001",
                 "http://localhost",
@@ -85,6 +94,10 @@ public class SecurityConfig {
                 "http://30.211.97.238",
                 "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.", "://")
         ));
@@ -106,6 +119,7 @@ public class SecurityConfig {
             .authorizeHttpRequests(auth -> auth
                     .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
                     .requestMatchers("/api/ws/**", "/api/sockjs/**").permitAll()
+                    .requestMatchers("/api/v3/api-docs/**").permitAll()
                     .requestMatchers(HttpMethod.POST, "/api/auth/**").permitAll()
                     .requestMatchers(HttpMethod.GET, "/api/posts/**").permitAll()
                     .requestMatchers(HttpMethod.GET, "/api/comments/**").permitAll()
@@ -123,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")
@@ -176,7 +192,9 @@ public class SecurityConfig {
                         return;
                     }
                 } else if (!uri.startsWith("/api/auth") && !publicGet
-                        && !uri.startsWith("/api/ws") && !uri.startsWith("/api/sockjs")) {
+                        && !uri.startsWith("/api/ws") && !uri.startsWith("/api/sockjs")
+                        && !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\"}");
@@ -195,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/ShardInfo.java

@@ -0,0 +1,14 @@
+package com.openisle.config;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+public class ShardInfo {
+    private int shardIndex;
+    private String queueName;
+    private String routingKey;
+}

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

@@ -0,0 +1,84 @@
+package com.openisle.config;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+@Component
+@Slf4j
+public class ShardingStrategy {
+    
+    // 固定为16以匹配RabbitMQConfig中的十六进制分片逻辑
+    private static final int QUEUE_COUNT = 16;
+    
+    // 分片分布统计
+    private final Map<Integer, AtomicLong> shardCounts = new ConcurrentHashMap<>();
+    
+    /**
+     * 根据用户名获取分片信息（基于哈希值首字符）
+     */
+    public ShardInfo getShardInfo(String username) {
+        if (username == null || username.isEmpty()) {
+            // 空用户名默认分到第0个分片
+            return getShardInfoByIndex(0);
+        }
+        
+        // 计算用户名的哈希值并转为十六进制字符串
+        String hash = Integer.toHexString(Math.abs(username.hashCode()));
+        
+        // 取哈希值的第一个字符 (0-9, a-f)
+        char firstChar = hash.charAt(0);
+        
+        // 十六进制字符映射到队列
+        int shard = getShardFromHexChar(firstChar);
+        recordShardUsage(shard);
+        
+        log.debug("Username '{}' -> hash '{}' -> firstChar '{}' -> shard {}", 
+                 username, hash, firstChar, shard);
+        
+        return getShardInfoByIndex(shard);
+    }
+    
+    /**
+     * 将十六进制字符映射到分片索引
+     */
+    private int getShardFromHexChar(char hexChar) {
+        int charValue;
+        if (hexChar >= '0' && hexChar <= '9') {
+            charValue = hexChar - '0'; // 0-9
+        } else if (hexChar >= 'a' && hexChar <= 'f') {
+            charValue = hexChar - 'a' + 10; // 10-15
+        } else {
+            // 异常情况，默认为0
+            charValue = 0;
+        }
+        
+        // 映射到队列数量范围内
+        return charValue % QUEUE_COUNT;
+    }
+    
+    /**
+     * 根据分片索引获取分片信息
+     */
+    private ShardInfo getShardInfoByIndex(int shard) {
+        String shardKey = Integer.toHexString(shard);
+        return new ShardInfo(
+            shard,
+            "notifications-queue-" + shardKey,
+            "notifications.shard." + shardKey
+        );
+    }
+    
+    /**
+     * 记录分片使用统计
+     */
+    private void recordShardUsage(int shard) {
+        shardCounts.computeIfAbsent(shard, k -> new AtomicLong(0)).incrementAndGet();
+    }
+
+}

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/config/WebSocketConfig.java

@@ -1,110 +0,0 @@
-package com.openisle.config;
-
-import com.openisle.service.JwtService;
-import lombok.RequiredArgsConstructor;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.context.annotation.Configuration;
-import org.springframework.messaging.Message;
-import org.springframework.messaging.MessageChannel;
-import org.springframework.messaging.simp.config.ChannelRegistration;
-import org.springframework.messaging.simp.config.MessageBrokerRegistry;
-import org.springframework.messaging.simp.stomp.StompCommand;
-import org.springframework.messaging.simp.stomp.StompHeaderAccessor;
-import org.springframework.messaging.support.ChannelInterceptor;
-import org.springframework.messaging.support.MessageHeaderAccessor;
-import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
-import org.springframework.security.core.Authentication;
-import org.springframework.security.core.userdetails.UserDetailsService;
-import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker;
-import org.springframework.web.socket.config.annotation.StompEndpointRegistry;
-import org.springframework.web.socket.config.annotation.WebSocketMessageBrokerConfigurer;
-
-@Configuration
-@EnableWebSocketMessageBroker
-@RequiredArgsConstructor
-public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
-    
-    private final JwtService jwtService;
-    private final UserDetailsService userDetailsService;
-    @Value("${app.website-url}")
-    private String websiteUrl;
-
-    @Override
-    public void configureMessageBroker(MessageBrokerRegistry config) {
-        // Enable a simple memory-based message broker to carry the messages back to the client on destinations prefixed with "/topic" and "/queue"
-        config.enableSimpleBroker("/topic", "/queue");
-        // Set user destination prefix for personal messages
-        config.setUserDestinationPrefix("/user");
-        // Designates the "/app" prefix for messages that are bound for @MessageMapping-annotated methods.
-        config.setApplicationDestinationPrefixes("/app");
-    }
-
-    @Override
-    public void registerStompEndpoints(StompEndpointRegistry registry) {
-        // 1) 原生 WebSocket（不带 SockJS）
-        registry.addEndpoint("/api/ws")
-                .setAllowedOriginPatterns(
-                        "https://staging.open-isle.com",
-                        "https://www.staging.open-isle.com",
-                        websiteUrl,
-                        websiteUrl.replace("://www.", "://"),
-                        "http://localhost:*",
-                        "http://127.0.0.1:*",
-                        "http://192.168.7.98:*",
-                        "http://30.211.97.238:*"
-                );
-
-        // 2) SockJS 回退：单独路径
-        registry.addEndpoint("/api/sockjs")
-                .setAllowedOriginPatterns(
-                        "https://staging.open-isle.com",
-                        "https://www.staging.open-isle.com",
-                        websiteUrl,
-                        websiteUrl.replace("://www.", "://"),
-                        "http://localhost:*",
-                        "http://127.0.0.1:*",
-                        "http://192.168.7.98:*",
-                        "http://30.211.97.238:*"
-                )
-                .withSockJS()
-                .setWebSocketEnabled(true)
-                .setSessionCookieNeeded(false);
-    }
-
-
-
-    @Override
-    public void configureClientInboundChannel(ChannelRegistration registration) {
-        registration.interceptors(new ChannelInterceptor() {
-            @Override
-            public Message<?> preSend(Message<?> message, MessageChannel channel) {
-                StompHeaderAccessor accessor = MessageHeaderAccessor.getAccessor(message, StompHeaderAccessor.class);
-                
-                if (StompCommand.CONNECT.equals(accessor.getCommand())) {
-                    System.out.println("WebSocket CONNECT command received");
-                    String authHeader = accessor.getFirstNativeHeader("Authorization");
-                    System.out.println("Authorization header: " + (authHeader != null ? "present" : "missing"));
-                    
-                    if (authHeader != null && authHeader.startsWith("Bearer ")) {
-                        String token = authHeader.substring(7);
-                        try {
-                            String username = jwtService.validateAndGetSubject(token);
-                            System.out.println("JWT validated for user: " + username);
-                            var userDetails = userDetailsService.loadUserByUsername(username);
-                            Authentication auth = new UsernamePasswordAuthenticationToken(
-                                userDetails, null, userDetails.getAuthorities());
-                            accessor.setUser(auth);
-                            System.out.println("WebSocket user set: " + username);
-                        } catch (Exception e) {
-                            System.err.println("JWT validation failed: " + e.getMessage());
-                        }
-                    }
-                } else if (StompCommand.SUBSCRIBE.equals(accessor.getCommand())) {
-                    System.out.println("WebSocket SUBSCRIBE to: " + accessor.getDestination());
-                    System.out.println("WebSocket user during subscribe: " + (accessor.getUser() != null ? accessor.getUser().getName() : "null"));
-                }
-                return message;
-            }
-        });
-    }
-}

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")
@@ -26,6 +35,7 @@ public class AuthController {
     private final GithubAuthService githubAuthService;
     private final DiscordAuthService discordAuthService;
     private final TwitterAuthService twitterAuthService;
+    private final TelegramAuthService telegramAuthService;
     private final RegisterModeService registerModeService;
     private final NotificationService notificationService;
     private final UserRepository userRepository;
@@ -42,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"));
@@ -55,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"
@@ -69,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());
         }
@@ -77,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()) {
@@ -105,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"));
@@ -121,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",
@@ -143,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());
@@ -190,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);
@@ -218,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());
@@ -266,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());
@@ -313,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());
@@ -360,25 +395,86 @@ 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());
+        if (viaInvite && !inviteValidateResult.isValidate()) {
+            return ResponseEntity.badRequest().body(Map.of("error", "Invalid invite token"));
+        }
+        Optional<AuthResult> resultOpt = telegramAuthService.authenticate(
+                req,
+                registerModeService.getRegisterMode(),
+                viaInvite);
+        if (resultOpt.isPresent()) {
+            AuthResult result = resultOpt.get();
+            if (viaInvite && result.isNewUser()) {
+                inviteService.consume(req.getInviteToken(), inviteValidateResult.getInviteToken().getInviter().getUsername());
+                return ResponseEntity.ok(Map.of(
+                        "token", jwtService.generateToken(result.getUser().getUsername()),
+                        "reason_code", "INVITE_APPROVED"
+                ));
+            }
+            if (RegisterMode.DIRECT.equals(registerModeService.getRegisterMode())) {
+                return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+            }
+            if (!result.getUser().isApproved()) {
+                if (result.getUser().getRegisterReason() != null && !result.getUser().getRegisterReason().isEmpty()) {
+                    return ResponseEntity.badRequest().body(Map.of(
+                            "error", "Account awaiting approval",
+                            "reason_code", "IS_APPROVING",
+                            "token", jwtService.generateReasonToken(result.getUser().getUsername())
+                    ));
+                }
+                return ResponseEntity.badRequest().body(Map.of(
+                        "error", "Account awaiting approval",
+                        "reason_code", "NOT_APPROVED",
+                        "token", jwtService.generateReasonToken(result.getUser().getUsername())
+                ));
+            }
+            return ResponseEntity.ok(Map.of("token", jwtService.generateToken(result.getUser().getUsername())));
+        }
+        return ResponseEntity.badRequest().body(Map.of(
+                "error", "Invalid telegram data",
+                "reason_code", "INVALID_CREDENTIALS"
+        ));
+    }
+
     @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)));
@@ -387,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,17 +67,44 @@ 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

@@ -3,9 +3,16 @@ package com.openisle.controller;
 import com.openisle.dto.PostDetailDto;
 import com.openisle.dto.PostRequest;
 import com.openisle.dto.PostSummaryDto;
+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;
@@ -20,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;
@@ -34,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();
@@ -42,7 +55,8 @@ public class PostController {
                 req.getTitle(), req.getContent(), req.getTagIds(),
                 req.getType(), req.getPrizeDescription(), req.getPrizeIcon(),
                 req.getPrizeCount(), req.getPointCost(),
-                req.getStartTime(), req.getEndTime());
+                req.getStartTime(), req.getEndTime(),
+                req.getOptions(), req.getMultiple());
         draftService.deleteDraft(auth.getName());
         PostDetailDto dto = postMapper.toDetailDto(post, auth.getName());
         dto.setReward(levelService.awardForPost(auth.getName()));
@@ -51,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(),
@@ -59,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);
@@ -81,12 +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,
@@ -94,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,
@@ -131,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,
@@ -156,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,
@@ -181,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/MessageNotificationPayload.java

@@ -0,0 +1,15 @@
+package com.openisle.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serializable;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class MessageNotificationPayload implements Serializable {
+    private String targetUsername;
+    private Object payload;
+}

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

@@ -0,0 +1,17 @@
+package com.openisle.dto;
+
+import lombok.Data;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Map;
+
+@Data
+public class PollDto {
+    private List<String> options;
+    private Map<Integer, Integer> votes;
+    private LocalDateTime endTime;
+    private List<AuthorDto> participants;
+    private Map<Integer, List<AuthorDto>> optionParticipants;
+    private boolean multiple;
+}

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/PostRequest.java

@@ -26,5 +26,8 @@ public class PostRequest {
     private Integer pointCost;
     private LocalDateTime startTime;
     private LocalDateTime endTime;
+    // fields for poll posts
+    private List<String> options;
+    private Boolean multiple;
 }
 

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

@@ -31,6 +31,7 @@ public class PostSummaryDto {
     private int pointReward;
     private PostType type;
     private LotteryDto lottery;
+    private PollDto poll;
     private boolean rssExcluded;
     private boolean closed;
 }

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

@@ -0,0 +1,16 @@
+package com.openisle.dto;
+
+import lombok.Data;
+
+/** Request for Telegram login. */
+@Data
+public class TelegramLoginRequest {
+    private String id;
+    private String firstName;
+    private String lastName;
+    private String username;
+    private String photoUrl;
+    private Long authDate;
+    private String hash;
+    private String inviteToken;
+}

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

@@ -5,18 +5,24 @@ import com.openisle.dto.PostDetailDto;
 import com.openisle.dto.PostSummaryDto;
 import com.openisle.dto.ReactionDto;
 import com.openisle.dto.LotteryDto;
+import com.openisle.dto.PollDto;
+import com.openisle.dto.AuthorDto;
 import com.openisle.model.CommentSort;
 import com.openisle.model.Post;
 import com.openisle.model.LotteryPost;
+import com.openisle.model.PollPost;
 import com.openisle.model.User;
+import com.openisle.model.PollVote;
 import com.openisle.service.CommentService;
 import com.openisle.service.ReactionService;
 import com.openisle.service.SubscriptionService;
+import com.openisle.repository.PollVoteRepository;
 import lombok.RequiredArgsConstructor;
 import org.springframework.stereotype.Component;
 
 import java.time.LocalDateTime;
 import java.util.List;
+import java.util.Map;
 import java.util.stream.Collectors;
 
 /** Mapper responsible for converting posts into DTOs. */
@@ -32,6 +38,7 @@ public class PostMapper {
     private final UserMapper userMapper;
     private final TagMapper tagMapper;
     private final CategoryMapper categoryMapper;
+    private final PollVoteRepository pollVoteRepository;
 
     public PostSummaryDto toSummaryDto(Post post) {
         PostSummaryDto dto = new PostSummaryDto();
@@ -89,9 +96,20 @@ 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);
         }
+
+        if (post instanceof PollPost pp) {
+            PollDto p = new PollDto();
+            p.setOptions(pp.getOptions());
+            p.setVotes(pp.getVotes());
+            p.setEndTime(pp.getEndTime());
+            Map<Integer, List<AuthorDto>> optionParticipants = pollVoteRepository.findByPostId(pp.getId()).stream()
+                    .collect(Collectors.groupingBy(PollVote::getOptionIndex,
+                            Collectors.mapping(v -> userMapper.toAuthorDto(v.getUser()), Collectors.toList())));
+            p.setOptionParticipants(optionParticipants);
+            p.setMultiple(Boolean.TRUE.equals(pp.getMultiple()));
+            dto.setPoll(p);
+        }
     }
 }

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

@@ -5,6 +5,8 @@ import lombok.Getter;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
 import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.annotations.SQLDelete;
+import org.hibernate.annotations.Where;
 
 import java.time.LocalDateTime;
 
@@ -13,6 +15,8 @@ import java.time.LocalDateTime;
 @Setter
 @NoArgsConstructor
 @Table(name = "comments")
+@SQLDelete(sql = "UPDATE comments SET deleted_at = CURRENT_TIMESTAMP(6) WHERE id = ?")
+@Where(clause = "deleted_at IS NULL")
 public class Comment {
     @Id
     @GeneratedValue(strategy = GenerationType.IDENTITY)
@@ -41,4 +45,7 @@ public class Comment {
     @Column
     private LocalDateTime pinnedAt;
 
+    @Column(name = "deleted_at")
+    private LocalDateTime deletedAt;
+
 }

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

@@ -14,6 +14,13 @@ public class InviteToken {
     @Id
     private String token;
 
+    /**
+     * Short token used in invite links. Existing records may have this field null
+     * and fall back to {@link #token} for backward compatibility.
+     */
+    @Column(unique = true)
+    private String shortToken;
+
     @ManyToOne
     private User inviter;
 

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

@@ -1,5 +1,6 @@
 package com.openisle.model;
 
+import com.fasterxml.jackson.annotation.JsonBackReference;
 import jakarta.persistence.*;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -20,6 +21,7 @@ public class Message {
 
     @ManyToOne(optional = false, fetch = FetchType.LAZY)
     @JoinColumn(name = "conversation_id")
+    @JsonBackReference
     private MessageConversation conversation;
 
     @ManyToOne(optional = false, fetch = FetchType.LAZY)

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

@@ -1,5 +1,7 @@
 package com.openisle.model;
 
+import com.fasterxml.jackson.annotation.JsonBackReference;
+import com.fasterxml.jackson.annotation.JsonManagedReference;
 import jakarta.persistence.*;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -41,8 +43,10 @@ public class MessageConversation {
     private Message lastMessage;
 
     @OneToMany(mappedBy = "conversation", cascade = CascadeType.ALL, orphanRemoval = true)
+    @JsonBackReference
     private Set<MessageParticipant> participants = new HashSet<>();
 
     @OneToMany(mappedBy = "conversation", cascade = CascadeType.ALL, orphanRemoval = true)
+    @JsonBackReference
     private Set<Message> messages = new HashSet<>();
 }

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

@@ -1,5 +1,6 @@
 package com.openisle.model;
 
+import com.fasterxml.jackson.annotation.JsonBackReference;
 import jakarta.persistence.*;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -19,6 +20,7 @@ public class MessageParticipant {
 
     @ManyToOne(optional = false, fetch = FetchType.LAZY)
     @JoinColumn(name = "conversation_id")
+    @JsonBackReference
     private MessageConversation conversation;
 
     @ManyToOne(optional = false, fetch = FetchType.LAZY)

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

@@ -40,6 +40,12 @@ public enum NotificationType {
     LOTTERY_WIN,
     /** Your lottery post was drawn */
     LOTTERY_DRAW,
+    /** Someone participated in your poll */
+    POLL_VOTE,
+    /** Your poll post has concluded */
+    POLL_RESULT_OWNER,
+    /** A poll you participated in has concluded */
+    POLL_RESULT_PARTICIPANT,
     /** Your post was featured */
     POST_FEATURED,
     /** You were mentioned in a post or comment */

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

@@ -4,6 +4,8 @@ import jakarta.persistence.*;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
+import org.hibernate.annotations.SQLDelete;
+import org.hibernate.annotations.Where;
 
 import java.time.LocalDateTime;
 
@@ -13,6 +15,8 @@ import java.time.LocalDateTime;
 @Setter
 @NoArgsConstructor
 @Table(name = "point_histories")
+@SQLDelete(sql = "UPDATE point_histories SET deleted_at = CURRENT_TIMESTAMP(6) WHERE id = ?")
+@Where(clause = "deleted_at IS NULL")
 public class PointHistory {
     @Id
     @GeneratedValue(strategy = GenerationType.IDENTITY)
@@ -46,4 +50,7 @@ public class PointHistory {
 
     @Column(name = "created_at", nullable = false)
     private LocalDateTime createdAt;
+
+    @Column(name = "deleted_at")
+    private LocalDateTime deletedAt;
 }

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

@@ -0,0 +1,43 @@
+package com.openisle.model;
+
+import jakarta.persistence.*;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import java.time.LocalDateTime;
+import java.util.*;
+
+@Entity
+@Table(name = "poll_posts")
+@Getter
+@Setter
+@NoArgsConstructor
+@PrimaryKeyJoinColumn(name = "post_id")
+public class PollPost extends Post {
+    @ElementCollection
+    @CollectionTable(name = "poll_post_options", joinColumns = @JoinColumn(name = "post_id"))
+    @Column(name = "option_text")
+    private List<String> options = new ArrayList<>();
+
+    @ElementCollection
+    @CollectionTable(name = "poll_post_votes", joinColumns = @JoinColumn(name = "post_id"))
+    @MapKeyColumn(name = "option_index")
+    @Column(name = "vote_count")
+    private Map<Integer, Integer> votes = new HashMap<>();
+
+    @ManyToMany
+    @JoinTable(name = "poll_participants",
+            joinColumns = @JoinColumn(name = "post_id"),
+            inverseJoinColumns = @JoinColumn(name = "user_id"))
+    private Set<User> participants = new HashSet<>();
+
+    @Column
+    private Boolean multiple = false;
+
+    @Column
+    private LocalDateTime endTime;
+
+    @Column
+    private boolean resultAnnounced = false;
+}

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

@@ -0,0 +1,28 @@
+package com.openisle.model;
+
+import jakarta.persistence.*;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+@Entity
+@Table(name = "poll_votes", uniqueConstraints = @UniqueConstraint(columnNames = {"post_id", "user_id", "option_index"}))
+@Getter
+@Setter
+@NoArgsConstructor
+public class PollVote {
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @ManyToOne(fetch = FetchType.LAZY, optional = false)
+    @JoinColumn(name = "post_id")
+    private PollPost post;
+
+    @ManyToOne(fetch = FetchType.LAZY, optional = false)
+    @JoinColumn(name = "user_id")
+    private User user;
+
+    @Column(name = "option_index", nullable = false)
+    private int optionIndex;
+}

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;

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